Registry Explorer

hatch.registry_explorer

Utilities for exploring a Hatch package registry.

This module provides functions to search and extract information from a Hatch registry data structure (see hatch_all_pkg_metadata_schema.json).

Functions

find_package(registry, package_name, repo_name=None)

Find a package by name, optionally within a specific repository.

Parameters:

Name	Type	Description	Default
registry	Dict[str, Any]	The registry data.	required
package_name	str	Name of the package to find.	required
repo_name	str	Name of the repository to search in. Defaults to None.	None

Returns:

Type	Description
Optional[Dict[str, Any]]	Optional[Dict[str, Any]]: Package data if found, None otherwise.

Source code in hatch/registry_explorer.py

def find_package(
    registry: Dict[str, Any], package_name: str, repo_name: Optional[str] = None
) -> Optional[Dict[str, Any]]:
    """Find a package by name, optionally within a specific repository.

    Args:
        registry (Dict[str, Any]): The registry data.
        package_name (str): Name of the package to find.
        repo_name (str, optional): Name of the repository to search in. Defaults to None.

    Returns:
        Optional[Dict[str, Any]]: Package data if found, None otherwise.
    """
    repos = registry.get("repositories", [])
    if repo_name:
        repos = [r for r in repos if r.get("name") == repo_name]
    for repo in repos:
        for pkg in repo.get("packages", []):
            if pkg.get("name") == package_name:
                return pkg
    return None

find_package_version(pkg, version_constraint=None)

Find a version dict for a package, optionally matching a version constraint.

This function uses a multi-step approach to find the appropriate version: 1. If no constraint is given, it returns the latest version 2. If that's not found, it falls back to the highest version number 3. For specific constraints, it sorts versions and checks compatibility

Parameters:

Name	Type	Description	Default
pkg	Dict[str, Any]	The package dictionary.	required
version_constraint	str	A version constraint string (e.g., '>=1.2.0'). Defaults to None.	None

Returns:

Type	Description
Optional[Dict[str, Any]]	Optional[Dict[str, Any]]: The version dict matching the constraint or latest version.

Source code in hatch/registry_explorer.py

def find_package_version(
    pkg: Dict[str, Any], version_constraint: Optional[str] = None
) -> Optional[Dict[str, Any]]:
    """Find a version dict for a package, optionally matching a version constraint.

    This function uses a multi-step approach to find the appropriate version:
    1. If no constraint is given, it returns the latest version
    2. If that's not found, it falls back to the highest version number
    3. For specific constraints, it sorts versions and checks compatibility

    Args:
        pkg (Dict[str, Any]): The package dictionary.
        version_constraint (str, optional): A version constraint string (e.g., '>=1.2.0'). Defaults to None.

    Returns:
        Optional[Dict[str, Any]]: The version dict matching the constraint or latest version.
    """
    versions = pkg.get("versions", [])
    if not versions:
        return None
    if not version_constraint:
        # Return the version dict matching latest_version
        latest = pkg.get("latest_version")
        for v in versions:
            if v.get("version") == latest:
                return v
        # fallback: return the highest version
        try:
            return max(versions, key=lambda x: Version(x.get("version", "0")))
        except Exception:
            return versions[-1]  # Try to find a version matching the constraint
    try:
        sorted_versions = sorted(
            versions, key=lambda x: Version(x.get("version", "0")), reverse=True
        )
    except Exception:
        sorted_versions = versions

    # If no exact match, try parsing as a constraint
    for v in sorted_versions:
        if _match_version_constraint(v.get("version", ""), version_constraint):
            return v
    return None

find_repository(registry, repo_name)

Find a repository by name.

Parameters:

Name	Type	Description	Default
registry	Dict[str, Any]	The registry data.	required
repo_name	str	Name of the repository to find.	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Optional[Dict[str, Any]]: Repository data if found, None otherwise.

Source code in hatch/registry_explorer.py

def find_repository(
    registry: Dict[str, Any], repo_name: str
) -> Optional[Dict[str, Any]]:
    """Find a repository by name.

    Args:
        registry (Dict[str, Any]): The registry data.
        repo_name (str): Name of the repository to find.

    Returns:
        Optional[Dict[str, Any]]: Repository data if found, None otherwise.
    """
    for repo in registry.get("repositories", []):
        if repo.get("name") == repo_name:
            return repo
    return None

get_latest_version(pkg)

Get the latest version string for a package dict.

Parameters:

Name	Type	Description	Default
pkg	Dict[str, Any]	The package dictionary.	required

Returns:

Type	Description
Optional[str]	Optional[str]: Latest version string if available, None otherwise.

Source code in hatch/registry_explorer.py

def get_latest_version(pkg: Dict[str, Any]) -> Optional[str]:
    """Get the latest version string for a package dict.

    Args:
        pkg (Dict[str, Any]): The package dictionary.

    Returns:
        Optional[str]: Latest version string if available, None otherwise.
    """
    return pkg.get("latest_version")

get_package_release_url(pkg, version_constraint=None)

Get the release URI for a package version matching the constraint (or latest).

Parameters:

Name	Type	Description	Default
pkg	Dict[str, Any]	The package dictionary.	required
version_constraint	str	A version constraint string (e.g., '>=1.2.0'). Defaults to None.	None

Returns:

Type	Description
Tuple[Optional[str], Optional[str]]	Tuple[Optional[str], Optional[str]]: A tuple containing: - str: The release URI satisfying the constraint (or None) - str: The matching version string (or None)

Source code in hatch/registry_explorer.py

def get_package_release_url(
    pkg: Dict[str, Any], version_constraint: Optional[str] = None
) -> Tuple[Optional[str], Optional[str]]:
    """Get the release URI for a package version matching the constraint (or latest).

    Args:
        pkg (Dict[str, Any]): The package dictionary.
        version_constraint (str, optional): A version constraint string (e.g., '>=1.2.0'). Defaults to None.

    Returns:
        Tuple[Optional[str], Optional[str]]: A tuple containing:
            - str: The release URI satisfying the constraint (or None)
            - str: The matching version string (or None)
    """
    if pkg is None:
        return None, None

    vdict = find_package_version(pkg, version_constraint)
    if vdict:
        return vdict.get("release_uri"), vdict.get("version")
    return None, None

list_packages(registry, repo_name=None)

List all package names, optionally within a specific repository.

Parameters:

Name	Type	Description	Default
registry	Dict[str, Any]	The registry data.	required
repo_name	str	Name of the repository to list packages from. Defaults to None.	None

Returns:

Type	Description
List[str]	List[str]: List of package names.

Source code in hatch/registry_explorer.py

def list_packages(
    registry: Dict[str, Any], repo_name: Optional[str] = None
) -> List[str]:
    """List all package names, optionally within a specific repository.

    Args:
        registry (Dict[str, Any]): The registry data.
        repo_name (str, optional): Name of the repository to list packages from. Defaults to None.

    Returns:
        List[str]: List of package names.
    """
    packages = []
    repos = registry.get("repositories", [])
    if repo_name:
        repos = [r for r in repos if r.get("name") == repo_name]
    for repo in repos:
        for pkg in repo.get("packages", []):
            packages.append(pkg.get("name"))
    return packages

list_repositories(registry)

List all repository names in the registry.

Parameters:

Name	Type	Description	Default
registry	Dict[str, Any]	The registry data.	required

Returns:

Type	Description
List[str]	List[str]: List of repository names.

Source code in hatch/registry_explorer.py

def list_repositories(registry: Dict[str, Any]) -> List[str]:
    """List all repository names in the registry.

    Args:
        registry (Dict[str, Any]): The registry data.

    Returns:
        List[str]: List of repository names.
    """
    return [repo.get("name") for repo in registry.get("repositories", [])]