Writing EDXML Data¶

The EDXML SDK features several components for producing EDXML data, all based on the excellent lxml library. Data generation is incremental, which allows for developing efficient system components that generate or process EDXML data in a streaming fashion.

EDXMLWriter¶

The EDXMLWriter class is the prime, low level EDXML generator. For most practical use cases a transcoder offers a superior means for generating EDXML data.

Using the EDXML writer is pretty straight forward, as the following example demonstrates:

from edxml import EDXMLWriter, EDXMLEvent
from edxml.ontology import Ontology

# Create basic ontology
ontology = Ontology()
ontology.create_object_type(name='some.object.type')
source = ontology.create_event_source(uri='/some/source/')
event_type = ontology.create_event_type(name='some.event.type')
event_type.create_property(name='prop', object_type_name='some.object.type')

# Create an EDXML event
event = EDXMLEvent(
    properties={'prop': {'FooBar'}},
    event_type_name=event_type.get_name(),
    source_uri=source.get_uri()
)

# Generate EDXML data (writes to stdout)
with EDXMLWriter() as writer:
    writer.add_ontology(ontology)
    writer.add_event(event)

Class Documentation¶

class edxml.EDXMLWriter(output=<_io.BufferedWriter name='<stdout>'>, validate=True, log_repaired_events=False, pretty_print=True)¶

Bases: object

Class for generating EDXML streams

The output parameter is a file-like object that will be used to send the XML data to. When the output parameter is set to None, the generated XML data will be returned by the methods that generate output.

The optional validate parameter controls if the generated EDXML stream should be auto-validated or not. Automatic validation is enabled by default.

Parameters:	output (file) – File-like output object validate (bool) – Enable output validation (True) or not (False) log_repaired_events (bool) – Log repaired events (True) or not (False)

enable_auto_repair_normalize(event_type_name, property_names)¶

Enables automatic repair of the property values of events of specified type. Whenever an invalid event is generated by the mediator it will try to repair the event by normalizing object values of specified properties.

Parameters:	event_type_name (str) – property_names (List[str]) –
Returns:	The EDXMLWriter instance
Return type:	edxml.EDXMLWriter

enable_auto_repair_drop(event_type_name, property_names)¶

Allows dropping invalid object values from the specified event properties while repairing invalid events. This will only be done as a last resort when normalizing object values failed or is disabled.

Parameters:	event_type_name (str) – property_names (List[str]) –
Returns:	The EDXMLWriter instance
Return type:	edxml.EDXMLWriter

ignore_invalid_events(warn=False)¶

Instructs the EDXML writer to ignore invalid events. After calling this method, any event that fails to validate will be dropped. If warn is set to True, a detailed warning will be printed, allowing the source and cause of the problem to be determined.

Note

This has no effect when event validation is disabled.

Parameters:	warn (bool) – Print warnings or not
Returns:	The EDXMLWriter instance
Return type:	EDXMLWriter

flush()¶

When no output was provided when creating the EDXML writer, any generated EDXML data is stored in an internal buffer. In that case, this method will return the content of the buffer and clear it. Otherwise, an empty string is returned.

Returns:	Generated EDXML data
Return type:	bytes

add_ontology(ontology)¶

Writes an EDXML ontology element into the output.

Parameters:	ontology (edxml.ontology.Ontology) – The ontology
Returns:	The EDXMLWriter instance
Return type:	edxml.writer.EDXMLWriter

close()¶

Finalizes the output data stream.

Returns:	The EDXMLWriter instance
Return type:	edxml.writer.EDXMLWriter

add_event(event, sort=False)¶

Adds specified event to the output data stream.

When the sort parameter is set to True, the properties, attachments and event parents are sorted as required for obtaining the event in its normal form as defined in the EDXML specification. While this does not actually output the events in their normal form, the sorting does make it easier to spot relevant differences between events.

Parameters:	event (edxml.EDXMLEvent) – The event sort (bool) – Sort event components yes or no
Returns:	The EDXMLWriter instance
Return type:	edxml.writer.EDXMLWriter

add_foreign_element(element)¶

Adds specified foreign element to the output data stream.

Parameters:	element (etree._Element) – The element
Returns:	The EDXMLWriter instance
Return type:	edxml.writer.EDXMLWriter