PyPI API¶

Functions for interacting with the PyPI stats API and PyPI JSON API.

Download Statistics¶

fetch_package_stats(
    package_name: str,
) -> PackageStats | None

Fetch download statistics for a package from PyPI.

Returns None if the package doesn't exist or the API is unreachable.

fetch_all_package_stats(
    packages: list[str],
    max_workers: int = DEFAULT_MAX_WORKERS,
) -> dict[str, PackageStats | None]

Fetch stats for multiple packages in parallel.

Parameters:

Name	Type	Description	Default
`packages`	`list[str]`	List of package names to fetch.	required
`max_workers`	`int`	Maximum number of parallel API requests.	`DEFAULT_MAX_WORKERS`

Returns:

Type	Description
`dict[str, PackageStats \| None]`	Dict mapping package names to their stats (or None if fetch failed).

fetch_python_versions(
    package_name: str,
) -> list[CategoryDownloads] | None

Fetch download breakdown by Python version for a package.

Returns None if the package doesn't exist or the API is unreachable.

fetch_os_stats(
    package_name: str,
) -> list[CategoryDownloads] | None

Fetch download breakdown by operating system for a package.

Returns None if the package doesn't exist or the API is unreachable.

aggregate_env_stats(
    packages: list[str],
    max_workers: int = DEFAULT_MAX_WORKERS,
) -> EnvSummary

Aggregate Python version and OS distribution across all packages.

Uses parallel fetching for improved performance.

Parameters:

Name	Type	Description	Default
`packages`	`list[str]`	List of package names to aggregate.	required
`max_workers`	`int`	Maximum number of parallel API requests.	`DEFAULT_MAX_WORKERS`

Returns:

Type	Description
`EnvSummary`	Dict with 'python_versions' and 'os_distribution' lists of (name, count) tuples.

fetch_pypi_releases(
    package_name: str,
) -> list[PyPIRelease] | None

Fetch release history from the PyPI JSON API.

Parameters:

Name	Type	Description	Default
`package_name`	`str`	Name of the package.	required

Returns:

Type	Description
`list[PyPIRelease] \| None`	List of releases sorted by upload date ascending,
`list[PyPIRelease] \| None`	or None if the API is unreachable.

check_package_exists(
    package_name: str,
) -> tuple[bool | None, str | None]

Check if a package exists on PyPI.

Uses a HEAD request to the PyPI Simple API for minimal overhead.

Parameters:

Name	Type	Description	Default
`package_name`	`str`	Name of the package to check.	required

Returns:

Type	Description
`bool \| None`	Tuple of (exists, error_message):
`str \| None`	(True, None) if package exists
`tuple[bool \| None, str \| None]`	(False, None) if package not found (404)
`tuple[bool \| None, str \| None]`	(None, error_message) on network or other errors

fetch_user_packages(username: str) -> list[str] | None

Fetch list of packages owned by a PyPI user.

Uses PyPI's XML-RPC API to get the user's packages.

Parameters:

Name	Type	Description	Default
`username`	`str`	PyPI username.	required

Returns:

Type	Description
`list[str] \| None`	List of package names owned by the user (may be empty),
`list[str] \| None`	or None if API error occurs.