API Reference

Classes

Core

class misery.Repo

Protocol for all repositories to implement.

async add(entity: misery.core.T) → None

Add a new entity to the repository.

Parameters

entity – An entity to add.

async add_many(entities: Iterable[misery.core.T]) → None

Add multiple entities to the repository.

Parameters

entities – Entities to add.

async count(**kwargs: Any) → int

Count entities that match given lookup parameters. If there are no lookup parameters, count all entities in the repository.

Parameters

kwargs – Lookup parameters as field-value pairs.

async count_filtered(filter_: misery.core.F) → int

Count entities that match a given filter.

async delete(**kwargs: Any) → None

Delete entities. When kwargs is empty, delete all.

Parameters

kwargs – Lookup parameters as field-value pairs.

async exists(**kwargs: Any) → bool

Check if there is an entity for given lookup parameters.

Parameters

kwargs – Lookup parameters as field-value pairs.

async get(**kwargs: Any) → misery.core.T

Get an entity. Raise misery.NotFound if the entity is missing.

Parameters

kwargs – Lookup parameters as field-value pairs.

async get_first(filters: Sequence[misery.core.F] = (), order: Sequence[str] = ()) → misery.core.T

Get the first entity matching given filters. Raise misery.NotFound if the entity is missing.

Parameters

  • filters – Sequence of filters.

  • order – Sequence of fields by which to sort entities. If a field starts with the “-” character, entities for the field will be shown in descending order.

async get_for_update(**kwargs: Any) → misery.core.T

Get an entity and lock it for update. Raise misery.NotFound if the entity is missing.

Parameters

kwargs – Lookup parameters as field-value pairs.

async get_many(filters: Sequence[misery.core.F] = (), order: Sequence[str] = (), limit: Optional[int] = None, page: int = 1, offset: int = 0) → Iterable[misery.core.T]

Get multiple entities.

Parameters

  • filters – Sequence of filters.

  • order – Sequence of fields by which to sort entities. If a field starts with the “-” character, entities for the field will be shown in descending order.

  • limit – Maximum number of entities to show on the page.

  • page – Page number. Only when the limit parameter is used.

  • offset – Number of entities to skip.

async update(entity: misery.core.T) → None

Save an updated entity. Raise misery.NotFound if the entity is not present in the repository.

Parameters

entity – An updated entity.

class misery.F(type: misery.core.FilterType, field: str, value: Any, not_: bool = False)

Object used for filtering entities before getting them from a repository.

classmethod and_(*filters: misery.core.F) → misery.core.F

Create a filter that combines multiple filters with the “AND” operator.

classmethod contains(field: str, value: Any) → misery.core.F

Create a filter to find entities whose field contains a given value.

Case-sensitive.

classmethod endswith(field: str, value: str) → misery.core.F

Create a filter to find entities whose field ends with a given value.

Case-sensitive.

classmethod eq(field: str, value: Any) → misery.core.F

Create a filter to find entities with a specified field value.

classmethod gt(field: str, value: Any) → misery.core.F

Create a filter to find entities with a field value that is greater than a given one.

classmethod gte(field: str, value: Any) → misery.core.F

Create a filter to find entities with a field value that is greater than or equal to a given one.

classmethod hasany(field: str, value: Sequence) → misery.core.F

Create a filter to find entities whose array-like field contains any value from a given sequence.

classmethod icontains(field: str, value: str) → misery.core.F

Create a filter to find entities whose field contains a given value.

Case-insensitive.

classmethod iendswith(field: str, value: str) → misery.core.F

Create a filter to find entities whose field value ends with a given value.

Case-insensitive.

classmethod ieq(field: str, value: Any) → misery.core.F

Create a filter to find entities with a specified field value.

Case-insensitive.

classmethod imatches(field: str, value: str) → misery.core.F

Create a filter to find entities whose field value matches a regular expression in the value parameter.

Case-insensitive.

classmethod in_(field: str, value: Any) → misery.core.F

Create a filter to find entities whose field is within a given value.

Case-sensitive.

classmethod ineq(field: str, value: Any) → misery.core.F

Create a filter to find entities with a field value that is not equal to a given one.

Case-insensitive.

classmethod ipin(field: str, subnet: str) → misery.core.F

Create a filter to find entities whose field is an IP address contained within a given subnet.

classmethod istartswith(field: str, value: str) → misery.core.F

Create a filter to find entities whose field starts with a given value.

Case-insensitive.

classmethod lt(field: str, value: Any) → misery.core.F

Create a filter to find entities with a field value that is less than a given one.

classmethod lte(field: str, value: Any) → misery.core.F

Create a filter to find entities with a field value that is less than or equal to a given one.

classmethod matches(field: str, value: str) → misery.core.F

Create a filter to find entities whose field matches a regular expression in the value parameter.

Case-sensitive.

classmethod ncontains(field: str, value: Any) → misery.core.F

Create a filter to find entities whose field doesn’t contain a given value.

Case-sensitive.

classmethod nendswith(field: str, value: str) → misery.core.F

Create a filter to find entities whose field doesn’t end with a given value.

Case-sensitive.

classmethod neq(field: str, value: Any) → misery.core.F

Create a filter to find entities with a field value that is not equal to a given one.

classmethod nicontains(field: str, value: str) → misery.core.F

Create a filter to find entities whose field doesn’t contain a given value.

Case-insensitive.

classmethod niendswith(field: str, value: str) → misery.core.F

Create a filter to find entities whose field value doesn’t end with a given value.

Case-insensitive.

classmethod nimatches(field: str, value: str) → misery.core.F

Create a filter to find entities whose field value doesn’t match a regular expression in the value parameter.

Case-insensitive.

classmethod nin(field: str, value: Any) → misery.core.F

Create a filter to find entities whose field is not within a given value.

Case-sensitive.

classmethod nipin(field: str, subnet: str) → misery.core.F

Create a filter to find entities whose field is an IP address not contained within a given subnet.

classmethod nistartswith(field: str, value: str) → misery.core.F

Create a filter to find entities whose field doesn’t start with a given value.

Case-insensitive.

classmethod nmatches(field: str, value: str) → misery.core.F

Create a filter to find entities whose field value doesn’t match a regular expression in the value parameter.

Case-sensitive.

classmethod nstartswith(field: str, value: str) → misery.core.F

Create a filter to find entities whose field doesn’t start with a given value.

Case-sensitive.

classmethod or_(*filters: misery.core.F) → misery.core.F

Create a filter that combines multiple filters with the “OR” operator.

classmethod startswith(field: str, value: str) → misery.core.F

Create a filter to find entities whose field starts with a given value.

Case-sensitive.

class misery.TransactionManager

Protocol of an object that is used for transaction management.

async __aenter__() → None

Start a new transaction.

async __aexit__(exc_type: Any, exc: Any, tb: Any) → None

Commit or rollback a transaction.

class misery.NotFound

Error to raise when an entity cannot be found in the repository.

class misery.QueryError(message: str, query: str)

Error to raise when a query to the database cannot be processed.

Dictionary

class misery.dictionary.DictRepo(storage: dict)

Implementation of the misery.Repo protocol. It uses a dictionary to store entities.

property data: dict[Any, T]

Nested dictionary inside the storage dictionary. The repository uses this nested dictionary to save entities.

id_field = 'id'

Name of the ID field of an entity.

abstract property key: str

Key inside the storage dictionary. The value of this key is also a dictionary. The repository uses this nested dictionary to save entities.

class misery.dictionary.DictTransactionManager(storage: dict)

Implementation of the misery.TransactionManager protocol. It uses a dictionary to store entities.

PostgreSQL

class misery.postgres.PostgresRepo(conn: Union[asyncpg.connection.Connection, asyncpg.pool.Pool])

Implementation of the misery.Repo protocol that uses asyncpg to communicate with PostgreSQL.

async after_add(entity: misery.postgres.T) → None

Action after adding a new entity.

By default, this method doesn’t do anything. Override it to your liking.

async after_update(entity: misery.postgres.T) → None

Action after update.

By default, this method doesn’t do anything. Override it to your liking.

property conn: Union[asyncpg.connection.Connection, asyncpg.pool.Pool]

Connection or pool that is used for interaction with the database.

Use this property in your custom methods.

dump(entity: misery.postgres.T) → dict

Map an entity to a database record.

Override this method if needed.

async fetch_many(query: pypika.dialects.PostgreSQLQuery) → Iterable[misery.postgres.T]

Find multiple records in the database and map them to entities.

async fetch_one(query: pypika.dialects.PostgreSQLQuery) → misery.postgres.T

Find a record in the database and map it to an entity.

id_field = 'id'

Name of the ID field of an entity.

load(record: dict) → misery.postgres.T

Map a database record to an entity.

Override this method if needed.

property query: pypika.dialects.PostgreSQLQuery

Query to select records from the database.

Override this property when you need something more complex than selecting all columns from the main table of the repository.

abstract property table: pypika.queries.Table

Main table of the repository. It is used to autogenerate SQL queries.

class misery.postgres.PostgresTransactionManager(conn: Union[asyncpg.connection.Connection, asyncpg.pool.Pool])

Implementation of the misery.TransactionManager protocol that uses asyncpg to communicate with PostgreSQL.

ClickHouse

class misery.clickhouse.ClickHouseRepo(session: aiohttp.client.ClientSession)

Implementation of the misery.Repo protocol that uses aiohttp to communicate with ClickHouse.

async delete(**kwargs: Any) → None

Don’t use this method in production because ClickHouse isn’t good at deleting records.

dump(entity: misery.clickhouse.T) → dict

Map an entity to a database record.

Override this method if needed.

async fetch_many(query: pypika.dialects.ClickHouseQuery) → Iterable[misery.clickhouse.T]

Find multiple records in the database and map them to entities.

async fetch_one(query: pypika.dialects.ClickHouseQuery) → misery.clickhouse.T

Find a record in the database and map it to an entity.

id_field = 'id'

Name of the ID field of an entity.

load(record: dict) → misery.clickhouse.T

Map a database record to an entity.

Override this method if needed.

property query: pypika.dialects.ClickHouseQuery

Query to select records from the database.

Override this property when you need something more complex than selecting all columns from the main table of the repository.

abstract property table: pypika.queries.Table

Main table of the repository. It is used to autogenerate SQL queries.

async update(entity: misery.clickhouse.T) → None

Don’t use this method in production because ClickHouse isn’t good at updating records.

class misery.clickhouse.ClickHouseTransactionManager

This class exists only for compatibility with the protocol because ClickHouse doesn’t support transactions. It doesn’t do anything to the database.