Caution

This API is not finalized, and may change in a patch version.

unearth.finder#

The main class for the unearth package.

class unearth.finder.PackageFinder(session: Fetcher | None = None, *, index_urls: Iterable[str] = (), find_links: Iterable[str] = (), trusted_hosts: Iterable[str] = (), target_python: TargetPython | None = None, ignore_compatibility: bool = False, no_binary: Iterable[str] = (), only_binary: Iterable[str] = (), prefer_binary: Iterable[str] = (), respect_source_order: bool = False, verbosity: int = 0, exclude_newer_than: datetime | None = None)#

The main class for the unearth package.

Parameters:

  • session – The session to use for the finder. If not provided, a temporary session will be created.

  • index_urls – The index URLs to search for packages.

  • find_links – The links to search for packages.

  • trusted_hosts: – The trusted hosts.:

  • target_python – The links must match the target Python

  • ignore_compatibility – Whether to ignore the compatibility check

  • no_binary – The names of the packages to disallow wheels

  • only_binary – The names of the packages to disallow non-wheels

  • prefer_binary – The names of the packages to prefer binary distributions even if newer sdist pacakges exist.

  • respect_source_order – If True, packages from the source coming earlier are more preferred, even if they have lower versions.

  • verbosity – The verbosity level.

  • exclude_newer_than – A datetime that when provided, excludes any version newer than it.

Add a find links URL to the finder search scope.

Parameters:

url (str) – The find links URL to add.

add_index_url(url: str) → None#

Add an index URL to the finder search scope.

Parameters:

url (str) – The index URL to add.

build_evaluator(package_name: str, allow_yanked: bool = False) → Evaluator#

Build an evaluator for the given package name.

Parameters:

  • package_name – The desired package name

  • allow_yanked – Whether to allow yanked candidates.

Returns:

The evaluator for the given package name

Return type:

Evaluator

download_and_unpack(link: Link, location: str | pathlib.Path, download_dir: str | pathlib.Path | None = None, hashes: dict[str, list[str]] | None = None, download_reporter: DownloadReporter = <function noop_download_reporter>, unpack_reporter: UnpackReporter = <function noop_unpack_reporter>) → pathlib.Path#

Download and unpack the package at the given link.

If the link is a remote link, it will be downloaded to the download_dir. Then, if the link is a wheel, the path of wheel file will be returned, otherwise it will be unpacked to the destination. Specially, if the link refers to a local directory, the path will be returned directly, otherwise the unpacked source path will be returned. And if the link has a subdirectory fragment, the subdirectory will be returned.

Parameters:

  • link (Link) – The link to download

  • location – The destination directory

  • download_dir – The directory to download to, or None to use a temporary directory created by unearth.

  • hashes (dict[str, list[str]]|None) – The optional hash dict for validation.

  • download_reporter (DownloadReporter) – The download reporter for progress reporting. By default, it does nothing.

  • unpack_reporter (UnpackReporter) – The unpack reporter for progress reporting. By default, it does nothing.

Returns:

The path to the installable file or directory.

find_all_packages(package_name: str, allow_yanked: bool = False, hashes: dict[str, list[str]] | None = None) → Sequence[Package]#

Find all packages with the given package name, best match first.

Parameters:

  • package_name (str) – The desired package name

  • allow_yanked (bool) – Whether to allow yanked candidates.

  • hashes (dict[str, list[str]]|None) – The hashes to filter on.

Returns:

The packages list sorted by best match

Return type:

Sequence[Package]

find_best_match(requirement: Requirement | str, allow_yanked: bool | None = None, allow_prereleases: bool | None = None, hashes: dict[str, list[str]] | None = None) → BestMatch#

Find the best match for the given requirement.

Parameters:

  • requirement – A packaging.requirements.Requirement instance or a string to construct it.

  • allow_yanked (bool|None) – Whether to allow yanked candidates, or None to infer from the specifier.

  • allow_prereleases (bool|None) – Whether to allow prereleases, or None to infer from the specifier.

  • hashes (dict[str, list[str]]|None) – The hashes to filter on.

Returns:

The best match

Return type:

BestMatch

find_matches(requirement: Requirement | str, allow_yanked: bool | None = None, allow_prereleases: bool | None = None, hashes: dict[str, list[str]] | None = None) → Sequence[Package]#

Find all packages matching the given requirement, best match first.

Parameters:

  • requirement – A packaging.requirements.Requirement instance or a string to construct it.

  • allow_yanked (bool|None) – Whether to allow yanked candidates, or None to infer from the specifier.

  • allow_prereleases (bool|None) – Whether to allow prereleases, or None to infer from the specifier.

  • hashes (dict[str, list[str]]|None) – The hashes to filter on.

Returns:

The packages sorted by best match

Return type:

Sequence[Package]

class unearth.finder.BestMatch(best: Package | None, applicable: Sequence[Package], candidates: Sequence[Package])#

The best match for a package.

applicable: Sequence[Package]#

The applicable packages, excluding those with unmatching versions.

best: Package | None#

The best matching package, or None if no match was found.

candidates: Sequence[Package]#

All candidates found for the requirement.