protocols.dao.Dao
A duck type with methods common to all DAOs.
Usage
protocols.dao.Dao()Methods
| Name | Description |
|---|---|
| delete() | Delete a resource by providing its ID. |
| find_all() | Find all resources that match the specified filter. |
| find_one() | Find the resource that matches the specified filter. |
| get_by_id() | Get a resource by providing its ID. |
| insert() | Create a new resource. |
| update() | Update an existing resource. |
| upsert() | Update the provided resource if it already exists, create it otherwise. |
| with_transaction() | Creates a transaction manager that uses an async context manager interface: |
delete()
Delete a resource by providing its ID.
Usage
delete(id_)Parameters
id_: ID- The ID of the resource.
Raises
ResourceNotFoundError- when resource with the specified id_ was not found
find_all()
Find all resources that match the specified filter.
Usage
find_all(*, filter_=None, mapping=None, skip=None, limit=None, sort=None)The values in the filter are used to select the resources. Provide them using the same Python types as the corresponding DTO model fields, e.g. a UUID object for a UUID field and a datetime object for a datetime field. The behavior for non-scalar values depends on the specific provider.
Parameters
filter_: Mapping[str, Any] | None = None-
A mapping where the keys correspond to the names of resource fields and the values correspond to the actual values of the resource fields.
mapping: Mapping[str, Any] | None = None-
Deprecated alias for
filter_. skip: int | None = None-
Number of matching resources to skip before yielding results. Defaults to None (no skipping).
limit: int | None = None-
Maximum number of resources to yield. Defaults to None (no limit). Specifying 0 is interpreted literally and returns no results.
sort: list[str] | None = None-
A list of field names defining the sort order, where field names prefixed with “-” indicate descending order. For example, if sort is specified as
["name", "-age"], the results would be sorted first by “name” in ascending order, then by “age” in descending order. When paginating with skip/limit, providing a sort order is strongly recommended to ensure consistent, deterministic results. Defaults to None (no sort).
Returns
FindResult[Dto]- A FindResult that is async-iterable and also provides total_count().
Raises
InvalidMappingError-
If
mappingdoesn’t pass validation. ValueError-
if
skiporlimitare less than 0.
find_one()
Find the resource that matches the specified filter.
Usage
find_one(*, filter_=None, mapping=None)It is expected that at most one resource matches the constraints. An exception is raised if no or multiple hits are found.
The values in the filter are used to select the resources. Provide them using the same Python types as the corresponding DTO model fields, e.g. a UUID object for a UUID field and a datetime object for a datetime field. The behavior for non-scalar values depends on the specific provider.
Parameters
filter_: Mapping[str, Any] | None = None-
A mapping where the keys correspond to the names of resource fields and the values correspond to the actual values of the resource fields
mapping: Mapping[str, Any] | None = None-
Deprecated alias for
filter_.
Returns
Dto-
Returns a hit in the form of the respective DTO model if exactly one hit
was found that matches the given filter.
Raises
NoHitsFoundError-
If no hit was found.
MultipleHitsFoundError- Raised when obtaining more than one hit.
get_by_id()
Get a resource by providing its ID.
Usage
get_by_id(id_)Parameters
id_: ID- The ID of the resource.
Returns
Dto- The resource represented using the respective DTO model.
Raises
ResourceNotFoundError- when resource with the specified id_ was not found
insert()
Create a new resource.
Usage
insert(dto)Parameters
dto: Dto- Resource content as a pydantic-based data transfer object including the resource ID.
Raises
ResourceAlreadyExistsError-
when a resource with the ID specified in the dto does already exist.
UniqueConstraintViolationError- when inserting the dto would violate a unique index constraint over some field other than the ID field.
update()
Update an existing resource.
Usage
update(dto, *, precondition=None)If precondition is supplied, the resource is only updated if its current values match them. The check and the update happen atomically.
Parameters
dto: Dto-
The updated resource content as a pydantic-based data transfer object including the resource ID.
precondition: Mapping[str, Any] | None = None- A mapping of field names to the values the existing resource must have. It does not need to contain the ID field, since that is implied.
Raises
ResourceNotFoundError-
when resource with the id specified in the dto was not found
PreconditionFailedError-
when the resource exists but doesn’t match
precondition InvalidMappingError-
when
preconditiondoesn’t pass validation UniqueConstraintViolationError- when updating the dto would violate a unique index constraint over some field other than the ID field.
upsert()
Update the provided resource if it already exists, create it otherwise.
Usage
upsert(dto)Parameters
dto: Dto- Resource content as a pydantic-based data transfer object including the resource ID.
Raises
UniqueConstraintViolationError- when upserting the dto would violate a unique index constraint over some field other than the ID field.
with_transaction()
Creates a transaction manager that uses an async context manager interface:
Usage
with_transaction()Upon aenter, pens a new transactional scope. Returns a transaction-scoped DAO.
Upon aexit, closes the transactional scope. A full rollback of the transaction is performed in case of an exception. Otherwise, the changes to the database are committed and flushed.