Skip to main content

TLV Python Parser - Version 0.7.1

A Tag-Length-Value (also known as Type-Length-Value) is an encoding scheme used for many protocols.

The tag is fixed in size (can be set from 1 to 4 bytes). The length is automatically determined by how many bytes it would take to represent the size of the value by default, but could be set to a fixed size (from 1 to 4 bytes). The value field is of variable size.

The fields are:

  • Tag: An alphanumeric code that represents the kind of field the object represents;
  • Length: Size of the value field (in bytes);
  • Value: Variable-sized series of bytes which contains data for this field object.

Advantages of using TLV:

  • Sequences are usually easy to parse;
  • Unknown tags or elements can be skipped or ignored, so new versions can be added without a problem;
  • Elements can be placed in any order;
  • New elements can be created without breaking the protocol itself or the parsing function.

For more information, you can see: https://en.wikipedia.org/wiki/Type-length-value

Installation

You can install directly from PyPI:

  pip install uttlv

Or download the source code and install using pip:

  pip install .

How to use

To start using this package, just import the package and create an object

  from uttlv import TLV

  # Create object
  t = TLV()

To add a tag to object, do it like a dict value:

  # A tag of int value
  t[0x01] = 10
  # A tag of string value
  t[0x02] = 'test'
  # A tag of an array of bytes
  t[0x03] = bytes([1, 2, 3])
  # Or another TLV object
  another_one = TLV()
  another_one[0x05] = 234
  t[0x04] = another_one

A tag can only be int, str, bytes or a TLV itself. Any other type will raise a TypeError exception. If a tag is inserted and another object with same tag value already exists on the object, the tag will be overriden with the new value.

To get the underlying array, just call to_byte_array() method:

  arr = t.to_byte_array()
  print('TLV:', arr)

Parse

To parse an array, just call the method parse_array():

  # create object
  t = TLV()
  # parse from object
  data = bytes([0x03, 0x00, 0x04, 0x00, 0x00, 0x00, 0x0A])
  t.parse_array(data)

Pretty print

If you call tree(), the object will create a string with a tree-like structure to print:

  from prtlv import TLV

  # Create object
  t = TLV()
  # Add value
  t[0x01] = 10
  # Print it
  print('Value:\n', t.tree())
  ## <output>
  ## Value: 
  ## 1: 10
  ##

Tag map

You can also add a dictionary to map a tag to its underline class type, so it's showed as correct type instead of a bytearray.

The dictionary must have all keys as the tag values and its respective values as the class type of the tag:

  config = {
      0x01: {TLV.Config.Type: int, TLV.Config.Name: 'NUM_POINTS'},
      0x02: {TLV.Config.Type: int, TLV.Config.Name: 'IDLE_PERIOD'},
      0x03: {TLV.Config.Type: str, TLV.Config.Name: 'NAME'},
      0x04: {TLV.Config.Type: str, TLV.Config.Name: 'CITY'},
      0x05: {TLV.Config.Type: bytes, TLV.Config.Name: 'VERSION'},
      0x06: {TLV.Config.Type: bytes, TLV.Config.Name: 'DATA'},
      0x07: {TLV.Config.Type: TLV, TLV.Config.Name: 'RELATED'},
      0x08: {TLV.Config.Type: TLV, TLV.Config.Name: 'COMMENT'},
      0x09: {TLV.Config.Type: TLV, TLV.Config.Name: 'Empty'}
  }

  # Set global default map
  TLV.set_global_tag_map(config)

  # Set tag map for a specific instance (this will override the global setting)
  t = TLV()
  t.set_local_tag_map(config)

For now, only 'int', 'str', 'bytes', 'TLV', and a dictionary are accepted as valid classes. Any other class will raise AttributeError.

If a tag map is configured, one can use the tag name to access its value:

 t = TLV()
 t['NUM_POINTS'] = 10
 print(t['NUM_POINTS'])

Nested tag maps can be configured by replacing the configured type with another configuration dictionary:

  config = {
    0x01: {TLV.Config.Name: 'FIRST_NEST', TLV.Config.Type: {
      0x01: {TLV.Config.Name: 'SECOND_NEST', TLV.Config.Type: {
        0x01: {TLV.Config.Name: 'THIRD_NEST', TLV.Config.Type: int}
      }}
    }}
  }

And also can print it with all tag names instead of values:

 t.tree(use_names=True)
 ## <output>
 ## NUM_POINTS: 10

You can access also the tags directly:

 t = TLV()
 t['NUM_POINTS'] = 10
 print(t.NUM_POINTS)

By default, a field defined as type str in the tag map would be encoded or decoded as utf-8. The encoder can be replaced to use utf16, utf32 or ascii by setting it in

 uttlv.tlv.ALLOWED_TYPES[str] = uttlv.tlv.encoder.Utf16Encoder

or

 uttlv.tlv.ALLOWED_TYPES[str] = uttlv.tlv.encoder.Utf32Encoder

or

 uttlv.tlv.ALLOWED_TYPES[str] = uttlv.tlv.encoder.AsciiEncoder

respectively.

Iterator

You can iterate through the available tags inside a TLV object by using iter():

t = TLV()
t.parse_array(bytes(command_data))

for command in t:
  pass

Metadata

Release files for uttlv 0.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uttlv 0.7.1
File Size Uploaded Provenance Actions
uttlv-0.7.1.tar.gz 8.8 kB Without provenance Details for uttlv-0.7.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for uttlv 0.7.1
File Interpreter ABI Platform Actions
uttlv-0.7.1-py3-none-any.whl Python 3 none any Details for uttlv-0.7.1-py3-none-any.whl

Total release size: 17.6 kB

Release files / uttlv-0.7.1.tar.gz

Download URL uttlv-0.7.1.tar.gz
Size 8.8 kB
Tags Source
SHA-256 checksum
How to use checksums
68c39b83383ca93a1e229ed1bdefb648cab49e272bff05803004bf80392ae5a7
BLAKE2b-256 checksum
How to use checksums
591b38936eb5e223ec7655db94d982943e698eea41da32a6d7263cdf7ee0f04f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.1.14 CPython/3.10.5 Windows/10

Release files / uttlv-0.7.1-py3-none-any.whl

Download URL uttlv-0.7.1-py3-none-any.whl
Size 8.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0729452afa2de5531e1d624c382ac44c72c6aecb1de1acd249a1bed74aafc72c
BLAKE2b-256 checksum
How to use checksums
71b4c1c2ce613c48e7925010fa63aff1282ef0a04eaf898a3c1e331521c4fbd6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.1.14 CPython/3.10.5 Windows/10

Security for uttlv 0.7.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page