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 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) → 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
- 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
-
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[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. 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
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.
-
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
UnsupportedRepoVersionError – if the repository version has a greater major component than the supported repository version
-
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
requests.HTTPError – if the repository responds with an HTTP error code other than 404
UnsupportedRepoVersionError – if the repository version has a greater major component than the supported repository version
-
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
-
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
-
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 addedChanged in version 0.9.0:
has_metadata
,metadata_url
, andmetadata_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.
-
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 isNone
-
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
-
classmethod
from_link
(link: pypi_simple.classes.Link, project_hint: Optional[str] = None) → pypi_simple.classes.DistributionPackage[source]¶ New in version 0.7.0.
Construct a
DistributionPackage
from aLink
on a project page.- Parameters
- Return type
-
property
-
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)