- Breaking changes in a minor release
If a user uses version pinning, then required dependencies requiring a different version will break.
So we use narrow ranges (downside is package gets outdated):
A broad range means too many versions to support:
Use Semantic Versioning#
- Major - Breaking / incompatible API change (reset other digits)
- Minor - Add functionality in a backwards compatible way. Bump minor version and reset patch.
- Patch - Security or bug fix that doesn’t break the API
Avoid API Churn#
You don’t want to force user’s of your API to change the way they use it
- Removing an API
- Renaming an API
- Changing the parmameters of an API
Setting your Requirements correctly#
install_requires uses a range and does not pin versions.
six>=1.11 is better than
If six uses semver, you could have done
Test supported versions#
Test your library with every supported python version and with earliest versions of all packages you depend on.
By default pip installs the latest versions of your dependencies
apache-beam: httplib2>=0.8,<=0.11.3 google-api-python-client: httplib2>=0.9.2, <1
pip install apache-beam google-api-python-client
In this case the installation is successful and version that is installed is the upper bound of the overlapping range.
It will install
pip install google-api-python-client apache-beam
Gives an error about incompatibilities
Pip resolves dependencies on a first come first serve basis
The order your dependencies are installed if you use requirements.txt are arbitrary
Help your users:
- Use semantic versioning
- Avoid API churn
- Support as large a version range as possible
- Support the latest version of your dependencies