maestral.utils.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.

class maestral.utils.orm.SqlType[source]

Bases: object

Base class to represent Python types in SQLite table

sql_type = 'TEXT'
py_type

alias of str

static sql_to_py(value)[source]

Converts the return value from sqlite3 to the target Python type.

static py_to_sql(value)[source]

Converts a Python value to a type accepted by sqlite3.

class maestral.utils.orm.SqlString[source]

Bases: maestral.utils.orm.SqlType

Class to represent Python strings in SQLite table

sql_type = 'TEXT'
py_type

alias of str

class maestral.utils.orm.SqlInt[source]

Bases: maestral.utils.orm.SqlType

Class to represent Python integers in SQLite table

sql_type = 'INTEGER'
py_type

alias of int

class maestral.utils.orm.SqlFloat[source]

Bases: maestral.utils.orm.SqlType

Class to represent Python floats in SQLite table

sql_type = 'REAL'
py_type

alias of float

class maestral.utils.orm.SqlPath[source]

Bases: maestral.utils.orm.SqlType

Class to represent Python paths in SQLite table

This class contains special handling for strings with surrogate escape characters which can appear in badly encoded file names.

sql_type = 'TEXT'
py_type

alias of str

class maestral.utils.orm.SqlEnum(enum)[source]

Bases: maestral.utils.orm.SqlType

Class to represent Python enums in SQLite table

Parameters

enum (Iterable[enum.Enum]) –

Return type

None

sql_type = 'TEXT'
py_type

alias of enum.Enum

sql_to_py(value)[source]
Parameters

value (Optional[str]) –

Return type

Optional[enum.Enum]

static py_to_sql(value)[source]
Parameters

value (Optional[enum.Enum]) –

Return type

Optional[str]

class maestral.utils.orm.Column(type, nullable=True, unique=False, primary_key=False, default=None)[source]

Bases: property

Represents a column in a database table.

Parameters
  • type (maestral.utils.orm.SqlType) – Column type in database table. Python types which don’t have SQLite equivalents, such as enum.Enum, will be converted appropriately.

  • nullable (bool) – When set to False, will cause the “NOT NULL” phrase to be added when generating the column.

  • 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.

  • default (Union[str, int, float, enum.Enum, None, Type[NoDefault]]) – 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()[source]

Returns a string with constraints for the SQLite column definition.

Return type

str

render_properties()[source]

Returns a string with properties for the SQLite column definition.

Return type

str

render_column()[source]

Returns a string with the full SQLite column definition.

Return type

str

py_to_sql(value)[source]

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

Parameters

value (Optional[Union[str, int, float, enum.Enum]]) – Native Python value.

Returns

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

Return type

Optional[Union[str, int, float]]

sql_to_py(value)[source]

Converts a database column value to the original Python type.

Parameters

value (Optional[Union[str, int, float]]) – Value from database column. Only accepts str, int, float or None.

Returns

Converted Python value.

Return type

Optional[Union[str, int, float, enum.Enum]]

class maestral.utils.orm.NoDefault[source]

Bases: object

Class to denote the absence of a default value.

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

class maestral.utils.orm.Database(*args, **kwargs)[source]

Bases: object

Proxy class to access sqlite3.connect method.

Return type

None

property connection: sqlite3.Connection

Returns an existing SQL connection or creates a new one.

close()[source]

Closes the SQL connection.

Return type

None

commit()[source]

Commits SQL changes.

Return type

None

execute(sql, *args)[source]

Creates a cursor and executes the given SQL statement.

Parameters
  • sql (str) – SQL statement to execute.

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

Returns

The created cursor.

Return type

sqlite3.Cursor

executescript(script)[source]

Creates a cursor and executes the given SQL script.

Parameters

script (str) – SQL script to execute.

Returns

The created cursor.

Return type

None

class maestral.utils.orm.Manager(db, model)[source]

Bases: object

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
Return type

None

create_table()[source]

Creates the table as defined by the model.

Return type

None

clear_cache()[source]

Clears our cache.

Return type

None

get_primary_key(obj)[source]

Returns the primary key for a model object / row in the table.

Parameters

obj (maestral.utils.orm.Model) – Model instance which represents the row.

Returns

Primary key for row.

Return type

Optional[Union[str, int, float]]

all()[source]

Get all model objects / rows from database in a single query.

Returns

List of model objects.

Return type

List[maestral.utils.orm.Model]

iter_all(size=1000)[source]

Get all model objects / rows from database in multiple queries.

Parameters

size (int) – Number of rows to fetch in each query.

Returns

Iterator over lists of model objects.

Return type

Generator[List[maestral.utils.orm.Model], Any, None]

create(**kwargs)[source]

Create a model object from SQL column values

Parameters

kwargs – Column values.

Returns

Model object.

Return type

maestral.utils.orm.Model

delete(obj)[source]

Delete a model object / row from database

Parameters

obj (maestral.utils.orm.Model) – Object / row to delete.

Return type

None

get(primary_key)[source]

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 (Optional[Union[str, int, float, enum.Enum]]) – Primary key for row.

Returns

Model object representing the row.

Return type

Optional[maestral.utils.orm.Model]

has(primary_key)[source]

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

Parameters

primary_key (Optional[Union[str, int, float, enum.Enum]]) – The primary key.

Returns

Whether the corresponding row exists in the table.

Return type

bool

save(obj)[source]

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 (maestral.utils.orm.Model) – Model object to save.

Returns

Saved model object.

Return type

maestral.utils.orm.Model

update(obj)[source]

Updates the database table from a model object.

Parameters

obj (maestral.utils.orm.Model) – The object to update.

Return type

None

query_to_objects(sql, *args)[source]

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

Parameters
  • sql (str) – SQL statement to execute.

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

Returns

List of model objects from the query.

Return type

List[maestral.utils.orm.Model]

count()[source]

Returns the number of rows in the table.

Return type

int

class maestral.utils.orm.Model(**kwargs)[source]

Bases: object

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 this Model and define Column`s as class properties. Override the ``__tablename__` attribute with the actual table name.

Initialise with keyword arguments corresponding to column names and values.

Parameters

kwargs – Keyword arguments assigning values to table columns.

Return type

None