Skip to content
Back to top
View this page

Caution

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

# `installer.records`

Provides an object-oriented model for handling PEP 376 RECORD files.

## Example

    >>> from installer.records import parse_record_file, RecordEntry
    >>> lines = [
    ...     "file.py,sha256=AVTFPZpEKzuHr7OvQZmhaU3LvwKz06AJw8mT\\_pNh2yI,3144",
    ...     "distribution-1.0.dist-info/RECORD,,",
    ... ]
    >>> records = parse_record_file(lines)
    >>> li = list(records)
    >>> len(li)
    2
    >>> record_tuple = li[0]
    >>> record_tuple
    ('file.py', 'sha256=AVTFPZpEKzuHr7OvQZmhaU3LvwKz06AJw8mT\\_pNh2yI', '3144')
    >>> record = RecordEntry.from_elements(*record_tuple)
    >>> record
    RecordEntry(path='file.py', hash_=Hash(name='sha256', value='AVTFPZpEKzuHr7OvQZmhaU3LvwKz06AJw8mT\\_pNh2yI'), size=3144)
    >>> record.path
    'file.py'
    >>> record.hash_
    Hash(name='sha256', value='AVTFPZpEKzuHr7OvQZmhaU3LvwKz06AJw8mT\\_pNh2yI')
    >>> record.size
    3144
    >>> record.validate(b"...")
    False

## Reference

installer.records.parse_record_file(rows)

  Parse a PEP 376 RECORD.

  Returns an iterable of 3-value tuples, that can be passed to `RecordEntry.from_elements`.

  Parameters:

    rows (Iterable[str]) – iterator providing lines of a RECORD (no trailing newlines).

  Return type:

    Iterator[tuple[str, str, str]]

class installer.records.RecordEntry

  Represents a single record in a RECORD file.

  A list of `RecordEntry` objects fully represents a RECORD file.

  Most consumers should use `RecordEntry.from_elements()`, since no validation or parsing is performed by this constructor.

  path: str

    File’s path.

  hash_: Hash | None

    Hash of the file’s contents.

  size: int | None

    File’s size in bytes.

  to_row(path_prefix=None)

    Convert this into a 3-element tuple that can be written in a RECORD file.

    Parameters:

      path_prefix (str | None) – A prefix to attach to the path – must end in /

    Returns:

      a (path, hash, size) row

    Return type:

      tuple[str, str, str]

  __init__(path, hash_, size)
    Parameters:

      - path (str)

      - hash_ (Hash | None)

      - size (int | None)

    Return type:

      None

  validate(data)

    Validate that `data` matches this instance.

    Attention

    Deprecated since version 1.0.0: Use `validate_stream()` instead, with `BytesIO(data)`.

    Parameters:

      data (bytes) – Contents of the file corresponding to this instance.

    Returns:

      whether `data` matches hash and size.

    Return type:

      bool

  validate_stream(stream)

    Validate that data read from stream matches this instance.

    Parameters:

      stream (BinaryIO) – Representing the contents of the file.

    Returns:

      Whether data read from stream matches hash and size.

    Return type:

      bool

  classmethod from_elements(path, hash_, size)

    Build a RecordEntry object, from values of the elements.

    Typical usage:

        for row in parse_record_file(f):
            record = RecordEntry.from_elements(row[0], row[1], row[2])

    Meaning of each element is specified in PEP 376.

    Parameters:

      - path (str) – first element (file’s path)

      - hash_ (str) – second element (hash of the file’s contents)

      - size (str) – third element (file’s size in bytes)

    Raises:

      InvalidRecordEntry – if any element is invalid

    Return type:

      RecordEntry

class installer.records.Hash

  Represents the “hash” element of a RecordEntry.

  Most consumers should use `Hash.parse()` instead, since no validation or parsing is performed by this constructor.

  name: str

    Name of the hash function.

  value: str

    Hashed value.

  validate(data)

    Validate that `data` matches this instance.

    Parameters:

      data (bytes) – Contents of the file.

    Returns:

      Whether `data` matches the hashed value.

    Return type:

      bool

  classmethod parse(h)

    Build a Hash object, from a “name=value” string.

    This accepts a string of the format for the second element in a record, as described in PEP 376.

    Typical usage:

        Hash.parse("sha256=Y0sCextp4SQtQNU-MSs7SsdxD1W-gfKJtUlEbvZ3i-4")

    Parameters:

      h (str) – a name=value string

    Return type:

      Hash

  __init__(name, value)
    Parameters:

      - name (str)

      - value (str)

    Return type:

      None