From .in requirement files generate and fix .lock and .unlock files
* Python 3.9 through 3.13, PyPy
new in 0.2.x
compatible release operator support; arbitrary equality issue UnResolvable; add logging-strict and pytest-logging-strict support;
new in 0.1.x
fork portion of drain-swamp;
Fix the requirements/constraint files and there would be little or no need to fix venvs
wreck is a homophone (same or similar pronunciation) of req,
abbreviated form of requirement. The past tense of wreck is either
wrecked or rekt; depending on how old you are.
Generates both lock and unlock requirement files. Fixes both! Minimizing the likelihood of dependency conflicts
Focus is on the requirements and constraints files, venv aware, but not dependent on venv. Not a venv manager.
Caters to authors of apps (lock) and packages (lock and unlock).
GIL and multithreading UX aside, resolving dependency conflicts is the next most frustrating issue facing Python coders
Often don't consider there will be multiple venv, not always just one. So all requirements don't apply to all venv
Configuration read from pyproject.toml. There is one section per venv. Then run one cli command per venv.
Unlike other packages, per .in file, produces two files: .unlock and .lock
For a particular venv, fixes all requirement files, rather than one file at a time
The needs of an app and a package author cannot be solved by a tool that caters only towards app authors
For dependency conflicts, that can't be automagically resolved, falls into these categories:
unresolvable
pip<24.2andpip>=24.2is unresolvable.One possible solution is to split requirements into multiple venv
shared between multiple venv
Ideally, code is kept DRY (don't repeat yourself) as pragmatic. This applies equally to requirements and constraints.
.shared.inconstraints are included into many venv, special care must be taken.wreckdeals with fixing requirements and constraints which apply to one venv at a time. When applies to multiple venv,wrecksupports this, but can't fix conflicts.
In pyproject.toml, for each venv, add a [[tool.venv]] section.
[[tool.venvs]]
venv_base_path = '.venv'
reqs = [
'requirements/dev',
'requirements/kit',
'requirements/pip',
'requirements/pip-tools',
'requirements/prod.shared',
'requirements/manage',
'requirements/mypy',
'requirements/tox',
]
[[tool.venvs]]
venv_base_path = '.doc/.venv'
reqs = [
'docs/requirements',
'docs/pip-tools',
]
These are top most level requirement files without last suffix.
The additional requirements are for use by tox and CI/CD workflows.
- use posix relative paths
- assumed the venv are within the package base folder
- requirements and constraints files are not required to be in a subfolder, however it's highly encouraged
Possible corresponding dependency section
[tool.setuptools.dynamic]
dependencies = { file = ['requirements/prod.shared.unlock'] }
optional-dependencies.pip = { file = ['requirements/pip.lock'] }
optional-dependencies.pip_tools = { file = ['requirements/pip-tools.lock'] }
optional-dependencies.dev = { file = ['requirements/dev.lock'] }
optional-dependencies.manage = { file = ['requirements/manage.lock'] }
optional-dependencies.docs = { file = ['docs/requirements.lock'] }
Dependencies last suffix is .unlock
Possible corresponding dependency section
[tool.setuptools.dynamic]
dependencies = { file = ['requirements/prod.shared.lock'] }
optional-dependencies.pip = { file = ['requirements/pip.lock'] }
optional-dependencies.pip_tools = { file = ['requirements/pip-tools.lock'] }
optional-dependencies.dev = { file = ['requirements/dev.lock'] }
optional-dependencies.manage = { file = ['requirements/manage.lock'] }
optional-dependencies.docs = { file = ['docs/requirements.lock'] }
Dependencies last suffix is .lock
req fix --venv-relpath='.venv'
req fix --venv-relpath='.doc/.venv'Provide path to the pyproject.toml if different location from cwd.
Either the absolute path to the base folder or the file.
req fix --venv-relpath='.venv' --path=~/parent_folder/package_base_folder
req fix --venv-relpath='.venv' --path=~/parent_folder/package_base_folder/pyproject.toml--venv-relpath does not support absolute path
reqs fix options
| cli | default | description |
|---|---|---|
| -p/--path | cwd | absolute path to package base folder |
| -v/--venv-relpath | None | venv relative path. None implies all venv use the same python interpreter version |
| -t/--timeout | 15 | Web connection time in seconds |
| --show-unresolvables | True | For each venv, in a table print the unresolvable dependency conflicts |
| --show-fixed | True | For each venv, in a table print fixed issues |
| --show-resolvable-shared | True | For each venv in a table print resolvable issues that involve .shared.in files |
0 -- Evidently sufficient effort put into unittesting. Job well done, beer on me!
1 -- Failures occurred. failed compiles report onto stderr
2 -- entrypoint incorrect usage
3 -- path given for config file reverse search cannot find a pyproject.toml file
4 -- pyproject.toml config file parse issue. Expecting [[tool.venvs]] sections
5 -- package pip-tools is required to lock package dependencies. Install it
6 -- Missing some .in files. Support file(s) not checked
7 -- venv base folder does not exist. Create it
8 -- expecting [[tool.venvs]] field reqs to be a sequence
9 -- No such venv found
10 -- timeout occurred. Check web connection
| file | description |
|---|---|
| requirements-*.in | might contain pins. Maybe either a requirement or a constraints file |
| requirements-*.txt | output file consumable by pip |
Difference between requirements and constraints
- constraints files cannot have lines with
-e - constraints files cannot have lines with extras e.g.
coverage[toml] - If needed, constraints are applied
The requirements- prefix is noisy, provides no useful info, ugly.
It's use is discouraged.
| file | description |
|---|---|
| *.in | raw requirement or contraints file |
| *.shared.in | constraints file could be shared by more than one venv |
| *.lock | locked requirement file |
| *.unlock | unlocked requirement file |
There is also *.shared.lock and *.shared.unlock
Document issues in the respective *.in and *.shared.in file. Every
undocumented pin is bad UX.
The fixes of each dependency conflict issue should be separated into
a pins-*[.shared].in file.
e.g. pins-ccfi.in or pins-myst-parser.in
When the crisis is over. Removed these files along with any links to them.
| package | description |
|---|---|
| pip-compile-multi | sync multiple calls produces lock files |
| uv | A venv manager. Offers cli options to resolve conflicts |
| poetry | venv manager and build backend. Complex config within pyproject.toml |
| package | description |
|---|---|
| pip-tools | does not sync multiple calls |
| pip | present actionable info. Includes an ugly traceback |
| package | description |
|---|---|
| pyp2req | venv unaware. Fixes nothing.
Prints backend requires and top level dependencies to stdout
|
No package deals exclusively, effectively, and solely with requirements/constraint files. The top packages, which actual fixes dependency conflicts, are venv managers. Gives options to mitigate issues.
The top packages apply fixes to the venv, not the requirements/constraint files.
If the requirements/constraint files are fixed, there would be little or no need to fix venvs.
If anyone disagrees with these assessments of other packages, create an issue. Recommend a 1-2 line description
Any/all known shortcomings are tracked within CHANGES.rst section
Known regressions.
Accepted feature requests are tracked within CHANGES.rst section Feature request.
There should also be a cooresponding issue.
aGPLv3+
The short ramifications are:
- commercial/public entities must obtain a license waiver
Meaning pay to support the project and towards funding ongoing package maintainance.
- Do not change the copyright notice; that's serious IP theft.