API Reference

xtuml

The following section lists functions, classes and exceptions from the xtuml module. The operations are independent of the underlying metamodel definition, i.e. the sql schema.

Loading Metamodels

xtuml.load_metamodel(resource)

Load and return a metamodel from a resource. The resource may be either a filename, or a list of filenames.

Usage example:

>>> metamodel = xtuml.load_metamodel(['schema.sql', 'data.sql'])

class xtuml.ModelLoader

Class for loading metamodels previously persisted to disk.

Data may be provided in any order, e.g. instances followed by associations, followed by class definitions. One single loader may be used to build several xtuml.MetaModel objects, and additional data may be provided at any time.

Note: Additional data will not affect previosly built metamodels.

Usage example:

>>> l = xtuml.ModelLoader()
>>> l.filename_input('data.sql')
>>> l.filename_input('schema.sql')
>>> m1 = l.build_metamodel()
>>> l.filename_input('additional_data.sql')
>>> m2 = l.build_metamodel()

build_metamodel(id_generator=None)

Build and return a xtuml.MetaModel containing previously loaded input.

file_input(file_object)

Read and parse data from a file object, i.e. the type of object returned by the builtin python function open().

filename_input(filename)

Open and read from a filename on disk, and parse its content.

input(data, name='<string>')

Parse data directly from a string. The name is used when reporting positional information if the parser encounter syntax errors.

populate(metamodel)

Populate a metamodel with entities previously encountered from input.

Metamodel Operations

class xtuml.MetaModel(id_generator=None)

A metamodel contains metaclasses with associations between them.

Note: All identifiers, e.g. attributes, association ids, key letters (the kind or name of a class), are case insensitive.

clone(instance)

Create a shallow clone of an instance.

Note: the clone and the original instance does not have to be part of the same metaclass.

find_class(kind)

Find a class of some kind in the metamodel.

find_metaclass(kind)

Find a metaclass of some kind in the metamodel.

new(kind, *args, **kwargs)

Create and return a new instance in the metamodel of some kind.

Optionally, initial attribute values may be assigned to the new instance by passing them as positional or keyword arguments. Positional arguments are assigned in the order in which they appear in the metaclass.

select_many(kind, *args)

Query the metamodel for a set of instances of some kind. Query operators such as where_eq(), order_by() or filter functions may be passed as optional arguments.

Usage example:

>>> m = xtuml.load_metamodel('db.sql')
>>> inst_set = m.select_many('My_Class', lambda sel: sel.number > 5)

select_one(kind, *args)

Query the metamodel for a single instance of some kind. Query operators such as where_eq(), order_by() or filter functions may be passed as optional arguments.

Usage example:

>>> m = xtuml.load_metamodel('db.sql')
>>> inst = m.select_one('My_Class', lambda sel: sel.name == 'Test')

xtuml.navigate_one(instance)

Initialize a navigation from one instance to another across a one-to-one association.

The resulting query will return an instance or None.

Usage example:

>>> from xtuml import navigate_one as one
>>> m = xtuml.load_metamodel('db.sql')
>>> inst = m.select_any('My_Modeled_Class')
>>> other_inst = one(inst).Some_Other_Class[4]()

The syntax is somewhat similar to the action language used in BridgePoint. The same semantics would be expressed in BridgePoint as:

select any inst from instances of My_Modeled_Class;
select one other_inst related by inst->Some_Other_Class[R4];

Note: If the navigated association is reflexive, a phrase must be provided, e.g.

>>> other_inst = one(inst).Some_Other_Class[4, 'some phrase']()

xtuml.navigate_any(instance_or_set)

Initialize a navigation from an instance, or a set of instances, to associated instances across a one-to-many or many-to-many association.

The resulting query will return an instance or None.

xtuml.navigate_many(instance_or_set)

Initialize a navigation from an instance, or a set of instances, to associated instances across a one-to-many or many-to-many association.

The resulting query will return a set of instances.

xtuml.navigate_subtype(supertype, rel_id)

Perform a navigation from supertype to its subtype across rel_id. The navigated association must be modeled as a subtype-supertype association.

The return value will an instance or None.

xtuml.relate(from_instance, to_instance, rel_id, phrase='')

Relate from_instance to to_instance across rel_id. For reflexive association, a phrase indicating the direction must also be provided.

The two instances are related to each other by copying the identifying attributes from the instance on the TO side of a association to the instance n the FROM side. Updated values which affect existing associations are propagated. A set of all affected instances will be returned.

xtuml.unrelate(from_instance, to_instance, rel_id, phrase='')

Unrelate from_instance from to_instance across rel_id. For reflexive associations, a phrase indicating the direction must also be provided.

The two instances are unrelated from each other by reseting the identifying attributes on the FROM side of the association. Updated values which affect existing associations are propagated. A set of all affected instances will be returned.

xtuml.delete(instance, disconnect=True)

Delete an instance from its metaclass instance pool and optionally disconnect it from any links it might be connected to.

xtuml.cardinality(instance_or_set)

Get the cardinality of an instance_or_set.

xtuml.where_eq(**kwargs)

Return a where-clause that filters out instances based on named keywords.

Usage example:

>>> from xtuml import where_eq as where
>>> m = xtuml.load_metamodel('db.sql')
>>> inst = m.select_any('My_Modeled_Class', where(My_Number=5))

xtuml.order_by(*attrs)

Return a query ordering operator that will order an instance set based on attribute names passed. When ordering on multiple attributes is specified, the set will be sorted by the first attribute and then within each value of this, by the second attribute and so on.

Usage example:

>>> from xtuml import order_by
>>> m = xtuml.load_metamodel('db.sql')
>>> inst = m.select_many('My_Class', order_by('Name', 'Number'))

xtuml.reverse_order_by(*attrs)

Return a reversed query ordering operator with the same behavior as order_by() but reversed order.

Usage example:

>>> from xtuml import reverse_order_by
>>> m = xtuml.load_metamodel('db.sql')
>>> inst = m.select_many('My_Class', reverse_order_by('Name', 'Number'))

xtuml.sort_reflexive(set_of_instances, rel_id, phrase)

Sort a set of instances in the order they appear across a conditional and reflexive association. The first instance in the resulting ordered set is not associated to an instance across the given phrase.

xtuml.get_metamodel(class_or_instance)

Get the metamodel in which a class_or_instance was created.

xtuml.get_metaclass(class_or_instance)

Get the metaclass for a class_or_instance.

class xtuml.MetaClass(kind, metamodel=None)

A metaclass contain metadata for instances, e.g. what attributes are available, what thier types are, and so on.

In addition, each metaclass also handle allocations of instances.

append_attribute(name, type_name)

Append an attribute with a given name and type name at the end of the list of attributes.

property attribute_names

Obtain an ordered list of all attribute names.

attribute_type(attribute_name)

Obtain the type of an attribute.

clone(instance)

Create a shallow clone of an instance.

Note: the clone and the original instance does not have to be part of the same metaclass.

delete(instance, disconnect=True)

Delete an instance from the instance pool and optionally disconnect it from any links it might be connected to. If the instance is not part of the metaclass, a MetaException is thrown.

delete_attribute(name)

Delete an attribute with a given name from the list of attributes.

insert_attribute(index, name, type_name)

Insert an attribute with a given name and type name at some index in the list of attributes.

navigate(inst, kind, rel_id, phrase='')

Navigate across a link with some rel_id and phrase that yields instances of some kind.

new(*args, **kwargs)

Create and return a new instance.

query(dictonary_of_values)

Query the instance pool for instances with attributes that match a given dictonary of values.

select_many(*args)

Select several instances from the instance pool. Query operators such as where_eq(), order_by() or filter functions may be passed as optional arguments.

select_one(*args)

Select a single instance from the instance pool. Query operators such as where_eq(), order_by() or filter functions may be passed as optional arguments.

xtuml.check_association_integrity(m, rel_id=None)

Check the model for integrity violations on association(s).

xtuml.check_uniqueness_constraint(m, kind=None)

Check the model for uniqueness constraint violations.

Persistance

xtuml.persist_database(metamodel, path, mode='w')

Persist all instances, class definitions and association definitions in a metamodel by serializing them and saving to a path on disk.

xtuml.persist_instances(metamodel, path, mode='w')

Persist all instances in a metamodel by serializing them and saving to a path on disk.

xtuml.persist_schema(metamodel, path, mode='w')

Persist all class and association definitions in a metamodel by serializing them and saving to a path on disk.

xtuml.serialize(resource)

Serialize some xtuml resource, e.g. an instance or a complete metamodel.

xtuml.serialize_database(metamodel)

Serialize all instances, class definitions, association definitions, and unique identifiers in a metamodel.

xtuml.serialize_schema(metamodel)

Serialize all class and association definitions in a metamodel.

xtuml.serialize_instances(metamodel)

Serialize all instances in a metamodel.

xtuml.serialize_instance(instance)

Serialize an instance from a metamodel.

xtuml.serialize_classes(metamodel)

Serialize all class definitions in a metamodel.

xtuml.serialize_class(Cls)

Serialize an xtUML metamodel class.

xtuml.serialize_associations(metamodel)

Serialize all association definitions in a metamodel.

xtuml.serialize_association(ass)

Serialize an xtuml metamodel association.

xtuml.serialize_unique_identifiers(metamodel)

Tools

class xtuml.UUIDGenerator

A uuid-based id generator. 128-bit unique numbers are generated randomly each time a new id is requested.

class xtuml.IntegerGenerator

An integer-based id generator. Integers are generated sequentially, starting from the number one.

Generally, the uuid-based id generator shall be used. In some cases such as testing however, having deterministic unique ids may be benifitial.

Usage example:

>>> l = xtuml.ModelLoader()
>>> l.filename_input("schema.sql")
>>> l.filename_input("data.sql")
>>> m = l.build_metamodel(xtuml.IntegerGenerator())

class xtuml.Walker

A walker may be used to walk a tree.

accept(node, **kwargs)

Invoke the visitors before and after decending down the tree. The walker will also try to invoke a method matching the pattern accept_<type name>, where <type name> is the name of the accepted node.

default_accept(node, **kwargs)

The default accept behaviour is to decend into the iterable member node.children (if available).

class xtuml.Visitor

A visitor may be used to visit tree nodes walked by a walker.

default_enter(node)

The default behaviour when entering a node if no other action is defined by a subclass is to do nothing.

default_leave(node)

The default behaviour when leaving a node if no other action is defined by a subclass is to do nothing.

enter(node)

Tries to invoke a method matching the pattern enter_<type name>, where <type name> is the name of the type of the node.

leave(node)

Tries to invoke a method matching the pattern leave_<type name>, where <type name> is the name of the type of the node.

class xtuml.NodePrintVisitor

A visitor that prints a tree-like structure to stdout.

default_render(node)

The default behaviour when rendering a node if no other rendering method is defined by a subclass is to render the class name.

render(node)

Try to invoke a method matching the pattern render_<type name>, where <type name> is the name of the rendering node.

Exceptions

exception xtuml.ParsingException

An exception that may be thrown while loading (and parsing) a metamodel.

exception xtuml.MetaException

Base class for all exceptions thrown by the xtuml.meta module.

exception xtuml.DeleteException

An exception that may be thrown during delete operations.

exception xtuml.RelateException(from_instance, to_instance, rel_id, phrase)

An exception that may be thrown during relate operations.

exception xtuml.UnrelateException(from_instance, to_instance, rel_id, phrase)

An exception that may be thrown during unrelate operations.

exception xtuml.MetaModelException

Base class for exceptions thrown by the MetaModel class.

exception xtuml.UnknownLinkException(from_kind, to_kind, rel_id, phrase)

An exception that may be thrown when a link is not found.

exception xtuml.UnknownClassException(kind)

An exception that may be thrown when a metaclass is not found.

bridgepoint

The following section lists functions and classes from the bridgepoint module. All operations require input expressed in the BridgePoint metamodel (ooaofooa).

Loading Models

bridgepoint.load_metamodel(resource=None, load_globals=True)

Load and return a metamodel expressed in ooaofooa from a resource. The resource may be either a filename, a path, or a list of filenames and/or paths.

class bridgepoint.ModelLoader(load_globals=True)

A xtuml.MetaModel loader with ooaofooa schema and globals pre-defined.

build_component(name=None, derived_attributes=False)

Instantiate and build a component from ooaofooa named name as a pyxtuml model. Classes, associations, attributes and unique identifers, i.e. O_OBJ, R_REL, O_ATTR in ooaofooa, are defined in the resulting pyxtuml model.

Optionally, control whether derived attributes shall be mapped into the resulting pyxtuml model as attributes or not.

Futhermore, if no name is provided, the entire content of the ooaofooa model is instantiated into the pyxtuml model.

filename_input(path_or_filename)

Open and read input from a path or filename, and parse its content.

If the filename is a directory, files that ends with .xtuml located somewhere in the directory or sub directories will be loaded as well.

If the filename is a zip archive, files that ends with .xtuml located somewhere in the archive will be loaded as well.

Model Transformation

bridgepoint.gen_text_action(instance)

Generate textual OAL action code from an instance in the BridgePoint metamodel. The input may be an instance of the following classes:

• S_SYNC

• S_BRG

• O_TFR

• O_DBATTR

• SM_ACT

• SPR_RO

• SPR_RS

• SPR_PO

• SPR_PS

In addition, anything in the ooaofooa subsystems Value or Body, e.g. ACT_SMT or V_VAL are also supported.

bridgepoint.prebuild_action(instance)

Transform textual OAL actions of an instance to instances in the ooaofooa subsystems Value and Body. The provided instance must be an instance of one of the following classes:

• S_SYNC

• S_BRG

• O_TFR

• O_DBATTR

• SM_ACT

• SPR_RO

• SPR_RS

• SPR_PO

• SPR_PS

bridgepoint.prebuild_model(metamodel)

Transform textual OAL actions in a ooaofooa metamodel to instances in the subsystems Value and Body. Instances of the following classes are supported:

• S_SYNC

• S_BRG

• O_TFR

• O_DBATTR

• SM_ACT

• SPR_RO

• SPR_RS

• SPR_PO

• SPR_PS