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 thesession
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 addedChanged 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 requestssession – 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
- Raises
requests.HTTPError – if the repository responds with an HTTP error code
UnsupportedContentTypeError – if the repository responds with an unsupported Content-Type
UnsupportedRepoVersionError – if the repository version has a greater major component than the supported repository version
- 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()
andget_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
- Return type
Iterator[str]
- Raises
requests.HTTPError – if the repository responds with an HTTP error code
UnsupportedRepoVersionError – if the repository version has a greater major component than the supported repository version
- 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. ReturnsNone
if the repository responds with a 404. All other HTTP errors cause arequests.HTTPError
to be raised.- Parameters
- Return type
Optional[ProjectPage]
- Raises
requests.HTTPError – if the repository responds with an HTTP error code other than 404
UnsupportedContentTypeError – if the repository responds with an unsupported Content-Type
UnsupportedRepoVersionError – if the repository version has a greater major component than the supported repository version
- get_project_url(project: str) str [source]
Returns the URL for the given project’s page in the repository.
- 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 aProgressTracker
— a context manager with anupdate(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 algorithmsDigestMismatchError – 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()
orstream_project_names()
instead- Return type
Iterator[str]
- Raises
requests.HTTPError – if the repository responds with an HTTP error code
UnsupportedContentTypeError – if the repository responds with an unsupported Content-Type
UnsupportedRepoVersionError – if the repository version has a greater major component than the supported repository version
- 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
requests.HTTPError – if the repository responds with an HTTP error code other than 404
UnsupportedContentTypeError – if the repository responds with an unsupported Content-Type
UnsupportedRepoVersionError – if the repository version has a greater major component than the supported repository version
- 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.
- 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
- 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 addedChanged in version 0.9.0:
has_metadata
,metadata_url
, andmetadata_digests
attributes addedChanged 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.
- 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 isNone
- 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
ifhas_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 stringsDeprecated since version 0.10.0: Use
digests
instead
- classmethod from_link(link: Link, project_hint: Optional[str] = None) DistributionPackage [source]
New in version 0.7.0.
Construct a
DistributionPackage
from aLink
on a project page.- Parameters
- Return type
- 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
- Raises
Constants
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 anupdate(increment: int)
method that will be called with the size of each downloaded file chunk.- __exit__(exc_type: Optional[Type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]) Optional[bool] [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 thetqdm.tqdm
constructor, and pass the result as theprogress
argument toPyPISimple.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()
withverify=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()
withverify=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
)
- 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
.