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_ (Hash | None) – hash of the file’s contents

  • size (int | None) – file’s size in bytes

Return type:

None

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]

validate(data)#

Validate that data matches this instance.

Attention

Deprecated since version 0.8.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.

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

Hash