maestral.database.orm ===================== .. py:module:: maestral.database.orm .. autoapi-nested-parse:: 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 --------------- .. py:class:: NoDefault Class to denote the absence of a default value. This is distinct from ``None`` which may be a valid default. .. py:class:: Column(sql_type, unique = False, primary_key = False, index = False, default = None) Bases: :py:obj:`Generic`\ [\ :py:obj:`T`\ , :py:obj:`ST`\ ] Represents a column in a database table. :param sql_type: Column type in database table. Python types which don't have SQLite equivalents, such as :class:`enum.Enum`, will be converted appropriately. :param unique: If ``True``, sets a unique constraint on the column. :param primary_key: If ``True``, marks this column as a primary key column. Currently, only a single primary key column is supported. :param index: If ``True``, create an index on this column. :param default: Default value for the column. Set to :class:`NoDefault` if no default value should be used. Note than None / NULL is a valid default for an SQLite column. .. py:method:: render_constraints() Returns a string with constraints for the SQLite column definition. .. py:method:: render_properties() Returns a string with properties for the SQLite column definition. .. py:method:: render_column() Returns a string with the full SQLite column definition. .. py:method:: py_to_sql(value) Converts a Python value to a value which can be stored in the database column. :param value: Native Python value. :returns: Converted Python value to store in database. Will only return str, int, float or None. .. py:method:: sql_to_py(value) Converts a database column value to the original Python type. :param value: Value from database column. Only accepts str, int, float or None. :returns: Converted Python value. .. py:class:: NonNullColumn(sql_type, unique = False, primary_key = False, index = False, default = NoDefault) Bases: :py:obj:`Column`\ [\ :py:obj:`T`\ , :py:obj:`ST`\ ] Subclass of :class:`Column` which is not nullable, i.e., does not accept or return None as a value. .. py:method:: py_to_sql(value) Converts a Python value to a value which can be stored in the database column. :param value: Native Python value. :returns: Converted Python value to store in database. Will only return str, int, float or None. .. py:method:: sql_to_py(value) Converts a database column value to the original Python type. :param value: Value from database column. Only accepts str, int, float or None. :returns: Converted Python value. .. py:method:: render_constraints() Returns a string with constraints for the SQLite column definition. .. py:class:: Manager(db, model) Bases: :py:obj:`Generic`\ [\ :py:obj:`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. :param db: Database to use. :param model: Model for database table. .. py:method:: create_table_if_not_exists() Creates the table as defined by the model. .. py:method:: clear_cache() Clears our cache. .. py:method:: delete(query) .. py:method:: select(query) .. py:method:: select_iter(query, size = 1000) .. py:method:: select_sql(sql, *args) Performs the given SQL query and converts any returned rows to model objects. :param sql: SQL statement to execute. :param args: Parameters to substitute for placeholders in SQL statement. :returns: List of model objects from the query. .. py:method:: delete_primary_key(primary_key) Delete a model object / row from database by primary key. :param primary_key: Primary key for row. .. py:method:: 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. :param primary_key: Primary key for row. :returns: Model object representing the row. .. py:method:: has(primary_key) Checks if a model object exists in database by its primary key :param primary_key: The primary key. :returns: Whether the corresponding row exists in the table. .. py:method:: 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. :param obj: Model object to save. :returns: Saved model object. .. py:method:: update(obj) Updates the database table from a model object. :param obj: The object to update. .. py:method:: count() Returns the number of rows in the table. .. py:method:: clear() Delete all rows from table. .. py:class:: 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 :class:`Model` and define class properties as :class:`Column`. Override the ``__tablename__`` attribute with the SQLite table name to use. The ``__columns__`` attribute will be populated automatically for you.