budosystems.storage.repository.Repository

class Repository

Bases: ABC

Interface for storage repositories.

abstract __init__(**kwargs: Any) → None

Abstract initializer that accepts arbitrary keyword arguments.

Implementations should specify more precisely those it needs.

Parameters:

kwargs – Keyword arguments used for initializing the repository.

abstract load(entity_type: type[ET], entity_id: UUID) → ET

An implementation will return an Entity with an ID matching the parameter.

Parameters:

  • entity_type – The specific type of Entity expected.

  • entity_id – The ID used to search the repository.

Returns:

The Entity matching the ID.

Raises:

EntityReadError – If the repository fails to retrieve an Entity with the given ID.

abstract save(entity: Entity, save_option: SaveOption = SaveOption.create_or_update) → None

An implementation will store the provided entity.

Parameters:

  • entity – The entity object needing to be stored.

  • save_option – Whether to allow creation, update, or both.

Raises:

  • EntitySaveError –

    If the repository failed to store the given Entity.

    Reasons for failure related to the save_option parameter are reported as

  • EntityAlreadyExists – If save_option is set to SaveOption.create_only and a matching entity already exists in the repository.

  • EntityNotFound – If save_option is set to SaveOption.update_only and a matching entity does not currently exist in the repository.

abstract delete(entity_type: type[ET], entity_id: UUID, must_exist: bool = False) → None

An implementation will delete Entity with an ID matching the parameter.

Parameters:

  • entity_type – The specific type of Entity expected.

  • entity_id – The ID of the entity to be deleted.

  • must_exist – If True, raises an exception if no entity with the ID exists in the repository. If False (default), proceed silently.

Raises:

EntityNotFound – If must_exist is set to True and a matching entity does not already exist in the repository.

abstract match(entity_type: type[ET], data: dict[str, Any]) → list[ET]

An implementation will return every instance of entity_type with field values matching data.

Parameters:

  • entity_type – The specific type of Entity expected.

  • data – Mapping where the keys correspond to the field names of the entities, and the values correspond to the field values to match. Omitted keys are not matched.

abstract find_entities(query: Query) → list[Entity]

An implementation will search for entities according to the query.

Parameters:

query – Specification of the entities to return.

Returns:

A (possibly empty) list of the entities satisfying the query.

Raises:

QueryError – If there are problems with the query.

abstract find_data(query: Query) → list[dict[str, Any]]

An implementation will search for data according to the query.

The structure and format of the expected data is specified in the query.

Parameters:

query – Specification of the data to return.

Returns:

A (possibly empty) list of the data entries satisfying the query.

Raises:

QueryError – If there are problems with the query.