asnkitrt 1.0.1__py3-none-any.whl

asnkitrt/__init__.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2025 BoxTheta
+#
+# SPDX-License-Identifier: MIT
+
+"""Encode and decode ASN.1 types of compiled specifications, which
+are found in `.asni` files.
+
+Nothing in this package parses ASN.1. That is what the compiler
+`asnkitcc` does, which makes the `.asni` files.
+
+```python
+>>> import asnkitrt
+>>> foo = asnkitrt.load_asni_file('foo.asni', 'uper')
+>>> foo.encode('Question', {'id': 1, 'question': 'Is 1+1=3?'})
+```
+
+"""
+
+from . import codecs, constants, errors, runtime, syntax
+from .errors import (
+    CompileError,
+    ConstraintsError,
+    DecodeError,
+    EncodeError,
+    Error,
+    ParseError,
+)
+from .runtime import Specification, load, load_asni, load_asni_file
+from .version import __version__
+
+__author__ = "BoxTheta"
+
+__all__ = [
+    "CompileError",
+    "ConstraintsError",
+    "DecodeError",
+    "EncodeError",
+    "Error",
+    "ParseError",
+    "Specification",
+    "codecs",
+    "constants",
+    "errors",
+    "load",
+    "load_asni",
+    "load_asni_file",
+    "runtime",
+    "syntax",
+    "__version__",
+]

asnkitrt/codecs/__init__.py

@@ -0,0 +1,520 @@
+# Copyright (c) 2025 BoxTheta
+# Copyright (c) 2017-2019 Erik Moqvist
+#
+# SPDX-License-Identifier: MIT
+
+import importlib
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Any, List
+
+from ..errors import ConstraintsError as _ConstraintsError
+from ..errors import DecodeError as _DecodeError
+from ..errors import EncodeError as _EncodeError
+from ..errors import Error
+
+
+class BaseType(object):
+    """
+    Base Type class containing common functionality between all codecs
+    """
+
+    def __init__(self, name: str, type_name: str) -> None:
+        self.name = name
+        self.type_name = type_name
+        self.optional = False
+        self.default: Any = None
+
+    def set_default(self, value: Any) -> None:
+        self.default = value
+
+    def get_default(self) -> Any:
+        return self.default
+
+    def has_default(self) -> bool:
+        return self.default is not None
+
+    def is_default(self, value: Any) -> bool:
+        return value == self.default
+
+    def encode(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError("To be implemented by subclasses.")
+
+    def decode(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError("To be implemented by subclasses.")
+
+    def __repr__(self) -> str:
+        return "{}({})".format(self.__class__.__name__, self.name)
+
+    def type_label(self) -> str:
+        return (
+            "{}({})".format(self.type_name, self.name) if self.name else self.type_name
+        )
+
+
+class ErrorWithLocation(Exception):
+    """
+    Mixin for Error classes which have location list
+    """
+
+    def __init__(self, message: str, location: BaseType | None = None) -> None:
+        """
+
+        :param str message:
+        :param BaseType location: Type error occured for
+        """
+        self.message = message
+        self.location: List[BaseType] = [location] if location else []
+
+    def add_location(self, element: BaseType) -> None:
+        """
+        Add location data for element
+        :param BaseType element:
+        :return:
+        """
+        # Don't add name if it is blank (for SEQUENCE OF, SET OF etc)
+        if not getattr(element, "no_error_location", False) and (
+            not self.location or element != self.location[-1]
+        ):
+            self.location.append(element)
+
+    @property
+    def location_str(self) -> str:
+        return ".".join(loc.name for loc in self.location[::-1] if loc.name)
+
+    def __str__(self) -> str:
+        if self.location:
+            return "{}: {}".format(self.location_str, self.message)
+        else:
+            return self.message
+
+
+class EncodeError(ErrorWithLocation, _EncodeError):
+    """General ASN.1 encode error."""
+
+    pass
+
+
+class NamedNumbersMixin(object):
+    """An INTEGER, which can be given by the name of any of its named
+    numbers when encoding. It is always a number when decoded.
+
+    """
+
+    named_numbers: Any = None
+
+    def to_number(self, data: Any) -> Any:
+        if not isinstance(data, str):
+            return data
+
+        try:
+            return self.named_numbers[data]
+        except (KeyError, TypeError):
+            raise EncodeError(
+                "Expected an integer or a named number, but got '{}'.".format(data)
+            )
+
+    def is_default(self, value: Any) -> bool:
+        return self.to_number(value) == self.default  # type: ignore[attr-defined]
+
+
+class DecodeError(ErrorWithLocation, _DecodeError):
+    """
+    General ASN.1 decode error with error location in the message.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        offset: int | None = None,
+        location: BaseType | None = None,
+    ) -> None:
+        """
+
+        :param str message: Message for error
+        :param int offset: Data offset at which error occurred. Can be bits or bytes depending on codec
+        :param BaseType location: Element in which error occurred
+        """
+        super(DecodeError, self).__init__(message, location=location)
+        self.offset = offset
+
+    def __str__(self) -> str:
+        if self.location:
+            _str = "{}: {}".format(self.location_str, self.message)
+        else:
+            _str = self.message
+        if self.offset is not None:
+            _str += self.get_offset_message()
+        return _str
+
+    def get_offset_message(self) -> str:
+        """
+        Get offset details to add to error message
+        :return:
+        """
+        return " (At offset: {})".format(self.offset)
+
+
+class ConstraintsError(ErrorWithLocation, _ConstraintsError):
+    """
+    General ASN.1 constraints error with error location in the message.
+    """
+
+    pass
+
+
+class OutOfDataError(DecodeError):
+    """
+    Error for when trying to read data beyond length of type
+    """
+
+    def __init__(self, offset_bits: int, location: BaseType | None = None) -> None:
+        super(OutOfDataError, self).__init__(
+            "out of data", offset=offset_bits, location=location
+        )
+
+    def get_offset_message(self) -> str:
+        """
+        Get offset details to add to error message
+        :return:
+        """
+        return " (At bit offset: {})".format(self.offset)
+
+
+# A GeneralizedTime: the date and the hour, then the minute and the
+# second or not, a fraction of the last of them or not, and the offset
+# or not (X.680 46.3).
+_GENERALIZED_TIME = re.compile(
+    r"(\d{4})(\d{2})(\d{2})(\d{2})(?:(\d{2})(\d{2})?)?(?:[.,](\d+))?"
+    r"(Z|[+-]\d{2}(?:\d{2})?)?\Z",
+    re.ASCII,
+)
+
+
+def _parse_generalized_time(string: str) -> datetime:
+    match = _GENERALIZED_TIME.match(string)
+
+    if match is None:
+        raise ValueError
+
+    year, month, day, hour, minute, second, fraction, offset = match.groups()
+
+    # A fraction is one of the hour, the minute or the second, as
+    # microseconds rounded down. The digits past the 20th are less than a
+    # microsecond, and are not looked at.
+    if minute is None:
+        unit = 3_600_000_000
+    elif second is None:
+        unit = 60_000_000
+    else:
+        unit = 1_000_000
+
+    if fraction is None:
+        microseconds = 0
+    else:
+        digits = fraction[:20]
+        microseconds = int(digits) * unit // 10 ** len(digits)
+
+    minutes = int(minute or 0) + microseconds // 60_000_000
+    microseconds %= 60_000_000
+    seconds = int(second or 0) + microseconds // 1_000_000
+
+    if offset is None:
+        tzinfo = None
+    elif offset == "Z":
+        tzinfo = timezone(timedelta(hours=0))
+    else:
+        hours = int(offset[1:3])
+        offset_minutes = int(offset[3:5] or 0)
+
+        if hours > 23 or offset_minutes > 59:
+            raise ValueError
+
+        sign = -1 if offset[0] == "-" else 1
+        tzinfo = timezone(timedelta(minutes=sign * (hours * 60 + offset_minutes)))
+
+    return datetime(
+        int(year),
+        int(month),
+        int(day),
+        int(hour),
+        minutes,
+        seconds,
+        microseconds % 1_000_000,
+        tzinfo=tzinfo,
+    )
+
+
+def check_local_time(value: Any) -> None:
+    """Check that `value`, a ``datetime.time`` or a ``datetime.datetime``,
+    is one of a TIME-OF-DAY or a DATE-TIME, which are a local time to the
+    second (X.680 38.4.2, 38.4.3).
+
+    """
+
+    if value.microsecond != 0 or value.tzinfo is not None:
+        raise EncodeError(
+            "A TIME-OF-DAY or a DATE-TIME has no fraction of a second and no offset."
+        )
+
+
+def format_or(items: List[Any]) -> str:
+    """Return a string of comma separated items, with the last to items
+    separated by "or".
+
+    [1, 2, 3] -> "1, 2 or 3"
+
+    """
+
+    formatted_items = []
+
+    for item in items:
+        try:
+            item = "'" + item + "'"
+        except TypeError:
+            item = str(item)
+
+        formatted_items.append(item)
+
+    if len(items) == 1:
+        return formatted_items[0]
+    else:
+        return "{} or {}".format(", ".join(formatted_items[:-1]), formatted_items[-1])
+
+
+def utc_time_to_datetime(string: str) -> datetime:
+    """Convert given ASN.1 UTC time string `string` to a
+    ``datetime.datetime`` object.
+
+    """
+
+    length = len(string)
+
+    try:
+        if string[-1] == "Z":
+            if length == 11:
+                return datetime.strptime(string[:-1], "%y%m%d%H%M")
+            elif length == 13:
+                return datetime.strptime(string[:-1], "%y%m%d%H%M%S")
+            else:
+                raise ValueError
+        elif length == 15:
+            return datetime.strptime(string, "%y%m%d%H%M%z")
+        elif length == 17:
+            return datetime.strptime(string, "%y%m%d%H%M%S%z")
+        else:
+            raise ValueError
+    except (ValueError, IndexError):
+        raise Error("Expected a UTC time string, but got '{}'.".format(string))
+
+
+def utc_time_from_datetime(date: datetime) -> str:
+    """Convert given ``datetime.datetime`` object `date` to an ASN.1 UTC
+    time string.
+
+    """
+
+    fmt = "%y%m%d%H%M"
+
+    if date.second > 0:
+        fmt += "%S"
+
+    if date.tzinfo is None:
+        fmt += "Z"
+    else:
+        fmt += "%z"
+
+    return date.strftime(fmt)
+
+
+def restricted_utc_time_to_datetime(string: str) -> datetime:
+    """Convert given restricted ASN.1 UTC time string `string` to a
+    ``datetime.datetime`` object.
+
+    """
+
+    try:
+        if string[-1] != "Z":
+            raise ValueError
+
+        if len(string) != 13:
+            raise ValueError
+
+        return datetime.strptime(string[:-1], "%y%m%d%H%M%S")
+    except (ValueError, IndexError):
+        raise Error(
+            "Expected a restricted UTC time string, but got '{}'.".format(string)
+        )
+
+
+def restricted_utc_time_from_datetime(date: datetime) -> str:
+    """Convert given ``datetime.datetime`` object `date` to an restricted
+    ASN.1 UTC time string.
+
+    """
+
+    offset = date.utcoffset()
+
+    if offset is not None:
+        date -= offset
+
+    return date.strftime("%y%m%d%H%M%S") + "Z"
+
+
+def generalized_time_to_datetime(string: str) -> datetime:
+    """Convert given ASN.1 generalized time string `string` to a
+    ``datetime.datetime`` object.
+
+    """
+
+    try:
+        return _parse_generalized_time(string)
+    except (ValueError, IndexError):
+        raise Error("Expected a generalized time string, but got '{}'.".format(string))
+
+
+def generalized_time_from_datetime(date: datetime) -> str:
+    """Convert given ``datetime.datetime`` object `date` to an ASN.1
+    generalized time string.
+
+    """
+
+    # A fraction after the minute would be one of a minute (X.680 46.3).
+    if date.microsecond > 0:
+        string = date.strftime("%Y%m%d%H%M%S.%f").rstrip("0")
+    elif date.second > 0:
+        string = date.strftime("%Y%m%d%H%M%S")
+    else:
+        string = date.strftime("%Y%m%d%H%M")
+
+    if date.tzinfo is not None:
+        if date.utcoffset():
+            string += date.strftime("%z")
+        else:
+            string += "Z"
+
+    return string
+
+
+def restricted_generalized_time_to_datetime(string: str) -> datetime:
+    """Convert given restricted ASN.1 generalized time string `string` to
+    a ``datetime.datetime`` object.
+
+    """
+
+    try:
+        if string[-1] != "Z":
+            raise ValueError
+
+        if "." in string:
+            if string[-2] == "0":
+                raise ValueError
+
+            if string[14] != ".":
+                raise ValueError
+        elif len(string) != 15:
+            raise ValueError
+
+        # Read as a time with no offset.
+        return _parse_generalized_time(string[:-1])
+    except (ValueError, IndexError):
+        raise Error(
+            "Expected a restricted generalized time string, but got '{}'.".format(
+                string
+            )
+        )
+
+
+def restricted_generalized_time_from_datetime(date: datetime) -> str:
+    """Convert given ``datetime.datetime`` object `date` to an restricted
+    ASN.1 generalized time string.
+
+    """
+
+    offset = date.utcoffset()
+
+    if offset is not None:
+        date -= offset
+
+    if date.microsecond > 0:
+        string = date.strftime("%Y%m%d%H%M%S.%f").rstrip("0")
+    else:
+        string = date.strftime("%Y%m%d%H%M%S")
+
+    return string + "Z"
+
+
+def bmp_string_encode(text: str) -> bytes:
+    """A BMPString in the 2-octet form, of which each character is in the
+    BMP (X.690 8.23.8, X.696 27.4).
+
+    """
+
+    for character in text:
+        if ord(character) > 0xFFFF:
+            raise EncodeError(
+                "Expected a character in the BMP, but got U+{:04X}.".format(
+                    ord(character)
+                )
+            )
+
+    return text.encode("utf-16-be")
+
+
+def bmp_string_decode(data: bytes | bytearray) -> str:
+    """The text of a BMPString in the 2-octet form. A surrogate is not a
+    character.
+
+    """
+
+    if len(data) % 2 != 0:
+        raise DecodeError("Expected a BMPString of an even number of octets.")
+
+    units = [
+        int.from_bytes(data[offset : offset + 2], "big")
+        for offset in range(0, len(data), 2)
+    ]
+
+    for unit in units:
+        if 0xD800 <= unit <= 0xDFFF:
+            raise DecodeError(
+                "Expected a character in the BMP, but got the surrogate "
+                "0x{:04X}.".format(unit)
+            )
+
+    return "".join(map(chr, units))
+
+
+def format_bytes(tag: bytes | bytearray) -> str:
+    """
+    Format tag as hex string
+    :param bytes tag:
+    :return:
+    """
+    return tag.hex()
+
+
+# A codec is imported when first used, by name or as an attribute of
+# this package.
+_SUBMODULES = [
+    "ber",
+    "codec",
+    "compiler",
+    "constraints_checker",
+    "der",
+    "gser",
+    "jer",
+    "oer",
+    "per",
+    "permitted_alphabet",
+    "type_checker",
+    "uper",
+    "xer",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name in _SUBMODULES:
+        return importlib.import_module("." + name, __name__)
+
+    raise AttributeError("module '{}' has no attribute '{}'".format(__name__, name))