High-Level API

class pypi_simple.PyPISimple(endpoint: str = 'https://pypi.org/simple/', auth: Optional[Any] = None, session: Optional[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) 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[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

download_package(pkg: DistributionPackage, path: Union[AnyStr, os.PathLike[AnyStr]], verify: bool = True, keep_on_error: bool = False, progress: Optional[Callable[[Optional[int]], ProgressTracker]] = None, timeout: Optional[Union[float, Tuple[float, float]]] = None) None[source]

New in version 0.10.0.

Download the given DistributionPackage to the given path.

If an error occurs while downloading or verifying digests, and keep_on_error is not true, the downloaded file is not saved.

Download progress can be tracked (e.g., for display by a progress bar) by passing an appropriate callable as the progress argument. This callable will be passed the length of the downloaded file, if known, and it must return a ProgressTracker — a context manager with an update(increment: int) method that will be passed the size of each downloaded chunk as each chunk is received.

Parameters
  • pkg (DistributionPackage) – the distribution package to download

  • path – the path at which to save the downloaded file; any parent directories of this path will be created as needed

  • verify (bool) – whether to verify the package’s digests against the downloaded file

  • keep_on_error (bool) – whether to keep (true) or delete (false) the downloaded file if an error occurs

  • progress – a callable for contructing a progress tracker

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

Raises
  • requests.HTTPError – if the repository responds with an HTTP error code

  • NoDigestsError – if verify is true and the given package does not have any digests with known algorithms

  • DigestMismatchError – if verify is true and the digest of the downloaded file does not match the expected value

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[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[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[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[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

Changed in version 0.10.0: digests attribute added

property filename

The basename of the package file

property url

The URL from which the package file can be downloaded, with any hash digest fragment removed

Changed in version 0.10.0: Hash digest fragments are now stripped from the URL

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 digests

A collection of hash digests for the file as a dict mapping hash algorithm names to hex-encoded digest strings

property has_metadata

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

Changed in version 0.10.0: Will now be None if not specified by repository

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: str

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 metadata_url: str

The URL of the package file’s Core Metadata file, if it exists; cf. has_metadata

Changed in version 0.10.0: Now always defined; would previously be None if has_metadata was false

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

Returns the hash digests for the file as a dict mapping hash algorithm names to hex-encoded digest strings

Deprecated since version 0.10.0: Use digests instead

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

classmethod from_pep691_details(data: Any, project_hint: Optional[str] = None, base_url: Optional[str] = None) DistributionPackage[source]

New in version 0.10.0.

Construct a DistributionPackage from an object taken from the "files" field of a PEP 691 project detail response.

Parameters
  • data – a file dictionary

  • 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.

  • base_url (Optional[str]) – an optional URL to join to the front of a relative file URL (usually the URL of the page being parsed)

Return type

DistributionPackage

Raises

TypeError – if data is not a dict

Constants

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)

Progress Trackers

class pypi_simple.ProgressTracker[source]

A typing.Protocol for progress trackers. A progress tracker must be usable as a context manager whose __enter__ method performs startup & returns itself and whose __exit__ method performs shutdown/cleanup. In addition, a progress tracker must have an update(increment: int) method that will be called with the size of each downloaded file chunk.

__enter__() T[source]
__exit__(exc_type: Optional[Type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) Optional[bool][source]
update(increment: int) None[source]
pypi_simple.tqdm_progress_factory(**kwargs: Any) Callable[[Optional[int]], ProgressTracker][source]

A function for displaying a progress bar with tqdm during a download. Naturally, using this requires tqdm to be installed alongside pypi-simple.

Call tqdm_progress_factory() with any arguments you wish to pass to the tqdm.tqdm constructor, and pass the result as the progress argument to PyPISimple.download_package().

Example:

with PyPISimple() as client:
    page = client.get_project_page("pypi-simple")
    pkg = page.packages[-1]
    client.download_package(
        pkg,
        path=pkg.filename,
        progress=tqdm_progress_factory(desc="Downloading ..."),
    )

Exceptions

exception pypi_simple.DigestMismatchError[source]

Bases: ValueError

New in version 0.10.0.

Raised by PyPISimple.download_package() with verify=True when the digest of the downloaded file does not match the expected value

algorithm

The name of the digest algorithm used

expected_digest

The expected digest

actual_digest

The digest of the file that was actually received

exception pypi_simple.NoDigestsError[source]

Bases: ValueError

New in version 0.10.0.

Raised by PyPISimple.download_package() with verify=True when the given package does not have any digests with known algorithms

exception pypi_simple.UnsupportedContentTypeError[source]

Bases: ValueError

Raised when a response from a simple repository has an unsupported Content-Type

url

The URL that returned the response

content_type

The unsupported Content-Type

exception pypi_simple.UnsupportedRepoVersionError[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

exception pypi_simple.UnexpectedRepoVersionWarning[source]

Bases: UserWarning

New in version 0.10.0.

Emitted upon encountering a simple repository whose repository version (PEP 629) has a greater minor version components than the maximum supported repository version (SUPPORTED_REPOSITORY_VERSION).

This warning can be emitted by anything that can raise UnsupportedRepoVersionError.