Object: pypiapiobject.py - Object for querying the PyPI JSON API

Purpose:

This module provides the object implementation for interacting with PyPI’s JSON API.

Platform:

Linux/Windows | Python 3.8+

Developer:

J Berendt

Email:

development@s3dev.uk

Comments:

n/a

References:

The following links provide the requirements (specification) on which this module’s logic and API interactions are based:

Example:

Create an instance of the object and query the API to obtain release-specific metadata:

>>> from ppklib.objects.jsonapiobject import PyPIAPIObject

>>> papi = PyPIAPIObject(name='utils4',
                         version='1.7.0',
                         wheel='utils4-1.7.0-cp312-cp312-win_amd64.whl')
>>> papi.get_and_filter()

>>> # Inspect the flattened data.
>>> papi.data
{'author': None,
 'author_email': 'The Developers <development@s3dev.uk>',
 'name': 'utils4',
 'summary': 'A general utilities package for Python 3.7+.',
 'requires_dist': ['colorama'],
 'version': '1.7.0',
 'yanked': False,
 'yanked_reason': None,
 'filename': 'utils4-1.7.0-cp312-cp312-win_amd64.whl',
 'md5_digest': 'c8e0b67399cedb52ade57a2d33f52fe6',
 'python_version': 'cp312',
 'packagetype': 'bdist_wheel',
 'requires_python': '>=3.7',
 'upload_time_iso_8601': '2025-01-04T17:13:14.409585Z',
 'vulnerabilities': [],
 'latest_version': '1.7.0'}
class PyPIAPIObject(name: str = None, version: str = None, wheel: str = None)[source]

Bases: object

Object designed for interacting with PyPI’s JSON API.

Parameters:
  • name (str, optional) – Name of the package to query. Providing only the name will return the latest project-based metadata. For wheel-specific (release-specific) metadata, provide the version and/or wheel arguments too. Defaults to None.

  • version (str, optional) – Query the metadata specific to this version; otherwise the metadata for the latest version will be returned. Defaults to None.

  • wheel (str, optional) – Wheel filename. Providing only this argument will return version-specific release information. The project name and version will be parsed from the wheel filename. Defaults to None.

property data: dict

Accessor to the filtered JSON response as a flat dictionary.

This property returns the filtered response from the JSON API as a flattened dictionary. This is to enable easy conversion to a pandas.Series or pandas.DataFrame.

property name: str

Accessor to the name of the target package.

property rawjson: dict

Accessor to the raw JSON data returned by the API.

This property returns the complete JSON response from the API.

property status_code: int

Accessor to the response’s status code.

property version: str

Accessor to the version number of the target package.

property vulns: list

Accessor to the vulnerabilities as listed by PyPI.

Specifically, this is an accessor to the 'vulnerabilities' key of the data property, which is a subset of the API response.

If the full response is required, please use the rawjson property.

Note

Vulnerabilities are only available if the wheel argument is used on instantiation, as the wheel argument is used to query a specific release from PyPI.

property wheel: str

Accessor to the wheel’s filename for the target package.

get() bool[source]

Query the PyPI database using the JSON API.

Use this method to populate the _rawjson attribute, which is accessed through the rawjson property.

Returns:

True if the request succeeds, otherwise False.

Return type:

bool

get_and_filter()[source]

Query the PyPI database using the JSON API and filter the results.

This method filters the full response to create a flattened dictionary with the ‘frequently used’/’most descriptive’ key/value pairs.

The primary purpose for creating a flattened subset is to facilitate easy conversion to a pandas.Series or pandas.DataFrame, as these can be created from a simple dict object.

_build_request() dict[source]

Build the GET request using the available arguments.

Returns:

A dictionary containing the parameters required for a requests.get() request. Simply pass this dict into the function with double asterisks for unpacking.

Return type:

dict

_extract_release_metadata() None[source]

Extract release-specific metadata from the response.

This method extracts release-specific metadata from the ['urls'] key and therefore both the version and wheel arguments must be provided. If these are missing, this method is not executed.

Note

The extracted keys from the 'urls' key of the raw JSON are defined in libs/config.toml.

_extract_project_metadata() None[source]

Extract project metadata from the response.

This method only extracts metadata from the ['info'] key and is therefore only project (not release) data.

Note

The extracted keys from the 'info' key of the raw JSON are defined in libs/config.toml.

_get_latest_version() None[source]

Query to get the latest version of the package.

Note

This must be a separate request as the version key lists the version of the queried package, which differs if the version parameter of the API is provided. Therefore, this query is run without a specified version to ensure the latest version is obtained.

_getrequest() bool[source]

Send the GET request to the API and store the response.

If successful, the raw JSON response is stored into the _rawjson attribute of this class.

Returns:

True if the response to the GET request is 200, otherwise False.

Return type:

bool

_test_args() None[source]

Verify the appropriate arguments are provided.

Tasks:
  • Normalise the name attribute value.

  • If either the name or version are not provided, and the wheel filename is provided, the name and version are derived from the wheel filename.