Cobalt Documentation. Release Code for South Africa

Size: px

Start display at page:

Download "Cobalt Documentation. Release Code for South Africa"

Clementine Wilson
5 years ago
Views:

1 Cobalt Documentation Release Code for South Africa Mar 09, 2018

3 Contents 1 Quickstart 3 2 Contributing 5 3 Contents cobalt Indices and tables 13 Python Module Index 15 i

4 ii

5 Cobalt is a lightweight Python library for working with Akoma Ntoso Act documents. It makes it easy to work with Akoma Ntoso metadata, FRBR URIs and generate Tables of Contents for a document. It is lightweight because most operations are done on the XML document directly without intermediate objects. You still need to understand how Akoma Ntoso works. Contribute to Cobalt on GitHub at github.com/code4sa/cobalt. Contents 1

6 2 Contents

7 CHAPTER 1 Quickstart Install using: $ pip install cobalt Use it like this: >>> from cobalt import Act >>> act = Act() >>> act.title = "Act 10 of 1980" >>> act.frbr_uri = "/za/act/1980/10" >>> act.year '1980' >>> act.number '10' >>> print act.to_xml() [ lots of xml ] 3

8 4 Chapter 1. Quickstart

9 CHAPTER 2 Contributing 1. Clone the repo 2. Install development dependencies: pip install -e.[dev] 3. Make your changes 4. Run tests: nosetests && flake8 5. Send a pull request 5

10 6 Chapter 2. Contributing

11 CHAPTER 3 Contents 3.1 cobalt Acts class cobalt.act.act(xml=none) An act is a lightweight wrapper around an Akoma Ntoso 2.0 XML act document. It provides methods to help access and manipulate the underlying XML directly, in particular the metadata for the document. The Act object provides quick access to certain sections of the document: See also: Variables root lxml.objectify.objectifiedelement root of the XML document meta lxml.objectify.objectifiedelement meta element body lxml.objectify.objectifiedelement body element init (xml=none) Setup a new instance with the string in xml. body_xml The raw XML string of the body element of the document. When setting this property, XML must be rooted at a body element. components() Get an OrderedDict of component name to lxml.objectify.objectifiedelement objects. expression_date Date from the FRBRExpression element expression_frbr_uri() The FRBR Expression URI as a FrbrUri instance that uniquely identifies this document universally. 7

12 frbr_uri The FRBR Work URI as a FrbrUri instance that uniquely identifies this document universally. get_subcomponent(component, subcomponent) Get the named subcomponent in this document, such as chapter/2 or section/13a. lxml.objectify. ObjectifiedElement or None. language The 3-letter ISO language code of this document manifestation_date Date from the FRBRManifestation element nature The nature of the document, such as an act, derived from frbr_uri. Read-only. number The act number, derived from frbr_uri. Read-only. publication_date Date of the publication publication_name Name of the publication in which this act was published publication_number Sequence number of the publication table_of_contents(builder=none) Get the table of contents of this document as a list of cobalt.toc.tocelement instances. title Short title work_date Date from the FRBRWork element year The act year, derived from frbr_uri. Read-only. class cobalt.toc.tocbuilder This builds a Table of Contents for an Act. A Table of Contents is a tree of TOCElement instances, each element representing an item of interest in the Table of Contents. Each item has attributes useful for presenting a Table of Contents, such as a type (chapter, part, etc.), a number, a heading and further child elements. The TOC is assembled from certain tags in the document, see toc_components. The Table of Contents can also be used to lookup the XML element corresponding to an item in the Table of Contents identified by its subcomponent path. This is useful when handling URIs such as.../eng/main/ section/1 or.../eng/main/part/c. See cobalt.act.act.get_subcomponent(). Some components can be uniquely identified by their type and number, such as Section 2. Others require context, such as Part 2 of Chapter 1. The latter are controlled by toc_non_unique_elements. The easiest way to build a Table of Contents is with cobalt.act.act.table_of_contents(). init () x. init (... ) initializes x; see help(type(x)) for signature table_of_contents(act) Get the table of contents of act as a list of TOCElement instances. 8 Chapter 3. Contents

13 class cobalt.toc.tocelement(element, component, type_, heading=none, id_=none, num=none, subcomponent=none, parent=none, children=none) An element in the table of contents of a document, such as a chapter, part or section. Variables children further TOC elements contained in this one, may be None or empty element lxml.objectify.objectifiedelement the XML element of this TOC element heading heading for this element, excluding the number, may be None id XML id string of the node in the document, may be None num number of this element, as a string, may be None component number of the component that this item is a part of, as a string subcomponent name of this subcomponent, used by cobalt.act.act. get_subcomponent(), may be None type element type, one of: chapter, part, section etc. init (element, component, type_, heading=none, id_=none, num=none, subcomponent=none, parent=none, children=none) friendly_title() Build a friendly title for this, based on heading names etc 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) An FRBR URI parser which understands Akoma Ntoso 3.0 FRBR URIs (IRIs) for works and expressions. 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('/za-jhb/act/by-law/2003/public-health/eng: / main/part/a.xml') >>> uri.country 'za' >>> uri.locality 'jhb' >>> uri.doctype 'act' >>> uri.subtype 'by-law' >>> uri.date '2003' >>> uri.number 'public-health' >>> uri.language 3.1. cobalt 9

14 'eng' >>> uri.expression_date ': ' >>> 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: /main/part/a' >>> uri.manifestation_uri() '/za-jhb/act/by-law/2003/public-health/eng: /main/part/a.xml' See also: Variables 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), 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 akoma-ntoso-3.0-schema/naming-conventions-1/bungenihelpcenterreferencemanualpage init (country, locality, doctype, subtype, actor, date, number, work_component=none, language=none, expression_date=none, expression_component=none, expression_subcomponent=none, format=none) expression_uri(work_component=true) String form of the expression URI. manifestation_uri(work_component=true) String form of the manifestation URI. uri() String form of the work URI, excluding the work component, if any. 10 Chapter 3. Contents

15 work_uri(work_component=true) String form of the work URI Rendering class cobalt.render.htmlrenderer(act=none, uri=none, country=none, language=none, subtype=none, xslt_filename=none, xslt_dir=none, xslt_params=none) Renders an Akoma Ntoso Act XML document into HTML using XSL transforms. For the most part, the document tree is copied directly by converting Akoma Ntoso elements into div or span HTML elements. The class attribute on each element is set to an-element where element is the Akoma Ntoso element name. The id attribute is copied over directly. init (act=none, uri=none, country=none, language=none, subtype=none, xslt_filename=none, xslt_dir=none, xslt_params=none) Create a new, re-usable render. The renderer must be able to find an appropriate XSL stylesheet based on the provided parameters. Parameters act the act from which to take the language, country, etc. uri (cobalt.uri.frbruri) the URI from which to take language, country, etc. country two-letter country code language three- or two-letter language code subtype document subtype (eg. bylaw ), or None xslt_dir directory in which to look for files xslt_filename specify filename directly, all other params ignored xslt_params dict of parameters to pass to the XSLT (optional) defaultidscope(node) Default scope for ID attributes when rendering. render(node) Render an XML Tree or Element object into an HTML string render_xml(xml) Render an XML string into an HTML string 3.1. cobalt 11

16 12 Chapter 3. Contents

17 CHAPTER 4 Indices and tables genindex modindex search 13

18 14 Chapter 4. Indices and tables

19 Python Module Index c cobalt, 7 cobalt.act, 7 cobalt.render, 11 cobalt.toc, 8 cobalt.uri, 9 15

20 16 Python Module Index

21 Index Symbols init () (cobalt.act.act method), 7 init () (cobalt.render.htmlrenderer method), 11 init () (cobalt.toc.tocbuilder method), 8 init () (cobalt.toc.tocelement method), 9 init () (cobalt.uri.frbruri method), 10 A Act (class in cobalt.act), 7 B body_xml (cobalt.act.act attribute), 7 C cobalt (module), 7 cobalt.act (module), 7 cobalt.render (module), 11 cobalt.toc (module), 8 cobalt.uri (module), 9 components() (cobalt.act.act method), 7 D defaultidscope() (cobalt.render.htmlrenderer method), 11 E expression_date (cobalt.act.act attribute), 7 expression_frbr_uri() (cobalt.act.act method), 7 expression_uri() (cobalt.uri.frbruri method), 10 F frbr_uri (cobalt.act.act attribute), 7 FrbrUri (class in cobalt.uri), 9 friendly_title() (cobalt.toc.tocelement method), 9 G get_subcomponent() (cobalt.act.act method), 8 H HTMLRenderer (class in cobalt.render), 11 L language (cobalt.act.act attribute), 8 M manifestation_date (cobalt.act.act attribute), 8 manifestation_uri() (cobalt.uri.frbruri method), 10 N nature (cobalt.act.act attribute), 8 number (cobalt.act.act attribute), 8 P publication_date (cobalt.act.act attribute), 8 publication_name (cobalt.act.act attribute), 8 publication_number (cobalt.act.act attribute), 8 R render() (cobalt.render.htmlrenderer method), 11 render_xml() (cobalt.render.htmlrenderer method), 11 T table_of_contents() (cobalt.act.act method), 8 table_of_contents() (cobalt.toc.tocbuilder method), 8 title (cobalt.act.act attribute), 8 TOCBuilder (class in cobalt.toc), 8 TOCElement (class in cobalt.toc), 8 U uri() (cobalt.uri.frbruri method), 10 W work_date (cobalt.act.act attribute), 8 work_uri() (cobalt.uri.frbruri method), 10 Y year (cobalt.act.act attribute), 8 17

Terminology the actors

Practical #1 Summer School LEX September 2009 C.I.R.S.F.I.D. University of Bologna Monica Palmirani 5-01.-10 1 Legal Analysis 5-01.-10 2 Terminology the actors Original document: text approved by the assembly