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, attribs=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 with a known namespace. Raises ValueError on error.
- 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, for_root=True)¶
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.
- get_portion_element(portion, component=None)¶
Get a single portion of this document. The portion is usually an eId, as specified by https://docs.oasis-open.org/legaldocml/akn-nc/v1.0/os/akn-nc-v1.0-os.html#_Toc531692279.
The optional component is the ancestor element within which to look for the portion.
Range portions (eg. chp_1->chp_3) are not supported by this function.
- 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.
- non_eid_portions = ['arguments', 'background', 'conclusions', 'decision', 'header', 'introduction', 'motivation', 'preamble', 'preface', 'remedies']¶
Portion names that are valid portions, but don’t have eids, for use with get_portion_element.
- 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.
- cobalt.akn.datestring(value)¶
Format a date as an XML-suitable string. If the date is None, uses NULL_DATE.
- cobalt.akn.parsedate(value)¶
Parse an XML date string into a real date. If the value is the NULL_DATE, returns None.
Amendment¶
- class cobalt.amendment.Amendment(xml=None)¶
Bases:
AmendmentStructure
- document_type = 'amendment'¶
The name of the document type, corresponding to the primary document XML element.
- class cobalt.amendment.AmendmentList(xml=None)¶
Bases:
CollectionStructure
- document_type = 'amendmentList'¶
The name of the document type, corresponding to the primary document XML element.
- class cobalt.amendment.AmendmentStructure(xml=None)¶
Bases:
StructuredDocument
- main_content_tag = 'amendmentBody'¶
The name of the structural type’s main content element.
- structure_type = 'amendmentStructure'¶
The name of this document’s structural type.
Collection¶
- class cobalt.collection.Collection(xml=None)¶
Bases:
CollectionStructure
- document_type = 'documentCollection'¶
The name of the document type, corresponding to the primary document XML element.
- class cobalt.collection.CollectionStructure(xml=None)¶
Bases:
StructuredDocument
- main_content_tag = 'collectionBody'¶
The name of the structural type’s main content element.
- structure_type = 'collectionStructure'¶
The name of this document’s structural type.
- class cobalt.collection.OfficialGazette(xml=None)¶
Bases:
CollectionStructure
- document_type = 'officialGazette'¶
The name of the document type, corresponding to the primary document XML element.
Debate¶
- class cobalt.debate.Debate(xml=None)¶
Bases:
DebateStructure
- document_type = 'debate'¶
The name of the document type, corresponding to the primary document XML element.
- class cobalt.debate.DebateStructure(xml=None)¶
Bases:
StructuredDocument
- main_content_tag = 'debateBody'¶
The name of the structural type’s main content element.
- structure_type = 'debateStructure'¶
The name of this document’s structural type.
Hierarchical structure¶
- class cobalt.hierarchical.Act(xml=None)¶
Bases:
HierarchicalStructure
An Akoma Ntoso Act document.
- document_type = 'act'¶
The name of the document type, corresponding to the primary document XML element.
- 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.
- 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:
HierarchicalStructure
An Akoma Ntoso Bill document.
- document_type = 'bill'¶
The name of the document type, corresponding to the primary document XML element.
- class cobalt.hierarchical.HierarchicalStructure(xml=None)¶
Bases:
StructuredDocument
- main_content_tag = 'body'¶
The name of the structural type’s main content element.
- structure_type = 'hierarchicalStructure'¶
The name of this document’s structural type.
- 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)¶
Bases:
JudgmentStructure
- document_type = 'judgment'¶
The name of the document type, corresponding to the primary document XML element.
- class cobalt.judgment.JudgmentStructure(xml=None)¶
Bases:
StructuredDocument
- main_content_tag = 'judgmentBody'¶
The name of the structural type’s main content element.
- structure_type = 'judgmentStructure'¶
The name of this document’s structural type.
Open structure¶
- class cobalt.openstructure.DebateReport(xml=None)¶
Bases:
OpenStructure
- document_type = 'debateReport'¶
The name of the document type, corresponding to the primary document XML element.
- class cobalt.openstructure.Document(xml=None)¶
Bases:
OpenStructure
- document_type = 'doc'¶
The name of the document type, corresponding to the primary document XML element.
- class cobalt.openstructure.OpenStructure(xml=None)¶
Bases:
StructuredDocument
- main_content_tag = 'mainBody'¶
The name of the structural type’s main content element.
- structure_type = 'openStructure'¶
The name of this document’s structural type.
- class cobalt.openstructure.Statement(xml=None)¶
Bases:
OpenStructure
- document_type = 'statement'¶
The name of the document type, corresponding to the primary document XML element.
Portion¶
- class cobalt.portion.Portion(xml=None)¶
Bases:
PortionStructure
- document_type = 'portion'¶
The name of the document type, corresponding to the primary document XML element.
- class cobalt.portion.PortionStructure(xml=None)¶
Bases:
StructuredDocument
- main_content_tag = 'portionBody'¶
The name of the structural type’s main content element.
- structure_type = 'portionStructure'¶
The name of this document’s structural type.
FRBR URIs¶
- class cobalt.uri.FrbrUri(country, locality, doctype, subtype, actor, date, number, work_component=None, language=None, expression_date=None, format=None, portion=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_1.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.work_component 'main' >>> uri.portion 'part_1' >>> 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_1' >>> uri.manifestation_uri() '/za-jhb/act/by-law/2003/public-health/eng:2015-01-01/!main~part_1.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
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.