<p align="center">
<a href="https://pypi.python.org/pypi/poetry-relax/" alt="Latest version">
<img alt="Latest version" src="https://img.shields.io/pypi/v/poetry-relax?style=flat-square">
</a>
<a href="https://devguide.python.org/versions/" alt="Supported Python versions">
<img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/poetry-relax?style=flat-square">
</a>
<a href="https://github.com/madkinsz/poetry-relax/actions/workflows/test.yaml?query=branch%3Amain" alt="Test status">
<img alt="Test status" src="https://img.shields.io/github/actions/workflow/status/madkinsz/poetry-relax/test.yaml?label=test&style=flat-square">
</a>
<a href="https://github.com/madkinsz/poetry-relax/actions/workflows/build.yaml?query=branch%3Amain" alt="Build status">
<img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/madkinsz/poetry-relax/build.yaml?label=build&style=flat-square">
</a>
</p>
# poetry-relax
A [Poetry](https://github.com/python-poetry/poetry) plugin to relax dependency versions when publishing libraries. Relax your project's dependencies from `foobar^2.0.0` to `foobar>=2.0.0`.
By default, Poetry uses caret constraints which would limit `foobar` versions to `<3.0`.
**poetry-relax** removes these upper version bounds, allowing dependencies to be upgraded.
Removing upper version bounds is important when publishing libraries.
When searching for versions of dependencies to install, the resolver (e.g. `pip`) must respect the bounds your library specifies.
When a new version of the dependency is released, consumers of your library _cannot_ install it unless a new version of your library is also released.
It is not feasible to release patches for every previous version of most libraries, which forces users to use the most recent version of the library or be stuck without the new version of the dependency.
When many libraries contain upper version bounds, the dependencies can easily become _unsolvable_ — where libraries have incompatible dependency version requirements.
By removing upper version bounds from your library, control is returned to the user.
Poetry's default behavior is to include upper version bounds. Many people have spoken up against this style of dependency management in the Python ecosystem, including members of the Python core development team. See [the bottom of the readme](#references) for links and additional context.
Since the Poetry project will not allow this behavior to be configured, maintainers have resorted to manual editing of dependency constraints after adding. **poetry-relax** aims to automate and simplify this process.
**poetry-relax** provides:
- Automated removal of upper bound constraints specified with `^`
- Safety check if package requirements are still solvable after relaxing constraints
- Upgrade of dependencies after relaxing constraints
- Update of the lock file without upgrading dependencies
- Limit dependency relaxation to specific dependency groups
- Retention of intentional upper bounds indicating true incompatibilities
- CLI messages designed to match Poetry's output
## Installation
The plugin must be installed in Poetry's environment. This requires use of the `self` subcommand.
```bash
$ poetry self add poetry-relax
```
## Usage
Relax constraints for which Poetry set an upper version:
```bash
$ poetry relax
```
Relax constraints and check that they are resolvable without performing upgrades:
```bash
$ poetry relax --check
```
Relax constraints and upgrade packages:
```bash
$ poetry relax --update
```
Relax constraints and update the lock file without upgrading packages:
```bash
$ poetry relax --lock
```
Preview the changes `poetry relax` would make without modifying the project:
```bash
$ poetry relax --dry-run
```
Relax constraints for specific dependency groups:
```bash
$ poetry relax --only foo --only bar
```
Relax constraints excluding specific dependency groups:
```bash
$ poetry relax --without foo --without bar
```
## Examples
The behavior of Poetry is quite reasonable for local development! `poetry relax` is most useful when used in CI/CD pipelines.
### Relaxing requirements before publishing
Run `poetry relax` before building and publishing a package.
See it at work in [the release workflow for this project](https://github.com/madkinsz/poetry-relax/blob/main/.github/workflows/release.yaml).
### Relaxing requirements for testing
Run `poetry relax --update` before tests to test against the newest possible versions of packages.
See it at work in [the test workflow for this project](https://github.com/madkinsz/poetry-relax/blob/main/.github/workflows/test.yaml).
## Frequently asked questions
> Can this plugin change the behavior of `poetry add` to relax constraints?
Not at this time. The Poetry project states that plugins must not alter the behavior of core Poetry commands. If this behavior would be useful for you, please chime in [on the tracking issue](https://github.com/madkinsz/poetry-relax/issues/5).
> Does this plugin remove upper constraints I've added?
This plugin will only relax constraints specified with a caret (`^`). Upper constraints added with `<` and `<=` will not be changed.
> Is this plugin stable?
This plugin is tested against multiple versions of Poetry and has an integration focused test suite. It is safe to use this in production, though it is recommend to pin versions. Breaking changes will be avoided unless infeasible due to upstream changes in Poetry. This project follows the semantic versioning scheme and breaking changes will be denoted by a change to the major version number.
> Will this plugin drop the upper bound on Python itself?
Believe it or not, this is an even more contentious subset of this issue as Poetry will not allow packages with no upper bound on Python to exist alongside those that include one. This basically means that we cannot relax this requirement without breaking the vast majority of use-cases. For this reason, we cannot relax `python^3` at this time. See [the post on the Poetry discussion board](https://github.com/python-poetry/poetry/discussions/3757#discussioncomment-435345) for more details.
## Contributing
This project is managed with Poetry. Here are the basics for getting started.
Clone the repository:
```bash
$ git clone https://github.com/madkinsz/poetry-relax.git
$ cd poetry-relax
```
Install packages:
```bash
$ poetry install
```
Run the test suite:
```bash
$ pytest tests
```
Run linters before opening pull requests:
```bash
$ ./scripts/lint check .
$ ./scripts/lint fix .
```
## References
There's a lot to read on this topic! It's contentious and causing a lot of problems for maintainers and users.
The following blog posts by Henry Schreiner are quite comprehensive:
- [Should You Use Upper Bound Version Constraints?](https://iscinumpy.dev/post/bound-version-constraints/)
- [Poetry Versions](https://iscinumpy.dev/post/poetry-versions/)
Content from some members of the Python core developer team:
- [Semantic Versioning Will Not Save You](https://hynek.me/articles/semver-will-not-save-you/)
- [Why I don't like SemVer anymore](https://snarky.ca/why-i-dont-like-semver/)
- [Version numbers: how to use them?](https://bernat.tech/posts/version-numbers/)
- [Versioning Software](https://caremad.io/posts/2016/02/versioning-software/)
Discussion and issues in the Poetry project:
- [Please stop pinning to major versions by default, especially for Python itself](https://github.com/python-poetry/poetry/issues/3747)
- [Change default dependency constraint from ^ to >=](https://github.com/python-poetry/poetry/issues/3427)
- [Developers should be able to turn off dependency upper-bound calculations](https://github.com/python-poetry/poetry/issues/2731)
Raw data
{
"_id": null,
"home_page": "https://github.com/madkinsz/poetry-relax",
"name": "poetry-relax",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "poetry,plugin,versioning,version",
"author": "Zanie",
"author_email": "contact@zanie.dev",
"download_url": "https://files.pythonhosted.org/packages/60/5a/f461d64beace6de04235ce0bb5c3145b973e3423e7db37a8646bcf90cd87/poetry_relax-1.1.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"https://pypi.python.org/pypi/poetry-relax/\" alt=\"Latest version\">\n <img alt=\"Latest version\" src=\"https://img.shields.io/pypi/v/poetry-relax?style=flat-square\">\n </a>\n <a href=\"https://devguide.python.org/versions/\" alt=\"Supported Python versions\">\n <img alt=\"Supported Python versions\" src=\"https://img.shields.io/pypi/pyversions/poetry-relax?style=flat-square\">\n </a>\n <a href=\"https://github.com/madkinsz/poetry-relax/actions/workflows/test.yaml?query=branch%3Amain\" alt=\"Test status\">\n <img alt=\"Test status\" src=\"https://img.shields.io/github/actions/workflow/status/madkinsz/poetry-relax/test.yaml?label=test&style=flat-square\">\n </a>\n <a href=\"https://github.com/madkinsz/poetry-relax/actions/workflows/build.yaml?query=branch%3Amain\" alt=\"Build status\">\n <img alt=\"Build status\" src=\"https://img.shields.io/github/actions/workflow/status/madkinsz/poetry-relax/build.yaml?label=build&style=flat-square\">\n </a>\n</p>\n\n# poetry-relax\n\nA [Poetry](https://github.com/python-poetry/poetry) plugin to relax dependency versions when publishing libraries. Relax your project's dependencies from `foobar^2.0.0` to `foobar>=2.0.0`.\n\nBy default, Poetry uses caret constraints which would limit `foobar` versions to `<3.0`.\n**poetry-relax** removes these upper version bounds, allowing dependencies to be upgraded.\n\nRemoving upper version bounds is important when publishing libraries.\nWhen searching for versions of dependencies to install, the resolver (e.g. `pip`) must respect the bounds your library specifies.\nWhen a new version of the dependency is released, consumers of your library _cannot_ install it unless a new version of your library is also released.\n\nIt is not feasible to release patches for every previous version of most libraries, which forces users to use the most recent version of the library or be stuck without the new version of the dependency.\nWhen many libraries contain upper version bounds, the dependencies can easily become _unsolvable_ \u2014 where libraries have incompatible dependency version requirements.\nBy removing upper version bounds from your library, control is returned to the user.\n\nPoetry's default behavior is to include upper version bounds. Many people have spoken up against this style of dependency management in the Python ecosystem, including members of the Python core development team. See [the bottom of the readme](#references) for links and additional context.\n\nSince the Poetry project will not allow this behavior to be configured, maintainers have resorted to manual editing of dependency constraints after adding. **poetry-relax** aims to automate and simplify this process.\n\n**poetry-relax** provides:\n- Automated removal of upper bound constraints specified with `^`\n- Safety check if package requirements are still solvable after relaxing constraints\n- Upgrade of dependencies after relaxing constraints\n- Update of the lock file without upgrading dependencies\n- Limit dependency relaxation to specific dependency groups\n- Retention of intentional upper bounds indicating true incompatibilities\n- CLI messages designed to match Poetry's output\n\n## Installation\n\nThe plugin must be installed in Poetry's environment. This requires use of the `self` subcommand.\n\n```bash\n$ poetry self add poetry-relax\n```\n\n## Usage\n\nRelax constraints for which Poetry set an upper version:\n\n```bash\n$ poetry relax\n```\n\nRelax constraints and check that they are resolvable without performing upgrades:\n\n```bash\n$ poetry relax --check\n```\n\nRelax constraints and upgrade packages:\n\n```bash\n$ poetry relax --update\n```\n\nRelax constraints and update the lock file without upgrading packages:\n\n```bash\n$ poetry relax --lock\n```\n\nPreview the changes `poetry relax` would make without modifying the project:\n\n```bash\n$ poetry relax --dry-run\n```\n\nRelax constraints for specific dependency groups:\n\n```bash\n$ poetry relax --only foo --only bar\n```\n\nRelax constraints excluding specific dependency groups:\n\n```bash\n$ poetry relax --without foo --without bar\n```\n\n\n## Examples\n\nThe behavior of Poetry is quite reasonable for local development! `poetry relax` is most useful when used in CI/CD pipelines.\n\n### Relaxing requirements before publishing\n\nRun `poetry relax` before building and publishing a package.\n\nSee it at work in [the release workflow for this project](https://github.com/madkinsz/poetry-relax/blob/main/.github/workflows/release.yaml).\n\n\n### Relaxing requirements for testing\n\nRun `poetry relax --update` before tests to test against the newest possible versions of packages.\n\nSee it at work in [the test workflow for this project](https://github.com/madkinsz/poetry-relax/blob/main/.github/workflows/test.yaml).\n\n## Frequently asked questions\n\n> Can this plugin change the behavior of `poetry add` to relax constraints?\n\nNot at this time. The Poetry project states that plugins must not alter the behavior of core Poetry commands. If this behavior would be useful for you, please chime in [on the tracking issue](https://github.com/madkinsz/poetry-relax/issues/5).\n\n> Does this plugin remove upper constraints I've added?\n\nThis plugin will only relax constraints specified with a caret (`^`). Upper constraints added with `<` and `<=` will not be changed.\n\n> Is this plugin stable?\n\nThis plugin is tested against multiple versions of Poetry and has an integration focused test suite. It is safe to use this in production, though it is recommend to pin versions. Breaking changes will be avoided unless infeasible due to upstream changes in Poetry. This project follows the semantic versioning scheme and breaking changes will be denoted by a change to the major version number.\n\n> Will this plugin drop the upper bound on Python itself?\n\nBelieve it or not, this is an even more contentious subset of this issue as Poetry will not allow packages with no upper bound on Python to exist alongside those that include one. This basically means that we cannot relax this requirement without breaking the vast majority of use-cases. For this reason, we cannot relax `python^3` at this time. See [the post on the Poetry discussion board](https://github.com/python-poetry/poetry/discussions/3757#discussioncomment-435345) for more details.\n\n## Contributing\n\nThis project is managed with Poetry. Here are the basics for getting started.\n\nClone the repository:\n```bash\n$ git clone https://github.com/madkinsz/poetry-relax.git\n$ cd poetry-relax\n```\n\nInstall packages:\n```bash\n$ poetry install\n```\n\nRun the test suite:\n```bash\n$ pytest tests\n```\n\nRun linters before opening pull requests:\n```bash\n$ ./scripts/lint check .\n$ ./scripts/lint fix .\n```\n\n## References\n\nThere's a lot to read on this topic! It's contentious and causing a lot of problems for maintainers and users.\n\nThe following blog posts by Henry Schreiner are quite comprehensive:\n- [Should You Use Upper Bound Version Constraints?](https://iscinumpy.dev/post/bound-version-constraints/)\n- [Poetry Versions](https://iscinumpy.dev/post/poetry-versions/)\n\nContent from some members of the Python core developer team:\n- [Semantic Versioning Will Not Save You](https://hynek.me/articles/semver-will-not-save-you/)\n- [Why I don't like SemVer anymore](https://snarky.ca/why-i-dont-like-semver/)\n- [Version numbers: how to use them?](https://bernat.tech/posts/version-numbers/)\n- [Versioning Software](https://caremad.io/posts/2016/02/versioning-software/)\n\nDiscussion and issues in the Poetry project:\n- [Please stop pinning to major versions by default, especially for Python itself](https://github.com/python-poetry/poetry/issues/3747)\n- [Change default dependency constraint from ^ to >=](https://github.com/python-poetry/poetry/issues/3427)\n- [Developers should be able to turn off dependency upper-bound calculations](https://github.com/python-poetry/poetry/issues/2731)\n",
"bugtrack_url": null,
"license": "",
"summary": "Plugin for Poetry to relax upper version pins",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/madkinsz/poetry-relax",
"Repository": "https://github.com/madkinsz/poetry-relax"
},
"split_keywords": [
"poetry",
"plugin",
"versioning",
"version"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e90dc8d9471e36ebf973e0c5ec69b23114a94a71e9515f79b69cc75ebb745b9b",
"md5": "034484c6c3ce83f4cccf1af391ae9a25",
"sha256": "35d0b3b58f533dd3482e7156aba358b21e3559affef2b5d93e209c9f842fd03c"
},
"downloads": -1,
"filename": "poetry_relax-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "034484c6c3ce83f4cccf1af391ae9a25",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 12593,
"upload_time": "2023-11-23T15:38:39",
"upload_time_iso_8601": "2023-11-23T15:38:39.589905Z",
"url": "https://files.pythonhosted.org/packages/e9/0d/c8d9471e36ebf973e0c5ec69b23114a94a71e9515f79b69cc75ebb745b9b/poetry_relax-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "605af461d64beace6de04235ce0bb5c3145b973e3423e7db37a8646bcf90cd87",
"md5": "0bd5c268e31c2c441bdd90089c453e0b",
"sha256": "8f341c1c62e5a1c02005c77e87f4224d28a6b8da5a66a98614db9e286e2b3bc7"
},
"downloads": -1,
"filename": "poetry_relax-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "0bd5c268e31c2c441bdd90089c453e0b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 13624,
"upload_time": "2023-11-23T15:38:41",
"upload_time_iso_8601": "2023-11-23T15:38:41.250665Z",
"url": "https://files.pythonhosted.org/packages/60/5a/f461d64beace6de04235ce0bb5c3145b973e3423e7db37a8646bcf90cd87/poetry_relax-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-23 15:38:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "madkinsz",
"github_project": "poetry-relax",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "poetry-relax"
}
JSON
