# Poetry Monorepo Dependency Plugin
[](https://pypi.org/project/poetry-monorepo-dependency-plugin/)
[](https://opensource.org/licenses/mit)
Forked and inspired by the [poetry-stickywheel-plugin](https://github.com/artisanofcode/poetry-stickywheel-plugin), this
[Poetry][poetry] plugin facilitates the usage of more complex monorepo project structures by pinning version dependencies when
building and publishing archives with local path dependencies to other Poetry projects within the same monorepo.
## Installation
```
poetry self add poetry-monorepo-dependency-plugin
```
If you want to activate `poetry-monorepo-dependency-plugin` for all [build][poetry-build],
[publish][poetry-publish], and [export][poetry-export] command invocations, add the following to your project's `pyproject.toml`
that has path dependencies to other Poetry projects:
```toml
[tool.poetry-monorepo-dependency-plugin]
enable = true
```
## Usage
During archive building or publishing, this plugin will rewrite [path dependencies](https://python-poetry.org/docs/dependency-specification/#path-dependencies)
to other Poetry projects using the corresponding pinned version dependency extracted from the referenced project's `pyproject.toml`.
The extracted dependency version will be applied to the generated archive using the strategy specified in the `version-pinning-strategy`
configuration. By referencing pinned version dependencies in published archive files, package consumers may more easily depend on
and install packages that are built within complex monorepos, without needing to replicate the exact folder structure utilized within
the monorepo for that project's dependencies.
For example, assume that `spam` and `ham` Poetry projects exist within the same monorepo and use the following `pyproject.toml`
configurations.
`spam/pyproject.toml`:
```toml
[tool.poetry]
name = "spam"
version = "0.1.0"
[tool.poetry.dependencies]
ham = {path = "../ham", develop = true}
```
`ham/pyproject.toml`:
```
[tool.poetry]
name = "ham"
version = "1.2.3"
```
When generating `wheel` or `sdist` archives for the `spam` project through Poetry's [build][poetry-build] or
[publish][poetry-publish] commands, the corresponding `spam` package will be constructed as if its dependency on the
`ham` project were declared as `ham = "1.2.3"`. As a result, package metadata in archives for `spam` will shift from
`Requires-Dist: ham @ ../ham` to `Requires-Dist: ham (==1.2.3)`
Additionally, to address [path dependencies](https://python-poetry.org/docs/dependency-specification/#path-dependencies) not being portable, this plugin provides
the ability to extend Poetry's [export][poetry-export] command using the `export-without-path-deps` command. This command will exclude path dependencies from being written to intermediate `requirements.txt` export. When installing the exported
`requirements.txt` on another machine and/or Docker container local Paths dependencies can not be resolved and therefore can not
be installed so they are removed.
### Command line mode
If you need greater control over when `poetry-monorepo-dependency-plugin` is activated, this plugin exposes new `build-rewrite-path-deps`
and `publish-rewrite-path-deps` Poetry commands for on-demand execution. For example, it may be desirable to only use this
plugin during CI to support a monorepo's artifact deployment and/or release process. When these custom Poetry commands are invoked,
any configuration defined in the project's `pyproject.toml` `[tool.poetry-monorepo-dependency-plugin]` section is ignored and all options
(other than `enable`) are exposed as command line options. For example:
```commandline
poetry build-rewrite-path-deps --version-pinning-strategy=semver
```
To generate a `requirements.txt` without path dependencies use the `export-without-path-deps`. For example:
```commandline
poetry export-without-path-deps -f requirements.txt --output requirements.txt
```
### Configuration
The following configuration options are supported within your project's `pyproject.toml` configuration:
* `[tool.poetry-monorepo-dependency-plugin]`: Parent-level container for plugin
* `enable` (`boolean`, default: `false`): Since Poetry plugins are globally installed, this configuration allows projects
to opt-in to this plugin's modifications of the archives built and/or published Poetry
* `version-pinning-strategy` (`string`, default: `mixed`, options: `mixed`, `semver`, `exact`): Strategy by which path
dependencies to other Poetry projects will be versioned in generated archives. Given a path dependency to a Poetry project
with version `1.2.3`, the version of the dependency referenced in the generated archive is `^1.2.3` for
`semver` and `=1.2.3` for `exact`. `mixed` mode switches versioning strategies based on whether the dependency
Poetry project version is an in-flight development version or a release - if a development version (i.e. `1.2.3.dev456`),
a variant of `semver` is used that applies an upper-bound of the next patch version (i.e. `>=1.2.3.dev,<1.2.4`), and
if a release version (i.e. `1.2.3`), `exact` is applied (i.e. `=1.2.3`).
## Licence
`poetry-monorepo-dependency-plugin` is available under the [MIT licence][mit_licence].
## Releasing to PyPI
Releasing `poetry-monorepo-dependency-plugin` relies on the [maven-release-plugin](https://maven.apache.org/maven-release/maven-release-plugin/)
to automate manual release activities and [Habushu](https://bitbucket.org/cpointe/habushu/) to automate the execution of a
Poetry-based DevOps workflow via a custom Maven lifecycle. During Maven's `deploy` phase, the appropriate plugin packages
will be published to PyPI.
A [PyPI account](https://pypi.org/account/register/) with access to the [poetry-monorepo-dependency-plugin](https://pypi.org/project/poetry-monorepo-dependency-plugin/)
project is required. PyPI account credentials should be specified in your `settings.xml` under the `<id>pypi</id>` `<server>` entry:
```xml
<settings>
<servers>
<server>
<id>pypi</id>
<username>pypi-username</username>
<password>{encrypted-pypi-password}</password>
</server>
</servers>
</settings>
```
Execute `mvn release:clean release:prepare`, answer the prompts for the versions and tags, and execute `mvn release:perform` to publish
the package to PyPI.
[poetry]: https://python-poetry.org/
[poetry-build]: https://python-poetry.org/docs/cli/#build
[poetry-export]: https://python-poetry.org/docs/cli/#export
[poetry-publish]: https://python-poetry.org/docs/cli/#publish
[mit_licence]: http://dan.mit-license.org/
Raw data
{
"_id": null,
"home_page": "https://github.com/TechnologyBrewery/poetry-monorepo-dependency-plugin",
"name": "poetry-monorepo-dependency-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Eric Konieczny",
"author_email": "ekoniec1@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/71/a3/ce8f65af9a63647be620501f2b986c659d793099bb0f0cfb3d7ab58929aa/poetry_monorepo_dependency_plugin-1.2.0.tar.gz",
"platform": null,
"description": "# Poetry Monorepo Dependency Plugin\n\n[](https://pypi.org/project/poetry-monorepo-dependency-plugin/)\n\n\n[](https://opensource.org/licenses/mit)\n\nForked and inspired by the [poetry-stickywheel-plugin](https://github.com/artisanofcode/poetry-stickywheel-plugin), this\n[Poetry][poetry] plugin facilitates the usage of more complex monorepo project structures by pinning version dependencies when \nbuilding and publishing archives with local path dependencies to other Poetry projects within the same monorepo.\n\n## Installation\n\n```\npoetry self add poetry-monorepo-dependency-plugin\n```\n\nIf you want to activate `poetry-monorepo-dependency-plugin` for all [build][poetry-build],\n[publish][poetry-publish], and [export][poetry-export] command invocations, add the following to your project's `pyproject.toml`\nthat has path dependencies to other Poetry projects:\n\n```toml\n[tool.poetry-monorepo-dependency-plugin]\nenable = true\n```\n\n## Usage\n\nDuring archive building or publishing, this plugin will rewrite [path dependencies](https://python-poetry.org/docs/dependency-specification/#path-dependencies) \nto other Poetry projects using the corresponding pinned version dependency extracted from the referenced project's `pyproject.toml`.\nThe extracted dependency version will be applied to the generated archive using the strategy specified in the `version-pinning-strategy`\nconfiguration. By referencing pinned version dependencies in published archive files, package consumers may more easily depend on\nand install packages that are built within complex monorepos, without needing to replicate the exact folder structure utilized within\nthe monorepo for that project's dependencies.\n\nFor example, assume that `spam` and `ham` Poetry projects exist within the same monorepo and use the following `pyproject.toml`\nconfigurations.\n\n`spam/pyproject.toml`:\n```toml\n[tool.poetry]\nname = \"spam\"\nversion = \"0.1.0\"\n\n[tool.poetry.dependencies]\nham = {path = \"../ham\", develop = true}\n```\n\n`ham/pyproject.toml`:\n```\n[tool.poetry]\nname = \"ham\"\nversion = \"1.2.3\"\n```\nWhen generating `wheel` or `sdist` archives for the `spam` project through Poetry's [build][poetry-build] or \n[publish][poetry-publish] commands, the corresponding `spam` package will be constructed as if its dependency on the\n`ham` project were declared as `ham = \"1.2.3\"`. As a result, package metadata in archives for `spam` will shift from\n`Requires-Dist: ham @ ../ham` to `Requires-Dist: ham (==1.2.3)`\n\nAdditionally, to address [path dependencies](https://python-poetry.org/docs/dependency-specification/#path-dependencies) not being portable, this plugin provides\nthe ability to extend Poetry's [export][poetry-export] command using the `export-without-path-deps` command. This command will exclude path dependencies from being written to intermediate `requirements.txt` export. When installing the exported \n`requirements.txt` on another machine and/or Docker container local Paths dependencies can not be resolved and therefore can not \nbe installed so they are removed. \n\n### Command line mode\n\nIf you need greater control over when `poetry-monorepo-dependency-plugin` is activated, this plugin exposes new `build-rewrite-path-deps`\nand `publish-rewrite-path-deps` Poetry commands for on-demand execution. For example, it may be desirable to only use this\nplugin during CI to support a monorepo's artifact deployment and/or release process. When these custom Poetry commands are invoked, \nany configuration defined in the project's `pyproject.toml` `[tool.poetry-monorepo-dependency-plugin]` section is ignored and all options\n(other than `enable`) are exposed as command line options. For example:\n```commandline\npoetry build-rewrite-path-deps --version-pinning-strategy=semver\n```\n\nTo generate a `requirements.txt` without path dependencies use the `export-without-path-deps`. For example:\n```commandline\npoetry export-without-path-deps -f requirements.txt --output requirements.txt\n```\n\n### Configuration\n\nThe following configuration options are supported within your project's `pyproject.toml` configuration:\n\n* `[tool.poetry-monorepo-dependency-plugin]`: Parent-level container for plugin\n * `enable` (`boolean`, default: `false`): Since Poetry plugins are globally installed, this configuration allows projects\nto opt-in to this plugin's modifications of the archives built and/or published Poetry\n * `version-pinning-strategy` (`string`, default: `mixed`, options: `mixed`, `semver`, `exact`): Strategy by which path \ndependencies to other Poetry projects will be versioned in generated archives. Given a path dependency to a Poetry project \nwith version `1.2.3`, the version of the dependency referenced in the generated archive is `^1.2.3` for \n`semver` and `=1.2.3` for `exact`. `mixed` mode switches versioning strategies based on whether the dependency\nPoetry project version is an in-flight development version or a release - if a development version (i.e. `1.2.3.dev456`), \na variant of `semver` is used that applies an upper-bound of the next patch version (i.e. `>=1.2.3.dev,<1.2.4`), and \nif a release version (i.e. `1.2.3`), `exact` is applied (i.e. `=1.2.3`).\n \n## Licence\n\n`poetry-monorepo-dependency-plugin` is available under the [MIT licence][mit_licence].\n\n## Releasing to PyPI\n\nReleasing `poetry-monorepo-dependency-plugin` relies on the [maven-release-plugin](https://maven.apache.org/maven-release/maven-release-plugin/)\nto automate manual release activities and [Habushu](https://bitbucket.org/cpointe/habushu/) to automate the execution of a\nPoetry-based DevOps workflow via a custom Maven lifecycle. During Maven's `deploy` phase, the appropriate plugin packages\nwill be published to PyPI. \n\nA [PyPI account](https://pypi.org/account/register/) with access to the [poetry-monorepo-dependency-plugin](https://pypi.org/project/poetry-monorepo-dependency-plugin/) \nproject is required. PyPI account credentials should be specified in your `settings.xml` under the `<id>pypi</id>` `<server>` entry:\n\n```xml\n<settings>\n <servers>\n <server>\n <id>pypi</id>\n <username>pypi-username</username>\n <password>{encrypted-pypi-password}</password>\n </server>\n </servers>\n</settings>\n```\nExecute `mvn release:clean release:prepare`, answer the prompts for the versions and tags, and execute `mvn release:perform` to publish\nthe package to PyPI. \n\n[poetry]: https://python-poetry.org/\n[poetry-build]: https://python-poetry.org/docs/cli/#build\n[poetry-export]: https://python-poetry.org/docs/cli/#export\n[poetry-publish]: https://python-poetry.org/docs/cli/#publish\n[mit_licence]: http://dan.mit-license.org/",
"bugtrack_url": null,
"license": "MIT",
"summary": "Poetry plugin that generates more easily consumable archives for projects in a monorepo structure with path dependencies on other Poetry projects",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/TechnologyBrewery/poetry-monorepo-dependency-plugin",
"Repository": "https://github.com/TechnologyBrewery/poetry-monorepo-dependency-plugin"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "88d5de0f074c7c1c93de9efe0f5607fc237b0583763de8764ba17ee62be9c976",
"md5": "ba87393f7a629685192231eb83af159b",
"sha256": "0401c9895c9264fb3cfffb87db2507c1272b23fe4747a6c4491e40d12998dd77"
},
"downloads": -1,
"filename": "poetry_monorepo_dependency_plugin-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba87393f7a629685192231eb83af159b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 9205,
"upload_time": "2024-03-14T18:51:34",
"upload_time_iso_8601": "2024-03-14T18:51:34.112859Z",
"url": "https://files.pythonhosted.org/packages/88/d5/de0f074c7c1c93de9efe0f5607fc237b0583763de8764ba17ee62be9c976/poetry_monorepo_dependency_plugin-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "71a3ce8f65af9a63647be620501f2b986c659d793099bb0f0cfb3d7ab58929aa",
"md5": "ee5e1c769173ce3e5c97834f1b06753c",
"sha256": "39d7667526a947eaf29ce625e903f1af99d758fb7ca90c088f3c47c42c18342d"
},
"downloads": -1,
"filename": "poetry_monorepo_dependency_plugin-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "ee5e1c769173ce3e5c97834f1b06753c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 8645,
"upload_time": "2024-03-14T18:51:35",
"upload_time_iso_8601": "2024-03-14T18:51:35.929294Z",
"url": "https://files.pythonhosted.org/packages/71/a3/ce8f65af9a63647be620501f2b986c659d793099bb0f0cfb3d7ab58929aa/poetry_monorepo_dependency_plugin-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-14 18:51:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TechnologyBrewery",
"github_project": "poetry-monorepo-dependency-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "poetry-monorepo-dependency-plugin"
}
JSON
