Unearth Package Fetcher

Warnings

• breaking Unearth dropped support for Python 3.8 in version 0.18.0. Earlier, Python 3.7 and below were dropped in version 0.17.2. Users on affected Python versions will encounter errors.
  Fix: Ensure your Python environment is 3.9 or newer. If you must use Python 3.8, pin `unearth<0.18.0`. For Python 3.7 or older, pin `unearth<0.17.2`.
• gotcha Handling of Git URLs, especially with branches and specific revisions, has been refined across several versions. A regression in earlier 0.18.x versions might have prevented correct parsing of Git URLs with branches.
  Fix: Always use the latest `unearth` version (0.18.2+) to ensure robust and correct parsing and fetching from Git URLs that include branches or specific commit references.
• gotcha Starting from version 0.17.0, `unearth` became more explicit with warnings related to parsing `.netrc` files. Users might see warnings if their `.netrc` is malformed, has incorrect permissions, or if authentication fails.
  Fix: Verify that your `.netrc` file is correctly formatted and has appropriate file permissions (e.g., `chmod 600 ~/.netrc`). Warnings were made less verbose in 0.17.1 and 0.17.2.

Install

• pip install unearth Install latest version

Imports

• Unearth

  from unearth import Unearth

Quickstart

This example demonstrates how to initialize `Unearth` and use it to find the best match for a Python package from PyPI, using a temporary cache directory.

import tempfile
from pathlib import Path
from unearth import Unearth

# Create a temporary directory for caching resolved packages
with tempfile.TemporaryDirectory() as cache_dir_str:
    cache_dir = Path(cache_dir_str)

    # Instantiate Unearth to search for packages on PyPI
    finder = Unearth(
        index_urls=["https://pypi.org/simple"],
        cache_dir=cache_dir
    )

    # Find matches for a specific package, e.g., 'requests'
    matches = finder.find_matches("requests")

    # Get the best matching distribution
    best_match = matches.best_match

    if best_match:
        print(f"Found best match: {best_match.name} {best_match.version} from {best_match.link.url}")
        # To actually download, you would process best_match.link.url
        # Unearth primarily provides the links, not direct download functionality
    else:
        print("No matches found for requests.")