assembl.lib.sqla module

Some utilities for working with SQLAlchemy, and the definition of BaseOps.

class assembl.lib.sqla.BaseOps

Bases: object

Base class for SQLAlchemy models in IdeaLoom.

Many protocols are defined here.

apply_side_effects_without_json(context=None, request=None)

Apply side-effects in non-json context

assert_unique()

Assert this object is unique

classmethod base_conditions(alias=None, alias_maker=None)

Return a list of SQLA expressions that will filter out instances of this class

Mostly used to exclude archived versions; see assembl.lib.history_mixin The exclusion pattern is used by the traversal API, and by the RDF mapping.

classmethod base_polymorphic_class()

Returns the base class of this class above Base.

change_class(newclass, json=None, **kwargs)

Change the class of an instance, deleting and creating table rows as needed.

container_url()

What is the URL where we expect to find this resource

classmethod create(obj=None, flush=False, **values)

Create an instance. Not used.

classmethod create_from_json(json, context=None, object_importer=None, parse_def_name='default_reverse', duplicate_handling=None)

Create an object from its JSON representation.

property db

Return the SQLAlchemy db session object. (per-http-request)

classmethod expand_view_def(view_def)

Return the full view_def specification for this class.

Follows the @extend links and the _default view.

classmethod external_typename()

What is the class name that will be sent on the API, as @type.

Will use a class-local name defined as __external_typename, otherwise will use the python class name directly.

classmethod external_typename_with_inheritance()

Returns the external_typename() of the root class below this one.

classmethod extra_collections_dict()

Returns a dictionary of (named) collections of objects related to an instance of this class

Many collections can be obtained by introspection on SQLAlchemy relationships, but collections here go beyond this.

find_duplicate(expunge=True, must_define_uniqueness=False)

Verifies that no other object exists that would conflict. See unique_query for usable flag.

generic_json(view_def_name='default', user_id=None, permissions=('Conversation.R', 'Idea.R'), base_uri='local:')

Return a representation of this object as a JSON object, according to the given view_def and access control.

classmethod get(id, session=None)

Return the record by id.

classmethod get_by(raise_=False, **criteria)

Return the record corresponding to the criteria.

Throw an exception on record not found and raise_ == True, else return None.

classmethod get_database_id(uri)

Parse a URI to extract the database ID

get_id_as_str()

Return the primary key as a string.

classmethod get_inheritance()

Return a dictionary of external class names to their parent classe’s name.

static get_inheritance_for(classnames, with_ontology=True)

Return get_inheritance() for some classes

classmethod get_instance(identifier, session=None)

Get an instance of this class using a numeric ID or URI.

static get_json_inheritance_for(classnames, with_ontology=True)

Return get_inheritance() as a json string

classmethod get_subclasses()

Return the list of subclasses of this class

get_unique_from_db(expunge=True)

Returns the object, or a unique object from the DB

handle_duplication(json={}, parse_def={}, context=None, duplicate_handling=None, object_importer=None)

Look for duplicates of this object.

Some uniqueness is handled in the database, but it is difficult to do across tables. Often we will use the classe’s unique_query to find an duplicate, and react appropriately here. Appropriateness depends on the classe’s default_duplicate_handling, which can be overridden.

classmethod inject_api(name, as_object=False)

Inject common methods in an API module. Unused.

classmethod iri_class()

Return an IRI pattern for instances of this class.

The uri_generic() will follow this pattern. Used for Virtuoso RDF-Relational mapping; disabled for now.

property is_new_instance

Return True if the instance wasn’t fetched from the database.

is_owner(user_id)

The user owns this ressource, and has more permissions.

iteritems(include=None, exclude=None)

Return a generator that iterates through model columns.

Fields iterated through can be specified with include/exclude.

locked_object_creation(object_generator, lock_table_cls=None, num_attempts=3)

Utility method to create objects as a side effect. Will use an exclusive table lock to ensure that the objects are created only once. Not all object creation should need this, but it should be used when many connexions might attempt to create the same unique objects.

Parameters

object_generator (func) – a function (w/o parameters) that will create the objects that need to be created (as iterable). They will be added and committed in a subtransaction. Will be called many times.

Returns

Whether there was anything added (maybe not in this process)

classmethod polymorphic_filter()

Return a SQLA expression that tests for subclasses of this class

classmethod polymorphic_identities()

Return the list of polymorphic identities defined in subclasses.

populate_from_context(context)

If object created in this context, populate some relations from that context.

This is the magic fallback, ideally define the relationships you want populated explicitly in subclasses of this.

classmethod restrict_to_owners(query, user_id, alias=None)

filter query according to object owners

classmethod restrict_to_owners_condition(query, user_id, alias=None, alias_maker=None)

filter query according to object owners

retypeable_as = ()

If it is possible to mutate the class of this object after its creation, using :py:meth:BaseOps.change_class, declare here the list of classes it can be retyped into

save(flush=False)

Encapsulate db.add().

send_to_changes(connection=None, operation=<CrudOperation.UPDATE: 0>, discussion_id=None, view_def='changes')

Ask for this object to be sent on the changes websocket.

See assembl.tasks.changes_router.

classmethod special_quad_patterns(alias_maker, discussion_id)

Returns a list of quad map patterns for RDF mapping, beyond those defined by introspection.

Important: If defined somewhere, override in subclasses to avoid inheritance.

tombstone()

Return a Tombstone object.

This object will be sent on the websocket and will express that this object has been deleted.

unique_query()

returns a couple (query, usable), with a sqla query for conflicting similar objects. usable is true if the query has to be enforced; sometimes it makes sense to return un-usable query that will be used to construct queries of subclasses. Note that when a duplicate is found, you’ll often want to expunge the original.

update_from_json(json, user_id=None, context=None, object_importer=None, permissions=None, parse_def_name='default_reverse')

Update (patch) an object from its JSON representation.

uri(base_uri='local:')

The URI of this instance.

It may be a LOD URL if the namespace is resolved.

classmethod uri_generic(id, base_uri='local:')

Return the identity of this object as a URI in the local: namespace

Composed from the root type name and database Id. The local: namespace actually corresponds to the server name, and is intended to become the basis of a LOD architecture.

user_can(user_id, operation, permissions)

Whether the user, with the given permissions, can perform the given Crud operation on this instance.

classmethod user_can_cls(user_id, operation, permissions)

Whether the user, with the given permissions, can perform the given Crud operation on instances of this class.

classmethod validator(mapping_cls=None, include=None, exclude=None)

Return a ColanderAlchemy schema mapper.

Fields targeted by the validator can be specified with include/exclude. Not used at this point.

class assembl.lib.sqla.CleanupStrategy

Bases: sqlalchemy.engine.strategies.PlainEngineStrategy

create(*args, **kwargs)

Given arguments, returns a new Engine instance.

class assembl.lib.sqla.CrudOperation(value)

Bases: enum.Enum

An enumeration.

class assembl.lib.sqla.DuplicateHandling(value)

Bases: enum.Enum

How to handle duplicates. Assumes that the unique_query is valid.

exception assembl.lib.sqla.ObjectNotUniqueError

Bases: ValueError

class assembl.lib.sqla.PrivateObjectMixin

Bases: object

marker class for objects that should be sent to owner

class assembl.lib.sqla.TableLockCreationThread(object_generator, lock_table_name, num_attempts=3)

Bases: threading.Thread

Utility class to create objects as a side effect. Will use an exclusive table lock to ensure that the objects are created only once. Does it on another thread to minimize the time that the table is locked. Not all object creation should need this, but it should be used when many connexions might attempt to create the same unique objects.

Parameters

object_generator (func) – a function (w/o parameters) that will create the objects that need to be created (as iterable). They will be added and committed in a subtransaction. Will be called many times.

Returns

Whether there was anything added (maybe not in this process)

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

assembl.lib.sqla.after_commit_listener(session)

After commit, actually send the Json representation of changed objects to the assembl.tasks.changes_router, through 0MQ.

assembl.lib.sqla.before_commit_listener(session)

Create the Json representation of changed objects which will be sent to the assembl.tasks.changes_router

We have to do this before commit, while objects are still attached.

assembl.lib.sqla.configure_engine(settings, zope_tr=True, autoflush=True, session_maker=None, **engine_kwargs)

Return an SQLAlchemy engine configured as per the provided config.

assembl.lib.sqla.engine_rollback_listener(connection)

In case of rollback, forget about object changes.

assembl.lib.sqla.get_named_object(identifier, typename=None)

Get an object given a typename and identifier

assembl.lib.sqla.get_session_maker()

Get the application global sessionmaker object

assembl.lib.sqla.includeme(config)

Initialize SQLAlchemy at app start-up time.

assembl.lib.sqla.initialize_session_maker(zope_tr=True, autoflush=True)

Initialize the application global sessionmaker object

assembl.lib.sqla.random() → x in the interval [0, 1).

assembl.lib.sqla.session_rollback_listener(session)

In case of rollback, forget about object changes.

assembl.lib.sqla.uses_list(prop)

is a property a list?