Cobalt API¶
Cobalt has classes for each Akoma Ntoso document type.
Base classes¶
Cobalt’s class hierarchy mimics that of the Akoma Ntoso standard. There is a single root class for all Akoma Ntoso documents. There are subclasses for each of the Akoma Ntoso document structure types, such as hierarchicalStructure, debateStructure, etc. Finally, there is a class for each Akoma Ntoso document type (act, bill, judgment, etc.) that extends the corresponding structure type.
-
class
cobalt.akn.
AkomaNtosoDocument
(xml=None)¶ Base class for Akoma Ntoso documents.
- Variables
root –
lxml.objectify.ObjectifiedElement
root of the XML documentnamespace – primary XML namespace
-
ensure_element
(name, after, at=None)¶ Helper to get an element if it exists, or create it if it doesn’t.
- Parameters
name – dotted path from self or at
after – element after which to place the new element if it doesn’t exist
at – element at which to start looking, (defaults to self if None)
-
get_element
(name, root=None)¶ Lookup a dotted-path element, start at root (or self if root is None). Returns None if the element doesn’t exist.
-
parse
(xml, document_type=None)¶ Parse XML and ensure it’s Akoma Ntoso. Raises ValueError on error. Returns the root element.
-
class
cobalt.akn.
StructuredDocument
(xml=None)¶ Common base class for AKN documents with a known document structure.
-
components
()¶ Get an OrderedDict of component name to
lxml.objectify.ObjectifiedElement
objects. Components are this document, and <component> and <attachment> elements inside this document.
-
document_type
= None¶ The name of the document type, corresponding to the primary document XML element.
-
classmethod
empty_document
(version='3.0')¶ Return XML for an empty document of this type, using the given AKN version.
-
classmethod
empty_meta
(frbr_uri, version='3.0', maker=None)¶ Create a meta element for an frbr_uri, using the provided version or element maker.
-
property
expression_date
¶ Date from the FRBRExpression element
-
expression_frbr_uri
()¶ The FRBR Expression URI as a
cobalt.uri.FrbrUri
instance that uniquely identifies this document universally.
-
classmethod
for_document_type
(document_type)¶ Return the subclass for this document type.
-
property
frbr_uri
¶ The FRBR Manifestation URI as a
cobalt.uri.FrbrUri
instance that uniquely identifies this document universally.
-
property
language
¶ The 3-letter ISO-639-2 language code of this document.
-
property
main
¶ Get the main document element (normally the first child of the root element).
-
property
main_content
¶ Get the main content element of the document.
-
main_content_tag
= None¶ The name of the structural type’s main content element.
-
property
manifestation_date
¶ Date from the FRBRManifestation element
-
property
meta
¶ Get the meta element of the document.
-
parse
(xml, document_type=None)¶ Parse XML and ensure it’s Akoma Ntoso. Raises ValueError on error. Returns the root element.
-
structure_type
= None¶ The name of this document’s structural type.
-
property
title
¶ Short title
-
property
work_date
¶ Date from the FRBRWork element. Normally, this date must match the date portion of the work’s FRBR URI. However, since that may be a partial date (such as just a year), this return value may be different to the date string stored in the FRBRdate element. In particular, if the date is just a year, the month and day both default to 1.
-
Amendment¶
-
class
cobalt.amendment.
Amendment
(xml=None)¶
-
class
cobalt.amendment.
AmendmentList
(xml=None)¶
-
class
cobalt.amendment.
AmendmentStructure
(xml=None)¶
Collection¶
-
class
cobalt.collection.
Collection
(xml=None)¶
-
class
cobalt.collection.
CollectionStructure
(xml=None)¶
-
class
cobalt.collection.
OfficialGazette
(xml=None)¶
Hierarchical structure¶
-
class
cobalt.hierarchical.
Act
(xml=None)¶ Bases:
cobalt.hierarchical.HierarchicalStructure
An Akoma Ntoso Act document.
-
property
publication_date
¶ Date of publication as a datetime.date object.
-
property
publication_name
¶ Name of the publication in which this act was published.
-
property
publication_number
¶ Sequence number of the publication.
-
property
-
class
cobalt.hierarchical.
AmendmentEvent
(date=None, amending_title=None, amending_uri=None)¶ Bases:
object
An event that amended a document.
- Variables
date –
datetime.date
date of the eventamending_title – String title of the amending document
amending_uri – String form of the FRBR URI of the amending document
-
class
cobalt.hierarchical.
Bill
(xml=None)¶ Bases:
cobalt.hierarchical.HierarchicalStructure
An Akoma Ntoso Bill document.
-
class
cobalt.hierarchical.
HierarchicalStructure
(xml=None)¶
-
class
cobalt.hierarchical.
RepealEvent
(date=None, repealing_title=None, repealing_uri=None)¶ Bases:
object
An event that repealed a document.
- Variables
date –
datetime.date
date of the eventrepealing_title – String title of the repealing document
repealing_uri – String form of the FRBR URI of the repealing document
Judgment¶
-
class
cobalt.judgment.
Judgment
(xml=None)¶
-
class
cobalt.judgment.
JudgmentStructure
(xml=None)¶
Open structure¶
-
class
cobalt.openstructure.
DebateReport
(xml=None)¶
-
class
cobalt.openstructure.
Document
(xml=None)¶
-
class
cobalt.openstructure.
OpenStructure
(xml=None)¶
-
class
cobalt.openstructure.
Statement
(xml=None)¶
FRBR URIs¶
-
class
cobalt.uri.
FrbrUri
(country, locality, doctype, subtype, actor, date, number, work_component=None, language=None, expression_date=None, expression_component=None, expression_subcomponent=None, format=None, prefix='akn')¶ An object for working with Akoma Ntoso 3.0 FRBR URIs (IRIs).
URIs can be parsed from a plain string using
parse()
or they can be constructed directly. URIs can be manipulated in-place once constructed, which is useful for turning a work-level URI into an expression or manifestation URI.URIs can be transformed back to the string form of work, expression and manifestation URIs using the
work_uri()
,expression_uri()
andmanifestation_uri()
methods.Example:
>>> uri = FrbrUri.parse('/akn/za-jhb/act/by-law/2003/public-health/eng:2015-01-01/!main/part/A.xml') >>> uri.prefix 'akn' >>> uri.country 'za' >>> uri.locality 'jhb' >>> uri.doctype 'act' >>> uri.subtype 'by-law' >>> uri.date '2003' >>> uri.number 'public-health' >>> uri.language 'eng' >>> uri.expression_date ':2015-01-01' >>> uri.expression_component 'main' >>> uri.expression_subcomponent 'part/A' >>> uri.format 'xml' >>> uri.work_uri() '/za-jhb/act/by-law/2003/public-health' >>> uri.expression_uri() '/za-jhb/act/by-law/2003/public-health/eng:2015-01-01/main/part/A' >>> uri.manifestation_uri() '/za-jhb/act/by-law/2003/public-health/eng:2015-01-01/main/part/A.xml'
- Variables
prefix – optional akn prefix
country – two letter country code
locality – locality within the country, may be None
doctype – type of document (eg.
act
)subtype – document subtype, may be None
actor – emenating actor, may be None
date – document data (str), YYYY[-MM[-DD]]
number – document number (str)
work_component – name of the work component, may be None
language – three-letter expression language code, may be None
expression_date – expression date (str), [@:]YYYY[-MM[-DD]], may be None
expression_component – name of the expression component, may be None
expression_subcomponent – name of the expression subcomponent, may be None
format – format extension, may be None
-
clone
()¶ Return a copy of this FrbrUri object.
-
expression_uri
(work_component=True)¶ String form of the expression URI.
-
manifestation_uri
(work_component=True)¶ String form of the manifestation URI.
-
classmethod
parse
(s)¶ Parse a string into an FrbrUri instance.
- Raises
ValueError – if parsing fails
-
property
place
¶ Full place code, including both country and locality (if present).
-
uri
()¶ String form of the work URI, excluding the work component, if any.
-
work_uri
(work_component=True)¶ String form of the work URI.
-
property
year
¶ The year, derived from
date
. Read-only.
Schemas and validation¶
Cobalt can validate Akoma Ntoso documents against the Akoma Ntoso schema. Two schemas are provided:
Strict: the official AKN schema
Lenient: a slightly modified version of the official schema. Duplicate eId attributes are allowed, and FRBRdate elements are allowed to have year-only @date values.
-
cobalt.schemas.
validate
(akn_doc, strict=False)¶ Validate this AKN document against its schema. if strict is True, then also validate the uniqueness of eId attributes. Returns a (validates, errors) tuple.
-
cobalt.schemas.
assert_validates
(akn_doc, strict=False)¶ Assert that this AKN document validates against the AKN schema. Raises lxml.etree.DocumentInvalid if validation fails.