Database adapters

Table of Contents

• Database adapters
  • adapter_manager
  • AdapterBase
  • Column and relation types
    • ColumnType
    • RelationType
  • Adapters
    • SqlAlchemy adapter
    • Django ORM adapter

adapter_manager

save_to_db.adapters.utils.adapter_manager.get_adapter_cls(model_or_cls)

Returns database adapter class for given ORM model instance or class.

Parameters:model_or_cls – an ORM model instance or class. Returns:An adapter class (subclass of AdapterBase) for the model.

AdapterBase

class save_to_db.adapters.utils.adapter_base.AdapterBase(adapter_settings)

Base adapter class for all database adapters. Here you can see descriptions of all required methods for DB adapters that are going to extend this class.

Variables:adapter_settings – Adapter configuration object.

BATCH_SIZE = 300

Maximum number of models that can be pulled with one query.

See also

batch_size class variable of Item class.

COMPOSITE_KEYS_SUPPORTED = True

Must be set to True if ORM supports composite primary keys.

REVERSE_MODEL_AUTOUPDATE_SUPPORTED = True

Must be set to True if ORM automatically updates model that is being assigned to or unassigned from another model.

SAVE_MODEL_BEFORE_COMMIT = False

This value must be set to True if a model has to be first saved before its changes can be committed to database.

add_related_models(model, fkey, related_models)

Adds related models for x-to-many relationships to a parent model.

Parameters:

• model – Parent ORM model instance.
• key – Parent ORM model instance foreign key field.
• related_models – Referenced ORM models.

clear_related_models(model, fkey)

Removes related models for x-to-many relationships from a parent model.

Parameters:

• model – Parent ORM model instance.
• fkey – Parent ORM model instance foreign key field.

commit()

Commits current transaction to database.

create_blank_model(model_cls)

Create empty model instance.

Parameters:model_cls – ORM model class to create. Returns:Newly created ORM model instance.

delete(model)

Deletes model from the database.

Parameters:model – ORM model to be deleted.

execute_delete(model_cls, selectors, keepers)

Deletes all rows in database that can be selected using selectors except those that can be selected using keepers.

For example, suppose our selectors and keepers look like this:

selectors = [{
    'field_1': 10,
    'field_2': 20,
}, {
    'field_1': 30,
    'field_2': 40,
}]

keepers = [{
    'field_10': 100,
    'field_20': 200,
}, {
    'field_10': 300,
    'field_20': 400,
}]

SQL query can look like this:

DELETE FROM model_cls_table
WHERE
/* selectors */
((field_1 = 10 AND field_2 = 20) OR
 (field_1 = 30 AND field_2 = 40))
AND
/* keepers */
((field_10 != 100 OR field_20 != 200) AND
 (field_10 != 300 OR field_20 != 400))

Parameters:

• model_cls – ORM model class used to work with database table.
• selectors – List of dictionaries with model field names as keys and model field values as dictionary values.
• keepers – Same as selectors.

execute_unref(parent, fkey, selectors, keepers)

Removes models from x-to-many field.

Parameters:

• parent – Parent ORM model.
• fkey – X-to-many foreign key field of parent.
• selectors –

  List of dictionaries with model field names as keys and model field values as dictionary values.

  See also

  selectors and keepers parameters of execute_delete() method.

• keepers – Same as selectors.

get(items_and_fkeys)

Accepts items and their foreign keys and gets corresponding models from database.

Warning

Items must have the same ORM model class.

Parameters:items_and_fkeys –

a list of lists of type:

[
    [item, {fkey: model, ...}],
    ...
]

Returns:List of created and updated models.

get_all_models(model_cls, sort_key=None)

Returns all models from database model_cls class.

Note

Used by tests only.

Parameters:

• model_cls – An ORM model class.
• sort_key – If not None then result is sorted using this function as key argument for sort method of the result list.

Returns:

List of all model instances for model_cls class.

get_model_cls_by_table_fullname(name)

Return ORM model class based on full table that that model class uses.

Parameters:name – table full name. Returns:ORM model class.

classmethod get_primary_key_names(model_cls)

Returns tuple of primary key names.

Parameters:model_cls – ORM model class. Returns:Tuple of primary key names of model_cls.

get_related_x_to_many(model, fkey)

Returns iterable of many-to-many related models.

Parameters:

• model – ORM model instance.
• fkey – field name used for reference.

classmethod get_table_fullname(model_cls)

Returns full table name with schema (if applicable) used by an ORM model class.

Parameters:model_cls – An ORM model class. Returns:Full table name with schema (if applicable). Examples:

• ’public.some_table’
• ’some_table’ (no schema, e.g. SQLite database).

classmethod is_usable(model_cls)

Returns True if this adapter can deal with model_cls class. Here you must somehow recognize that the model class was created using the particular ORM library that this adapter is for.

Parameters:model_cls – ORM model class (of any library). Returns:Boolean value indicating whether this adapter can deal with the given model class.

iter_all_models()

Returns an iteratorable of all known ORM model classes.

Returns:An iteratorable of all known ORM model classes

classmethod iter_fields(model_cls)

Returns an iteratorable of field names and their types. Foreign keys and relations must be ignored.

Parameters:model_cls – ORM model class for which column data are going to be returned. Returns:An iteratorable of tuples of type:

(field_name, field_type)

Where:

• field_name is a name of an ORM model field.
• field_type must be one of the fields of ColumnType enumeration class.

classmethod iter_relations(model_cls)

Returns an iteratorable of names of fields that reference other ORM models.

Parameters:model_cls – ORM model class for which relations are going to be iterated. Returns:An iteratorable of tuples of type:

(relation_field_name, relation_model_cls, relation_type, reverse_key)

Where:

• relation_field_name is a field of the model_cls that references another model.
• relation_model_cls is an ORM model class being referenced.
• relation_type must be one of the fields of RelationType enumeration class.
• reverse_key is the relationship name used in related model to reference the original model.

classmethod iter_required_fields(model_cls)

Returns an iteratorable of names of fields that cannot be null for an ORM model class:

• Simple field value cannot be null if the column has a not null constraint.
• Relation field cannot be null if any column used as foreign key (can be multiple in case of composite key) is not null.

Parameters:model_cls – ORM model class for which relations are going to be iterated. Returns:An iteratorable of names of fields that cannot be null.

classmethod iter_unique_field_combinations(model_cls)

Returns an iteratorable of unique constraints (set of field names) on the model.

Note

Relation considered to be unique if the set of columns used as foreign keys (can be multiple in case of composite key) has a unique constraint.

Relations can be unique together with other fields.

Parameters:model_cls – ORM model class for which relations are going to be iterated. Returns:Returns an iteratorable of unique constraints.

merge_models(models, merge_policy=None, ignore_fields=None)

Merges models into one. First model from models becomes the result model, all other models get deleted.

Parameters:

• models – List of ORM models (of the same class) to be merged into one.
• merge_policy – An instance of MergePolicy class.
• ignore_fields – List of field to ignore (not copy to result model) when merging.

Returns:

First model from models into which all other models are merged.

persist(item)

Saves item data into a database by creating or update appropriate database records.

Parameters:item – an instance of ItemBase to persist. Returns:Item list and corresponding ORM models as a list of lists (in case one item updates multiple models).

pprint(*models)

Pretty prints models.

Parameters:*models – List of models to print.

related_x_to_many_contains(model, fkey, child_models)

Returns list of contained models from child_models by model parent model trough field_name foreign key field.

Note

The returned list must contain instances from child_models list, not other instances for the same database rows.

Parameters:

• model – ORM model instance.
• fkey – field name used for reference.
• child_models – list of child models.

Returns:

Returns list of contained models from child_models by model parent model trough fkey foreign key field.

related_x_to_many_exists(model, fkey)

Returns True if model contains any other models with field_name relation key.

Parameters:

• model – Parent ORM model instance.
• fkey – Parent ORM model instance foreign key field.

Returns:

True if model contains any other models with the relation key.

rollback()

Rolls back current transaction.

save_model(model)

Saves ORM model to database.

Note

If possible, session must not be committed, just flushed.

Parameters:

• model – Parent ORM model instance.
• key – Parent ORM model instance foreign key field.

Column and relation types

ColumnType

class save_to_db.adapters.utils.column_type.ColumnType

Enumeration class for all possible DB types with which this library can deal.

Note

See the source code for helper methods that each enumeration has.

BINARY = 1

Any type of binary data

BOOLEAN = 2

Boolean value

DATE = 8

Date value

DATETIME = 10

Date and time value (timestamp)

DECIMAL = 7

Any type of numbers with fraction (decimal.Decimal)

FLOAT = 6

Any type of numbers with fraction (float)

INTEGER = 5

Any type of integer data

OTHER = 11

Unknown data type

STRING = 3

String value, like char or varchar

TEXT = 4

String unlimited in length

TIME = 9

Time value

is_num()

is_str()

RelationType

class save_to_db.adapters.utils.relation_type.RelationType

Enumeration class for all possible relation types.

Note

See the source code for helper methods that each enumeration has.

MANY_TO_MANY = 4

MANY_TO_ONE = 3

ONE_TO_MANY = 2

ONE_TO_ONE = 1

is_many_to_many()

is_many_to_one()

is_many_to_x()

is_one_to_many()

is_one_to_one()

is_one_to_x()

is_x_to_many()

is_x_to_one()

reverse()

Adapters

SqlAlchemy adapter

class save_to_db.adapters.sqlalchemy_adapter.SqlalchemyAdapter(adapter_settings)

An adapter for working with SqlAlchemy library.

The adapter_settings for this class is a simple Python dictionary that must contain next values:

• session is an SqlAlchemy session object that will be used to query a database.
• ModelBase is a declarative base class for ORM models.

Django ORM adapter

class save_to_db.adapters.django_adapter.DjangoAdapter(adapter_settings)

An adapter for working with Django ORM.

The adapter_settings is a dictionary with next values:

• using is a database name (a key from DATABASES dictionary in the “settings.py” file of a Django project), if it isn’t provided “default” database is used.

Note

If you are going to use transactions provided by this library, set autocommit for the database to False:

from django.db import transaction
from save_to_db import Persister
from save_to_db.adapters import DjangoAdapter

persister = Persister(DjangoAdapter(adapter_settings={}))

# Next function takes a `using` argument which should be the
# name of a database. If it isn’t provided, Django uses the
# "default" database.
transaction.set_autocommit(False, using='database_name')

try:
    persister.persist(save_to_db_item)
    persister.commit()
except:
    persister.rollback()

Alternativy, you can use Django transactions directly:

from django.db import transaction
from save_to_db import Persister
from save_to_db.adapters import DjangoAdapter

persister = Persister(DjangoAdapter(adapter_settings={}))

with transaction.atomic():
    persister.persist(save_to_db_item)