utils#

Some utilities for manipulating EBML documents: translate to/from XML, etc. This module may be imported or used as a command-line utility.

Created on Aug 11, 2017

todo:

Clean up and standardize usage of the term ‘size’ versus ‘length.’

todo:

Modify (or create an alternate version of) toXml() that writes directly to a file, allowing the conversion of huge EBML files.

todo:

Add other options to command-line utility for the other arguments of toXml() and xml2ebml().

ebmlite.util.createID(schema, idClass, exclude=(), minId=129, maxId=536870910, count=1)#

Generate unique EBML IDs. Primarily intended for use ‘offline’ by humans creating EBML schemata.

Parameters:

  • schema (Schema) – The Schema in which the new IDs must coexist.

  • idClass (str) – The EBML class of ID, one of (case-insensitive): * ‘a’: Class A (1 octet, base 0x8X) * ‘b’: Class B (2 octets, base 0x4000) * ‘c’: Class C (3 octets, base 0x200000) * ‘d’: Class D (4 octets, base 0x10000000)

  • exclude (Tuple[int]) – A list of additional IDs to avoid.

  • minId (int) – The minimum ID value, within the ID class’ range.

  • maxId (int) – The maximum ID value, within the ID class’ range.

  • count (int) – The maximum number of IDs to generate. The result may be fewer than specified if too few meet the given criteria.

Return type:

List[int]

Returns:

A list of EBML IDs that match the given criteria.

ebmlite.util.flatiter(element, depth=None)#

Recursively crawl an EBML document or element, depth-first, yielding all elements (or elements down to a given depth).

Parameters:

  • element – The EBML Document or Element to iterate.

  • depth – The maximum recursion depth. None or a value less than zero will fully recurse without limit.

ebmlite.util.loadXml(xmlFile, schema, ebmlFile=None)#

Helpful utility to load an EBML document from an XML file.

Parameters:

  • xmlFile – The XML source. Can be a filename, an open file-like stream, or a parsed XML document.

  • schema (Schema) – The EBML schema to use. Can be a filename or an instance of a Schema.

  • ebmlFile (Union[BinaryIO, str, None]) – The name of the temporary EBML file to write, or :memory: to use RAM (like sqlite3). Defaults to an automatically-generated temporary file.

:return The root node of the specified EBML file.

ebmlite.util.pprint(el, values=True, out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, indent='  ', binary_codec='ignore', void_codec='ignore', _depth=0)#

Test function to recursively crawl an EBML document or element and print its structure, with child elements shown indented.

Parameters:

  • el (Element) – An instance of a Document or Element subclass.

  • values (bool) – If True, show elements’ values.

  • out (IO) – A file-like stream to which to write.

  • indent (str) – The string containing the character(s) used for each indentation.

  • binary_codec (Union[Callable, str]) – The name of a class from ebmlite.xml_codecs, or an instance of a codec, for rendering binary elements as text.

  • void_codec (Union[Callable, str]) – The name of a class from ebmlite.xml_codecs, or an instance of a codec, for rendering the contents of Void elements as text.

ebmlite.util.printSchemata(paths=None, out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, absolute=True)#

Display a list of schemata in SCHEMA_PATH. A thin wrapper for the core listSchemata() function.

Parameters:

  • paths (Optional[List[Union[str, Path]]]) – A list of paths to search for schemata, in addition to those in SCHEMA_PATH.

  • out (Union[str, Path, IO]) – A file-like stream or filename to which to write.

  • absolute (bool) – If True, use absolute paths in the schema filenames.

ebmlite.util.toXml(el, parent=None, offsets=True, sizes=True, types=True, ids=True, binary_codec='base64', void_codec='ignore')#

Convert an EBML Document to XML. Binary elements will contain base64-encoded data in their body. Other non-master elements will contain their value in a value attribute.

Parameters:

  • el (Element) – An instance of an EBML Element or Document subclass.

  • parent – The resulting XML element’s parent element, if any.

  • offsets (bool) – If True, create a offset attributes for each generated XML element, containing the corresponding EBML element’s offset.

  • sizes (bool) – If True, create size attributes containing the corresponding EBML element’s size.

  • types (bool) – If True, create type attributes containing the name of the corresponding EBML element type.

  • ids (bool) – If True, create id attributes containing the corresponding EBML element’s EBML ID.

  • binary_codec (Union[Callable, str]) – The name of an XML codec class from ebmlite.xml_codecs, or an instance of a codec, for rendering binary elements as text.

  • void_codec (Union[Callable, str]) – The name of an XML codec class from ebmlite.xml_codecs, or an instance of a codec, for rendering the contents of Void elements as text.

:return The root XML element of the file.

ebmlite.util.validateID(elementId)#

Verify that a number is a valid EBML element ID. A ValueError will be raised if the element ID is invalid.

Valid ranges for the four classes of EBML ID are:

  • A: 0x81 to 0xFE

  • B: 0x407F to 0x7FFE

  • C: 0x203FFF to 0x3FFFFE

  • D: 0x101FFFFF to 0x1FFFFFFE

Parameters:

elementId (int) – The element ID to validate

Raises:

ValueError, although certain edge cases may raise another type.

Return type:

bool

ebmlite.util.xml2ebml(xmlFile, ebmlFile, schema, sizeLength=None, headers=True, unknown=True)#

Convert an XML file to EBML.

Todo:

Convert XML on the fly, rather than parsing it first, allowing for the conversion of arbitrarily huge files.

Parameters:

  • xmlFile – The XML source. Can be a filename, an open file-like stream, or a parsed XML document.

  • ebmlFile (BinaryIO) – The EBML file to write. Can be a filename or an open file-like stream.

  • schema (Union[str, Path, Schema]) – The EBML schema to use. Can be a filename or an instance of a Schema.

  • sizeLength (Optional[int]) – The default length of each element’s size descriptor. Must be large enough to store the largest ‘master’ element. If an XML element has a sizeLength attribute, it will override this.

  • headers (bool) – If True, generate the standard EBML EBML element if the XML document does not contain one.

  • unknown (bool) – If True, unknown element names will be allowed, provided their XML elements include an id attribute with the EBML ID (in hexadecimal).

Returns:

the size of the ebml file in bytes.

Raises:

NameError – raises if an xml element is not present in the schema.