dbxincluder API documentation

Internals

dbxincluder is divided into two parts:

The xinclude submodule handles the pure XInclude 1.1 specification. It was necessary to re-implement it in Python as libxml2 does not handle all required XInclude 1.1 features itself.

When processing a document, it is first run through the XInclude processor, then the DocBook transclusion processor.

dbxincluder.xinclude

The XInclude process works in two stages:

The first stage handles all xi:include elements by replacing them with either the target subdocument or the xi:fallback child, if available.

The second stage then handles the xi:fallback elements in the document by replacing them with their content. As xi:fallback can contain muliple children, this can’t happen in the first stage due to the way the iteration works.

xinclude module: Processes raw XInclude 1.1 elements

exception dbxincluder.xinclude.ResourceError(elem, message=None, file=None, severity='Error')

Same as DBXIException, just for resource errors

dbxincluder.xinclude.append_to_tail(elem, string)

Append str to elem’s tail.

dbxincluder.xinclude.append_to_text(elem, string)

Append str to elem’s text.

dbxincluder.xinclude.copy_attributes(elem, subtree)

Modifies subtree according to https://www.w3.org/XML/2012/08/xinclude-11/Overview.html#attribute-copying with the attributes of elem. Does not return anything.

Parameters:
  • elem – XInclude source elemend
  • subtree – Target subtree/element
dbxincluder.xinclude.flatten_subtree(tree)

Remove all xi:fallback elements in tree by replacing them with their content.

dbxincluder.xinclude.get_target(elem, base_url, xmlcatalog=None, file=None)

Return tuple of the content of the target document as string and the URL that was used

Parameters:
  • elem – XInclude element
  • base_url – xml:base of the element
  • xmlcatalog – XML catalog to use (None means default)
Raises:
  • DBXIException – href attribute is missing
  • ResourceError – Couldn’t fetch target
dbxincluder.xinclude.handle_xifallback(elem, xmlcatalog=None, file=None, xinclude_stack=None)

Process the xi:include tag elem. It will be replaced by the content of the xi:fallback subelement.

Parameters:
  • elem – The XInclude element to process
  • xmlcatalog – XML catalog to use (None means default)
  • file – URL used to report errors
  • xinclude_stack – List (or None) of str with url and fragid to detect infinite recursion
Returns:

True if xi:fallback found
dbxincluder.xinclude.handle_xinclude(elem, base_url, xmlcatalog=None, file=None, xinclude_stack=None)

Process the xi:include tag elem.

Parameters:
  • elem – The XInclude element to process
  • base_url – xml:base to use if not specified in the document
  • xmlcatalog – XML catalog to use (None means default)
  • file – URL used to report errors
  • xinclude_stack – List (or None) of str with url and fragid to detect infinite recursion
dbxincluder.xinclude.parse_fragid_rfc5147(fragid)

https://tools.ietf.org/html/rfc5147

Returns:None or tuple(‘line’/’char’, start, end/None)
dbxincluder.xinclude.process_subtree(tree, base_url, xmlcatalog, file, xinclude_stack)

Like process_xinclude, but for subtrees.

dbxincluder.xinclude.process_tree(tree, base_url=None, xmlcatalog=None, file=None, xinclude_stack=None)

Processes an ElementTree: - Search and process xi:include - Add xml:base (=source) to the root element - Add dbxi:line to show where the source xi:include is

Parameters:
  • tree – ElementTree to process (gets modified)
  • base_url – xml:base to use if not set in the tree
  • xmlcatalog – XML catalog to use (None means default)
  • file – URL used to report errors
  • xinclude_stack – Internal
dbxincluder.xinclude.process_xinclude(tree, base_url=None, xmlcatalog=None, file=None, parent_line=None, xinclude_stack=None)

Processes an ElementTree: - Search and process xi:include - Add xml:base (=source) to the root element - Add dbxi:parentline to the root element to show where it was included at

This does not resolve xi:fallback correctly. Use process_tree for that.

Parameters:
  • tree – ElementTree to process (gets modified)
  • base_url – xml:base to use if not set in the tree
  • xmlcatalog – XML catalog to use (None means default)
  • file – URL used to report errors
  • parent_line – line in the document where the source xi:include is
  • xinclude_stack – Internal
dbxincluder.xinclude.text_fragid(content, fragid=None)

Implementation of https://tools.ietf.org/html/rfc5147

If fragid is invalid, it returns the complete content as according to the nonsensical spec.

Parameters:
  • content – Input as str
  • fragid – fragid according to RFC5147
Return tuple:

(Result as str, Success as bool)
dbxincluder.xinclude.validate_xinclude(elem, file)

Raise DBXIException if the XInclude element elem is not valid.

dbxincluder.docbook

The DocBook transclusion process works in three stages:

First, the XIncluded document is iterated and each element with xml:id set gets a new custom dbxi:newid attribute. This is computed for each element separately, based on the nearest trans:idfixup and trans:linkscope values.

The second stage iterates the document again, finding all references to elements in the same document and updating them to the new values of the dbxi:newid attributes.

The last pass cleans up the custom attributes by setting xml:id to the value of dbxi:newid and removing the dbxi: attributes. It also removes DocBook transclusiton attributes (trans:\*) and unneeded namespace declarations.

Handle the DocBook specific part of transclusion

dbxincluder.docbook.associate_new_ids(subtree)

Assign elements their new ids as new ‘dbxi:newid’ attribute.

Parameters:subtree – The XIncluded subtree to process
dbxincluder.docbook.find_target(elem, subtree, value, linkscope)

Resolves reference to id value beginning from elem

Parameters:
  • elem – Source of reference
  • subtree – XIncluded subtree
  • value – ID of reference
  • linkscope – DB transclusion linkscope (local/near/global)
Returns:

Target element or None
dbxincluder.docbook.fixup_references(subtree)

Fix all references if idfixup is set

Parameters:subtree – subtree to process
dbxincluder.docbook.new_ref(elem, idfixup_elem, value, linkscope)

Returns the fixed reference as string or None. Uses same parameters as find_target.

dbxincluder.docbook.process_tree(tree, base_url, xmlcatalog=None, file=None)

Processes an ElementTree. Handles all xi:include with xinclude.process_tree and processes all docbook attributes on the output.

Parameters:
  • tree – ElementTree to process (gets modified)
  • base_url – xml:base to use if not set in the tree
  • xmlcatalog – XML catalog to use (None means default)
  • file – URL used to report errors
Returns:

Nothing