High-Level API

class pypi_simple.PyPISimple(endpoint: str = 'https://pypi.org/simple/', auth: Optional[Any] = None, session: Optional[requests.sessions.Session] = None)[source]

A client for fetching package information from a Python simple package repository.

If necessary, login/authentication details for the repository can be specified at initialization by setting the auth parameter to either a (username, password) pair or another authentication object accepted by requests.

If more complicated session configuration is desired (e.g., setting up caching), the user must create & configure a requests.Session object appropriately and pass it to the constructor as the session parameter.

A PyPISimple instance can be used as a context manager that will automatically close its session on exit, regardless of where the session object came from.

Changed in version 0.8.0: Now usable as a context manager

Changed in version 0.5.0: session argument added

Changed in version 0.4.0: auth argument added

Parameters

  • endpoint (str) – The base URL of the simple API instance to query; defaults to the base URL for PyPI’s simple API

  • auth –

    Optional login/authentication details for the repository; either a (username, password) pair or another authentication object accepted by requests

  • session – Optional requests.Session object to use instead of creating a fresh one

get_index_page(timeout: Optional[Union[float, Tuple[float, float]]] = None) → pypi_simple.classes.IndexPage[source]

New in version 0.7.0.

Fetches the index/root page from the simple repository and returns an IndexPage instance.

Warning

PyPI’s project index file is very large and takes several seconds to parse. Use this method sparingly.

Parameters

timeout (Union[float, Tuple[float,float], None]) – optional timeout to pass to the requests call

Return type

IndexPage

Raises
stream_project_names(chunk_size: int = 65535, timeout: Optional[Union[float, Tuple[float, float]]] = None) → Iterator[str][source]

New in version 0.7.0.

Returns a generator of names of projects available in the repository. The names are not normalized.

Unlike get_index_page() and get_projects(), this function makes a streaming request to the server and parses the document in chunks. It is intended to be faster than the other methods, especially when the complete document is very large.

Warning

This function is rather experimental. It does not have full support for web encodings, encoding detection, or handling invalid HTML.

Parameters

  • chunk_size (int) – how many bytes to read from the response at a time

  • timeout (Union[float, Tuple[float,float], None]) – optional timeout to pass to the requests call

Return type

Iterator[str]

Raises
get_project_page(project: str, timeout: Optional[Union[float, Tuple[float, float]]] = None) → Optional[pypi_simple.classes.ProjectPage][source]

New in version 0.7.0.

Fetches the page for the given project from the simple repository and returns a ProjectPage instance. Returns None if the repository responds with a 404. All other HTTP errors cause a requests.HTTPError to be raised.

Parameters

  • project (str) – The name of the project to fetch information on. The name does not need to be normalized.

  • timeout (Union[float, Tuple[float,float], None]) – optional timeout to pass to the requests call

Return type

Optional[ProjectPage]

Raises
get_project_url(project: str) → str[source]

Returns the URL for the given project’s page in the repository.

Parameters

project (str) – The name of the project to build a URL for. The name does not need to be normalized.

Return type

str

get_projects() → Iterator[str][source]

Returns a generator of names of projects available in the repository. The names are not normalized.

Warning

PyPI’s project index file is very large and takes several seconds to parse. Use this method sparingly.

Deprecated since version 0.7.0: Use get_index_page() or stream_project_names() instead

Return type

Iterator[str]

Raises
get_project_files(project: str) → List[pypi_simple.classes.DistributionPackage][source]

Returns a list of DistributionPackage objects representing all of the package files available in the repository for the given project.

When fetching the project’s information from the repository, a 404 response is treated the same as an empty page, resulting in an empty list. All other HTTP errors cause a requests.HTTPError to be raised.

Deprecated since version 0.7.0: Use get_project_page() instead

Parameters

project (str) – The name of the project to fetch information on. The name does not need to be normalized.

Return type

List[DistributionPackage]

Raises
class pypi_simple.IndexPage(projects: List[str], repository_version: Optional[str], last_serial: Optional[str])[source]

New in version 0.7.0.

A parsed index/root page from a simple repository

property projects

The project names listed in the index. The names are not normalized.

property repository_version

The repository version reported by the page, or None if not specified

property last_serial

The value of the X-PyPI-Last-Serial response header returned when fetching the page, or None if not specified

class pypi_simple.ProjectPage(project: str, packages: List[pypi_simple.classes.DistributionPackage], repository_version: Optional[str], last_serial: Optional[str])[source]

New in version 0.7.0.

A parsed project page from a simple repository

property project

The name of the project the page is for

property packages

A list of packages (as DistributionPackage objects) listed on the project page

property repository_version

The repository version reported by the page, or None if not specified

property last_serial

The value of the X-PyPI-Last-Serial response header returned when fetching the page, or None if not specified

class pypi_simple.DistributionPackage(filename: str, url: str, project: Optional[str], version: Optional[str], package_type: Optional[str], requires_python: Optional[str], has_sig: Optional[bool], yanked: Optional[str], metadata_digests: Optional[Dict[str, str]])[source]

Information about a versioned archive file from which a Python project release can be installed

Changed in version 0.5.0: yanked attribute added

Changed in version 0.9.0: has_metadata, metadata_url, and metadata_digests attributes added

property filename

The basename of the package file

property url

The URL from which the package file can be downloaded

property project

The name of the project (as extracted from the filename), or None if the filename cannot be parsed

property version

The project version (as extracted from the filename), or None if the filename cannot be parsed

property package_type

The type of the package, or None if the filename cannot be parsed. The recognized package types are:

  • 'dumb'

  • 'egg'

  • 'msi'

  • 'rpm'

  • 'sdist'

  • 'wheel'

  • 'wininst'

property requires_python

An optional version specifier string declaring the Python version(s) in which the package can be installed

property has_sig

Whether the package file is accompanied by a PGP signature file. This is None if the package repository does not report such information.

Changed in version 0.7.0: Will now be None if not specified by repository; previously would be False in such a situation

property yanked

If the package file has been “yanked” from the package repository (meaning that it should only be installed when that specific version is requested), this attribute will be a string giving the reason why it was yanked; otherwise, it is None.

property metadata_digests

If the package repository provides a Core Metadata file for the package, this is a (possibly empty) dict of digests of the file, given as a mapping from hash algorithm names to hex-encoded digest strings; otherwise, it is None

property sig_url

The URL of the package file’s PGP signature file, if it exists; cf. has_sig

Changed in version 0.6.0: Now always defined; would previously be None if has_sig was false

property has_metadata

Whether the package file is accompanied by a Core Metadata file

property metadata_url

If the package repository provides a Core Metadata file for the package, this is the URL for that file; otherwise, it is None.

get_digests() → Dict[str, str][source]

Extracts the hash digests from the package file’s URL and returns a dict mapping hash algorithm names to hex-encoded digest strings

New in version 0.7.0.

Construct a DistributionPackage from a Link on a project page.

Parameters

  • link (Link) – a link parsed from a project page

  • project_hint (Optional[str]) – Optionally, the expected value for the project name (usually the name of the project page on which the link was found). The name does not need to be normalized.

Return type

DistributionPackage

pypi_simple.PYPI_SIMPLE_ENDPOINT: str = 'https://pypi.org/simple/'

The base URL for PyPI’s simple API

pypi_simple.SUPPORTED_REPOSITORY_VERSION: str = '1.0'

The maximum supported simple repository version (See PEP 629)

exception pypi_simple.UnsupportedRepoVersionError(declared_version: str, supported_version: str)[source]

Raised upon encountering a simple repository whose repository version (PEP 629) has a greater major component than the maximum supported repository version (SUPPORTED_REPOSITORY_VERSION)

declared_version: str

The version of the simple repository

supported_version: str

The maximum repository version that we support