Unearth Documentation#
A utility to fetch and download python packages
NOTICE This project is still in its early stage and the API may change before 1.0 release.
Why this project?#
This project exists as the last piece to complete the puzzle of a package manager. The other pieces are:
resolvelib - Resolves concrete dependencies from a set of (abstract) requirements.
unearth (This project) - Finds and downloads the best match(es) for a given requirement.
build - Builds wheels from the source code.
installer - Installs packages from wheels.
They provide all the low-level functionalities that are needed to resolve and install packages.
Why not pip?#
The core functionality is basically extracted from pip. However, pip is not designed to be used as a library and hence the API is not very stable.
Unearth serves as a stable replacement for pip’s PackageFinder
API. It will follow the conventions of Semantic Versioning so that downstream projects can use it to develop their own package finding and downloading.
Requirements#
unearth requires Python >=3.8
Installation#
$ python -m pip install --upgrade unearth
Quickstart#
Get the best matching candidate for a requirement:
>>> from unearth import PackageFinder
>>> finder = PackageFinder(index_urls=["https://pypi.org/simple/"])
>>> result = finder.find_best_match("flask>=2")
>>> result.best
Package(name='flask', version='2.1.2')
Using the CLI:
$ unearth "flask>=2"
{
"name": "flask",
"version": "3.0.0",
"link": {
"url": "https://files.pythonhosted.org/packages/36/42/015c23096649b908c809c69388a805a571a3bea44362fe87e33fc3afa01f/flask-3.0.0-py3-none-any.whl",
"comes_from": "https://pypi.org/simple/flask/",
"yank_reason": null,
"requires_python": ">=3.8",
"metadata": "https://files.pythonhosted.org/packages/36/42/015c23096649b908c809c69388a805a571a3bea44362fe87e33fc3afa01f/flask-3.0.0-py3-none-any.whl.metadata"
}
}