# Poetry plugin to Pin Path dependencies
[](https://python-poetry.org/)
[](https://codecov.io/gh/gerbenoostra/poetry-plugin-mono-repo-deps)
A [**Poetry**](https://python-poetry.org/) plugin for Poetry mono repositories, that will replace path dependencies with named dependency specifications.
A mono repository contains multiple Python packages, which can depend on each other.
These are typically path dependencies with the `develop = true` attribute.
This allows for easy development and local running.
However, when the packages are published to a PyPi repo, these dependencies should be named dependencies.
By publishing the packages with named dependencies, one can easily install the packages and their dependencies.
This plugin will replace path dependencies (`name @ path`) with named dependency specifications (`name ~= version`).
By default, this is done when building artifacts ([`poetry build`](https://python-poetry.org/docs/main/cli/#build)) and exporting the locked dependency list ([`poetry export`](https://github.com/python-poetry/poetry-plugin-export)).
The plugin can however be configured to modify any other command registered by Poetry or other plugins.
## An example using build and export
Suppose you have a single folder with 2 Python packages, where one (`app-b`) depends on the other (`lib-a`).
The used library has the following in its Poetry section:
```{toml}
# repo/A/pyproject.toml
[tool.poetry]
name = "lib-a"
version = "0.0.1"
```
The application package depends on the previous library as follows:
```{toml}
# repo/B/pyproject.toml
[tool.poetry]
name = "app-B"
[tool.poetry.dependencies]
library-a = {path = "../A", develop=true}
```
### Poetry build
By default, building the above project with Poetry (`poetry build`), will result in a build artifact (`tar.gz`/`whl`) containing a path dependency in its metadata similar to:
```
Requires-Dist: lib-a @ file:///your/local/checkout/project/root/lib-a
```
This prevents sharing the build and reusing the build artifact on other systems, as it expects to find `lib-a` at that specific path.
Using this Mono-Repo-Deps plugin, the Poetry build will result in the following dependency:
```
Requires-Dist: lib-a (>=0.0.1,<0.1.0)
```
### Poetry export
By default, exporting the full dependency list (`poetry export`) results in a dependency list (`requirements.txt`) that also contain path dedendencies with full paths:
```
lib-a @ file:///your/local/checkout/project/root/lib-a
```
Again, by using this Mono-Repo-Deps plugin, these will become:
```
lib-a==0.1.0
```
## Installation
You can install the plugin as explained in the [Poetry documentation about plugin usage](https://python-poetry.org/docs/main/plugins/#using-plugins).
Which can be summarized as:
If you used PipX to install Poetry:
```
pipx inject poetry poetry-plugin-mono-repo-deps
```
If you used Pip to install Poetry:
```
pip install poetry-plugin-mono-repo-deps
```
On non-Windows devices, you can also use Poetry's `self add` which will also validate compatibility:
```shell
poetry self add poetry-plugin-mono-repo-deps
```
## Usage:
As plugins are installed systemwide, **this plugin is by default disabled** to not unintentionally modify the existing behavior of Poetry.
Enable the plugin by adding the following (empty) section to your `pyproject.toml`:
```{toml}
# repo/B/pyproject.toml
[tool.poetry-monorepo.deps]
```
This is equivalent to adding the following default settings:
```{toml}
[tool.poetry-monorepo.deps]
enabled = true
commands = ["build", "export"]
constraint = "~="
source_types = ["file", "directory"]
only_develop = false
```
Possible alternative values can be found in the following section:
## Configuration:
### `enabled`
**Type**: `boolean`
**Default**: `true`
**Allowed values**: `true`, `false`
Whether the plugin should be activated for commands on this project.
### `commands`
**Type**: `List[string]`
**Default**: `["build", "export"]`
**Allowed values**: Any CLI command registered with Poetry (could also be provided by other plugins).
The intercepted poetry commands.
The plugin will intercept the command and update the internal representation of dependencies, changing the path dependencies to named dependency specifications.
### `constraint`
**Type**: `string`
**Default**: `~=`
**Allowed values**: `==`, `>=` , `~=` , `^` (All [valid Poetry version constraints](https://python-poetry.org/docs/dependency-specification/)).
The version constraint that is applied to the current version of the dependency.
For example, when the dependency has version `0.0.1`, and the default constraint string `~=` is used, it will result in a named dependency with version `>=0.1.0, <0.1.0`.
### `source_types`
**Type**: `List[string]`
**Default**: `["file", "directory"]` (local Path dependencies)
**Allowed values**: `["file", "directory", "url", "git"]`. (Any `source_type` attribute of Poetry's internal Dependency object, which includes the lowercase VCS identifier, like `git`).
The type of dependencies that should be replaced with their named version specification.
### `only_develop`
**Type**: `boolean`
**Default**: `false`
Enable to only replace `develop` dependencies, which, as currently implemented in Poetry, are only `directory` [Path dependencies](https://python-poetry.org/docs/main/dependency-specification/#path-dependencies).
This filter is **only applied to directory path** dependencies, as only those can have the `develop` mark.
If you configure `source_types` to be any Path dependency (ie. `file` or `directory`), all file path dependencies will be translated, while only the directory dependencies annotated with `develop = true` will be translated.
## Caveats
Currently, the plugin has only been verified to work with the `poetry build` and `poetry export` commands.
Though theoretically it should work with any other (plugin's) command, your mileage may vary.
## How it works
If enabled, this plugin registers itself to run before specific commands.
When these commands are run, it will modify the internal lock file representation that Poetry uses, replacing the path dependency objects with regular dependencies.
The idea came from the [Python Poetry Monorepo without Limitations](https://gerben-oostra.medium.com/python-poetry-mono-repo-without-limitations-dd63b47dc6b8) blog post on Medium, which describes how a simple script can modify the `pyproject.toml` before a build step, resulting in named dependencies in the build artifacts.
This plugin only temporarily modifies the structure, in memory, just for the command you run it on.
## Contributing
We recommend using PyEnv to select the right Python version:
```
pyenv local && poetry env use $(which python)
make venv
```
We use [pre-commit](https://pre-commit.com/), which most recent version requires Python >=3.9, while this project aims to work on Python >=3.8.
Therefore install pre-commit on your system yourself (using Homebrew / PipX)
Tests can be run with `make test`, linting with `make lint`
## License
This project is licensed under the terms of the MIT open-source license. Please refer to [MIT](https://github.com/gerbenoostra/poetry-plugin-mono-repo-deps/blob/HEAD/LICENSE) for the full terms.
Raw data
{
"_id": null,
"home_page": "https://github.com/gerbenoostra/poetry-plugin-mono-repo-deps",
"name": "poetry-plugin-mono-repo-deps",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "packaging, poetry",
"author": "Gerben Oostra",
"author_email": "ynnx1wmd@duck.com",
"download_url": "https://files.pythonhosted.org/packages/a6/d0/daebe320e736a382e8dc86e612f3011b4de3476fc88a8823c79640da3340/poetry_plugin_mono_repo_deps-0.2.1.tar.gz",
"platform": null,
"description": "# Poetry plugin to Pin Path dependencies\n\n[](https://python-poetry.org/)\n[](https://codecov.io/gh/gerbenoostra/poetry-plugin-mono-repo-deps)\n\nA [**Poetry**](https://python-poetry.org/) plugin for Poetry mono repositories, that will replace path dependencies with named dependency specifications.\n\nA mono repository contains multiple Python packages, which can depend on each other.\nThese are typically path dependencies with the `develop = true` attribute.\nThis allows for easy development and local running.\nHowever, when the packages are published to a PyPi repo, these dependencies should be named dependencies.\nBy publishing the packages with named dependencies, one can easily install the packages and their dependencies.\n\nThis plugin will replace path dependencies (`name @ path`) with named dependency specifications (`name ~= version`).\nBy default, this is done when building artifacts ([`poetry build`](https://python-poetry.org/docs/main/cli/#build)) and exporting the locked dependency list ([`poetry export`](https://github.com/python-poetry/poetry-plugin-export)).\nThe plugin can however be configured to modify any other command registered by Poetry or other plugins.\n\n## An example using build and export\n\nSuppose you have a single folder with 2 Python packages, where one (`app-b`) depends on the other (`lib-a`).\n\nThe used library has the following in its Poetry section:\n\n```{toml}\n# repo/A/pyproject.toml\n[tool.poetry]\nname = \"lib-a\"\nversion = \"0.0.1\"\n```\n\nThe application package depends on the previous library as follows:\n\n```{toml}\n# repo/B/pyproject.toml\n[tool.poetry]\nname = \"app-B\"\n\n[tool.poetry.dependencies]\nlibrary-a = {path = \"../A\", develop=true}\n```\n\n### Poetry build\n\nBy default, building the above project with Poetry (`poetry build`), will result in a build artifact (`tar.gz`/`whl`) containing a path dependency in its metadata similar to:\n\n```\nRequires-Dist: lib-a @ file:///your/local/checkout/project/root/lib-a\n```\n\nThis prevents sharing the build and reusing the build artifact on other systems, as it expects to find `lib-a` at that specific path.\n\nUsing this Mono-Repo-Deps plugin, the Poetry build will result in the following dependency:\n\n```\nRequires-Dist: lib-a (>=0.0.1,<0.1.0)\n```\n\n### Poetry export\n\nBy default, exporting the full dependency list (`poetry export`) results in a dependency list (`requirements.txt`) that also contain path dedendencies with full paths:\n\n```\nlib-a @ file:///your/local/checkout/project/root/lib-a\n```\n\nAgain, by using this Mono-Repo-Deps plugin, these will become:\n\n```\nlib-a==0.1.0\n```\n\n## Installation\n\nYou can install the plugin as explained in the [Poetry documentation about plugin usage](https://python-poetry.org/docs/main/plugins/#using-plugins).\n\nWhich can be summarized as:\n\nIf you used PipX to install Poetry:\n\n```\npipx inject poetry poetry-plugin-mono-repo-deps\n```\n\nIf you used Pip to install Poetry:\n\n```\npip install poetry-plugin-mono-repo-deps\n```\n\nOn non-Windows devices, you can also use Poetry's `self add` which will also validate compatibility:\n\n```shell\npoetry self add poetry-plugin-mono-repo-deps\n```\n\n## Usage:\n\nAs plugins are installed systemwide, **this plugin is by default disabled** to not unintentionally modify the existing behavior of Poetry.\n\nEnable the plugin by adding the following (empty) section to your `pyproject.toml`:\n\n```{toml}\n# repo/B/pyproject.toml\n[tool.poetry-monorepo.deps]\n```\n\nThis is equivalent to adding the following default settings:\n\n```{toml}\n[tool.poetry-monorepo.deps]\nenabled = true\ncommands = [\"build\", \"export\"]\nconstraint = \"~=\"\nsource_types = [\"file\", \"directory\"]\nonly_develop = false\n```\n\nPossible alternative values can be found in the following section:\n\n## Configuration:\n\n### `enabled`\n\n**Type**: `boolean`\n\n**Default**: `true`\n\n**Allowed values**: `true`, `false`\n\nWhether the plugin should be activated for commands on this project.\n\n### `commands`\n\n**Type**: `List[string]`\n\n**Default**: `[\"build\", \"export\"]`\n\n**Allowed values**: Any CLI command registered with Poetry (could also be provided by other plugins).\n\nThe intercepted poetry commands.\nThe plugin will intercept the command and update the internal representation of dependencies, changing the path dependencies to named dependency specifications.\n\n### `constraint`\n\n**Type**: `string`\n\n**Default**: `~=`\n\n**Allowed values**: `==`, `>=` , `~=` , `^` (All [valid Poetry version constraints](https://python-poetry.org/docs/dependency-specification/)).\n\nThe version constraint that is applied to the current version of the dependency.\n\nFor example, when the dependency has version `0.0.1`, and the default constraint string `~=` is used, it will result in a named dependency with version `>=0.1.0, <0.1.0`.\n\n### `source_types`\n\n**Type**: `List[string]`\n\n**Default**: `[\"file\", \"directory\"]` (local Path dependencies)\n\n**Allowed values**: `[\"file\", \"directory\", \"url\", \"git\"]`. (Any `source_type` attribute of Poetry's internal Dependency object, which includes the lowercase VCS identifier, like `git`).\n\nThe type of dependencies that should be replaced with their named version specification.\n\n### `only_develop`\n\n**Type**: `boolean`\n\n**Default**: `false`\n\nEnable to only replace `develop` dependencies, which, as currently implemented in Poetry, are only `directory` [Path dependencies](https://python-poetry.org/docs/main/dependency-specification/#path-dependencies).\n\nThis filter is **only applied to directory path** dependencies, as only those can have the `develop` mark.\n\nIf you configure `source_types` to be any Path dependency (ie. `file` or `directory`), all file path dependencies will be translated, while only the directory dependencies annotated with `develop = true` will be translated.\n\n## Caveats\n\nCurrently, the plugin has only been verified to work with the `poetry build` and `poetry export` commands.\nThough theoretically it should work with any other (plugin's) command, your mileage may vary.\n\n## How it works\n\nIf enabled, this plugin registers itself to run before specific commands.\nWhen these commands are run, it will modify the internal lock file representation that Poetry uses, replacing the path dependency objects with regular dependencies.\n\nThe idea came from the [Python Poetry Monorepo without Limitations](https://gerben-oostra.medium.com/python-poetry-mono-repo-without-limitations-dd63b47dc6b8) blog post on Medium, which describes how a simple script can modify the `pyproject.toml` before a build step, resulting in named dependencies in the build artifacts.\nThis plugin only temporarily modifies the structure, in memory, just for the command you run it on.\n\n## Contributing\n\nWe recommend using PyEnv to select the right Python version:\n\n```\npyenv local && poetry env use $(which python)\nmake venv\n```\n\nWe use [pre-commit](https://pre-commit.com/), which most recent version requires Python >=3.9, while this project aims to work on Python >=3.8.\nTherefore install pre-commit on your system yourself (using Homebrew / PipX)\n\nTests can be run with `make test`, linting with `make lint`\n\n## License\n\nThis project is licensed under the terms of the MIT open-source license. Please refer to [MIT](https://github.com/gerbenoostra/poetry-plugin-mono-repo-deps/blob/HEAD/LICENSE) for the full terms.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Poetry plugin to replace path dependencies in mono repos with named dependency specifications at build time",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/gerbenoostra/poetry-plugin-mono-repo-deps",
"Repository": "https://github.com/gerbenoostra/poetry-plugin-mono-repo-deps"
},
"split_keywords": [
"packaging",
" poetry"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a4676ed58d9e52be5e14af1dac936cbd01d6963de5722c322db351b2c5172c04",
"md5": "dc64df259bcfd7b94ac67d37a69442bf",
"sha256": "26c319c248c14f346a30ff494c15bd878ffe8f528f64cf6dcd8a50a7852b1c88"
},
"downloads": -1,
"filename": "poetry_plugin_mono_repo_deps-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc64df259bcfd7b94ac67d37a69442bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 8536,
"upload_time": "2024-05-03T06:41:45",
"upload_time_iso_8601": "2024-05-03T06:41:45.552682Z",
"url": "https://files.pythonhosted.org/packages/a4/67/6ed58d9e52be5e14af1dac936cbd01d6963de5722c322db351b2c5172c04/poetry_plugin_mono_repo_deps-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a6d0daebe320e736a382e8dc86e612f3011b4de3476fc88a8823c79640da3340",
"md5": "3581c7e75b5a44ed15b838c3e3110927",
"sha256": "6bd55761a2ffe6632181950624fa88be977e62aa25d48971e8c6c57611311556"
},
"downloads": -1,
"filename": "poetry_plugin_mono_repo_deps-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "3581c7e75b5a44ed15b838c3e3110927",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 19055,
"upload_time": "2024-05-03T06:41:47",
"upload_time_iso_8601": "2024-05-03T06:41:47.206675Z",
"url": "https://files.pythonhosted.org/packages/a6/d0/daebe320e736a382e8dc86e612f3011b4de3476fc88a8823c79640da3340/poetry_plugin_mono_repo_deps-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-03 06:41:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gerbenoostra",
"github_project": "poetry-plugin-mono-repo-deps",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "poetry-plugin-mono-repo-deps"
}
JSON
