maestral.database.orm

A basic object relational mapper for SQLite.

This is a very simple ORM implementation which contains only functionality needed by Maestral. Many operations will still require explicit SQL statements. This module is no alternative to fully featured ORMs such as sqlalchemy but may be useful when system memory is constrained.

Module Contents

class maestral.database.orm.NoDefault

Class to denote the absence of a default value.

This is distinct from None which may be a valid default.

class maestral.database.orm.Column(sql_type, unique=False, primary_key=False, index=False, default=None)

Bases: Generic[T, ST]

Represents a column in a database table.

Parameters:

• sql_type (maestral.database.types.SqlType[T, ST]) – Column type in database table. Python types which don’t have SQLite equivalents, such as enum.Enum, will be converted appropriately.

• unique (bool) – If True, sets a unique constraint on the column.

• primary_key (bool) – If True, marks this column as a primary key column. Currently, only a single primary key column is supported.

• index (bool) – If True, create an index on this column.

• default (T | type[NoDefault] | None) – Default value for the column. Set to NoDefault if no default value should be used. Note than None / NULL is a valid default for an SQLite column.

render_constraints()

Returns a string with constraints for the SQLite column definition.

Return type:

str

render_properties()

Returns a string with properties for the SQLite column definition.

Return type:

str

render_column()

Returns a string with the full SQLite column definition.

Return type:

str

py_to_sql(value)

Converts a Python value to a value which can be stored in the database column.

Parameters:

value (T | None) – Native Python value.

Returns:

Converted Python value to store in database. Will only return str, int, float or None.

Return type:

ST | None

sql_to_py(value)

Converts a database column value to the original Python type.

Parameters:

value (ST | None) – Value from database column. Only accepts str, int, float or None.

Returns:

Converted Python value.

Return type:

T | None

class maestral.database.orm.NonNullColumn(sql_type, unique=False, primary_key=False, index=False, default=NoDefault)

Bases: Column[T, ST]

Subclass of Column which is not nullable, i.e., does not accept or return None as a value.

Parameters:

• sql_type (maestral.database.types.SqlType[T, ST])

• unique (bool)

• primary_key (bool)

• index (bool)

• default (T | type[NoDefault])

py_to_sql(value)

Converts a Python value to a value which can be stored in the database column.

Parameters:

value (T | None) – Native Python value.

Returns:

Converted Python value to store in database. Will only return str, int, float or None.

Return type:

ST

sql_to_py(value)

Converts a database column value to the original Python type.

Parameters:

value (ST | None) – Value from database column. Only accepts str, int, float or None.

Returns:

Converted Python value.

Return type:

T

render_constraints()

Returns a string with constraints for the SQLite column definition.

Return type:

str

class maestral.database.orm.Manager(db, model)

Bases: Generic[M]

A data mapper interface for a table model.

Creates the table as defined in the model if it doesn’t already exist. Keeps a cache of weak references to all retrieved and created rows to speed up queries. The cache should be cleared manually changes where made to the table from outside this manager.

Parameters:

• db (maestral.database.core.Database) – Database to use.

• model (type[M]) – Model for database table.

create_table_if_not_exists()

Creates the table as defined by the model.

Return type:

None

clear_cache()

Clears our cache.

Return type:

None

delete(query)

Parameters:

query (maestral.database.query.Query)

Return type:

None

select(query)

Parameters:

query (maestral.database.query.Query)

Return type:

list[M]

select_iter(query, size=1000)

Parameters:

• query (maestral.database.query.Query)

• size (int)

Return type:

Generator[list[M], Any, None]

select_sql(sql, *args)

Performs the given SQL query and converts any returned rows to model objects.

Parameters:

• sql (str) – SQL statement to execute.

• args (Any) – Parameters to substitute for placeholders in SQL statement.

Returns:

List of model objects from the query.

Return type:

list[M]

delete_primary_key(primary_key)

Delete a model object / row from database by primary key.

Parameters:

primary_key (Any) – Primary key for row.

Return type:

None

get(primary_key)

Gets a model object from database by its primary key. This will return a cached value if available and None if no row with the primary key exists.

Parameters:

primary_key (Any) – Primary key for row.

Returns:

Model object representing the row.

Return type:

M | None

has(primary_key)

Checks if a model object exists in database by its primary key

Parameters:

primary_key (Any) – The primary key.

Returns:

Whether the corresponding row exists in the table.

Return type:

bool

save(obj)

Saves a model object to the database table. If the primary key is None, a new primary key will be generated by SQLite on inserting the row. This key will be retrieved and stored in the primary key property of the object.

Parameters:

obj (M) – Model object to save.

Returns:

Saved model object.

Return type:

M

update(obj)

Updates the database table from a model object.

Parameters:

obj (M) – The object to update.

Return type:

None

count()

Returns the number of rows in the table.

Return type:

int

clear()

Delete all rows from table.

Return type:

None

class maestral.database.orm.Model(**kwargs)

Abstract object model to represent an SQL table.

Instances of this class are model objects which correspond to rows in the database table.

To define a table, subclass Model and define class properties as Column. Override the __tablename__ attribute with the SQLite table name to use. The __columns__ attribute will be populated automatically for you.

Parameters:

kwargs (Any)