EDXML events are represented as instances of the EDXMLEvent class and its subclasses.
The event properties are accessible by means of the properties <edxml.EDXMLEvent.properties> attribute. The objects of each property are stored as sets. To make accessing properties as convenient as possible, events implement a MutableMapping, allowing more direct access. A quick example:
../edxml/examples/event_representation_properties_dict_read.py
Note that the event that we created above is incomplete. It is not even valid. We did not set an event type or an event source. EDXMLEvent instances are not bound to an ontology. As such there is no concept of validity in its instances. You can create any event you like, valid or invalid. Validating an instance can be done by means of its is_valid() <edxml.EDXMLEvent.is_valid> method, which accepts an ontology as parameter.
Due to events not being bound to an ontology there is no differentiation between a property that does not exist and a property that exists but is lacking any objects. Therefore, checking if the properties dictionary has a certain key will return False even if that key has been assigned an empty set.
Writing event properties works just as you would expect. Some examples are shown below.
../edxml/examples/event_representation_properties_dict_write.py
Event attachments can be accessed by means of the attachments <edxml.EDXMLEvent.attachments> attribute. This attribute is a dictionary mapping attachment names to the attachment values. The attachment values are also a dictionary mapping attachment identifiers to their string values. Another quick example:
../edxml/examples/event_representation_attachments_dict.py
As you can see in the above example, explicitly setting the identifiers of individual attachment values is not needed. When omitted, the SHA1 hashes of the attachment values will be used as identifiers.
The EDXMLEvent class has two subclasses. The first one is the ParsedEvent class. As the name suggests, this class is instantiated by EDXML parsers. In fact, it can only be instantiated by lxml, which is the library that the EDXML parser is built on. Its instances are a mix of a regular EDXMLEvent and a etree.Element instance. The reason for a separate parsed event variant is performance: The lxml library can generate these objects at minimal cost and can be passed through to EDXML writers for re-serialization at minimal cost.
The second subclass of EDXMLEvent is EventElement. This class is a wrapper around an lxml etree.Element instance containing an <event> XML element, providing the same convenient access interface as its parent, EDXMLEvent. The EventElement is mainly used for generating events that are intended for feeding to EDXML writers.
Since EDXML data is XML, all object values in an EDXML document are strings. As a result, the events that are generated by the parser will only contain values of type str. When writing object values into an event Python types other than str can be used. For example, writing a float into an event object is perfectly fine.
What happens when a non-string value is written into an event depends on the particular event implementation. The base class EDXMLEvent does not care about the values stored in its properties, until it needs to be converted into an EventElement. This happens when the event is written using a transcoder <transcoding> or using the EDXMLWriter <edxml.writer.EDXMLWriter>. At that point any non-string values are converted into strings. If that fails, an exception is raised.
Instances of EventElement are both an EDXML event and an XML element and the conversion to strings happens immediately when a property is written. This means that, in general, writing an event property may raise an exception.
The EDXML event implementations can convert various Python types into strings. These types include float, bool, datetime, Decimal and IP (from IPy).
Some types of characters are illegal in XML. For that reason writing an object value string into an event can raise a ValueError. Using the replace_invalid_characters() <edxml.EDXMLEvent.replace_invalid_characters> function illegal characters can be automatically replaced by replacement characters.
The class documentation of the various event implementations can be found below.
edxml.EDXMLEvent
edxml.ParsedEvent
edxml.EventElement