taucmdr.mvc.controller module

TODO: FIXME: Docs

class taucmdr.mvc.controller.Controller(model_cls, storage, context=None)[source]

Bases: object

The “C” in MVC.

model

Data model.

Type:AbstractModel
storage

Record storage.

Type:AbstractDatabase
context

A field filter, with syntax (key, value).

Type:List(Tuple)
Filtering according to a context means that only elements with
at least an element matching the rules set in the context will
be considered. Think of it as a whitelist.
A controller will filters results according to
- By default, nothing;
- If a context was given at the object's initialization,

the controller only allows objects matching the context;

- If a context is given during a command, it overrides the internal

context and the results are matched against it.

_associate(record, foreign_model, affected, via)[source]

Associates a record with another record.

Parameters:
  • record (Record) – Record to associate.
  • foreign_model (Model) – Foreign record’s data model.
  • affected (list) – Identifiers for the records that will be updated to associate with record.
  • via (str) – The name of the associated foreign attribute.
_disassociate(record, foreign_model, affected, via)[source]

Disassociates a record from another record.

Parameters:
  • record (Record) – Record to disassociate.
  • foreign_model (Model) – Foreign record’s data model.
  • affected (list) – Identifiers for the records that will be updated to disassociate from record.
  • via (str) – The name of the associated foreign attribute.
all(**kwargs)[source]
count(context=True)[source]

Return the number of records.

Returns:Effectively len(self.all())
Return type:int
create(data)[source]

Atomically store a new record and update associations.

Invokes the on_create callback after the data is recorded. If this callback raises an exception then the operation is reverted.

Parameters:data (dict) – Data to record.
Returns:The newly created data.
Return type:Model
delete(keys, context=True)[source]

Delete recorded data and update associations.

The behavior depends on the type of keys:
  • Record.ElementIdentifier: delete the record with that element identifier.
  • dict: delete all records with attributes matching keys.
  • list or tuple: delete all records matching the elements of keys.
  • bool(keys) == False: raise ValueError.

Invokes the on_delete callback after the data is deleted. If this callback raises an exception then the operation is reverted.

Parameters:
  • keys (dict) – Attributes to match.
  • keys – Fields or element identifiers to match.
exists(keys, context=True)[source]

Check if a record exists.

Parameters:keys – See AbstractStorage.exists.
Returns:True if a record matching keys exists, False otherwise.
Return type:bool
classmethod export_records(keys=None, eids=None)[source]

Export data records.

Constructs a dictionary containing records matching keys or eids and all their associated records. Association fields (model and collection) are not updated and may contain eids of undefined records.

Parameters:
  • keys (dict) – Attributes to match.
  • eids (list) – Record identifiers to match.
Returns:

Dictionary of tables containing records.
Return type:

dict

Example:

{
 'Brewery': {100: {'address': '4615 Hollins Ferry Rd, Halethorpe, MD 21227',
                   'brews': [10, 12, 14]}},
 'Beer': {10: {'origin': 100, 'color': 'gold', 'ibu': 45},
          12: {'origin': 100, 'color': 'dark', 'ibu': 15},
          14: {'origin': 100, 'color': 'pale', 'ibu': 30}}
}

Beer.export_records(eids=[10])

{
 'Brewery': {100: {'address': '4615 Hollins Ferry Rd, Halethorpe, MD 21227',
                   'brews': [10, 12, 14]}},
 'Beer': {10: {'origin': 100, 'color': 'gold', 'ibu': 45}}
}
static import_records(data)[source]

Import data records.

TODO: Docs

match(**kwargs)[source]
messages = {}
one(**kwargs)[source]
classmethod pop_topic(topic)[source]
populate(model, attribute=None, defaults=False, context=True)[source]

Merges associated data into the model record.

Example

Suppose we have the following Person records:

1: {'name': 'Katie', 'friends': [2, 3]}
2: {'name': 'Ryan', 'friends': [1]}
3: {'name': 'John', 'friends': [1]}

Populating Person({'name': 'Katie', 'friends': [2, 3]}) produces this dictionary:

{'name': 'Katie',
 'friends': [Person({'name': 'Ryan', 'friends': [1]}),
             Person({'name': 'John', 'friends': [1]}]})
Parameters:
  • attribute (Optional[str]) – If given, return only the populated attribute.
  • defaults (Optional[bool]) – If given, set undefined attributes to their default values.
Returns:

If attribute is None, a dictionary of controlled data merged with associated records. If attribute is not None, the value of the populated attribute.
Raises:

KeyError – attribute is undefined in the record.
classmethod push_to_topic(topic, message)[source]
search(**kwargs)[source]
unset(fields, keys)[source]

Unset recorded data fields and update associations.

The behavior depends on the type of keys:
  • Record.ElementIdentifier: update the record with that element identifier.
  • dict: update all records with attributes matching keys.
  • list or tuple: apply update to all records matching the elements of keys.
  • bool(keys) == False: raise ValueError.

Invokes the on_update callback after the data is modified. If this callback raises an exception then the operation is reverted.

Parameters:
  • fields (list) – Names of fields to unset.
  • keys – Fields or element identifiers to match.
update(data, keys)[source]

Change recorded data and update associations.

The behavior depends on the type of keys:
  • Record.ElementIdentifier: update the record with that element identifier.
  • dict: update all records with attributes matching keys.
  • list or tuple: apply update to all records matching the elements of keys.
  • bool(keys) == False: raise ValueError.

Invokes the on_update callback after the data is modified. If this callback raises an exception then the operation is reverted.

Parameters:
  • data (dict) – New data for existing records.
  • keys – Fields or element identifiers to match.
taucmdr.mvc.controller.contextualize(function)[source]

Decorator that filters a controller method’s returned records by context requirements.

Wraps the decorated function so that its result (a dict or list of records) is filtered to include only records matching the controller’s active context. Context is a list of (key, value) requirements checked via valid().

taucmdr.mvc.controller.valid(context, record)[source]