synta 0.3.1

ASN.1 parser, decoder, and encoder library with DER/BER support and C FFI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

"""Type stubs for synta.schema."""

from typing import Any, TypeVar, overload

T = TypeVar("T")

def asn1_field(
    *,
    tag: int | None = ...,
    explicit: bool = ...,
    implicit: bool = ...,
    default: Any = ...,
) -> Any:
    """Attach ASN.1 tagging metadata to a dataclass field.

    Returns a ``dataclasses.field()`` suitable for use as a class-body default.

    Args:
        tag: Context tag number (e.g. ``tag=0`` for ``[0]``).
             ``None`` (default) means the field is untagged.
        explicit: If ``True`` (default), use EXPLICIT tagging: the context
                  tag wraps the original TLV intact.
        implicit: If ``True``, use IMPLICIT tagging: the context tag replaces
                  the original tag.  Mutually exclusive with specifying
                  ``explicit=True`` at the same time.
        default: Default value for the dataclass field.  Defaults to ``None``
                 so that ``Optional[T]`` fields work without an extra ``= None``.
    """
    ...

def asn1_sequence_of(cls: type[T]) -> type[T]:
    """Decorator that adds ASN.1 SEQUENCE OF encode/decode to a ``@dataclass``.

    Use for *naked* ``SEQUENCE OF T`` types (homogeneous list with no named
    fields).  The class must have exactly one non-optional ``list[T]`` field;
    the element type is inferred from that annotation.

    Must be applied *after* ``@dataclass``::

        @asn1_sequence_of
        @dataclass
        class JWTClaimNames:
            items: list[synta.IA5String]

    The decorated class gains:

    * ``instance.to_der() -> bytes`` — encode as DER ``SEQUENCE OF T``.
    * ``ClassName.from_der(data: bytes)`` — decode DER bytes into a new instance.
    * ``ClassName._asn1_from_decoder(dec)`` — internal helper for nested use.
    """
    ...

def asn1_sequence(cls: type[T]) -> type[T]:
    """Decorator that adds ASN.1 SEQUENCE encode/decode to a ``@dataclass``.

    Must be applied *after* ``@dataclass``::

        @asn1_sequence
        @dataclass
        class Validity:
            not_before: synta.UtcTime
            not_after:  synta.UtcTime

    The decorated class gains:

    * ``instance.to_der() -> bytes`` — encode as DER SEQUENCE.
    * ``ClassName.from_der(data: bytes)`` — decode DER bytes into a new instance.
    * ``ClassName._asn1_from_decoder(dec)`` — internal helper for nested use.
    """
    ...

def asn1_choice(cls: type[T]) -> type[T]:
    """Decorator that adds ASN.1 CHOICE encode/decode to a ``@dataclass``.

    Must be applied *after* ``@dataclass``::

        @asn1_choice
        @dataclass
        class Time:
            utc_time:         synta.UtcTime | None = None
            generalized_time: synta.GeneralizedTime | None = None

    All fields should be typed as ``SomeType | None`` with ``default=None``.
    Exactly one field must be non-``None`` when encoding.

    The decorated class gains:

    * ``instance.to_der() -> bytes`` — encode the active variant as DER.
    * ``ClassName.from_der(data: bytes)`` — decode DER bytes into a new instance.
    * ``ClassName._asn1_from_decoder(dec)`` — internal helper for nested use.
    """
    ...