Event Type Factories

Apart from procedurally defining ontology elements it is also possible to define them in a declarative fashion. This is done by defining a class that extends EventTypeFactory. This class defines a set of class constants that can be populated to describe one or more event types. These event types can then be generated from these class constants.

A quick example to illustrate:

from edxml.ontology import EventTypeFactory


class MyFactory(EventTypeFactory):
    TYPES = ['event-type.a']
    TYPE_PROPERTIES = {
        'event-type.a': {'property-a': 'my.object.type'}
    }


ontology = MyFactory().generate_ontology()

The EventTypeFactory class is also the base of the RecordTranscoder class and its extensions. These classes combine ontology generation with event generation and are the most convenient way to generate EDXML data.

Of course there are many more class constants corresponding to many other EDXML ontology features. These can be found in the below class documentation. More extensive examples of using an EventTypeFactory can be found in Data Transcoding and in Introduction to EDXML Data Modelling.

edxml.ontology.EventTypeFactory

class edxml.ontology.EventTypeFactory

Bases: object

This class allows for the creation of event types in a declarative fashion. To this end it provides a collection of class constants from which one or more event types can be generated.

VERSION = 1

The VERSION attribute indicates the version of the event types that are generated by this record transcoder. It can be increased when the event types are changed. This allows merging of EDXML data that was generated by both older and newer versions of the record transcoder.

TYPES = []

The TYPES attribute contains the list of names of event types that will be generated by the factory.

TYPE_DESCRIPTIONS = {}

The TYPE_DESCRIPTIONS attribute is a dictionary mapping EDXML event type names to event type descriptions.

TYPE_DISPLAY_NAMES = {}

The TYPE_DISPLAY_NAMES attribute is a dictionary mapping EDXML event type names to event type display names. Each display name is a list, containing the singular form, optionally followed by the plural form, like this:

{'event-type-name': ['event', 'events']}

The plural form may be omitted. This can be done by omitting the second item in the list or by using a string in stead of a list. In that case, the plural form will be assumed to be the singular form with an additional ‘s’ appended.

TYPE_SUMMARIES = {}

The TYPE_SUMMARIES attribute is a dictionary mapping EDXML event type names to event summary templates.

TYPE_STORIES = {}

The TYPE_STORIES attribute is a dictionary mapping EDXML event type names to event story templates.

TYPE_PROPERTIES = {}

The TYPE_PROPERTIES attribute is a dictionary mapping EDXML event type names to their properties. For each key (the event type name) there should be a dictionary containing the desired property. A property dictionary must have a key containing the property name and a value containing the name of the object type. Properties will automatically be generated when this constant is populated.

Example:

{'event-type-name': {'property-name': 'object-type-name'}}

TYPE_PROPERTY_CONCEPTS = {}

The TYPE_PROPERTY_CONCEPTS attribute is a dictionary mapping EDXML event type names to property concept associations. The associations are dictionaries mapping property names to their associated concepts. The associated concepts are specified as a dictionary containing the names of the associated concepts as keys and their association confidences as values.

Example:

{
  'event-type-name': {
    'property-a': {'concept.name': 8},
    'property-b': {'concept.name': 8}, {'another.concept.name': 7},
  }
}

TYPE_PROPERTY_CONCEPTS_CNP = {}

The TYPE_PROPERTY_CONCEPTS_CNP attribute is a dictionary mapping EDXML event type names to property concept naming priorities (CNP). The priorities are specified as dictionaries mapping property names to concept CNPs. The concept CNPs are specified as a dictionary containing the names of the associated concepts as keys and their CNPs as values. When the CNP of a concept association is not specified, it will have the default value of 128.

Example:

{
  'event-type-name': {
    'property-a': {'concept.name': 192},
    'property-b': {'concept.name': 64}, {'another.concept.name': 0},
  }
}

TYPE_PROPERTY_ATTRIBUTES = {}

The TYPE_PROPERTY_ATTRIBUTES attribute is a dictionary mapping EDXML event type names to concept attributes. The concept attributes are specified as a dictionary mapping property names to attributes. Each attribute is a list containing the full attribute name, the singular display name and the plural display name, in that order. When the plural display name is omitted, it will be guessed by taking the singular form and appending an ‘s’ to it. When both singular and plural display names are omitted, they will be inherited from the object type. When the attribute of a concept association is not specified, it will inherit from the object type as per the EDXML specification.

Example:

{
  'event-type-name': {
    'property-a': {'concept.name': ['object.type.name:attribute.name-extension']},
    'property-b': {'concept.name': ['object.type.name:attribute.name-extension', 'singular', 'plural']},
  }
}

TYPE_UNIVERSALS_NAMES = {}

The TYPE_UNIVERSALS_NAMES attribute is a dictionary mapping EDXML event type names to name relations. The name relations are dictionaries mapping properties containing object values (source properties) to other properties containing names for those object values (target properties). Name relations are discussed in detail in the EDXML specification.

Note that the source properties are automatically marked as being single-valued.

Example:

{
  'event-type-name': {
    'product-id': 'product-name'
  }
}

TYPE_UNIVERSALS_DESCRIPTIONS = {}

The TYPE_UNIVERSALS_DESCRIPTIONS attribute is a dictionary mapping EDXML event type names to description relations. The description relations are dictionaries mapping properties containing object values (source properties) to other properties containing description for those object values (target properties). Description relations are discussed in detail in the EDXML specification.

Note that the source properties are automatically marked as being single-valued.

Example:

{
  'event-type-name': {
    'product-id': 'product-description'
  }
}

TYPE_UNIVERSALS_CONTAINERS = {}

The TYPE_UNIVERSALS_CONTAINERS attribute is a dictionary mapping EDXML event type names to container relations. The container relations are dictionaries mapping properties containing object values (source properties) to other properties providing ‘containers’ for those object values (target properties). Container relations are discussed in detail in the EDXML specification.

Note that the source properties are automatically marked as being single-valued.

Example:

{
  'event-type-name': {
    'product-name': 'product-category'
  }
}

TYPE_PROPERTY_DESCRIPTIONS = {}

The TYPE_PROPERTY_DESCRIPTIONS attribute is a dictionary mapping EDXML event type names to property descriptions. Each property description is a dictionary mapping property names to descriptions. It will be used to automatically set the descriptions of any automatically generated properties.

Example:

{
  'event-type-name': {
    'property-a': 'description',
    'property-b': 'description'
  }
}

TYPE_PROPERTY_SIMILARITY = {}

The TYPE_PROPERTY_SIMILARITY attribute is a dictionary mapping EDXML event type names to property similarities. Each property similarity is a dictionary mapping property names to EDXML ‘similar’ attributes. It will be used to automatically set the similar attributes of any automatically generated properties.

Example:

{
  'event-type-name': {
    'property-a': 'similar attribute',
    'property-b': 'similar attribute'
  }
}

TYPE_PROPERTY_MERGE_STRATEGIES = {}

The TYPE_PROPERTY_MERGE_STRATEGIES attribute is a dictionary mapping EDXML event type names to property merge strategies. Each property merge strategy is a dictionary mapping property names to EDXML ‘merge’ attributes, which indicate the merge strategy of the property. It will be used to set the merge attribute for any automatically generated properties.

When no merge strategy is given, automatically generated properties will have the default strategy, which is ‘match’ for hashed properties and ‘any’ for all other properties.

For convenience, the EventProperty class defines some class attributes representing the available merge strategies.

Example:

{
  'event-type-name': {
    'property-name': EventProperty.MERGE_ADD
  }
}

TYPE_HASHED_PROPERTIES = {}

The TYPE_HASHED_PROPERTIES attribute is a dictionary mapping EDXML event type names to lists of hashed properties. The lists will be used to set the ‘match’ merge strategy for the listed properties. Example:

{'event-type-name': ['hashed-property-a', 'hashed-property-b']}

PARENTS_CHILDREN = []

The PARENTS_CHILDREN attribute is a list containing parent-child event type relations. Each relation is a list containing the event type name of the parent, the EDXML ‘parent-description’ attribute and the event type name of the child event type, in that order. It will be used in conjunction with the CHILDREN_SIBLINGS and PARENT_MAPPINGS attributes to configure event type parents for any automatically generated event types. Example:

PARENTS_CHILDREN = [
  ['parent-event-type-name', 'containing', 'child-event-type-name']
]

Note

Please refer to the EDXML specification for details about how to choose a proper value for the parent-description attribute.

CHILDREN_SIBLINGS = []

The CHILDREN_SIBLINGS attribute is a list containing child-siblings event type relations. Each relation is a list containing the event type name of the child, the EDXML ‘siblings-description’ attribute and the event type name of the parent event type, in that order. Example:

CHILDREN_SIBLINGS = [
  ['child-event-type-name', 'contained in', 'parent-event-type-name']
]

Note

Please refer to the EDXML specification for details about how to choose a proper value for the siblings-description attribute.

PARENT_MAPPINGS = {}

The PARENT_MAPPINGS attribute is a dictionary mapping EDXML event type names to parent property mappings. Each mapping is a dictionary containing properties of the event type as keys and properties of the parent event type as values. Example:

PARENT_MAPPINGS = {
  'child-event-type-name': {
    'child-property-name-a': 'parent-property-name-a',
    'child-property-name-b': 'parent-property-name-b',
  }
}

Note

Please refer to the EDXML specification for details about how parent property mappings work.

TYPE_TIME_SPANS = {}

The TYPE_TIME_SPANS attribute contains the names of the properties that define the start and the end of the time spans of the events. When no property is set that defines the start or end of the event time spans, the start or end is implicitly defined to be the smallest or largest datetime value in the event, regardless of the property that contains the datetime value. By setting specific properties for the start and / or end of the time span, only the datetime values of that property define the start or end of the event timespan.

The attribute is a dictionary mapping EDXML event type names to tuples that define the time span properties. The first value in each tuple is the name of the property that defines the start of the event time spans, the second defines the end. By default, both are unset. Example:

{'event-type-name': ['timespan-start', 'timespan-end']}

TYPE_VERSIONS = {}

The TYPE_VERSIONS attribute contains the names of the properties that define the versions of the events.

The attribute is a dictionary mapping EDXML event type names to the names of the event properties that contain the version. Example:

{'event-type-name': 'version'}

TYPE_SEQUENCES = {}

The TYPE_SEQUENCES attribute contains the names of the properties that define the sequence numbers of the events. Together with event time spans, sequence numbers determine logical event order.

The attribute is a dictionary mapping EDXML event type names to the names of the event properties that contain the sequence number. Example:

{'event-type-name': 'sequence'}

TYPE_ATTACHMENTS = {}

The TYPE_ATTACHMENTS attribute is a dictionary mapping EDXML event type names to attachment names. Example:

{'event-type-name': ['my-attachment', 'another-attachment']}

TYPE_MULTI_VALUED_PROPERTIES = {}

The TYPE_MULTI_VALUED_PROPERTIES attribute is a dictionary mapping EDXML event type names to lists of property names that will be multi-valued. Example:

{'event-type-name': ['my-property', 'another-property']}

TYPE_OPTIONAL_PROPERTIES = {}

The TYPE_OPTIONAL_PROPERTIES attribute is a dictionary mapping EDXML event type names to lists of property names that will be optional. Example:

{'event-type-name': ['my-property', 'another-property']}

It is also possible to indicate that all event properties of a particular event type will be optional, like this:

{'event-type-name': True}

In this case TYPE_MANDATORY_PROPERTIES can be used to specify exceptions.

TYPE_MANDATORY_PROPERTIES = {}

All event properties are created as mandatory properties by default, unless TYPE_OPTIONAL_PROPERTIES indicates otherwise. When TYPE_OPTIONAL_PROPERTIES indicates that all event properties of a specific event type must be optional, TYPE_MANDATORY_PROPERTIES can list exceptions. It is a dictionary mapping EDXML event type names to lists of property names that will be mandatory. Example:

{'event-type-name': ['my-property', 'another-property']}

TYPE_ATTACHMENT_MEDIA_TYPES = {}

The TYPE_ATTACHMENT_MEDIA_TYPES attribute is a dictionary mapping EDXML event type names to attachment media types. The attachment media types are a dictionary mapping attachment names to its RFC 6838 media type. Example:

{'event-type-name': {'my-attachment': 'text/plain'}}

TYPE_ATTACHMENT_DISPLAY_NAMES = {}

The TYPE_ATTACHMENT_DISPLAY_NAMES attribute is a dictionary mapping EDXML event type names to attachment display names. The attachment display names are a dictionary mapping attachment names to display names. Each display name is a list, containing the singular form, optionally followed by the plural form, like this:

{'event-type-name': {'my-attachment': ['attachment', 'attachments']}}

The plural form may be omitted. This can be done by omitting the second item in the list or by using a string in stead of a list. In that case, the plural form will be assumed to be the singular form with an additional ‘s’ appended.

TYPE_ATTACHMENT_DESCRIPTIONS = {}

The TYPE_ATTACHMENT_DESCRIPTIONS attribute is a dictionary mapping EDXML event type names to attachment descriptions. The attachment descriptions are a dictionary mapping attachment names to its description. Example:

{'event-type-name': {'my-attachment': 'Just some attachment'}}

TYPE_ATTACHMENT_ENCODINGS = {}

The TYPE_ATTACHMENT_ENCODINGS attribute is a dictionary mapping EDXML event type names to attachment encodings. The attachment encodings are a dictionary mapping attachment names their encodings. Valid encodings are either ‘unicode’ or ‘base64’ Example:

{'event-type-name': {'my-attachment': 'unicode'}}

generate_ontology(target_ontology=None)

Generates the ontology elements, adding them to a target ontology. The target ontology is returned. By default, the target ontology is an empty ontology which is not validated after populating it. When another target ontology is passed, it will be updated using the generated ontology elements. This update operation does trigger ontology validation.

Parameters:target_ontology (edxml.ontology.Ontology) – Returns:The resulting ontology Return type:edxml.ontology.Ontology

create_concepts(ontology)

This method may be used to define EDXML concepts that are referred to by the generated event types.

create_object_types(ontology)

This method may be used to define EDXML object types that are referred to by the generated event types.

create_event_types(ontology)

This method generates all event types using the class constants of this event type factory. The event types are created in specified ontology. This ontology must have all required object types and concepts.

classmethod create_event_type(event_type_name, ontology)

Creates specified event type in the provided ontology using the class attributes of this factory. It returns the resulting event type. The resulting event types can optionally be tuned by overriding this method.

Parameters:

• event_type_name (str) – Name of the desired event type
• ontology (edxml.ontology.Ontology) – Ontology to add the event type to

Returns:

edxml.ontology.EventType