API Reference

sqla_model_context.context module

class sqla_model_context.context.EnforceMode(value)

Bases: enum.Enum

Determines how to enforce relationships at insert time.

ERROR = 4

LOG = 2

NONE = 1

WARN = 3

classmethod parse_arg(value: Union[str, bool, sqla_model_context.context.EnforceMode]) → sqla_model_context.context.EnforceMode

Parse an arguemtn into the enforcement mode enum. Possible values are:

• A boolean, where True means ERROR, i.e. do enforcement and raise an error, and False means do nothing (NONE)

• A string which corresponds to one of the enumerations.

• An actual enumeration value

This method always returns an enumeration value, or raises an error.

class sqla_model_context.context.ModelRelativeContextManager(basecls: Type[M], relationship_attr: str, fk_attr: Optional[str] = None, enforce: Union[bool, str, sqla_model_context.context.EnforceMode] = True, default_value: Optional[Callable[], R]] = None, logger: Optional[str] = None, listen: bool = True)

Bases: Generic[sqla_model_context.context.M, sqla_model_context.context.R]

A context manager to provide default values for a relationship property.

Using SQLAlchemy events, intercept the creation of model objects, and ensure that those objects have an appropriate relationship set. The enforce keyword also provides a check during the before_insert that the relationship property was set.

A default_value function can also be provided as a fallback. When the default_value is provided, it should return the correct default relationship entity in the current context.

This context manager assumes that the relationship on the target class is handled as a keyword argument during the __init__ method of the target instance, and that the foriegn key can also be detected as a keyword argument.

Parameters

• basecls (type) – The type used to filter events - can be a base class or mixin, which has the approprite relationship properties.

• relationship_attr (str) – The name of the relationship property on the model class. This is _not_ the underlying column but the actual relationship property where the related object can be found.

• fk_attr (str) – The name of the foreign key on the target model - used to identify when an explicit identifier has been passed to __init__. Defaults to relation_name_id for relation_name.

• enforce (bool) – When true (default), this relationship be enforced to be not-null during the insert event.

• default_value (callable) – A no-argument function which returns the appropriate default value for this context, which can be applied to target objects as relationship_attr.

property active

Is this context stack active and populated with a value

listen() → Iterator[sqla_model_context.context.ModelRelativeContextManager]

peek() → Optional[R]

Return the topmost relation value in the context stack.

If no value is on the stack, but a default_value function is provided, the return value from that is provided instead. When no acceptable value can be found, None is returned.

property proxy

Provides a proxy object which resolves to the object held by this context or the default.

This proxies relation() using werkzug’s LocalProxy object.

push(value: R) → Iterator[None]

Context manager for a particular value of the relation.

While inside this context, the value provided will be used for the relationship property on any class which inherits from basecls. Contexts can be nested within each other, where the innermost context takes precedence.

Parameters

value (R) – Relation value (model instance) which will be applied to every subclass of basecls.

relation() → R

Return the topmost relation value in the context stack.

If no value is on the stack, but a default_value function is provided, the return value from that is provided instead. When no acceptable value can be found, NoActiveRelation is raised.

sqla_model_context.exc module

exception sqla_model_context.exc.ContextRelationError

Bases: Exception

Error class encompasing potential problems with the context relation manager

exception sqla_model_context.exc.ContextRelationListenerWarning

Bases: sqla_model_context.exc.ContextRelationWarning

Warning raised when listeners are added twice

exception sqla_model_context.exc.ContextRelationWarning

Bases: Warning

exception sqla_model_context.exc.MissingRelation(clsname: str, relationship_name: str, target: M)

Bases: sqla_model_context.exc.ContextRelationError, Generic[sqla_model_context.exc.M]

Error indicating that a model is being saved without an appropriate value for a relationship

exception sqla_model_context.exc.NoActiveRelation(clsname: str, relationship_name: str)

Bases: sqla_model_context.exc.ContextRelationError

Error indicating that no relationship is currently active in the relationship context manager