3.1. obj_model package

3.1.1. Submodules

3.1.2. obj_model.abstract module

Support for abstract model classes

Author:Jonathan Karr <karr@mssm.edu>
Date:2017-05-23
Copyright:2016, Karr Lab
License:MIT
class obj_model.abstract.AbstractModel(**kwargs)[source]

Bases: obj_model.core.Model

Abstract model base class

class Meta[source]

Bases: obj_model.core.Meta

attribute_order = ()[source]
attributes = {}[source]
frozen_columns = 1[source]
indexed_attrs_tuples = ()[source]
inheritance = (<class 'obj_model.abstract.AbstractModel'>,)[source]
local_attributes = {}[source]
ordering = ()[source]
primary_attribute = None[source]
related_attributes = {}[source]
tabular_orientation = 1[source]
unique_together = ()[source]
verbose_name = 'Abstract model'[source]
verbose_name_plural = 'Abstract models'[source]
objects = <obj_model.core.Manager object>[source]
class obj_model.abstract.AbstractModelMeta[source]

Bases: obj_model.core.ModelMeta, abc.ABCMeta

Abstract model metaclass

3.1.3. obj_model.core module

Database-independent Django-like object model

Many classes contain the methods serialize() and deserialize(), which invert each other. serialize() converts a python object instance into a string representation, whereas deserialize() parses an object’s string representation – as would be stored in a file or spreadsheet representation of a biochemical model – into a python object instance. deserialize() returns an error when the string representation cannot be parsed into the python object. Deserialization methods for related attributes (subclasses of RelatedAttribute) do not get called until all other attributes have been deserialized. In particular, they’re called by obj_model.io.WorkbookReader.link_model. Therefore, they get passed all objects that are not inline, which can then be referenced to deserialize the related attribute.

Author:Jonathan Karr <karr@mssm.edu>
Author:Arthur Goldberg <Arthur.Goldberg@mssm.edu>
Date:2016-12-12
Copyright:2016, Karr Lab
License:MIT
class obj_model.core.Attribute(init_value=None, default=None, default_cleaned_value=None, verbose_name='', help='', primary=False, unique=False, unique_case_insensitive=False)[source]

Bases: object

Model attribute

name[source]

name

Type:str
init_value[source]

initial value

Type:object
default[source]

default value

Type:object
default_cleaned_value[source]

value to replace None values with during cleaning, or function which computes the value to replace None values

Type:object
verbose_name[source]

verbose name

Type:str
help[source]

help string

Type:str
primary[source]

indicate if attribute is primary attribute

Type:bool
unique[source]

indicate if attribute value must be unique

Type:bool
unique_case_insensitive[source]

if true, conduct case-insensitive test of uniqueness

Type:bool
clean(value)[source]

Convert attribute value into the appropriate type

Parameters:value (object) – value of attribute to clean
Returns:tuple of cleaned value and cleaning error
Return type:tuple of object, InvalidAttribute or None
deserialize(value)[source]

Deserialize value

Parameters:value (object) – semantically equivalent representation
Returns:tuple of cleaned value and cleaning error
Return type:tuple of object, InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (object) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:object
get_default()[source]

Get default value for attribute

Returns:initial value
Return type:object
get_default_cleaned_value()[source]

Get value to replace None values with during cleaning

Returns:initial value
Return type:object
get_init_value(obj)[source]

Get initial value for attribute

Parameters:obj (Model) – object whose attribute is being initialized
Returns:initial value
Return type:object
serialize(value)[source]

Serialize value

Parameters:value (object) – Python representation
Returns:simple Python representation
Return type:bool, float, str, or None
set_value(obj, new_value)[source]

Set value of attribute of object

Parameters:
  • obj (Model) – object
  • new_value (object) – new attribute value
Returns:

attribute value

Return type:

object

to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (object) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:object
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, otherwise return a list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

validate_unique(objects, values)[source]

Determine if the attribute values are unique

Parameters:
  • objects (list of Model) – list of Model objects
  • values (list) – list of values
Returns:

None if values are unique, otherwise return a list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

value_equal(val1, val2)[source]

Determine if attribute values are equal

Parameters:
  • val1 (object) – first value
  • val2 (object) – second value
Returns:

True if attribute values are equal

Return type:

bool

class obj_model.core.BooleanAttribute(default=False, default_cleaned_value=None, verbose_name='', help='Enter a Boolean value')[source]

Bases: obj_model.core.LiteralAttribute

Boolean attribute

default[source]

default value

Type:bool
default_cleaned_value[source]

value to replace None values with during cleaning

Type:bool
clean(value)[source]

Convert attribute value into the appropriate type

Parameters:value (object) – value of attribute to clean
Returns:tuple of cleaned value and cleaning error
Return type:tuple of bool, InvalidAttribute or None
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.DateAttribute(none=True, default=None, default_cleaned_value=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.LiteralAttribute

Date attribute

none[source]

if False, the attribute is invalid if its value is None

Type:bool
default[source]

default date

Type:date
default_cleaned_value[source]

value to replace None values with during cleaning, or function which computes the value to replace None values

Type:date
clean(value)[source]

Convert attribute value into the appropriate type

Parameters:value (object) – value of attribute to clean
Returns:(date, None), or (None, InvalidAttribute) reporting error
Return type:tuple
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (str) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:date
serialize(value)[source]

Serialize string

Parameters:value (date) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (date) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:str
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (date) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.DateTimeAttribute(none=True, default=None, default_cleaned_value=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.LiteralAttribute

Datetime attribute

none[source]

if False, the attribute is invalid if its value is None

Type:bool
default[source]

default datetime

Type:datetime
default_cleaned_value[source]

value to replace None values with during cleaning, or function which computes the value to replace None values

Type:datetime
clean(value)[source]

Convert attribute value into the appropriate type

Parameters:value (object) – value of attribute to clean
Returns:tuple of cleaned value and cleaning error
Return type:tuple of datetime, InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (str) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:datetime
serialize(value)[source]

Serialize string

Parameters:value (datetime) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (datetime) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:str
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (datetime) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.EnumAttribute(enum_class, none=False, default=None, default_cleaned_value=None, verbose_name='', help='', primary=False, unique=False, unique_case_insensitive=False)[source]

Bases: obj_model.core.LiteralAttribute

Enumeration attribute

enum_class[source]

subclass of Enum

Type:type
none[source]

if False, the attribute is invalid if its value is None

Type:bool
clean(value)[source]

Convert attribute value into the appropriate type

Parameters:value (object) – value of attribute to clean
Returns:tuple of cleaned value and cleaning error
Return type:tuple of Enum, InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (str) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:Enum
serialize(value)[source]

Serialize enumeration

Parameters:value (Enum) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (Enum) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:str
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.FloatAttribute(min=nan, max=nan, nan=True, default=nan, default_cleaned_value=nan, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.NumericAttribute

Float attribute

default[source]

default value

Type:float
default_cleaned_value[source]

value to replace None values with during cleaning

Type:float
min[source]

minimum value

Type:float
max[source]

maximum value

Type:float
nan[source]

if true, allow nan values

Type:bool
clean(value)[source]

Convert attribute value into the appropriate type

Parameters:value (object) – value of attribute to clean
Returns:tuple of cleaned value and cleaning error
Return type:tuple of float, InvalidAttribute or None
serialize(value)[source]

Serialize float

Parameters:value (float) – Python representation
Returns:simple Python representation
Return type:float
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

value_equal(val1, val2)[source]

Determine if attribute values are equal

Parameters:
  • val1 (object) – first value
  • val2 (object) – second value
Returns:

True if attribute values are equal

Return type:

bool

class obj_model.core.IntegerAttribute(min=None, max=None, default=None, default_cleaned_value=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.NumericAttribute

Integer attribute

default[source]

default value

Type:int
default_cleaned_value[source]

value to replace None values with during cleaning

Type:int
min[source]

minimum value

Type:int
max[source]

maximum value

Type:int
clean(value)[source]

Convert attribute value into the appropriate type

Parameters:value (object) – value of attribute to clean
Returns:tuple of cleaned value and cleaning error
Return type:tuple of int, InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (float) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:int
serialize(value)[source]

Serialize integer

Parameters:value (int) – Python representation
Returns:simple Python representation
Return type:float
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (int) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:float
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, otherwise return list of

errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.InvalidAttribute(attribute, messages, related=False, location=None, value=None)[source]

Bases: object

Represents an invalid attribute and its errors

attribute[source]

invalid attribute

Type:Attribute
messages[source]

list of error messages

Type:list
related[source]

indicates if error is about value or related value

Type:bool
location[source]

a string representation of the attribute’s location in an input file

Type:str
value[source]

invalid input value

Type:str
__str__()[source]

Get string representation of errors

Returns:string representation of errors
Return type:str
set_location_and_value(location, value)[source]

Set the location and value of the attribute

Parameters:
  • location (str) – a string representation of the attribute’s location in an input file
  • value (str) – the invalid input value
class obj_model.core.InvalidModel(model, attributes)[source]

Bases: object

Represents an invalid model, such as a model with an attribute that fails to meet specified constraints

model[source]

Model class

Type:class
attributes[source]

list of invalid attributes and their errors

Type:list
__str__()[source]

Get string representation of errors

Returns:string representation of errors
Return type:str
class obj_model.core.InvalidObject(object, attributes)[source]

Bases: object

Represents an invalid object and its errors

object[source]

invalid object

Type:object
attributes[source]

list of invalid attributes and their errors

Type:list
__str__()[source]

Get string representation of errors

Returns:string representation of errors
Return type:str
class obj_model.core.InvalidObjectSet(invalid_objects, invalid_models)[source]

Bases: object

Represents a list of invalid objects and invalid models

invalid_objects[source]

list of invalid objects

Type:list
invalid_models[source]

list of invalid models

Type:list
__str__()[source]

Get string representation of errors

Returns:string representation of errors
Return type:str
get_model_errors_by_model()[source]

Get model errors grouped by models

Returns:InvalidModel: dictionary of model errors, grouped by model
Return type:dict of Model
get_object_errors_by_model()[source]

Get object errors grouped by model

Returns:list of InvalidObject: dictionary of object errors, grouped by model
Return type:dict of Model
class obj_model.core.LiteralAttribute(init_value=None, default=None, default_cleaned_value=None, verbose_name='', help='', primary=False, unique=False, unique_case_insensitive=False)[source]

Bases: obj_model.core.Attribute

Base class for literal attributes (Boolean, enumeration, float, integer, string, etc.)

deserialize(value)[source]

Deserialize value

Parameters:value (object) – semantically equivalent representation
Returns:tuple of cleaned value and cleaning error
Return type:tuple of object, InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (object) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:object
serialize(value)[source]

Serialize value

Parameters:value (object) – Python representation
Returns:simple Python representation
Return type:bool, float, str, or None
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (object) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:object
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, otherwise return a list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.LocalAttribute(attr, primary_class, is_primary=True)[source]

Bases: object

Meta data about an local attribute in a class

attr[source]

attribute

Type:Attribute
cls[source]

class which owns this attribute

Type:type
name (:obj:`str`

name of the attr in cls

related_class[source]

other class which is related to this attribute

Type:type
related_name[source]

name of this attribute in related_cls

Type:str
primary_class[source]

class in which this attribute was defined

Type:type
primary_name[source]

name of this attribute in primary_cls

Type:str
secondary_class[source]

related class to primary_cls

Type:type
secondary_name[source]

name of this attribute in secondary_cls

Type:str
is_primary[source]

True if this attr was defined in cls (cls`=:obj:`primary_cls)

Type:bool

True if this attribute is an instance of RelatedAttribute

Type:bool
is_related_to_many (obj

bool): True if the value of this attribute is a list (*-to-many relationship)

class obj_model.core.LongStringAttribute(min_length=0, max_length=4294967295, default='', default_cleaned_value='', verbose_name='', help='', primary=False, unique=False, unique_case_insensitive=False)[source]

Bases: obj_model.core.StringAttribute

Long string attribute

class obj_model.core.Manager(cls)[source]

Bases: object

Enable O(1) dictionary-based searching of a Model’s instances

This class is inspired by Django’s Manager class. An instance of Manger is associated with each Model and accessed as the class attribute objects (as in Django). The tuples of attributes to index are specified by the indexed_attrs_tuples attribute of core.Model.Meta, which contains a tuple of tuples of attributes to index. Model`s with empty `indexed_attrs_tuples attributes incur no overhead from Manager.

Manager maintains a dictionary for each indexed attribute tuple, and a reverse index from each Model instance to its indexed attribute tuple keys.

These data structures support * O(1) get operations for Model instances indexed by a indexed attribute tuple * O(1) Model instance insert and update operations

cls[source]

the Model class which is being managed

Type:class
_new_instances[source]

set of all new instances of cls that have not been indexed, stored as weakrefs, so Model’s that are otherwise unused can be garbage collected

Type:WeakSet
_index_dicts[source]

indices that enable lookup of Model instances from their Meta.indexed_attrs_tuples mapping: <attr names tuple> -> <attr values tuple> -> WeakSet(<model_obj instances>)

Type:dict
_reverse_index[source]

a reverse index that provides all of each Model’s indexed attribute tuple keys mapping: <model_obj instances> -> <attr names tuple> -> <attr values tuple>

Type:WeakKeyDictionary
num_ops_since_gc[source]

number of operations since the last gc of weaksets

Type:int
GC_PERIOD = 1000[source]
all()[source]

Provide all instances of the Model managed by this Manager

Returns:a list of all instances of the managed Model or None if the Model is not indexed
Return type:list of Model
clear_new_instances()[source]

Clear the set of new instances that have not been inserted

get(**kwargs)[source]

Get the Model instance(s) that match the attribute name,value pair(s) in kwargs

The keys in kwargs must correspond to an entry in the Model’s indexed_attrs_tuples. Warning: this method is non-deterministic. To obtain Manager’s O(1) performance, Model instances in the index are stored in WeakSet’s. Therefore, the order of elements in the list returned is not reproducible. Applications that need reproducibility must deterministically order elements in lists returned by this method.

Parameters:

kwargs (dict) – keyword args mapping from attribute name(s) to value(s)

Returns:

a list of Model instances whose indexed attribute tuples have the values in kwargs; otherwise None, indicating no match

Return type:

list of Model

Raises:
  • ValueError – if no arguments are provided, or the attribute name(s) in kwargs.keys()
  • do not correspond to an indexed attribute tuple of the Model
get_one(**kwargs)[source]

Get one Model instance that matches the attribute name,value pair(s) in kwargs

Uses get.

Parameters:kwargs (dict) – keyword args mapping from attribute name(s) to value(s)
Returns:a Model instance whose indexed attribute tuples have the values in kwargs, or None if no Model satisfies the query
Return type:Model
Raises:ValueError – if get raises an exception, or if multiple instances match.
insert_all_new()[source]

Insert all new instances of this Manager’s Model’s into the search indices

reset()[source]

Reset this Manager

Empty Manager’s indices. Since Manager globally indexes all instances of a Model, this method is useful when multiple models are loaded sequentially.

upsert(model_obj)[source]

Update the indices for model_obj that are used to search on indexed attribute tuples

Upsert means update or insert. Update the indices if model_obj is already stored, otherwise insert model_obj. Users of Manager are responsible for calling this method if model_obj changes.

Costs O(I) where I is the number of indexed attribute tuples for the Model.

Parameters:model_obj (Model) – a Model instance
upsert_all()[source]

Upsert the indices for all of this Manager’s Model’s

class obj_model.core.ManyToManyAttribute(related_class, related_name='', default=[], default_cleaned_value=[], related_default=[], min_related=0, max_related=inf, min_related_rev=0, max_related_rev=inf, verbose_name='', verbose_related_name='', help='')[source]

Bases: obj_model.core.RelatedAttribute

Represents a many-to-many relationship between two types of objects.

deserialize(values, objects, decoded=None)[source]

Deserialize value

Parameters:
  • values (object) – String representation
  • objects (dict) – dictionary of objects, grouped by model
  • decoded (dict, optional) – dictionary of objects that have already been decoded
Returns:

tuple of cleaned value and cleaning error

Return type:

tuple of object, InvalidAttribute or None

get_init_value(obj)[source]

Get initial value for attribute

Parameters:obj (Model) – object whose attribute is being initialized
Returns:initial value
Return type:object

Get initial related value for attribute

Parameters:obj (object) – object whose attribute is being initialized
Returns:initial value
Return type:value (object)
Raises:ValueError – if related property is not defined
related_validate(obj, value)[source]

Determine if value is a valid value of the related attribute

Parameters:
  • obj (Model) – object being validated
  • value (list of Model) – value to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

serialize(value, encoded=None)[source]

Serialize related object

Parameters:
  • value (list of Model) – Python representation
  • encoded (dict, optional) – dictionary of objects that have already been encoded
Returns:

simple Python representation

Return type:

str

Update the values of the related attributes of the attribute

Parameters:
  • obj (object) – object whose attribute should be set
  • new_values (list) – value of the attribute
Returns:

value of the attribute

Return type:

list

Raises:

ValueError – if related property is not defined

set_value(obj, new_values)[source]

Get value of attribute of object

Parameters:
  • obj (Model) – object
  • new_values (list) – new attribute value
Returns:

new attribute value

Return type:

list

validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (list of Model) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.ManyToManyRelatedManager(object, attribute, related=True)[source]

Bases: obj_model.core.RelatedManager

Represent values and related values of related attributes

append(value, propagate=True)[source]

Add value to list

Parameters:
  • value (object) – value
  • propagate (bool, optional) – propagate change to related attribute
Returns:

self

Return type:

RelatedManager

remove(value, update_list=True, propagate=True)[source]

Remove value from list

Parameters:
  • value (object) – value
  • update_list (bool, optional) – update list
  • propagate (bool, optional) – propagate change to related attribute
Returns:

self

Return type:

RelatedManager

class obj_model.core.ManyToOneAttribute(related_class, related_name='', default=None, default_cleaned_value=None, related_default=[], min_related=0, min_related_rev=0, max_related_rev=inf, verbose_name='', verbose_related_name='', help='')[source]

Bases: obj_model.core.RelatedAttribute

Represents a many-to-one relationship between two types of objects. This is analagous to a foreign key relationship in a database.

deserialize(value, objects, decoded=None)[source]

Deserialize value

Parameters:
  • value (str) – String representation
  • objects (dict) – dictionary of objects, grouped by model
  • decoded (dict, optional) – dictionary of objects that have already been decoded
Returns:

tuple of cleaned value and cleaning error

Return type:

tuple of object, InvalidAttribute or None

Get initial related value for attribute

Parameters:obj (object) – object whose attribute is being initialized
Returns:initial value
Return type:value (object)
Raises:ValueError – if related property is not defined
related_validate(obj, value)[source]

Determine if value is a valid value of the related attribute

Parameters:
  • obj (Model) – object being validated
  • value (list of Model) – value to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

serialize(value, encoded=None)[source]

Serialize related object

Parameters:
  • value (Model) – Python representation
  • encoded (dict, optional) – dictionary of objects that have already been encoded
Returns:

simple Python representation

Return type:

str

Update the values of the related attributes of the attribute

Parameters:
  • obj (object) – object whose attribute should be set
  • new_values (list) – value of the attribute
Returns:

value of the attribute

Return type:

list

Raises:

ValueError – if related property is not defined

set_value(obj, new_value)[source]

Update the values of the related attributes of the attribute

Parameters:
  • obj (object) – object whose attribute should be set
  • new_value (Model) – new attribute value
Returns:

new attribute value

Return type:

Model

validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (Model) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.ManyToOneRelatedManager(object, attribute)[source]

Bases: obj_model.core.RelatedManager

Represent values of related attributes

append(value, propagate=True)[source]

Add value to list

Parameters:
  • value (object) – value
  • propagate (bool, optional) – propagate change to related attribute
Returns:

self

Return type:

RelatedManager

remove(value, update_list=True, propagate=True)[source]

Remove value from list

Parameters:
  • value (object) – value
  • propagate (bool, optional) – propagate change to related attribute
Returns:

self

Return type:

RelatedManager

class obj_model.core.Model(**kwargs)[source]

Bases: object

Base object model

_source[source]

file location, worksheet, column, and row where the object was defined

Type:ModelSource
objects[source]

a Manager that supports searching for Model instances

Type:Manager
DEFAULT_INDENT = 3[source]
DEFAULT_MAX_DEPTH = 2[source]
class Meta[source]

Bases: object

Meta data for Model

attributes[source]

attributes

Type:collections.OrderedDict
related_attributes[source]

attributes declared in related objects

Type:collections.OrderedDict
local_attributes[source]

dictionary that maps the names of all local attributes to their instances, including attributes defined in this class and attributes defined in related classes

Type:collections.OrderedDict
primary_attribute[source]

attribute with primary = True

Type:Attribute
unique_together[source]

controls what tuples of attribute values must be unique

Type:tuple
indexed_attrs_tuples[source]

tuples of attributes on which instances of this Model will be indexed by the Model’s Manager

Type:tuple
attribute_order[source]

tuple of attribute names, in the order in which they should be displayed

Type:tuple
verbose_name[source]

verbose name to refer to an instance of the model

Type:str
verbose_name_plural[source]

plural verbose name for multiple instances of the model

Type:str
tabular_orientation[source]

orientation of model objects in table (e.g. Excel)

Type:TabularOrientation
frozen_columns[source]

number of Excel columns to freeze

Type:int
inheritance[source]

tuple of all superclasses

Type:tuple
ordering[source]

controls the order in which objects should be printed when serialized

Type:tuple
attribute_order = ()[source]
attributes = None[source]
frozen_columns = 1[source]
indexed_attrs_tuples = ()[source]
inheritance = None[source]
ordering = None[source]
primary_attribute = None[source]
related_attributes = None[source]
tabular_orientation = 1[source]
unique_together = ()[source]
verbose_name = ''[source]
verbose_name_plural = ''[source]
__enter__()[source]

Enter context

__exit__(type, value, traceback)[source]

Exit context

__setattr__(attr_name, value, propagate=True)[source]

Set attribute and validate any unique attribute constraints

Parameters:
  • attr_name (str) – attribute name
  • value (object) – value
  • propagate (bool, optional) – propagate change through attribute set_value and set_related_value
__str__()[source]

Get the string representation of an object

Returns:string representation of object
Return type:str

Determine if the immediate related attributes of the class can be serialized

Returns:True if the related attributes can be serialized
Return type:bool
clean()[source]

Clean all of this Model’s attributes

Returns:
None if the object is valid,
otherwise return a list of errors as an instance of InvalidObject
Return type:InvalidObject or None
copy()[source]

Create a copy

Returns:model copy
Return type:Model
classmethod deserialize(value, objects)[source]

Deserialize value

Parameters:
  • value (str) – String representation
  • objects (dict) – dictionary of objects, grouped by model
Returns:

tuple of cleaned value

and cleaning error

Return type:

tuple of object, InvalidAttribute or None

difference(other)[source]

Get the semantic difference between two models

Parameters:other (Model) – other Model
Returns:difference message
Return type:str
classmethod from_dict(json, decode_primary_objects=True, primary_objects=None, decoded=None)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of an object that is compatible with JSON and YAML, including references to objects through __id keys.

Parameters:
  • json (dict) – simple Python representation of the object
  • decode_primary_objects (bool, optional) – if True, decode primary classes otherwise just look up objects by their IDs
  • primary_objects (list, optional) – list of instances of primary classes (i.e. non-line classes)
  • decoded (dict, optional) – dictionary of objects that have already been decoded
Returns:

decoded object

Return type:

Model

classmethod get_attrs(type=None, forward=True, reverse=True)[source]

Get attributes of a type, optionally including attributes from related classes. By default, return all attributes.

Parameters:
  • type (type or tuple of type, optional) – type of attributes to get
  • forward (bool, optional) – if True, include attributes from class
  • reverse (bool, optional) – if True, include attributes from related classes
Returns:

dictionary of the names and instances

of matching attributes

Return type:

dict of str, Attribute

get_attrs_by_val(type=None, reverse=True, include=None, exclude=None)[source]

Get attributes whose type is type and values are in include and not exclude, optionally including attributes from related classes. By default, get all attributes.

Parameters:
  • type (type or tuple of type, optional) – type of attributes to get
  • reverse (bool, optional) – if True, include attributes from related classes
  • include (list, optional) – list of values to filter for
  • exclude (list, optional) – list of values to filter out
Returns:

dictionary of the names and instances

of matching attributes

Return type:

dict of str, Attribute

get_empty_literal_attrs()[source]

Get empty (None, ‘’, or NaN) literal attributes

Returns:
dictionary of the names and instances
of empty literal attributes
Return type:dict of str, Attribute

Get empty (None or []) related attributes

Parameters:reverse (bool, optional) – if True, include attributes from related classes
Returns:
dictionary of the names and instances
of empty related attributes
Return type:dict of str, Attribute
classmethod get_literal_attrs()[source]

Get literal attributes

Returns:
dictionary of the names and instances
of literal attributes
Return type:dict of str, Attribute
classmethod get_manager()[source]

Get the manager for the model

Returns:manager
Return type:Manager
get_nested_attr(attr_path)[source]

Get the value of an attribute or a nested attribute of a model

Parameters:attr_path (list of list of str) – the path to an attribute or nested attribute of a model
Returns:value of the attribute or nested attribute
Return type:Object
get_non_empty_literal_attrs()[source]

Get non-empty (None, ‘’, or NaN) literal attributes

Returns:
dictionary of the names and instances
of non-empty literal attributes
Return type:dict of str, Attribute

Get non-empty (None or []) related attributes

Parameters:reverse (bool, optional) – if True, include attributes from related classes
Returns:
dictionary of the names and instances
of non-empty related attributes
Return type:dict of str, Attribute
get_primary_attribute()[source]

Get value of primary attribute

Returns:value of primary attribute
Return type:object

Get all related objects

Returns:related objects
Return type:set of Model

Get related attributes

Parameters:reverse (bool, optional) – if True, include attributes from related classes
Returns:
dictionary of the names and instances
of related attributes
Return type:dict of str, Attribute
classmethod get_sort_key(object, attr_name)[source]

Get sort key for Model instance object based on cls.Meta.ordering

Parameters:
  • object (Model) – Model instance
  • attr_name (str) – attribute name
Returns:

sort key for object

Return type:

object

get_source(attr_name)[source]

Get file location of attribute with name attr_name

Provide the type, filename, worksheet, row, and column of attr_name. Row and column use 1-based counting. Column is provided in Excel format if the file was a spreadsheet.

Parameters:attr_name (str) – attribute name
Returns:tuple of (type, basename, worksheet, row, column)
Raises:ValueError if the location of attr_name is unknown
has_attr_vals(_Model__type=None, **kwargs)[source]

Check if the type and values of the attributes of an object match a set of conditions

Parameters:__type (types.TypeType or tuple of types.TypeType) – subclass(es) of Model
:param **kwargs (dict of str: object): dictionary of attribute name/value pairs to find matching
object or create new object
Returns:
True if the object is an instance of __type and the
the values of the attributes of the object match kwargs
Return type:bool
is_equal(other)[source]

Determine whether two models are semantically equal

Parameters:other (Model) – object to compare
Returns:True if objects are semantically equal, else False
Return type:bool
classmethod is_serializable()[source]

Determine if the class (and its related classes) can be serialized

Raises:boolTrue if the class can be serialized
normalize()[source]

Normalize an object into a canonical form. Specifically, this method sorts the RelatedManagers into a canonical order because their order has no semantic meaning. Importantly, this canonical form is reproducible. Thus, this canonical form facilitates reproducible computations on top of Model objects.

pformat(max_depth=2, indent=3)[source]

Return a human-readable string representation of this Model.

Follows the graph of related Model’s up to a depth of max_depth. Model’s at depth max_depth+1 are represented by ‘<class name>: …’, while deeper Model’s are not traversed or printed. Re-encountered Model’s do not get printed, and are indicated by ‘<attribute name>: –’. Attributes that are related or iterable are indented.

For example, we have:

Model1_classname:       # Each model starts with its classname, followed by a list of
    attr1: value1           # attribute names & values.
    attr2: value2
    attr3:                  # Reference attributes can point to other Models; we indent these under the attribute name
        Model2_classname:   # Reference attribute attr3 contains Model2;
            ...                 # its attributes follow.
    attr4:
        Model3_classname:   # An iteration over reference attributes is a list at constant indentation:
            ...
    attr5:
        Model2_classname: --    # Traversing the Model network may re-encounter a Model; they're listed with '--'
    attr6:
        Model5_classname:
            attr7:
                Model5_classname: ...   # The size of the output is controlled with max_depth;
                                        # models encountered at depth = max_depth+1 are shown with '...'
Parameters:
  • max_depth (int, optional) – the maximum depth to which related Model’s should be printed
  • indent (int, optional) – number of spaces to indent
Returns:

obj:str: readable string representation of this Model

pprint(stream=None, max_depth=2, indent=3)[source]
serialize()[source]

Get value of primary attribute

Returns:value of primary attribute
Return type:str
set_nested_attr(attr_path, value)[source]

Set the value of an attribute or a nested attribute of a model

Parameters:
  • attr_path (list of list of str) – the path to an attribute or nested attribute of a model
  • value (object) – new value
Returns:

the same model with the value of an attribute

modified

Return type:

Model

set_source(path_name, sheet_name, attribute_seq, row)[source]

Set metadata about source of the file, worksheet, columns, and row where the object was defined

Parameters:
  • path_name (str) – pathname of source file for object
  • sheet_name (str) – name of spreadsheet containing source data for object
  • attribute_seq (list) – sequence of attribute names in source file; blank values indicate attributes that were ignored
  • row (int) – row number of object in its source file
classmethod sort(objects)[source]

Sort list of Model objects

Parameters:objects (list of Model) – list of objects
Returns:sorted list of objects
Return type:list of Model
to_dict(encode_primary_objects=True, max_depth=inf, encoded=None)[source]

Encode an object using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML. Use __id keys to avoid infinite recursion by encoding each object once and referring to objects by their __id for each repeated reference.

Parameters:
  • encode_primary_objects (bool, optional) – if True, encode primary classes otherwise just encode their IDs
  • max_depth (int, optional) – maximum depth to serialize
  • encoded (dict, optional) – objects that have already been encoded and their assigned JSON identifiers
Returns:

simple Python representation of the object

Return type:

dict

validate()[source]

Determine if the object is valid

Returns:
None if the object is valid,
otherwise return a list of errors as an instance of InvalidObject
Return type:InvalidObject or None

Validate attribute values

Raises:ValueError – if related attributes are not valid (e.g. if a class that is the subject of a relationship does not have a primary attribute)
classmethod validate_unique(objects)[source]

Validate attribute uniqueness

Parameters:objects (list of Model) – list of objects
Returns:list of invalid attributes and their errors
Return type:InvalidModel or None
class obj_model.core.ModelMeta[source]

Bases: type

static __new__(metacls, name, bases, namespace)[source]
Parameters:
  • metacls (Model) – Model, or a subclass of Model
  • name (str) – Model class name
  • bases (tuple) – tuple of superclasses
  • namespace (dict) – namespace of Model class definition
Returns:

a new instance of Model, or a subclass of Model

Return type:

Model

create_model_manager()[source]

Create a Manager for this Model

The Manager is accessed via a Model’s objects attribute

cls[source]

the Model class which is being managed

Type:Class
init_attribute_order()[source]

Initialize the order in which the attributes should be printed across Excel columns

init_attributes()[source]

Initialize attributes

init_inheritance()[source]

Create tuple of this model and superclasses which are subclasses of Model

init_ordering()[source]

Initialize how to sort objects

init_primary_attribute()[source]

Initialize the primary attribute of a model

Initialize related attributes

init_verbose_names()[source]

Initialize the singular and plural verbose names of a model

normalize_attr_tuples(attribute)[source]

Normalize a tuple of tuples of attribute names

Parameters:attribute (str) – the name of the attribute to validate and normalize
static normalize_tuple_of_tuples_of_attribute_names(tuple_of_tuples_of_attribute_names)[source]

Normalize a tuple of tuples of attribute names by sorting each member tuple

Enables simple indexing and searching of tuples

Parameters:tuple_of_tuples_of_attribute_names (tuple) – a tuple of tuples of attribute names
Returns:a tuple of sorted tuples of attribute names
Return type:tuple
classmethod validate_attr_tuples(name, bases, namespace, meta_attribute_name)[source]

Validate a tuple of tuples of attribute names

Parameters:meta_attribute_name (str) – the name of the attribute to validate and normalize
Raises:ValueError – if attributes are not valid
classmethod validate_attribute_inheritance(name, bases, namespace)[source]

Check attribute inheritance

Raises:ValueError – if subclass overrides a superclass attribute (instance of Attribute) with an incompatible attribute (i.e. an attribute that is not a subclass of the class of the super class’ attribute)
classmethod validate_attributes(name, bases, namespace)[source]

Validate attribute values

Raises:ValueError – if attributes are not valid
classmethod validate_primary_attribute(name, bases, namespace)[source]

Check the attributes

Raises:ValueError – if there are multiple primary attributes

Check the related attributes

Raises:ValueError – if an OneToManyAttribute or ManyToOneAttribute has a related_name equal to its name
class obj_model.core.ModelSource(path_name, sheet_name, attribute_seq, row)[source]

Bases: object

Represents the file, sheet, columns, and row where a Model instance was defined

path_name[source]

pathname of source file for object

Type:str
sheet_name[source]

name of spreadsheet containing source data for object

Type:str
attribute_seq[source]

sequence of attribute names in source file; blank values indicate attributes that were ignored

Type:list
row[source]

row number of object in its source file

Type:int
class obj_model.core.NumericAttribute(init_value=None, default=None, default_cleaned_value=None, verbose_name='', help='', primary=False, unique=False, unique_case_insensitive=False)[source]

Bases: obj_model.core.LiteralAttribute

Base class for numeric literal attributes (float, integer)

exception obj_model.core.ObjModelWarning[source]

Bases: UserWarning

obj_model warning

class obj_model.core.OneToManyAttribute(related_class, related_name='', default=[], default_cleaned_value=[], related_default=None, min_related=0, max_related=inf, min_related_rev=0, verbose_name='', verbose_related_name='', help='')[source]

Bases: obj_model.core.RelatedAttribute

Represents a one-to-many relationship between two types of objects. This is analagous to a foreign key relationship in a database.

deserialize(values, objects, decoded=None)[source]

Deserialize value

Parameters:
  • values (object) – String representation
  • objects (dict) – dictionary of objects, grouped by model
  • decoded (dict, optional) – dictionary of objects that have already been decoded
Returns:

tuple of cleaned value and cleaning error

Return type:

tuple of object, InvalidAttribute or None

get_init_value(obj)[source]

Get initial value for attribute

Parameters:obj (Model) – object whose attribute is being initialized
Returns:initial value
Return type:object
related_validate(obj, value)[source]

Determine if value is a valid value of the related attribute

Parameters:
  • obj (Model) – object being validated
  • value (Model) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

serialize(value, encoded=None)[source]

Serialize related object

Parameters:
  • value (list of Model) – Python representation
  • encoded (dict, optional) – dictionary of objects that have already been encoded
Returns:

simple Python representation

Return type:

str

Update the values of the related attributes of the attribute

Parameters:
  • obj (object) – object whose attribute should be set
  • new_value (Model) – new attribute value
Returns:

new attribute value

Return type:

Model

Raises:

ValueError – if related property is not defined

set_value(obj, new_values)[source]

Update the values of the related attributes of the attribute

Parameters:
  • obj (object) – object whose attribute should be set
  • new_values (list) – value of the attribute
Returns:

value of the attribute

Return type:

list

validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (list of Model) – value to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.OneToManyRelatedManager(object, attribute)[source]

Bases: obj_model.core.RelatedManager

Represent values of related attributes

append(value, propagate=True)[source]

Add value to list

Parameters:
  • value (object) – value
  • propagate (bool, optional) – propagate change to related attribute
Returns:

self

Return type:

RelatedManager

remove(value, update_list=True, propagate=True)[source]

Remove value from list

Parameters:
  • value (object) – value
  • propagate (bool, optional) – propagate change to related attribute
Returns:

self

Return type:

RelatedManager

class obj_model.core.OneToOneAttribute(related_class, related_name='', default=None, default_cleaned_value=None, related_default=None, min_related=0, min_related_rev=0, verbose_name='', verbose_related_name='', help='')[source]

Bases: obj_model.core.RelatedAttribute

Represents a one-to-one relationship between two types of objects.

deserialize(value, objects, decoded=None)[source]

Deserialize value

Parameters:
  • value (str) – String representation
  • objects (dict) – dictionary of objects, grouped by model
  • decoded (dict, optional) – dictionary of objects that have already been decoded
Returns:

tuple of cleaned value and cleaning error

Return type:

tuple of object, InvalidAttribute or None

related_validate(obj, value)[source]

Determine if value is a valid value of the related attribute

Parameters:
  • obj (Model) – object being validated
  • value (list of Model) – value to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

serialize(value, encoded=None)[source]

Serialize related object

Parameters:
  • value (Model) – Python representation
  • encoded (dict, optional) – dictionary of objects that have already been encoded
Returns:

simple Python representation

Return type:

str

Update the values of the related attributes of the attribute

Parameters:
  • obj (object) – object whose attribute should be set
  • new_value (Model) – value of the attribute
Returns:

value of the attribute

Return type:

Model

Raises:

ValueError – if related property is not defined or the attribute of new_value is not None

set_value(obj, new_value)[source]

Update the values of the related attributes of the attribute

Parameters:
  • obj (object) – object whose attribute should be set
  • new_value (Model) – new attribute value
Returns:

new attribute value

Return type:

Model

Raises:

ValueError – if related attribute of new_value is not None

validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (Model) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.PositiveFloatAttribute(max=nan, nan=True, default=nan, default_cleaned_value=nan, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.FloatAttribute

Positive float attribute

validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.PositiveIntegerAttribute(max=None, default=None, default_cleaned_value=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.IntegerAttribute

Positive integer attribute

validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.RegexAttribute(pattern, flags=0, min_length=0, max_length=None, default='', default_cleaned_value='', verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.StringAttribute

Regular expression attribute

pattern[source]

regular expression pattern

Type:str
flags[source]

regular expression flags

Type:int
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.RelatedAttribute(related_class, related_name='', init_value=None, default=None, default_cleaned_value=None, related_init_value=None, related_default=None, min_related=0, max_related=inf, min_related_rev=0, max_related_rev=inf, verbose_name='', verbose_related_name='', help='')[source]

Bases: obj_model.core.Attribute

Attribute which represents relationships with other objects

primary_class[source]

parent class

Type:class
related_class[source]

related class

Type:class
related_name[source]

name of related attribute on related_class

Type:str

verbose related name

Type:str
related_init_value[source]

initial value of related attribute

Type:object
related_default[source]

default value of related attribute

Type:object

minimum number of related objects in the forward direction

Type:int

maximum number of related objects in the forward direction

Type:int

minimum number of related objects in the reverse direction

Type:int

maximum number of related objects in the reverse direction

Type:int
deserialize(value, objects, decoded=None)[source]

Deserialize value

Parameters:
  • values (object) – String representation
  • objects (dict) – dictionary of objects, grouped by model
  • decoded (dict, optional) – dictionary of objects that have already been decoded
Returns:

tuple of cleaned value and cleaning error

Return type:

tuple of object, InvalidAttribute or None

from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (object) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:object

Get default related value for attribute

Parameters:obj (Model) – object whose attribute is being initialized
Returns:initial value
Return type:object
Raises:ValueError – if related property is not defined

Get initial related value for attribute

Parameters:obj (object) – object whose attribute is being initialized
Returns:initial value
Return type:value (object)
Raises:ValueError – if related property is not defined
related_validate(obj, value)[source]

Determine if value is a valid value of the related attribute

Parameters:
  • obj (Model) – object to validate
  • value (list) – value to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

serialize(value, encoded=None)[source]

Serialize related object

Parameters:
  • value (Model) – Python representation
  • encoded (dict, optional) – dictionary of objects that have already been encoded
Returns:

simple Python representation

Return type:

str

Update the values of the related attributes of the attribute

Parameters:
  • obj (object) – object whose attribute should be set
  • new_values (object) – value of the attribute
Returns:

value of the attribute

Return type:

object

to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (object) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:object
class obj_model.core.RelatedManager(object, attribute, related=True)[source]

Bases: list

Represent values and related values of related attributes

object[source]

model instance

Type:Model
attribute[source]

attribute

Type:Attribute
related[source]

is related attribute

Type:bool
add(value, **kwargs)[source]

Add value to list

Parameters:value (object) – value
Returns:self
Return type:RelatedManager
append(value, **kwargs)[source]

Add value to list

Parameters:value (object) – value
Returns:self
Return type:RelatedManager
clear()[source]

Remove all elements from list

Returns:self
Return type:RelatedManager
create(_RelatedManager__type=None, **kwargs)[source]

Create instance of primary class and add to list

Parameters:__type (types.TypeType or tuple of types.TypeType) – subclass(es) of Model

:param kwargs (dict of str: object): dictionary of attribute name/value pairs

Returns:created object
Return type:Model
Raises:ValueError – if keyword argument is not an attribute of the class
difference_update(values)[source]

Retain only values of list not in values

Parameters:values (list) – values to difference with list
Returns:self
Return type:RelatedManager
discard(value)[source]

Remove value from list if value in list

Parameters:value (object) – value
Returns:self
Return type:RelatedManager
extend(values)[source]

Add values to list

Parameters:values (list) – values to add to list
Returns:self
Return type:RelatedManager
get(_RelatedManager__type=None, **kwargs)[source]

Get related objects by attribute/value pairs and, optionally, only return matches that are also instances of Model subclass __type.

Parameters:__type (types.TypeType or tuple of types.TypeType) – subclass(es) of Model
:param **kwargs (dict of str: object): dictionary of attribute name/value pairs to find matching
objects
Returns:matching instances of Model
Return type:list of Model
get_one(_RelatedManager__type=None, **kwargs)[source]

Get a related object by attribute/value pairs; report an error if multiple objects match and, optionally, only return matches that are also instances of Model subclass __type.

Parameters:__type (types.TypeType or tuple of types.TypeType) – subclass(es) of Model
:param **kwargs (dict of str: object): dictionary of attribute name/value pairs to find matching
objects
Returns:matching instance of Model, or None if no matching instance
Return type:Model or None
Raises:ValueError – if multiple matching objects
get_or_create(_RelatedManager__type=None, **kwargs)[source]

Get or create a related object by attribute/value pairs. Optionally, only get or create instances of Model subclass __type.

Parameters:__type (types.TypeType or tuple of types.TypeType) – subclass(es) of Model
:param **kwargs (dict of str: object): dictionary of attribute name/value pairs to find matching
object or create new object
Returns:existing or new object
Return type:Model
index(*args, **kwargs)[source]

Get related object index by attribute/value pairs

Parameters:
  • *args (list of Model) – object to find
  • **kwargs (dict of str, object) – dictionary of attribute name/value pairs to find matching objects
Returns:

index of matching object

Return type:

int

Raises:

ValueError – if no argument or keyword argument is provided, if argument and keyword arguments are both provided, if multiple arguments are provided, if the keyword attribute/value pairs match no object, or if the keyword attribute/value pairs match multiple objects

intersection_update(values)[source]

Retain only intersection of list and values

Parameters:values (list) – values to intersect with list
Returns:self
Return type:RelatedManager
pop(i=-1)[source]

Remove an arbitrary element from the list

Parameters:i (int, optional) – index of element to remove
Returns:removed element
Return type:object
symmetric_difference_update(values)[source]

Retain values in only one of list and values

Parameters:values (list) – values to difference with list
Returns:self
Return type:RelatedManager
update(values)[source]

Add values to list

Parameters:values (list) – values to add to list
Returns:self
Return type:RelatedManager
exception obj_model.core.SchemaWarning[source]

Bases: obj_model.core.ObjModelWarning

Schema warning

class obj_model.core.SlugAttribute(verbose_name='', help=None, primary=True, unique=True)[source]

Bases: obj_model.core.RegexAttribute

Slug attribute to be used for string IDs

class obj_model.core.StringAttribute(min_length=0, max_length=255, default='', default_cleaned_value='', verbose_name='', help='', primary=False, unique=False, unique_case_insensitive=False)[source]

Bases: obj_model.core.LiteralAttribute

String attribute

default[source]

default value

Type:str
default_cleaned_value[source]

value to replace None values with during cleaning

Type:str
min_length[source]

minimum length

Type:int
max_length[source]

maximum length

Type:int
clean(value)[source]

Convert attribute value into the appropriate type

Parameters:value (object) – value of attribute to clean
Returns:tuple of cleaned value and cleaning error
Return type:tuple of str, InvalidAttribute or None
serialize(value)[source]

Serialize string

Parameters:value (str) – Python representation
Returns:simple Python representation
Return type:str
validate(obj, value)[source]

Determine if value is a valid value for this StringAttribute

Parameters:
  • obj (Model) – class being validated
  • value (object) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.TabularOrientation[source]

Bases: enum.Enum

Describes a table’s orientation

  • row: the first row contains attribute names; subsequents rows store objects
  • column: the first column contains attribute names; subsequents columns store objects
  • inline: a cell contains a table, as a comma-separated list for example
column = 2[source]
inline = 3[source]
row = 1[source]
class obj_model.core.TimeAttribute(none=True, default=None, default_cleaned_value=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.LiteralAttribute

Time attribute

none[source]

if False, the attribute is invalid if its value is None

Type:bool
default[source]

default time

Type:time
default_cleaned_value[source]

value to replace None values with during cleaning, or function which computes the value to replace None values

Type:time
clean(value)[source]

Convert attribute value into the appropriate type

Parameters:value (object) – value of attribute to clean
Returns:tuple of cleaned value and cleaning error
Return type:tuple of time, InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (str) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:time
serialize(value)[source]

Serialize string

Parameters:value (time) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (time) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:str
validate(obj, value)[source]

Determine if value is a valid value of the attribute

Parameters:
  • obj (Model) – object being validated
  • value (time) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of InvalidAttribute

Return type:

InvalidAttribute or None

class obj_model.core.UrlAttribute(min_length=0, verbose_name='URL', help='Enter a valid URL', primary=False, unique=False)[source]

Bases: obj_model.core.RegexAttribute

URL attribute to be used for URLs

class obj_model.core.Validator[source]

Bases: object

Engine to validate sets of objects

clean(objects)[source]

Clean a list of objects and return their errors

Parameters:object (list of Model) – list of objects
Returns:list of invalid objects/models and their errors
Return type:InvalidObjectSet or None
run(objects, get_related=False)[source]

Validate a list of objects and return their errors

Parameters:
  • objects (Model or list of Model) – object or list of objects
  • get_related (bool, optional) – if true, get all related objects
Returns:

list of invalid objects/models and their errors

Return type:

InvalidObjectSet or None

validate(objects)[source]

Validate a list of objects and return their errors

Parameters:object (list of Model) – list of Model instances
Returns:list of invalid objects/models and their errors
Return type:InvalidObjectSet or None
obj_model.core.excel_col_name(col)[source]

Convert column number to an Excel-style string.

From http://stackoverflow.com/a/19169180/509882

Parameters:col (int) – column number (positive integer)
Returns:alphabetic column name
Return type:str
Raises:ValueError – if col is not positive
obj_model.core.get_model(name, module=None)[source]

Get model with name name

Parameters:
  • name (str) – name
  • module (module, optional) – module
Returns:

model class

Return type:

class

obj_model.core.get_models(module=None, inline=True)[source]

Get models

Parameters:
  • module (module, optional) – module
  • inline (bool, optional) – if true, return inline models
Returns:

list of model classes

Return type:

list of class

3.1.4. obj_model.extra_attributes module

Additional attribute types

Author:Jonathan Karr <karr@mssm.edu>
Date:2017-05-10
Copyright:2017, Karr Lab
License:MIT
class obj_model.extra_attributes.BioDnaSeqAttribute(min_length=0, max_length=inf, default=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.extra_attributes.BioSeqAttribute

Bio.Seq.Seq attribute with Bio.Alphabet.DNAAlphabet

class obj_model.extra_attributes.BioProteinSeqAttribute(min_length=0, max_length=inf, default=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.extra_attributes.BioSeqAttribute

Bio.Seq.Seq attribute with Bio.Alphabet.ProteinAlphabet

class obj_model.extra_attributes.BioRnaSeqAttribute(min_length=0, max_length=inf, default=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.extra_attributes.BioSeqAttribute

Bio.Seq.Seq attribute with Bio.Alphabet.RNAAlphabet

class obj_model.extra_attributes.BioSeqAttribute(min_length=0, max_length=inf, default=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.Attribute

Bio.Seq.Seq attribute

_alphabet[source]

alphabet

Type:Bio.Alphabet.Alphabet
min_length[source]

minimum length

Type:int
max_length[source]

maximum length

Type:int
default[source]

default value

Type:Bio.Seq.Seq
deserialize(value)[source]

Deserialize value

Parameters:value (str) – semantically equivalent representation
Returns:tuple of cleaned value and cleaning error
Return type:tuple of Bio.Seq.Seq, core.InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (dict) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:Bio.Seq.Seq
serialize(value)[source]

Serialize string

Parameters:value (Bio.Seq.Seq) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (Bio.Seq.Seq) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:dict
validate(obj, value)[source]

Determine if value is a valid value

Parameters:
  • obj (Model) – class being validated
  • value (Bio.Seq.Seq) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of core.InvalidAttribute

Return type:

core.InvalidAttribute or None

validate_unique(objects, values)[source]

Determine if the attribute values are unique

Parameters:
  • objects (list of Model) – list of Model objects
  • values (list of Bio.Seq.Seq) – list of values
Returns:

None if values are unique, otherwise return a list of errors as an instance of core.InvalidAttribute

Return type:

core.InvalidAttribute or None

class obj_model.extra_attributes.FeatureLocationAttribute(default=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.Attribute

Bio.SeqFeature.FeatureLocation attribute

default[source]

default value

Type:Bio.SeqFeature.FeatureLocation
deserialize(value)[source]

Deserialize value

Parameters:value (str) – semantically equivalent representation
Returns:tuple of cleaned value and cleaning error
Return type:tuple of numpy.array, core.InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (dict) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:Bio.SeqFeature.FeatureLocation
serialize(value)[source]

Serialize string

Parameters:value (numpy.array) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (Bio.SeqFeature.FeatureLocation) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:dict
validate(obj, value)[source]

Determine if value is a valid value

Parameters:
  • obj (Model) – class being validated
  • value (numpy.array) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of core.InvalidAttribute

Return type:

core.InvalidAttribute or None

validate_unique(objects, values)[source]

Determine if the attribute values are unique

Parameters:
  • objects (list of Model) – list of Model objects
  • values (list of Bio.SeqFeature.FeatureLocation) – list of values
Returns:

None if values are unique, otherwise return a list of errors as an instance of core.InvalidAttribute

Return type:

core.InvalidAttribute or None

class obj_model.extra_attributes.FrequencyPositionMatrixAttribute(verbose_name='', help='')[source]

Bases: obj_model.core.Attribute

Bio.motif.matrix.FrequencyPositionMatrix attribute

deserialize(value)[source]

Deserialize value

Parameters:value (str) – string representation
Returns:tuple of cleaned value and cleaning error
Return type:tuple of Bio.motifs.matrix.FrequencyPositionMatrix, core.InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (dict) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:Bio.motifs.matrix.FrequencyPositionMatrix
serialize(value)[source]

Serialize value to a string

Parameters:value (Bio.motifs.matrix.FrequencyPositionMatrix) – Python representation
Returns:string representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (Bio.motifs.matrix.FrequencyPositionMatrix) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:dict
validate(obj, value)[source]

Determine if value is a valid value

Parameters:
  • obj (Model) – class being validated
  • value (Bio.motifs.matrix.FrequencyPositionMatrix) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of core.InvalidAttribute

Return type:

core.InvalidAttribute or None

class obj_model.extra_attributes.NumpyArrayAttribute(min_length=0, max_length=inf, default=None, verbose_name='', help='', primary=False, unique=False)[source]

Bases: obj_model.core.Attribute

numpy.array attribute

min_length[source]

minimum length

Type:int
max_length[source]

maximum length

Type:int
default[source]

default value

Type:numpy.ndarray
deserialize(value)[source]

Deserialize value

Parameters:value (str) – semantically equivalent representation
Returns:tuple of cleaned value and cleaning error
Return type:tuple of numpy.array, core.InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (list) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:numpy.array
serialize(value)[source]

Serialize string

Parameters:value (numpy.array) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (numpy.array) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:list
validate(obj, value)[source]

Determine if value is a valid value

Parameters:
  • obj (Model) – class being validated
  • value (numpy.array) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of core.InvalidAttribute

Return type:

core.InvalidAttribute or None

validate_unique(objects, values)[source]

Determine if the attribute values are unique

Parameters:
  • objects (list of Model) – list of Model objects
  • values (list of numpy.array) – list of values
Returns:

None if values are unique, otherwise return a list of errors as an instance of core.InvalidAttribute

Return type:

core.InvalidAttribute or None

class obj_model.extra_attributes.SympyBasicAttribute(type=<class 'sympy.core.basic.Basic'>, default=None, verbose_name='', help='', primary=False, unique=False, unique_case_insensitive=False)[source]

Bases: obj_model.core.Attribute

Base class for SymPy expression, symbol attributes

type[source]

attribute type (e.g. sympy.Basic, sympy.Expr, sympy.Symbol)

Type:sympy.core.assumptions.ManagedProperties
default[source]

default value

Type:sympy.Basic
deserialize(value)[source]

Deserialize value

Parameters:value (str) – semantically equivalent representation
Returns:tuple of cleaned value and cleaning error
Return type:tuple of sympy.Basic, core.InvalidAttribute or None
from_builtin(json)[source]

Decode a simple Python representation (dict, list, str, float, bool, None) of a value of the attribute that is compatible with JSON and YAML

Parameters:json (list) – simple Python representation of a value of the attribute
Returns:decoded value of the attribute
Return type:sympy.Basic
serialize(value)[source]

Serialize string

Parameters:value (sympy.Basic) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (sympy.Basic) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:str
validate(obj, value)[source]

Determine if value is a valid value

Parameters:
  • obj (Model) – class being validated
  • value (sympy.Basic) – value of attribute to validate
Returns:

None if attribute is valid, other return list of errors as an instance of core.InvalidAttribute

Return type:

core.InvalidAttribute or None

validate_unique(objects, values)[source]

Determine if the attribute values are unique

Parameters:
  • objects (list of Model) – list of Model objects
  • values (list of sympy.Basic) – list of values
Returns:

None if values are unique, otherwise return a list of errors as an instance of core.InvalidAttribute

Return type:

core.InvalidAttribute or None

class obj_model.extra_attributes.SympyExprAttribute(default=None, verbose_name='', help='', primary=False, unique=False, unique_case_insensitive=False)[source]

Bases: obj_model.extra_attributes.SympyBasicAttribute

SymPy expression attribute

default[source]

default value

Type:sympy.Expr
serialize(value)[source]

Serialize string

Parameters:value (sympy.Expr) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (sympy.Expr) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:str
class obj_model.extra_attributes.SympySymbolAttribute(default=None, verbose_name='', help='', primary=False, unique=False, unique_case_insensitive=False)[source]

Bases: obj_model.extra_attributes.SympyBasicAttribute

SymPy symbol attribute

default[source]

default value

Type:sympy.Symbol
serialize(value)[source]

Serialize string

Parameters:value (sympy.Symbol) – Python representation
Returns:simple Python representation
Return type:str
to_builtin(value)[source]

Encode a value of the attribute using a simple Python representation (dict, list, str, float, bool, None) that is compatible with JSON and YAML

Parameters:value (sympy.Symbol) – value of the attribute
Returns:simple Python representation of a value of the attribute
Return type:str

3.1.5. obj_model.io module

Reading/writing schema objects to/from files

  • Comma separated values (.csv)
  • Excel (.xlsx)
  • JavaScript Object Notation (.json)
  • Tab separated values (.tsv)
  • Yet Another Markup Language (.yaml, .yml)
Author:Jonathan Karr <karr@mssm.edu>
Author:Arthur Goldberg <Arthur.Goldberg@mssm.edu>
Date:2016-11-23
Copyright:2016, Karr Lab
License:MIT
exception obj_model.io.IoWarning[source]

Bases: obj_model.core.ObjModelWarning

IO warning

class obj_model.io.JsonReader[source]

Bases: obj_model.io.Reader

Read model objects from a JSON or YAML file

run(path, models=None, group_objects_by_model=False, validate=True)[source]

Read model objects from file(s) and validate them

Parameters:
  • path (str) – path to file(s)
  • models (types.TypeType or list of types.TypeType, optional) – type or list of type of objects to read
  • group_objects_by_model (bool, optional) – if True, group decoded objects by their types
  • validate (bool, optional) – if True, validate the data
Returns:

model objects grouped by Model class

Return type:

dict

Raises:

ValueError – if zero or multiple models are requested to be read

class obj_model.io.JsonWriter[source]

Bases: obj_model.io.Writer

Write model objects to a JSON or YAML file

run(path, objects, models=None, get_related=True, title=None, description=None, keywords=None, version=None, language=None, creator=None)[source]

Write a list of model classes to a JSON or YAML file

Parameters:
  • path (str) – path to write file(s)
  • objects (Model or list of Model) – object or list of objects
  • models (list of Model, optional) – models
  • title (str, optional) – title
  • description (str, optional) – description
  • keywords (str, optional) – keywords
  • version (str, optional) – version
  • language (str, optional) – language
  • creator (str, optional) – creator
Raises:

ValueError – if zero or multiple objects are requested to be written

class obj_model.io.Reader[source]

Bases: object

Write model objects to file(s)

run(path, models=None, group_objects_by_model=False, validate=True)[source]

Read a list of model objects from file(s) and validate them

File(s) may be a single Excel workbook with multiple worksheets or a set of delimeter separated files encoded by a single path with a glob pattern.

Parameters:
  • path (str) – path to file(s)
  • models (types.TypeType or list of types.TypeType, optional) – type of object to read or list of types of objects to read
  • group_objects_by_model (bool, optional) – if True, group decoded objects by their types
  • validate (bool, optional) – if True, validate the data
Returns:

model objects grouped by Model class

Return type:

dict

class obj_model.io.WorkbookReader[source]

Bases: obj_model.io.Reader

Read model objects from an Excel file or CSV and TSV files

classmethod get_ambiguous_sheet_names(sheet_names, models)[source]

Get names of sheets than cannot be unambiguously mapped to models (sheet names that map to multiple models).

Parameters:
  • sheet_names (list of str) – names of the sheets in the workbook/files
  • models (list of Model) – list of models
Returns:

dictionary of ambiguous sheet names and their matching models

Return type:

dict of str, list of Model

classmethod get_model_sheet_name(sheet_names, model)[source]

Get the name of the worksheet/file which corresponds to a model

Parameters:
  • sheet_names (list of str) – names of the sheets in the workbook/files
  • model (Model) – model
Returns:

name of sheet corresponding to the model or None if there is no sheet for the model

Return type:

str

Raises:

ValueError – if the model matches more than one sheet

classmethod get_possible_model_sheet_names(model)[source]

Return set of possible sheet names for a model

Parameters:model (Model) – Model
Returns:set of possible sheet names for a model
Return type:set
classmethod header_row_col_names(index, file_ext, tabular_orientation)[source]

Determine row and column names for header entries.

Parameters:
  • index (int) – index in header sequence
  • file_ext (str) – extension for model file
  • orientation (TabularOrientation) – orientation of the stored table
Returns:

tuple of row, column, header_entries

Construct object graph

Parameters:
  • model (Model) – an obj_model.core.Model
  • attributes (list of Attribute) – attribute order of data
  • data (list of list of object) – nested list of object data
  • objects (list) – list of model objects in order of data
  • objects_by_primary_attribute (dict) – dictionary of model objects grouped by model
  • decoded (dict, optional) – dictionary of objects that have already been decoded
Returns:

list of parsing errors

Return type:

list of str

read_model(reader, model, include_all_attributes=True, ignore_missing_attributes=False, ignore_extra_attributes=False, ignore_attribute_order=False)[source]

Instantiate a list of objects from data in a table in a file

Parameters:
  • reader (wc_utils.workbook.io.Reader) – reader
  • model (class) – the model describing the objects’ schema
  • include_all_attributes (bool, optional) – if True, export all attributes including those not explictly included in Model.Meta.attribute_order
  • ignore_missing_attributes (bool, optional) – if False, report an error if the worksheet/files don’t have all of attributes in the model
  • ignore_extra_attributes (bool, optional) – if True, do not report errors if attributes in the data are not in the model
  • ignore_attribute_order (bool) – if True, do not require the attributes to be provided in the canonical order
Returns:

tuple of

list of Attribute, list of list of object, list of str, list of Model: tuple of * attribute order of data * a two-dimensional nested list of object data * a list of parsing errors * constructed model objects

read_sheet(reader, sheet_name, num_row_heading_columns=0, num_column_heading_rows=0)[source]

Read file into a two-dimensional list

Parameters:
  • reader (wc_utils.workbook.io.Reader) – reader
  • sheet_name (str) – worksheet name
  • num_row_heading_columns (int, optional) – number of columns of row headings
  • num_column_heading_rows (int, optional) – number of rows of column headings
Returns:

  • list of list: two-dimensional list of table values
  • list of list: row headings
  • list of list: column_headings

Return type:

tuple

run(path, models=None, ignore_missing_sheets=False, ignore_extra_sheets=False, ignore_sheet_order=False, include_all_attributes=True, ignore_missing_attributes=False, ignore_extra_attributes=False, ignore_attribute_order=False, group_objects_by_model=True, validate=True)[source]

Read a list of model objects from file(s) and validate them

File(s) may be a single Excel workbook with multiple worksheets or a set of delimeter separated files encoded by a single path with a glob pattern.

Parameters:
  • path (str) – path to file(s)
  • models (types.TypeType or list of types.TypeType, optional) – type or list of type of objects to read
  • ignore_missing_sheets (bool, optional) – if False, report an error if a worksheet/ file is missing for one or more models
  • ignore_extra_sheets (bool, optional) – if True and all models are found, ignore other worksheets or files
  • ignore_sheet_order (bool, optional) – if True, do not require the sheets to be provided in the canonical order
  • include_all_attributes (bool, optional) – if True, export all attributes including those not explictly included in Model.Meta.attribute_order
  • ignore_missing_attributes (bool, optional) – if False, report an error if a worksheet/file doesn’t contain all of attributes in a model in models
  • ignore_extra_attributes (bool, optional) – if True, do not report errors if attributes in the data are not in the model
  • ignore_attribute_order (bool) – if True, do not require the attributes to be provided in the canonical order
  • group_objects_by_model (bool, optional) – if True, group decoded objects by their types
  • validate (bool, optional) – if True, validate the data
Returns:

model objects grouped by Model class

Return type:

dict

Raises:

ValueError – if

  • Sheets cannot be unambiguously mapped to models
  • The file(s) indicated by path is missing a sheet for a model and ignore_missing_sheets is False
  • The file(s) indicated by path contains extra sheets that don’t correspond to one of models and ignore_extra_sheets is False
  • The worksheets are file(s) indicated by path are not in the canonical order and ignore_sheet_order is False
  • Some models are not serializable
  • The data contains parsing errors found by read_model
class obj_model.io.WorkbookWriter[source]

Bases: obj_model.io.Writer

Write model objects to an Excel file or CSV or TSV file(s)

static create_worksheet_style(model)[source]

Create worksheet style for model

Parameters:model (class) – model class
Returns:worksheet style
Return type:WorksheetStyle
run(path, objects, models=None, get_related=True, title=None, description=None, keywords=None, version=None, language=None, creator=None, include_all_attributes=True)[source]
Write a list of model classes to an Excel file, with one worksheet for each model, or to
a set of .csv or .tsv files, with one file for each model.
Parameters:
  • path (str) – path to write file(s)
  • objects (Model or list of Model) – object or list of objects
  • models (list of Model, optional) – models in the order that they should appear as worksheets; all models which are not in models will follow in alphabetical order
  • title (str, optional) – title
  • description (str, optional) – description
  • keywords (str, optional) – keywords
  • version (str, optional) – version
  • language (str, optional) – language
  • creator (str, optional) – creator
  • include_all_attributes (bool, optional) – if True, export all attributes including those not explictly included in Model.Meta.attribute_order
write_model(writer, model, objects, include_all_attributes=True, encoded=None)[source]

Write a list of model objects to a file

Parameters:
  • writer (wc_utils.workbook.io.Writer) – io writer
  • model (class) – model
  • objects (list of Model) – list of instances of model
  • include_all_attributes (bool, optional) – if True, export all attributes including those not explictly included in Model.Meta.attribute_order
  • encoded (dict, optional) – objects that have already been encoded and their assigned JSON identifiers
write_sheet(writer, sheet_name, data, row_headings=None, column_headings=None, style=None)[source]

Write data to sheet

Parameters:
  • writer (wc_utils.workbook.io.Writer) – io writer
  • sheet_name (str) – sheet name
  • data (list of list of object) – list of list of cell values
  • row_headings (list of list of str, optional) – list of list of row headings
  • column_headings (list of list of str, optional) – list of list of column headings
  • style (WorksheetStyle, optional) – worksheet style
class obj_model.io.Writer[source]

Bases: object

Write model objects to file(s)

run(path, objects, models=None, get_related=True, title=None, description=None, keywords=None, version=None, language=None, creator=None)[source]
Write a list of model classes to an Excel file, with one worksheet for each model, or to
a set of .csv or .tsv files, with one file for each model.
Parameters:
  • path (str) – path to write file(s)
  • objects (Model or list of Model) – object or list of objects
  • models (list of Model, optional) – models in the order that they should appear as worksheets; all models which are not in models will follow in alphabetical order
  • title (str, optional) – title
  • description (str, optional) – description
  • keywords (str, optional) – keywords
  • version (str, optional) – version
  • language (str, optional) – language
  • creator (str, optional) – creator
obj_model.io.convert(source, destination, models, ignore_missing_sheets=False, ignore_extra_sheets=False, ignore_sheet_order=False, include_all_attributes=True, ignore_missing_attributes=False, ignore_extra_attributes=False, ignore_attribute_order=False)[source]

Convert among comma-separated (.csv), Excel (.xlsx), JavaScript Object Notation (.json), tab-separated (.tsv), and Yet Another Markup Language (.yaml, .yml) formats

Parameters:
  • source (str) – path to source file
  • destination (str) – path to save converted file
  • models (list of class) – list of models
  • ignore_missing_sheets (bool, optional) – if False, report an error if a worksheet/ file is missing for one or more models
  • ignore_extra_sheets (bool, optional) – if True and all models are found, ignore other worksheets or files
  • ignore_sheet_order (bool, optional) – if True, do not require the sheets to be provided in the canonical order
  • include_all_attributes (bool, optional) – if True, export all attributes including those not explictly included in Model.Meta.attribute_order
  • ignore_missing_attributes (bool, optional) – if False, report an error if a worksheet/file doesn’t contain all of attributes in a model in models
  • ignore_extra_attributes (bool, optional) – if True, do not report errors if attributes in the data are not in the model
  • ignore_attribute_order (bool) – if True, do not require the attributes to be provided in the canonical order
obj_model.io.create_template(path, models, title=None, description=None, keywords=None, version=None, language=None, creator=None)[source]

Create a template for a model

Parameters:
  • path (str) – path to write file(s)
  • models (list) – list of model, in the order that they should appear as worksheets; all models which are not in models will follow in alphabetical order
  • title (str, optional) – title
  • description (str, optional) – description
  • keywords (str, optional) – keywords
  • version (str, optional) – version
  • language (str, optional) – language
  • creator (str, optional) – creator
obj_model.io.get_ordered_attributes(cls, include_all_attributes=True)[source]

Get the attributes for a class in the order that they should be printed

Parameters:include_all_attributes (bool, optional) – if True, export all attributes including those not explictly included in Model.Meta.attribute_order
Returns:attributes in the order they should be printed
Return type:tuple of Attribute
obj_model.io.get_reader(ext)[source]

Get reader

Parameters:ext (str) – extension (.csv, .json, .tsv, .xlsx, .yaml, or .yml)
Returns:reader class
Return type:class
Raises:ValueError – if extension is not supported
obj_model.io.get_writer(ext)[source]

Get writer

Parameters:ext (str) – extension (.csv, .json, .tsv, .xlsx, .yaml, or .yml)
Returns:writer class
Return type:class
Raises:ValueError – if extension is not supported

3.1.6. obj_model.migrate module

Support schema migration

Author:Arthur Goldberg <Arthur.Goldberg@mssm.edu>
Date:2018-11-18
Copyright:2018, Karr Lab
License:MIT
class obj_model.migrate.MigrationController[source]

Bases: object

Manage migrations

Manage migrations on several dimensions: * Migrate a single model file through a sequence of schemas * Perform migrations parameterized by a configuration file

static get_migrations_config(migrations_config_file)[source]

Read and initially validate migrations configuration file

Parameters:migrations_config_file (str) – pathname of migrations configuration in YAML file
Returns:migration descriptions
Return type:list of MigrationDesc
Raises:MigratorError – if migrations_config_file cannot be read, or the migration descriptions in migrations_config_file are not valid
static migrate_from_config(migrations_config_file)[source]

Perform the migrations specified in a config file

Parameters:migrations_config_file (str) – migrations specified in a YAML file
Returns:migrated filenames
Return type:list of str
static migrate_from_desc(migration_desc)[source]

Perform a migration described in a MigrationDesc

Parameters:migration_desc (MigrationDesc) – a migration description
Returns:migrated filename
Return type:str
static migrate_over_schema_sequence(migration_desc)[source]

Migrate a model file over a sequence of schemas

Parameters:migration_desc (MigrationDesc) – a migration description
Returns:name of migrated file
Return type:str
Raises:MigratorError – if model_defs_files, renamed_models, and renamed_attributes are not consistent with each other;
class obj_model.migrate.MigrationDesc(name, existing_file=None, model_defs_files=None, renamed_models=None, renamed_attributes=None, migrated_file=None, migrate_suffix=None, migrate_in_place=False)[source]

Bases: object

Description of a sequence of migrations from an existing file

get_kwargs()[source]
standardize()[source]

Standardize

validate()[source]

Validate the attributes and relative cardinality of a migration description

class obj_model.migrate.Migrator(old_model_defs_file, new_model_defs_file, renamed_models=None, renamed_attributes=None)[source]

Bases: object

Support schema migration

old_model_defs_file[source]

file name of Python file containing old model definitions

Type:str
new_model_defs_file[source]

file name of Python file containing new model definitions

Type:str
old_model_defs_path[source]

pathname of Python file containing old model definitions

Type:str
new_model_defs_path[source]

pathname of Python file containing new model definitions

Type:str
modules[source]

modules being used for migration, indexed by full pathname

Type:dict
old_model_defs[source]

obj_model.Model definitions of the old models, keyed by name

Type:dict
new_model_defs[source]

obj_model.Model definitions of the new models, keyed by name

Type:dict
deleted_models[source]

model types defined in the old models but not the new models

Type:set
renamed_models[source]

model types renamed from the existing to the migrated schema

Type:list
models_map[source]

map from existing model names to migrated model names

Type:dict
renamed_attributes[source]

attribute names renamed from the existing to the migrated schema

Type:list
renamed_attributes_map[source]

map of attribute names renamed from the existing to the migrated schema

Type:dict
_migrated_copy_attr_name[source]

attribute name used to point old models to corresponding new models; not used in any old model definitions

Type:str
MIGRATED_COPY_ATTR_PREFIX = '__migrated_copy'[source]
MIGRATE_SUFFIX = '_migrated'[source]
full_migrate(existing_file, migrated_file=None, migrate_suffix=None, migrate_in_place=False)[source]

Migrate data from an existing file to a migrated file

Parameters:
  • existing_file (str) – pathname of file to migrate
  • migrated_file (str, optional) – pathname of migrated file; if not provided, save migrated file with new suffix in same directory as existing file
  • migrate_suffix (str, optional) – suffix of automatically created migrated filename; default is Migrator.MIGRATE_SUFFIX
  • migrate_in_place (bool, optional) – if set, overwrite existing_file with the migrated file and ignore migrated_file and migrate_suffix
Returns:

name of migrated file

Return type:

str

Raises:

MigratorError – if migrate_in_place is False and writing the migrated file would overwrite an existing file

initialize()[source]

Initialize a Migrator

Separate from prepare() so most of Migrator can be tested with models defined in code

migrate(existing_models)[source]

Migrate existing model instances to new schema

:param existing_models (list of obj_model.Model: ) the models being migrated

Returns:the migrated models
Return type:list of obj_model.Model
modules = {}[source]
prepare()[source]

Prepare for migration

Raises:MigratorError – if renamings are not valid, or inconsistencies exist between corresponding old and migrated classes
read_existing_model(existing_file)[source]

Read models from existing file

Parameters:existing_file (str) – pathname of file to migrate
Returns:the models in existing_file
Return type:list of obj_model.Model
run(files)[source]

Migrate some files

Parameters:files (list) – names of model files to migrate
write_migrated_file(migrated_models, model_order, existing_file, migrated_file=None, migrate_suffix=None, migrate_in_place=False)[source]

Write migrated models to an external representation

:param migrated_models (list of obj_model.Model: ) the migrated models :param model_order (list of obj_model.core.ModelMeta: ) migrated models in the order

they should appear in a workbook
Parameters:
  • existing_file (str) – pathname of file to migrate
  • migrated_file (str, optional) – pathname of migrated file; if not provided, save migrated file with new suffix in same directory as source file
  • migrate_suffix (str, optional) – suffix of automatically created migrated filename; default is Migrator.MIGRATE_SUFFIX
  • migrate_in_place (bool, optional) – if set, overwrite source_file with the migrated file and ignore migrated_file and migrate_suffix
Returns:

name of migrated file

Return type:

str

Raises:

MigratorError – if migrate_in_place is False and writing the migrated file would overwrite an existing file

exception obj_model.migrate.MigratorError(message=None)[source]

Bases: Exception

Exception raised for errors in obj_model.migrate

message[source]

the exception’s message

Type:str
class obj_model.migrate.RunMigration[source]

Bases: object

static main(args)[source]
static parse_args(cli_args)[source]

Parse command line arguments

Parameters:cli_args (list) – command line arguments
Returns:parsed command line arguements
Return type:argparse.Namespace

3.1.7. obj_model.utils module

Utilities

Author:Jonathan Karr <karr@mssm.edu>
Date:2016-11-23
Copyright:2016, Karr Lab
License:MIT
obj_model.utils.get_attribute_by_name(cls, name, case_insensitive=False)[source]

Return the attribute of Model class cls with name name

Parameters:
  • cls (class) – Model class
  • name (str) – attribute name
  • case_insensitive (bool, optional) – if True, ignore case
Returns:

attribute with name equal to the value of name or None if there is no matching attribute

Return type:

Attribute

obj_model.utils.get_attribute_by_verbose_name(cls, verbose_name, case_insensitive=False)[source]

Return the attribute of Model class cls with verbose name verbose_name

Parameters:
  • cls (class) – Model class
  • verbose_name (str) – verbose attribute name
  • case_insensitive (bool, optional) – if True, ignore case
Returns:

attribute with verbose name equal to the value of verbose_name or None if there is no matching attribute

Return type:

Attribute

obj_model.utils.get_component_by_id(models, id, identifier='id')[source]

Retrieve a model instance by its identifier

Parameters:
  • ( (model) – obj:list of Model): an iterable of Model objects
  • id (str) – the identifier being sought
  • identifier (str, optional) – the name of the identifier attribute
Returns:

the retrieved Model instance if found, or None

Return type:

Model

Raises:

AttributeError – if model does not have the attribute specified by identifier

Get all errors associated with an object and its related objects

Parameters:object (Model) – object
Returns:set of errors
Return type:InvalidObjectSet

Get the models that have relationships to a model

Parameters:
  • root_model (type) – subclass of Model
  • include_root_model (bool, optional) – include the root model in the returned list of models
Returns:

list of models that have relationships with root_model

Return type:

list of type

obj_model.utils.group_objects_by_model(objects)[source]

Group objects by their models

Parameters:objects (list of Model) – list of model objects
Returns:dictionary with object grouped by their class
Return type:dict
obj_model.utils.randomize_object_graph(obj)[source]

Randomize the order of the edges (RelatedManagers) in the object’s object graph.

Parameters:obj (Model) – instance of Model
obj_model.utils.source_report(obj, attr_name)[source]

Get the source file, worksheet, column, and row location of attribute attr_name of model object obj as a colon-separated string.

Parameters:
  • obj (Model) – model object
  • attr_name (str) – attribute name
Returns:

a string representation of the source file, worksheet, column, and row

location of attr_name of obj

Return type:

str

3.1.8. Module contents