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