Object: pypiapiobject.py - Object for querying the PyPI JSON API — ppklib - v0.2.0rc3 Documentation

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

  > - PyPI Index API

  > - PyPI JSON API

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)

  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

    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()

    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

    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

    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

    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

    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

    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

    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.