Skip to content
Back to top
View this page

Caution

This API is not finalised, and may change in a patch version.

# `installer.sources`

Source of information about a wheel file.

class installer.sources.WheelFile

  Implements WheelSource, for an existing file from the filesystem.

  Example usage:

      >>> with WheelFile.open("sampleproject-2.0.0-py3-none-any.whl") as source:
      ...     installer.install(source, destination)

  validation_error

    alias of `_WheelFileValidationError`

  __init__(f)

    Initialize a WheelFile object.

    Parameters:

      f (ZipFile) – An open zipfile, which will stay open as long as this object is used.

    Return type:

      None

  classmethod open(path)

    Create a wheelfile from a given path.

    Parameters:

      path (os.PathLike[str])

    Return type:

      Iterator[WheelFile]

  property dist_info_dir: str

    Name of the dist-info directory.

  property dist_info_filenames: list[str]

    Get names of all files in the dist-info directory.

  read_dist_info(filename)

    Get contents, from `filename` in the dist-info directory.

    Parameters:

      filename (str)

    Return type:

      str

  validate_record(*, validate_contents=True)

    Validate `RECORD` of the wheel.

    This method should be called before `install` if validation is required.

    File names will always be validated against `RECORD`.

    If `validate_contents` is true, sizes and hashes of files will also be validated against `RECORD`.

    Parameters:

      validate_contents (bool) – Whether to validate content integrity.

    Return type:

      None

  get_contents()

    Sequential access to all contents of the wheel (including dist-info files).

    This implementation requires that every file that is a part of the wheel archive has a corresponding entry in RECORD. If they are not, an `AssertionError` will be raised.

    Return type:

      Iterator[tuple[tuple[str, str, str], BinaryIO, bool]]

class installer.sources.WheelSource

  Represents an installable wheel.

  This is an abstract class, whose methods have to be implemented by subclasses.

  validation_error

    Added in version 0.7.0.

    Exception to be raised by `validate_record()` when validation fails. This is expected to be a subclass of `ValueError`.

    alias of `ValueError`

  __init__(distribution, version)

    Initialize a WheelSource object.

    Parameters:

      - distribution (str) – distribution name (like `urllib3`)

      - version (str) – version associated with the wheel

    Return type:

      None

  property dist_info_dir: str

    Name of the dist-info directory.

  property data_dir: str

    Name of the data directory.

  property dist_info_filenames: list[str]

    Get names of all files in the dist-info directory.

    Sample usage/behaviour:

        >>> wheel_source.dist_info_filenames
        ['METADATA', 'WHEEL']

  read_dist_info(filename)

    Get contents, from `filename` in the dist-info directory.

    Sample usage/behaviour:

        >>> wheel_source.read_dist_info("METADATA")
        ...

    Parameters:

      filename (str) – name of the file

    Return type:

      str

  validate_record()

    Validate `RECORD` of the wheel.

    Added in version 0.7.0.

    This method should be called before `install` if validation is required.

    Return type:

      None

  get_contents()

    Sequential access to all contents of the wheel (including dist-info files).

    This method should return an iterable. Each value from the iterable must be a tuple containing 3 elements:

    - record: 3-value tuple, to pass to `RecordEntry.from_elements`.

    - stream: An `io.BufferedReader` object, providing the contents of the file at the location provided by the first element (path).

    - is_executable: A boolean, representing whether the item has an executable bit.

    All paths must be relative to the root of the wheel.

    Sample usage/behaviour:

        >>> iterable = wheel_source.get_contents()
        >>> next(iterable)
        (('pkg/__init__.py', '', '0'), <...>, False)

    This method may be called multiple times. Each iterable returned must provide the same content upon reading from a specific file’s stream.

    Return type:

      Iterator[tuple[tuple[str, str, str], BinaryIO, bool]]