Records

zenpyre.records

Define records.

zenpyre.records.Record dataclass

A generic immutable record with a stable UUID identifier and arbitrary metadata.

Use :meth:from_metadata as the preferred constructor to automatically derive a stable UUID from the metadata dict.

Parameters:

Name	Type	Description	Default
id	str	Unique identifier for the record, typically a UUID derived from the metadata via :func:~zenpyre.utils.hashing.hash_dict_uuid.	required
metadata	dict[str, Any]	Arbitrary key-value metadata associated with the record. Defaults to an empty dict.	dict()

zenpyre.records.Record.from_metadata classmethod

from_metadata(metadata: dict[str, Any]) -> Record

Construct a :class:Record from a metadata dict.

Computes a stable UUID from metadata via :func:~zenpyre.utils.hashing.hash_dict_uuid and uses it as the record's id. Two calls with the same metadata contents (regardless of key insertion order) will produce the same id.

Parameters:

Name	Type	Description	Default
metadata	dict[str, Any]	Arbitrary key-value metadata to associate with the record. Used to derive the id.	required

Returns:

Type	Description
Record	A new :class:Record with id derived from
Record	metadata.

Example

>>> from zenpyre.records import Record
>>> record = Record.from_metadata({"source": "cats.txt", "page": 1})
>>> record.id  # doctest: +ELLIPSIS
'...'
>>> record.metadata
{'source': 'cats.txt', 'page': 1}

zenpyre.records.filter_by_metadata

filter_by_metadata(
    records: list[Record], metadata_key: str, value: Any
) -> list[Record]

Filter a list of records by the value of a metadata key.

Returns a new list containing only records whose metadata contains metadata_key with a value equal to value. Records missing metadata_key are excluded.

Parameters:

Name	Type	Description	Default
records	list[Record]	The list of :class:~zenpyre.records.Record instances to filter.	required
metadata_key	str	The metadata key to filter by.	required
value	Any	The value to match against. Records whose metadata_key equals this value are kept.	required

Returns:

Type	Description
list[Record]	A new list of :class:~zenpyre.records.Record instances whose metadata
list[Record]	matches the filter. The original list is not modified.

Example

>>> from zenpyre.records import Record, filter_by_metadata
>>> records = [
...     Record(id="a", metadata={"category": "Science"}),
...     Record(id="b", metadata={"category": "Cooking"}),
...     Record(id="c", metadata={"category": "Science"}),
... ]
>>> result = filter_by_metadata(records, "category", "Science")
>>> [r.id for r in result]
['a', 'c']

zenpyre.records.filter_by_metadata_range

filter_by_metadata_range(
    records: list[Record],
    metadata_key: str,
    lower: Any = None,
    upper: Any = None,
) -> list[Record]

Filter a list of records by a range of values for a metadata key.

Returns a new list containing only records whose metadata contains metadata_key with a value within the specified range [lower, upper] (inclusive on both ends). Either bound can be set to None to indicate no constraint on that side. If both bounds are None, all records that contain metadata_key are returned. Records missing metadata_key are always excluded.

Parameters:

Name	Type	Description	Default
records	list[Record]	The list of :class:~zenpyre.records.Record instances to filter.	required
metadata_key	str	The metadata key to filter by.	required
lower	Any	The inclusive lower bound. Pass None (the default) for no lower bound.	None
upper	Any	The inclusive upper bound. Pass None (the default) for no upper bound.	None

Returns:

Type	Description
list[Record]	A new list of :class:~zenpyre.records.Record instances whose
list[Record]	metadata_key value falls within [lower, upper]. The
list[Record]	original list is not modified.

Raises:

Type	Description
TypeError	If the metadata values are not comparable with the provided bounds (e.g. comparing str with int).

Example

>>> from zenpyre.records import Record, filter_by_metadata_range
>>> records = [
...     Record(id="a", metadata={"page": 1}),
...     Record(id="b", metadata={"page": 5}),
...     Record(id="c", metadata={"page": 10}),
... ]
>>> result = filter_by_metadata_range(records, "page", lower=2, upper=8)
>>> [r.id for r in result]
['b']
>>> result = filter_by_metadata_range(records, "page", lower=5)
>>> [r.id for r in result]
['b', 'c']
>>> result = filter_by_metadata_range(records, "page", upper=5)
>>> [r.id for r in result]
['a', 'b']

zenpyre.records.filter_by_metadata_values

filter_by_metadata_values(
    records: list[Record],
    metadata_key: str,
    values: set[Any],
) -> list[Record]

Filter a list of records by checking if a metadata value is in a set.

Returns a new list containing only records whose metadata contains metadata_key with a value that is a member of values. Records missing metadata_key are excluded.

Parameters:

Name	Type	Description	Default
records	list[Record]	The list of :class:~zenpyre.records.Record instances to filter.	required
metadata_key	str	The metadata key to filter by.	required
values	set[Any]	The set of accepted values. Records whose metadata_key is in this set are kept.	required

Returns:

Type	Description
list[Record]	A new list of :class:~zenpyre.records.Record instances whose
list[Record]	metadata_key value is in values. The original list is
list[Record]	not modified.

Example

>>> from zenpyre.records import Record, filter_by_metadata_values
>>> records = [
...     Record(id="a", metadata={"category": "Science"}),
...     Record(id="b", metadata={"category": "Cooking"}),
...     Record(id="c", metadata={"category": "Technology"}),
...     Record(id="d", metadata={"category": "Science"}),
... ]
>>> result = filter_by_metadata_values(records, "category", {"Science", "Technology"})
>>> sorted(r.id for r in result)
['a', 'c', 'd']

zenpyre.records.sort_by_metadata

sort_by_metadata(
    records: list[Record],
    metadata_key: str,
    *,
    keep_missing: bool = True,
    reverse: bool = False
) -> list[Record]

Sort a list of records by the value of a metadata key.

Records are sorted in ascending order by the value of metadata_key by default, or descending order if reverse=True. Records that do not contain metadata_key in their metadata are placed at the end of the result by default, or removed entirely if keep_missing=False.

Parameters:

Name	Type	Description	Default
records	list[Record]	The list of :class:~zenpyre.records.Record instances to sort.	required
metadata_key	str	The metadata key to sort by.	required
keep_missing	bool	If True (the default), records without metadata_key in their metadata are kept and placed at the end of the result. If False, they are excluded from the result entirely.	True
reverse	bool	If True, the result is sorted in descending order. Defaults to False, matching the behaviour of :func:sorted.	False

Returns:

Type	Description
list[Record]	A new sorted list of :class:~zenpyre.records.Record instances. The
list[Record]	original list is not modified.

Raises:

Type	Description
TypeError	If the metadata values for metadata_key are not mutually comparable (e.g. mixing str and int).

Example

>>> from zenpyre.records import Record, sort_by_metadata
>>> records = [
...     Record(id="b", metadata={"source": "b.txt"}),
...     Record(id="a", metadata={"source": "a.txt"}),
...     Record(id="c"),
... ]
>>> sorted_records = sort_by_metadata(records, "source")
>>> [r.metadata.get("source") for r in sorted_records]
['a.txt', 'b.txt', None]
>>> sorted_records = sort_by_metadata(records, "source", reverse=True)
>>> [r.metadata.get("source") for r in sorted_records]
['b.txt', 'a.txt', None]
>>> sorted_records = sort_by_metadata(records, "source", keep_missing=False)
>>> [r.metadata.get("source") for r in sorted_records]
['a.txt', 'b.txt']