Parsers

A parser extract structured information as a tree from a container as a file-like object. It does the type conversion when explicit but does not interpret anything else. Parsers can raise a ParserError.

EBML

EBML (Extensible Binary Meta Language) is used by Matroska and WebM.

Element types

enzyme.parsers.ebml.INTEGER

Signed integer element type

enzyme.parsers.ebml.UINTEGER

Unsigned integer element type

enzyme.parsers.ebml.FLOAT

Float element type

enzyme.parsers.ebml.STRING

ASCII-encoded string element type

enzyme.parsers.ebml.UNICODE

UTF-8-encoded string element type

enzyme.parsers.ebml.DATE

Date element type

enzyme.parsers.ebml.BINARY

Binary element type

enzyme.parsers.ebml.MASTER

Container element type

Main interface

enzyme.parsers.ebml.SPEC_TYPES

Specification types to Element types mapping

enzyme.parsers.ebml.READERS

Element types to reader functions mapping. See Readers

You can override a reader to use one of your choice here:

>>> def my_binary_reader(stream, size):
...     data = stream.read(size)
...     return data
>>> READERS[BINARY] = my_binary_reader
class enzyme.parsers.ebml.Element(id=None, type=None, name=None, level=None, position=None, size=None, data=None)

Base object of EBML

Parameters:
  • id (int) – id of the element, best represented as hexadecimal (0x18538067 for Matroska Segment element)
  • type (INTEGER, UINTEGER, FLOAT, STRING, UNICODE, DATE, MASTER or BINARY) – type of the element
  • name (string) – name of the element
  • level (int) – level of the element
  • position (int) – position of element’s data
  • size (int) – size of element’s data
  • data – data as read by the corresponding READERS
class enzyme.parsers.ebml.MasterElement(id=None, name=None, level=None, position=None, size=None, data=None)

Element of type MASTER that has a list of Element as its data

Parameters:
  • id (int) – id of the element, best represented as hexadecimal (0x18538067 for Matroska Segment element)
  • name (string) – name of the element
  • level (int) – level of the element
  • position (int) – position of element’s data
  • size (int) – size of element’s data
  • data (list of Element) – child elements

MasterElement implements some magic methods to ease manipulation. Thus, a MasterElement supports the in keyword to test for the presence of a child element by its name and gives access to it with a container getter:

>>> ebml_element = parse(open('test1.mkv', 'rb'), get_matroska_specs())[0]
>>> 'EBMLVersion' in ebml_element
False
>>> 'DocType' in ebml_element
True
>>> ebml_element['DocType']
Element(DocType, u'matroska')
load(stream, specs, ignore_element_types=None, ignore_element_names=None, max_level=None)

Load children Elements with level lower or equal to the max_level from the stream according to the specs

Parameters:
  • stream – file-like object from which to read
  • specs (dict) – see Specifications
  • max_level (int) – maximum level for children elements
  • ignore_element_types (list) – list of element types to ignore
  • ignore_element_names (list) – list of element names to ignore
  • max_level – maximum level of elements
get(name, default=None)

Convenience method for master_element[name].data if name in master_element else default

Parameters:
  • name (string) – the name of the child to get
  • default – default value if name is not in the MasterElement
Returns:

the data of the child Element or default
enzyme.parsers.ebml.parse(stream, specs, size=None, ignore_element_types=None, ignore_element_names=None, max_level=None)

Parse a stream for size bytes according to the specs

Parameters:
  • stream – file-like object from which to read
  • size (int or None) – maximum number of bytes to read, None to read all the stream
  • specs (dict) – see Specifications
  • ignore_element_types (list) – list of element types to ignore
  • ignore_element_names (list) – list of element names to ignore
  • max_level (int) – maximum level of elements
Returns:

parsed data as a tree of Element
Return type:

list

Note

If size is reached in a middle of an element, reading will continue until the element is fully parsed.

enzyme.parsers.ebml.parse_element(stream, specs, load_children=False, ignore_element_types=None, ignore_element_names=None, max_level=None)

Extract a single Element from the stream according to the specs

Parameters:
  • stream – file-like object from which to read
  • specs (dict) – see Specifications
  • load_children (bool) – load children elements if the parsed element is a MasterElement
  • ignore_element_types (list) – list of element types to ignore
  • ignore_element_names (list) – list of element names to ignore
  • max_level (int) – maximum level for children elements
Returns:

the parsed element
Return type:

Element
enzyme.parsers.ebml.get_matroska_specs(webm_only=False)

Get the Matroska specs

Parameters:webm_only (bool) – load only WebM specs
Returns:the specs in the appropriate format. See Specifications
Return type:dict

Readers

enzyme.parsers.ebml.readers.read_element_id(stream)

Read the Element ID

Parameters:stream – file-like object from which to read
Raises:ReadError – when not all the required bytes could be read
Returns:the id of the element
Return type:int
enzyme.parsers.ebml.readers.read_element_size(stream)

Read the Element Size

Parameters:stream – file-like object from which to read
Raises:ReadError – when not all the required bytes could be read
Returns:the size of element’s data
Return type:int
enzyme.parsers.ebml.readers.read_element_integer(stream, size)

Read the Element Data of type INTEGER

Parameters:
  • stream – file-like object from which to read
  • size (int) – size of element’s data
Raises:
  • ReadError – when not all the required bytes could be read
  • SizeError – if size is incorrect
Returns:

the read integer
Return type:

int
enzyme.parsers.ebml.readers.read_element_uinteger(stream, size)

Read the Element Data of type UINTEGER

Parameters:
  • stream – file-like object from which to read
  • size (int) – size of element’s data
Raises:
  • ReadError – when not all the required bytes could be read
  • SizeError – if size is incorrect
Returns:

the read unsigned integer
Return type:

int
enzyme.parsers.ebml.readers.read_element_float(stream, size)

Read the Element Data of type FLOAT

Parameters:
  • stream – file-like object from which to read
  • size (int) – size of element’s data
Raises:
  • ReadError – when not all the required bytes could be read
  • SizeError – if size is incorrect
Returns:

the read float
Return type:

float
enzyme.parsers.ebml.readers.read_element_string(stream, size)

Read the Element Data of type STRING

Parameters:
  • stream – file-like object from which to read
  • size (int) – size of element’s data
Raises:
  • ReadError – when not all the required bytes could be read
  • SizeError – if size is incorrect
Returns:

the read ascii-decoded string
Return type:

unicode
enzyme.parsers.ebml.readers.read_element_unicode(stream, size)

Read the Element Data of type UNICODE

Parameters:
  • stream – file-like object from which to read
  • size (int) – size of element’s data
Raises:
  • ReadError – when not all the required bytes could be read
  • SizeError – if size is incorrect
Returns:

the read utf-8-decoded string
Return type:

unicode
enzyme.parsers.ebml.readers.read_element_date(stream, size)

Read the Element Data of type DATE

Parameters:
  • stream – file-like object from which to read
  • size (int) – size of element’s data
Raises:
  • ReadError – when not all the required bytes could be read
  • SizeError – if size is incorrect
Returns:

the read date
Return type:

datetime
enzyme.parsers.ebml.readers.read_element_binary(stream, size)

Read the Element Data of type BINARY

Parameters:
  • stream – file-like object from which to read
  • size (int) – size of element’s data
Raises:
  • ReadError – when not all the required bytes could be read
  • SizeError – if size is incorrect
Returns:

raw binary data
Return type:

bytes

Specifications

The XML specification for Matroska can be found here. It is included with enzyme and can be converted to the appropriate format with get_matroska_specs().

The appropriate format of the specs parameter for parse(), parse_element() and load() is {id: (type, name, level)}