Requirement Specifications

The methods unearth.finder.PackageFinder.find_matches and unearth.finder.PackageFinder.find_best_match accept a requirements specification string or an instance of packaging.requirements.Requirement as the first argument.

The requirement string follows the specification of PEP 508. Here are some examples:

Named requirements

flask
werkzeug >= 1.0
click>=8,<9

The environment markers and extras, however, don’t play any role in the package finding, so they will be simply ignored.

URL requirements

You can specify a requirement with specific URL to the distribution file by including the URL in the requirement string, in the form of <name> @ <url>:

# A distribution archive for a package
pip @ https://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686
# A local path should be specified as a file:// URL
jinja2 @ file:///path/to/code/jinja2-2.10.zip
# It can even be a file:// URL to a local directory
pytz @ file:///path/to/code/pytz-2018.7

VCS requirements

Same as pip, unearth also supports requirements specified by VCS URLs. Like URL requirements, the VCS URL follows after the @ sign. The format is as follows:

<name> @ <vcs>+<url>[@ref]

where vcs can be one of git, hg, svn and bzr.

# A Git repository on the HEAD revision
django @ git+https://github.com/django/django.git
# A VCS repository specified by SSH URL and a specific ref.
pip @ git+git@github.com:pypa/pip.git@main
pip @ git+git@github.com:pypa/pip.git@22.0.3
pip @ svn+https://github.com/pypa/pip.git@123456
# A Git repository on the accurate commit id
flask @ git+https://github.com/pallets/flask.git@ca8e6217fe450435e024bcff3082d2a37445f7e1