{"id":16927564,"url":"https://github.com/zanieb/poetry-relax","last_synced_at":"2025-08-10T12:31:51.729Z","repository":{"id":59786459,"uuid":"536784944","full_name":"zanieb/poetry-relax","owner":"zanieb","description":"Poetry plugin to relax version pins","archived":false,"fork":false,"pushed_at":"2024-05-13T12:20:17.000Z","size":310,"stargazers_count":20,"open_issues_count":13,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-19T00:05:55.078Z","etag":null,"topics":["plugin","poetry-python","python","semantic-versioning","versioning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zanieb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"zanieb"}},"created_at":"2022-09-14T22:53:40.000Z","updated_at":"2024-05-19T00:05:55.078Z","dependencies_parsed_at":"2024-01-15T14:20:02.610Z","dependency_job_id":"25f5bfbe-32b1-47ba-af80-d7d42098aa6c","html_url":"https://github.com/zanieb/poetry-relax","commit_stats":null,"previous_names":["zanieb/poetry-relax","madkinsz/poetry-relax"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zanieb%2Fpoetry-relax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zanieb%2Fpoetry-relax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zanieb%2Fpoetry-relax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zanieb%2Fpoetry-relax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zanieb","download_url":"https://codeload.github.com/zanieb/poetry-relax/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229408791,"owners_count":18068479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["plugin","poetry-python","python","semantic-versioning","versioning"],"created_at":"2024-10-13T20:34:34.236Z","updated_at":"2024-12-12T15:36:47.752Z","avatar_url":"https://github.com/zanieb.png","language":"Python","funding_links":["https://github.com/sponsors/zanieb"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://pypi.python.org/pypi/poetry-relax/\" alt=\"Latest version\"\u003e\n        \u003cimg alt=\"Latest version\" src=\"https://img.shields.io/pypi/v/poetry-relax?style=flat-square\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://devguide.python.org/versions/\" alt=\"Supported Python versions\"\u003e\n        \u003cimg alt=\"Supported Python versions\" src=\"https://img.shields.io/pypi/pyversions/poetry-relax?style=flat-square\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/zanieb/poetry-relax/actions/workflows/test.yaml?query=branch%3Amain\" alt=\"Test status\"\u003e\n        \u003cimg alt=\"Test status\" src=\"https://img.shields.io/github/actions/workflow/status/zanieb/poetry-relax/test.yaml?label=test\u0026style=flat-square\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/zanieb/poetry-relax/actions/workflows/build.yaml?query=branch%3Amain\" alt=\"Build status\"\u003e\n        \u003cimg alt=\"Build status\" src=\"https://img.shields.io/github/actions/workflow/status/zanieb/poetry-relax/build.yaml?label=build\u0026style=flat-square\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\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\u003e=2.0.0`.\n\nBy default, Poetry uses caret constraints which would limit `foobar` versions to `\u003c3.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_ — 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/zanieb/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/zanieb/poetry-relax/blob/main/.github/workflows/test.yaml).\n\n## Frequently asked questions\n\n\u003e 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/zanieb/poetry-relax/issues/5).\n\n\u003e Does this plugin remove upper constraints I've added?\n\nThis plugin will only relax constraints specified with a caret (`^`). Upper constraints added with `\u003c` and `\u003c=` will not be changed.\n\n\u003e 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\u003e 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/zanieb/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 \u003e=](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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzanieb%2Fpoetry-relax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzanieb%2Fpoetry-relax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzanieb%2Fpoetry-relax/lists"}