Pure Python `X.690`_ implementation
===================================

.. image:: https://github.com/exhuma/x690/workflows/Build%20&%20Publish%20Docs/badge.svg?branch=main
    :alt: Build & Publish Docs

.. _X.690: https://www.itu.int/rec/recommendation.asp?lang=en&parent=T-REC-X.690-201508-I


This module contains a pure Python implementation of the "x690" standard for
BER encoding/decoding. Other encodings are currently unsupported but
pull-requests are welcome.


Supporting New Types
--------------------

Some applications may need to support types which are not defined in the X.690
standard. This is supported by this library but the types must be defined and
registered.

To register a type, simply subclass ``x690.types.Type``. This will take care of
the registration. Make sure that your new type is imported before using it.

New types should define the following 3 class-variables:

**TYPECLASS**
    A value from ``x690.util.TypeClass``
**NATURE**
    A value from ``x690.util.TypeNature``
**TAG**
    A numerical identifier for the type

Refer to the x690 standard for more details on these values. As a general
rule-of-thumb you can assume that the class is either "context" or
"application" (it might be good to keep the "universal" class reserved for
x690). The nature should be "primitive" for simple values and "constructed" for
composed types. The tag is free to choose as long as you don't overlap with an
existing type.

To convert raw-bytes into a Python object, override ``x690.Type.decode_raw``
and conversely also ``x690.Type.encode_raw``. Refer to the docstrings for more
details.


Reverse Engineering Bytes
-------------------------

All types defined in the ``x690`` library provide a ``.pretty()`` method which
returns a prettyfied string.

If you are confronted with a bytes-object encoded using X.690 but don't have
any documentation, you can write the following loop::

    from x690 import decode

    data = open("mydatafile.bin", "rb").read()

    value, nxt = decode(data)
    print(value.pretty())

    while nxt < len(data):
        value, nxt = decode(data, nxt)
        print(value.pretty())

This should get you started.

If the data contain non-standard types, they will get detected as "UnknownType"
and will print out the type-class, nature and tag in the pretty-printed block.

This will allow you to define your own subclass of ``x690.types.Type`` using
those values. Override ``decode(...)`` in that class to handle the unknown
type.


Examples
========

Encoding to bytes
-----------------

Encoding to bytes can be done by simply calling the Python builting ``bytes()``
on instances from ``x690.types``:

Encoding of a single value
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    >>> import x690.types as t
    >>> myvalue = t.Integer(12)
    >>> asbytes = bytes(myvalue)
    >>> repr(asbytes)
    b'\x02\x01\x0c'

Encoding of a composite value using Sequence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    >>> import x690.types as t
    >>> myvalue = t.Sequence(
    ...     t.Integer(12),
    ...     t.Integer(12),
    ...     t.Integer(12),
    ... )
    >>> asbytes = bytes(myvalue)
    >>> repr(asbytes)
    b'0\t\x02\x01\x0c\x02\x01\x0c\x02\x01\x0c'


Decoding from bytes
~~~~~~~~~~~~~~~~~~~

Decode bytes by calling ``x690.types.decode`` on your byte data. This will
return a tuple where the first value contains the decoded object, and the
second one will contain any remaining bytes which were not decoded.

.. code:: python

    >>> import x690
    >>> data = b'0\t\x02\x01\x0c\x02\x01\x0c\x02\x01\x0c'
    >>> decoded, nxt = x690.decode(data)
    >>> decoded
    Sequence(Integer(12), Integer(12), Integer(12))
    >>> nxt
    11


Type-Hinting & Enforcing
~~~~~~~~~~~~~~~~~~~~~~~~

**New in 0.3.0**

When decoding bytes, it is possible to specify an expcted type which does two
things: Firstly, it tells tools like ``mypy`` what the return type will be and
secondly, it runs an internal type-check which *ensures* that the returned
value is of the expected type. ``x690.exc.UnexpectedType`` is raised otherwise.

This does of course only work if you know the type in advance.

.. code:: python

    >>> import x690
    >>> import x690.types as t
    >>> data = b'0\t\x02\x01\x0c\x02\x01\x0c\x02\x01\x0c'
    >>> decoded, nxt = x690.decode(data, enforce_type=t.Sequence)
    >>> decoded
    Sequence(Integer(12), Integer(12), Integer(12))
    >>> nxt
    11


Strict Decoding
~~~~~~~~~~~~~~~

**New in 0.3.0**

When decoding using ``decode`` and you don't expect any remaining bytes, use
``strict=True`` which will raise ``x690.exc.IncompleteDecoding`` if there's any
remaining data.

.. code:: python

    >>> import x690
    >>> data = b'0\t\x02\x01\x0c\x02\x01\x0c\x02\x01\x0cjunk-bytes'
    >>> decoded, nxt = x690.decode(data, strict=True)
    Traceback (most recent call last):
      ...
    x690.exc.IncompleteDecoding: Strict decoding still had 10 remaining bytes!
