cap-tools 3.1.1

Python data bindings for the Common Alerting Protocol Version.

CAP-Tools

Python data bindings for the Common Alerting Protocol Version 1.2.

Getting started

This package contains a Python model for CAP XML documents that was generated using using xsData along with some convenience utilities.

To parse a CAP XML from a file into an instance of cap_tools.models.Alert, do as follows:

from cap_tools.models import Alert
from xsdata.formats.dataclass.parsers import XmlParser

parser = XmlParser()
alert = parser.parse("path/to/my/cap.xml", Alert)

For advanced usage, just take a look at the xsData docs.

Convenience utilities

In addition to the code that was generated using xsData, this library adds some convenience utilities on top.

Transforming the system-specific key-value-pairs to mappings

The Info.parameters, Info.event_codes and Area.geocode fields generated by xsData are implemented as a list of (containers of) key-value-pairs.

>>> import cap_tools
>>> from xsdata.formats.dataclass.parsers import XmlParser
>>> parser = XmlParser()
>>> alert = parser.parse("data/oasis/example2.xml")
>>> area = alert.infos[0].areas[0]
>>> area.geocodes
[Geocode(value_name=ValueName(value='SAME'), value=Value(value='006109')), Geocode(value_name=ValueName(value='SAME'), value=Value(value='006009')), Geocode(value_name=ValueName(value='SAME'), value=Value(value='006003'))]

This can more ergonomically be represented using a mapping. Use the Info.parameters_to_dict, Info.event_codes_to_dict and Area.geocode_to_dict methods to create instances of MultiDict from the data.

>>> geocodes_multidict = area.geocodes_to_dict()
>>> geocodes_multidict
<MultiDict('SAME': '006109', 'SAME': '006009', 'SAME': '006003')>
>>> geocodes_multidict["SAME"]
'006109'
>>> geocodes_multidict.getall("SAME")
['006109', '006009', '006003']

Remember that MultiDict.__getitem__() uses the first occurence of the key while a dict would have used the last because of its overwrite rules.

You can also write any mapping to the instance fields using the Info.parameters_from_dict, Info.event_codes_from_dict and Area.geocode_from_dict methods.

Use the MultiDict:

>>> geocodes_multidict.add("SAME", "123456")
>>> area.geocodes_from_dict(geocodes_multidict)
>>> area.geocodes
[Geocode(value_name=ValueName(value='SAME'), value=Value(value='006109')), Geocode(value_name=ValueName(value='SAME'), value=Value(value='006009')), Geocode(value_name=ValueName(value='SAME'), value=Value(value='006003')), Geocode(value_name=ValueName(value='SAME'), value=Value(value='123456'))]

Or use a dict:

>>> area.geocodes_from_dict({"foo": "bar", "lorem": "ipsum"})
>>> area.geocodes
[Geocode(value_name=ValueName(value='foo'), value=Value(value='bar')), Geocode(value_name=ValueName(value='lorem'), value=Value(value='ipsum'))]

The MultiDicts do not retain any connection to the model. In all cases, the internal state is always represented by the list of containers of key-value-pairs.

Splitting group listings

The attributes addresses, references and incidents of Alert store multiple values as "group listings", i.e. multiple values are space-delimited. You can split these attributes by using Alert.addresses_to_list(), Alert.references_to_list() and Alert.incidents_to_list() and write back to them with corresponding Alert.*_from_list() methods respectively.

Awareness of "en-US" as the default language

When no language is explicitly defined on an Info element, "en-US" is assumed per CAP spec. This library implements this behavior neither by using default values nor by using descriptor fields.

>>> alert.infos[0].language = "en-US"
>>> alert.infos[0].language
'en-US'
>>> alert.infos[0].language = None
>>> alert.infos[0].language is None
True
>>> alert.infos[0].language == "en-US"
False

To still have this "absence means en-US" logic implemented, two convenience methods are added to Info.

>>> alert.infos[0].set_language("de-DE")
>>> alert.infos[0].language
'de-DE'
>>> alert.infos[0].set_language("en-US")
>>> alert.infos[0].language is None
True
>>> alert.infos[0].get_language()
'en-US'

Using Info.get_language() returns "en-US" when Info.language is None and Info.set_language("en-US") sets Info.language to None (implicitly "en-US") instead of "en-US" (explicitly).

Limitations

While this library is fully typed to enable Python type safety, it currently does neither implement the pattern restrictions from the CAP v1.2 XSD specification (i.e. the pattern restriction for the XmlDateTime fields) nor the additional restrictions imposed by the normative alert message structure (e.g. Alert.identifier must not include spaces, commas or the characters "<" and "&").

This does not matter much when using this library for reading CAP messages - but when you are using this library to create CAP messages, you are responsible for respecting those additional restrictions yourself!