API Reference

Basic seeder

class sqlalchemyseeder.basic_seeder.BasicSeeder

Directly converts objects from dictionary without any further processing.

static entity_from_dict(entity_dict, entity_class)

Created an entity using the dictionary as initializer arguments.

static entity_from_json_string(json_string, entity_class)

Extract entity from given json string.

static entity_from_yaml_string(yaml_string, entity_class)

Extract entity from given yaml string.

Resolving seeder

class sqlalchemyseeder.resolving_seeder.ResolvingSeeder(session)

Seeder that can resolve entities with references to other entities.

This requires the data to be formatted in a custom Data format to define the references.

As entities have to define their target class they must be registered so the sqlalchemyseeder can retrieve them during the seeding process. This is typically done using register(), register_class() or register_module() which are hoisted methods from ClassRegistry. If a classpath is encountered but not recognized it will be resolved before continuing.

The session passed to this sqlalchemyseeder is used to resolve references. Flushes may occur depending on the session configuration and the passed parameters. The default behaviour when loading entities is to perform flushes but not to commit.

load_entities_from_data_dict(seed_data, separate_by_class=False, flush_on_create=True, commit=False)

Create entities from the given dictionary.

By default each entity is flushed into the provided session when it is created. This is useful if you want to reference them by id in other entities.

If this behaviour is not wanted (eg. the created entities are incomplete) you can disable it by setting flush_on_create to False when loading entities. The provided session can still flush if it is configured with autoflush=True.

No commit is issued unless commit is set to True.

Parameters:
  • seed_data – The formatted entity dict or list. This collection can be modified by the resolver.
  • separate_by_class – Whether the output should separate entities by class (in a dict).
  • flush_on_create – Whether entities should be flushed once they are created.
  • commit – Whether the session should be committed after entities are generated.
Returns:

List of entities or a dictionary mapping of classes to a list of entities based on separate_by_class.
Raises:

ValidationError – If the provided data does not conform to the expected data structure.
load_entities_from_json_file(seed_file, separate_by_class=False, flush_on_create=True, commit=False)

Convenience method to read the given file and parse it as json.

See: load_entities_from_data_dict

load_entities_from_json_string(json_string, separate_by_class=False, flush_on_create=True, commit=False)

Parse the given string as json.

See: load_entities_from_data_dict

load_entities_from_yaml_file(seed_file, separate_by_class=False, flush_on_create=True, commit=False)

Convenience method to read the given file and parse it as yaml.

See: load_entities_from_data_dict

load_entities_from_yaml_string(yaml_string, separate_by_class=False, flush_on_create=True, commit=False)

Parse the given string as yaml.

See: load_entities_from_data_dict

class sqlalchemyseeder.resolving_seeder.ClassRegistry

A cache of mappable classes used by ResolvingSeeder.

get_class_for_string(target)

Look for class in the cache. If it cannot be found and a full classpath is provided, it is first registered before returning.

Parameters:target – The class name or full classpath.
Returns:The class defined by the target.
Raises:AttributeError – If there is no registered class for the given target.
register(target)

Register module or class defined by target.

Parameters:

target –

If target is a class, it is registered directly using register_class.

If target is a module, it registers all mappable classes using register_module.

If target is a string, it is first resolved into either a module or a class. Which look like:

Module path: “path.to.module”

Class path: “path.to.module:MyClass”
Raises:
  • ValueError – If target string could not be parsed.
  • AttributeError – If target string references a class that does not exist.
register_class(cls)

Registers the given class with its full class path in the cache.

Parameters:cls – The class to register.
Returns:The class that was passed.
Raises:ValueError – If the class is not mappable (no associated SQLAlchemy mapper).
register_module(module_)

Retrieves all classes from the given module that are mappable.

Parameters:module – The module to inspect.
Returns:A set of all mappable classes that were found.

Exceptions

exception sqlalchemyseeder.exceptions.AmbiguousReferenceError

Raised when a reference matches more than one entity.

exception sqlalchemyseeder.exceptions.EntityBuildError

Internal error to signify that an entity cannot be built.

exception sqlalchemyseeder.exceptions.UnresolvedReferencesError

Raised when a reference could not be resolved during the seeding process.