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 document

  • namespace – 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 event

  • amending_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 event

  • repealing_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() and manifestation_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:

  1. Strict: the official AKN schema

  2. 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.