{
"info": {
"author": "Mide Technology",
"author_email": "help@mide.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 5 - Production/Stable",
"License :: OSI Approved :: MIT License",
"Natural Language :: English",
"Programming Language :: Python :: 2.7"
],
"description": "_ebmlite_ README\r\n================\r\n\r\n_ebmlite_ is a lightweight, \"pure Python\" library for parsing EBML (Extensible Binary Markup Language) data. It is designed to crawl through EBML files quickly and efficiently, and that's about it. _ebmlite_ can also do basic EBML encoding, but more advanced EBML manipulation (e.g. with a proper [DOM](https://en.wikipedia.org/wiki/Document_Object_Model)) are beyond its scope, and are better left to other libraries.\r\n\r\n_ebmlite_ is currently a work-in-progress. It is usable (we use it extensively), but does not (yet) implement the full EBML specification.\r\n\r\nParts of _ebmlite_ were modeled after [python-ebml](https://github.com/jspiros/python-ebml), which we had previously been using, but is not a directly derivative work. _ebmlite_ can import _python-ebml_ schemata XML (to a limited degree), but that is the extent of its cross-compatibility.\r\n\r\nEBML Overview (the short version)\r\n---------------------------------\r\n\r\n[EBML](http://matroska-org.github.io/libebml/) (Extensible Binary Markup Language) is a hierarchical tagged binary format, originally created for the [Matroska](https://www.matroska.org/) project. The hierarchical structure of EBML bears some conceptual/functional similarity to XML, although the actual structure differs significantly.\r\n\r\nIn the raw, EBML elements consist of a numeric ID, the size of the element, and a payload. It is space-efficient; the lengths of the ID and size descriptors are variable, using prefix bits to indicate their lengths, a system similar to UTF-8. The mapping of IDs to names and payload data types is done via an external schema.\r\n\r\nSee the [official specification](http://matroska-org.github.io/libebml/specs.html) for more information.\r\n\r\nEBML Schemata\r\n-------------\r\n\r\nAn EBML file is largely meaningless without a schema that defines its elements. The schema maps element IDs to names and data types; it also describes the structure (e.g. what elements can be children of other elements) and provides additional metadata. *Note: ebmlite currently uses the structure for decoding only, and does not stringently enforce it.*\r\n\r\n_ebmlite_ schemata are defined in XML. From these XML files, a `Schema` instance is created; within the `Schema` are `Element` subclasses for each element defined in the XML. Since the interpretation of an EBML file is almost entirely dependent on a schema, importing of EBML files is done through a `Schema` instance.\r\n\r\n```python\r\nfrom ebmlite import loadSchema\r\nschema = loadSchema('mide_ide.xml')\r\ndoc = schema.load('test_file.ebml')\r\n```\r\n\r\n_ebmlite_ uses its own Schema definition syntax; it can also import python-ebml schemata. It does not (currently) use the [official schema format](https://github.com/Matroska-Org/ebml-specification/blob/master/specification.markdown#ebml-schema).\r\n\r\nHere is an example of an _ebmlite_ schema, showing a simplified version of the definition of the standard EBML header elements:\r\n```XML\r\n\r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\nEach element defined in the schema is a subclass of one of 8 Element base classes:\r\n* **MasterElement:** An element containing other elements.\r\n* **IntegerElement:** Contains a signed integer value of variable length.\r\n* **UIntegerElement:** Contains an unsigned integer value of variable length.\r\n* **FloatElement:** Contains a 32 or 64 bit floating point value.\r\n* **StringElement:** Contains printable US-ASCII characters (0x20 to 0x7E).\r\n* **UnicodeElement:** Contains UTF-8 string data.\r\n* **DateElement:** Contains a timestamp, stored as nanoseconds since 2001-01-01T00:00:00 UTC as a 64 bit integer. _ebmlite_ automatically translates this into a Python `datetime.datetime` object.\r\n* **BinaryElement:** Contains binary data.\r\n\r\nElement definitions have several attributes:\r\n* `name` (string): The Element subclass' name.\r\n* `id` (integer): The Element subclass' EBML ID.\r\n* `global` (bool, optional): If \"true\" (e.g. `1` or `True`), the element may\r\nappear in any location in an EBML file, not just where it appears in the\r\nschema. This is equivalent to a `depth` of `-1` in a _python-ebml_ schema\r\n* `length` (integer, optional): A fixed size to use when encoding the element, overriding the EBML variable length encoding. Use to create byte-aligned structures.\r\n* `multiple` (bool, optional, default=1): Indicates that the element can appear more than once within the same parent. *Currently partially enforced for encoding.*\r\n* `mandatory` (bool, optional, default=0): Indicates that the element *must* be present. *Not currently enforced.*\r\n* `precache` (bool, optional, default varies by type): Indicates that the element's value should be read and cached when the element is parsed, rather than 'lazy-loaded' when explicitly accessed. Can be used to reduce the number of seeks when working with an EBML file after it has been imported. Simple numeric element types have this enabled by default; master, binary, and string/Unicode elements do not.\r\n\r\nThere are two additional, special-case Element subclasses which are not subclassed:\r\n* **UnknownElement:** Instantiated for elements with IDs that do not appear in the schema. Its payload is treated as binary data. The UnknownElement itself does not appear in the Schema. Unlike other Element subclasses, its ID can vary from instance to instance.\r\n* **VoidElement:** \"Void\" (ID `0xEC`) is a standard EBML element, typically used for padding. If the Schema defines the Void element, it is replaced by this special-case element. The contents of its payload are ignored.\r\n\r\nThe structure of the schema's XML defines the structure of the EBML document; children of a MasterElement in the schema are valid child element types in the EBML. An Element type can appear multiple times in a schema; i.e. if its type can appear as a child of different parent types. Only the first definition requires both `name` and `id` attributes. Successive definitions can be abbreviated to just the `name` and/or `id`; they will inherit all the other attributes of the first definition. Successive definitions must *not* have contradictory attributes, however.\r\n```XML\r\n\r\n \r\n \r\n \r\n \r\n\r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n \r\n\r\n \r\n \r\n \r\n \r\n \r\n\r\n```\r\n\r\n**Note:** As seen in the example above, _ebmlite_ allows an EBML document to have multiple elements at its root level. Several other EBML libraries do this as well, but this is apparently counter to the official spec. Officially, an EBML document should have only a single root element, similar to an XML file.\r\n\r\n_ebmlite_\r\n----------------\r\n### Schema\r\nThe ``Schema`` class is a factory used to encode and decode EBML files. When it's initialized, it scans through the schema file and creates a new class for each element present in the file; then, when encoding or decoding files, it references these classes in order to encapsulate everything safely. \r\n\r\n### Documents\r\n``Documents`` are subclasses of MasterElements, which act as an interface to EBML files and act as the root node of the EBML tree. Each ``Schema`` also creates a ``Document`` subclass to use, and the base ``Document`` class will not function without class variables defined by the ``Schema``. \r\n\r\n### Utils\r\nThe functions provided by util.py will expose the majority of functionality needed to users, without the need to interface too deeply with this library. The following functions are provided:\r\n* util.**toXml**(el, [parent=``None``,] [offsets=``True``,] [sizes=``True``,] [types=``True``,] [ids=``True``]): \r\nRecursively converts EBML elements into xml elements. \r\nArgument *el*: an EBML element or document. \r\nOptional argument *parent*: The resulting XML element's parent element, if any. \r\nOptional argument *offsets*: If `True`, create an ``offset`` attributes for\r\n each generated XML element, containing the corresponding EBML element's\r\n offset. \r\nOptional argument *sizes*: If `True`, create ``size`` attributes containing the\r\n corresponding EBML element's size. \r\nOptional argument *types*: If `True`, create ``type`` attributes containing the\r\n name of the corresponding EBML element type. \r\nOptional argument *ids*: If `True`, create ``id`` attributes containing the\r\n corresponding EBML element's EBML ID. \r\nReturns the root of an XML tree created using the xml.etree.ElementTree\r\n built-in class. \r\n\r\n\r\n* util.**xmlElement2ebml**(xmlEl, ebmlFile, schema, [sizeLength=4,] [unknown=True]): \r\nRecursively converts XML elements tonight into EBML elements. \r\nArgument *xmlEl*: The XML element. Its tag must match an element defined in the\r\n `schema`. \r\nArgument *ebmlFile*: An open file-like stream, to which the EBML data will be\r\n written. \r\nArgument *schema*: An `ebmlite.core.Schema` instance to use when writing the\r\n EBML document. \r\nOptional argument *sizeLength*: \r\nOptional argument *unknown*: If `True`, unknown element names will be allowed,\r\n provided their XML elements include an ``id`` attribute with the EBML\r\n ID (in hexadecimal). \r\nReturns the length of the encoded element, including header and children. \r\nRaises *NameError*: raised if an xml element is not present in the schema and\r\n unknown is False, OR if the xml element does not have an ID. \r\n\r\n\r\n* util.**xml2ebml**(xmlFile, ebmlFile, schema, [sizeLength=4,] [headers=True,] [unknown=True]):\r\nArgument *xmlFile*: The XML source. Can be a filename, an open file-like\r\n stream, or a parsed XML document. \r\nArgument *ebmlFile*: The EBML file to write. Can be a filename or an open\r\n file-like stream. \r\nArgument *schema*: The EBML schema to use. Can be a filename or an instance of\r\n a `Schema`. \r\nOptional argument *sizeLength*: The default length of each element's size\r\n descriptor. Must be large enough to store the largest 'master' element.\r\n If an XML element has a ``sizeLength`` attribute, it will override\r\n this. \r\nOptional argument *headers*: If `True`, generate the standard ``EBML`` EBML\r\n element if the XML document does not contain one. \r\nOptional argument *unknown*: If `True`, unknown element names will be allowed,\r\n provided their XML elements include an ``id`` attribute with the EBML\r\n ID (in hexadecimal). \r\nReturns the size of the ebml file in bytes. \r\nRaises NameError: raises if an xml element is not present in the schema.\r\n\r\n\r\n* util.**loadXml**(xmlFile, schema, [ebmlFile=``None``]): \r\nHelpful utility to load an EBML document from an XML file. \r\nArgument *xmlFile*: The XML source. Can be a filename, an open file-like\r\n stream, or a parsed XML document. \r\nArgument *schema*: The EBML schema to use. Can be a filename or an instance of\r\n a `Schema`. \r\nOptional Argument *ebmlFile*: The name of the temporary EBML file to write, or\r\n ``:memory:`` to use RAM (like `sqlite3`). Defaults to an\r\n automatically-generated temporary file. \r\nReturns the root node of the specified EBML file\r\n\r\n\r\n* util.**pprint**: \r\nTest function to recursively crawl an EBML document or element and print its\r\n structure, with child elements shown indented. \r\nArgument *el*: An instance of a `Document` or `Element` subclass. \r\nArgument *values*: If `True`, show elements' values. \r\nOptional Argument *out*: A file-like stream to which to write. \r\nOptional argument *indent*: The string containing the character(s) used for each\r\n indentation.\r\n\r\nUtils can also be called from the command line with the following syntax:\r\n```commandline\r\npython util.py {xml2ebml|ebml2xml|view} {FILE1.ebml|FILE1.xml} SCHEMA.xml [-o {FILE2.xml|FILE2.ebml}] [-c|--clobber] [-p|--pretty]\r\n```\r\nThe program requires you to specify a mode: xml2ebml, ebml2xml, or view. The first two modes convert xml files to ebml files and ebml files to xml files, respectively; the last mode formats an IDE file to be human-readable. \r\nFILE1: The location of the ebml or xml file to convert/view. \r\nSCHEMA: The location of the schema to use when interpreting these files. \r\nFILE2: The location to output to; otherwise, the output is directed into the console. \r\n-c|--clobber: If FILE2 exists, then overwrite it, otherwise the program will fail. \r\n-p|--pretty: Prints the output in a human-readable format.\r\n\r\n\r\nTo Do\r\n=====\r\n* Complete documentation and example code.\r\n* See `@todo` items in the Python files (i.e. `core.py`).\r\n\r\n\r\n",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/MideTechnology/ebmlite",
"keywords": "ebml binary matroska webm",
"license": "MIT",
"maintainer": "",
"maintainer_email": "",
"name": "ebmlite",
"package_url": "https://pypi.org/project/ebmlite/",
"platform": "",
"project_url": "https://pypi.org/project/ebmlite/",
"project_urls": {
"Homepage": "https://github.com/MideTechnology/ebmlite"
},
"release_url": "https://pypi.org/project/ebmlite/1.0.2/",
"requires_dist": null,
"requires_python": "~=2.7",
"summary": "A lightweight, \"pure Python\" library for parsing EBML (Extensible Binary Markup Language) data.",
"version": "1.0.2"
},
"last_serial": 5891871,
"releases": {
"1.0.0": [
{
"comment_text": "",
"digests": {
"md5": "c47d17bd7cb85794a8d866b79988915d",
"sha256": "b385aa8c00df9d1f3e41a1ec212dcd9306ec5a2ccd26c227a937c00a0a58fccf"
},
"downloads": -1,
"filename": "ebmlite-1.0.0-py2-none-any.whl",
"has_sig": false,
"md5_digest": "c47d17bd7cb85794a8d866b79988915d",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": "~=2.7",
"size": 11557926,
"upload_time": "2018-10-24T16:58:30",
"url": "https://files.pythonhosted.org/packages/70/01/bed56286542280086c53052bb365128a840716b60c3f9c5f25193ccc2a08/ebmlite-1.0.0-py2-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "5239c3536779c89d64af99c540c402d5",
"sha256": "4f9213843a3de9f55e11d3349e3a52e5e69511660ec028aad09be1bc7d89e21f"
},
"downloads": -1,
"filename": "ebmlite-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "5239c3536779c89d64af99c540c402d5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=2.7",
"size": 11551374,
"upload_time": "2018-10-24T16:58:54",
"url": "https://files.pythonhosted.org/packages/98/7e/4ef5a78d672e0f875ff99b1da31147e8a75c40ba486ab32b822584c279bc/ebmlite-1.0.0.tar.gz"
}
],
"1.0.1": [
{
"comment_text": "",
"digests": {
"md5": "778cbb7c9db0a4a497103070622b3c82",
"sha256": "0595ded6613a5fbc86b88b4936d0ecc9bc0866c1cf52d4db8919a2c201d195b8"
},
"downloads": -1,
"filename": "ebmlite-1.0.1-py2-none-any.whl",
"has_sig": false,
"md5_digest": "778cbb7c9db0a4a497103070622b3c82",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": "~=2.7",
"size": 11558078,
"upload_time": "2018-11-02T19:31:58",
"url": "https://files.pythonhosted.org/packages/e9/fb/3676d32b5e10b1b671408c59e61cee3afe981c0c824560b991b2882069bb/ebmlite-1.0.1-py2-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "74f60efcf0790ee44774b653f36ec085",
"sha256": "801be5a9dd03c6494ee3e51ea6adda6b209c1e58de3d987a5fc96dedbc5832b4"
},
"downloads": -1,
"filename": "ebmlite-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "74f60efcf0790ee44774b653f36ec085",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=2.7",
"size": 11551452,
"upload_time": "2018-11-02T19:32:19",
"url": "https://files.pythonhosted.org/packages/d3/df/a8f11926892b79246b5f14c9b51a6de1da7e8ebe32bc3494a84f9391e238/ebmlite-1.0.1.tar.gz"
}
],
"1.0.2": [
{
"comment_text": "",
"digests": {
"md5": "10ee74ea3b54fab9e620509795d21d1f",
"sha256": "9618564d029846f25e2ad6bc3407a579d944cb3fb7ece431565a72547c445006"
},
"downloads": -1,
"filename": "ebmlite-1.0.2-py2-none-any.whl",
"has_sig": false,
"md5_digest": "10ee74ea3b54fab9e620509795d21d1f",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": "~=2.7",
"size": 11568341,
"upload_time": "2019-09-26T17:51:51",
"url": "https://files.pythonhosted.org/packages/fc/52/673f01aa00daeb575ac0b3d5998443c0e80220c5877637cc0fb5d410aeb6/ebmlite-1.0.2-py2-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "d0fdc0b06cd8dde8a87c46c80f3b8204",
"sha256": "791ee39ff4045048bc5b1649da2d7dfc8dcacfde2994a3ea43fa73aa5ce1fd84"
},
"downloads": -1,
"filename": "ebmlite-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "d0fdc0b06cd8dde8a87c46c80f3b8204",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=2.7",
"size": 69955,
"upload_time": "2019-09-26T17:51:54",
"url": "https://files.pythonhosted.org/packages/e7/04/8d8961ec30bd1abff387f7756736249a59864936f7b4536ed00f8fdda70d/ebmlite-1.0.2.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "10ee74ea3b54fab9e620509795d21d1f",
"sha256": "9618564d029846f25e2ad6bc3407a579d944cb3fb7ece431565a72547c445006"
},
"downloads": -1,
"filename": "ebmlite-1.0.2-py2-none-any.whl",
"has_sig": false,
"md5_digest": "10ee74ea3b54fab9e620509795d21d1f",
"packagetype": "bdist_wheel",
"python_version": "py2",
"requires_python": "~=2.7",
"size": 11568341,
"upload_time": "2019-09-26T17:51:51",
"url": "https://files.pythonhosted.org/packages/fc/52/673f01aa00daeb575ac0b3d5998443c0e80220c5877637cc0fb5d410aeb6/ebmlite-1.0.2-py2-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "d0fdc0b06cd8dde8a87c46c80f3b8204",
"sha256": "791ee39ff4045048bc5b1649da2d7dfc8dcacfde2994a3ea43fa73aa5ce1fd84"
},
"downloads": -1,
"filename": "ebmlite-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "d0fdc0b06cd8dde8a87c46c80f3b8204",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=2.7",
"size": 69955,
"upload_time": "2019-09-26T17:51:54",
"url": "https://files.pythonhosted.org/packages/e7/04/8d8961ec30bd1abff387f7756736249a59864936f7b4536ed00f8fdda70d/ebmlite-1.0.2.tar.gz"
}
]
}