installer.records - installer

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

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.

  __init__(path, hash_, size)

    Construct a `RecordEntry` object.

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

    Parameters

      - path (str) – file’s path

      - hash_ (Optional[installer.records.Hash]) – hash of the file’s contents

      - size (Optional[int]) – file’s size in bytes

    Return type

      None

  to_line(path_prefix=None)

    Convert this into a line that can be written in a RECORD file.

    Parameters

      path_prefix (Optional[str]) – A prefix to attach to the path – must end in /

    Returns

      A binary-encoded line, that doesn’t contain a newline

    Return type

      bytes

  validate(data)

    Validate that `data` matches this instance.

    Parameters

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

    Returns

      whether `data` 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

      installer.records.RecordEntry

class installer.records.Hash

  Represents the “hash” element of a RecordEntry.

  __init__(name, value)

    Construct a `Hash` object.

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

    Parameters

      - name (str) – name of the hash function

      - value (str) – hashed value

    Return type

      None

  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

      installer.records.Hash