soia-client 1.0.0__py3-none-any.whl

soialib/impl/type_adapter.py

@@ -0,0 +1,56 @@
+from collections.abc import Callable
+from typing import Protocol
+
+from soialib import spec
+from soialib.impl.function_maker import ExprLike
+
+
+class TypeAdapter(Protocol):
+    def default_expr(self) -> ExprLike:
+        """
+        The default value for T.
+        """
+        ...
+
+    def to_frozen_expr(self, arg_expr: ExprLike) -> ExprLike:
+        """
+        Transforms the argument passed to the constructor of a frozen class into a
+        frozen value which will be assigned to the attribute of the frozen object.
+
+        The type of the returned expression must be T even if the argument does not have
+        the expected type. Ideally, the expression should raise an error in the latter
+        case.
+        """
+        ...
+
+    def is_not_default_expr(self, arg_expr: ExprLike, attr_expr: ExprLike) -> ExprLike:
+        """
+        Returns an expression which evaluates to true if the given value is *not* the
+        default value for T.
+        This expression is inserted in the constructor of a frozen class, after the
+        attribute has been assigned from the result of freezing arg_expr.
+        If possible, an implemtation should try to use arg_expr instead of attr_expr as
+        it offers a marginal performance advantage ('x' vs 'self.x').
+        """
+        ...
+
+    def to_json_expr(self, in_expr: ExprLike, readable: bool) -> ExprLike:
+        """
+        Returns an expression which can be passed to 'json.dumps()' in order to
+        serialize the given T into JSON format.
+        The JSON flavor (dense versus readable) is given by the 'readable' arg.
+        """
+        ...
+
+    def from_json_expr(self, json_expr: ExprLike) -> ExprLike:
+        """
+        Transforms 'json_expr' into a T.
+        The 'json_expr' arg is obtained by calling 'json.loads()'.
+        """
+        ...
+
+    # TODO: comment!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+    def finalize(
+        self,
+        resolve_type_fn: Callable[[spec.Type], "TypeAdapter"],
+    ) -> None: ...

soialib/keyed_items.py

@@ -0,0 +1,14 @@
+import abc
+from typing import Generic, Optional, TypeVar
+
+
+Item = TypeVar("Item")
+Key = TypeVar("Key")
+
+
+class KeyedItems(Generic[Item, Key], tuple[Item, ...], metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def find(self, key: Key) -> Optional[Item]: ...
+
+    @abc.abstractmethod
+    def find_or_default(self, key: Key) -> Item: ...

soialib/module_initializer.py

@@ -0,0 +1,79 @@
+from typing import Any, Union
+
+from soialib import spec
+from soialib.impl import arrays, enums, optionals, primitives, structs
+from soialib.impl.type_adapter import TypeAdapter
+from soialib.serializer import make_serializer
+
+RecordAdapter = Union[structs.StructAdapter, enums.EnumAdapter]
+
+
+_record_id_to_adapter: dict[str, RecordAdapter] = {}
+
+
+def init_module(
+    module: spec.Module,
+    globals: dict[str, Any],
+    # For testing
+    record_id_to_adapter: dict[str, RecordAdapter] = _record_id_to_adapter,
+) -> None:
+    def resolve_type(type: spec.Type) -> TypeAdapter:
+        if isinstance(type, spec.PrimitiveType):
+            if type == spec.PrimitiveType.BOOL:
+                return primitives.BOOL_ADAPTER
+            elif type == spec.PrimitiveType.BYTES:
+                return primitives.BYTES_ADAPTER
+            elif type == spec.PrimitiveType.FLOAT32:
+                return primitives.FLOAT32_ADAPTER
+            elif type == spec.PrimitiveType.FLOAT64:
+                return primitives.FLOAT64_ADAPTER
+            elif type == spec.PrimitiveType.INT32:
+                return primitives.INT32_ADAPTER
+            elif type == spec.PrimitiveType.INT64:
+                return primitives.INT64_ADAPTER
+            elif type == spec.PrimitiveType.STRING:
+                return primitives.STRING_ADAPTER
+            elif type == spec.PrimitiveType.TIMESTAMP:
+                return primitives.TIMESTAMP_ADAPTER
+            elif type == spec.PrimitiveType.UINT64:
+                return primitives.UINT64_ADAPTER
+        elif isinstance(type, spec.ArrayType):
+            return arrays.get_array_adapter(
+                resolve_type(type.item),
+                type.key_attributes,
+            )
+        elif isinstance(type, spec.OptionalType):
+            return optionals.get_optional_adapter(resolve_type(type.value))
+        elif isinstance(type, str):
+            # A record id.
+            return record_id_to_adapter[type]
+
+    module_adapters: list[RecordAdapter] = []
+    for record in module.records:
+        if record.id in record_id_to_adapter:
+            raise AssertionError(record.id)
+        adapter: RecordAdapter
+        if isinstance(record, spec.Struct):
+            adapter = structs.StructAdapter(record)
+        else:
+            adapter = enums.EnumAdapter(record)
+        module_adapters.append(adapter)
+        record_id_to_adapter[record.id] = adapter
+    # Once all the adapters of the module have been created, we can finalize them.
+    for adapter in module_adapters:
+        adapter.finalize(resolve_type)
+        gen_class = adapter.gen_class
+        # Add the class name to either globals() if the record is defined at the top
+        # level, or the parent class otherwise.
+        record_id = spec.RecordId.parse(adapter.spec.id)
+        parent_id = record_id.parent
+        class_name = adapter.spec.class_name
+        if parent_id:
+            parent_adapter = record_id_to_adapter[parent_id.record_id]
+            setattr(parent_adapter.gen_class, class_name, gen_class)
+            gen_class._parent_class = parent_adapter.gen_class
+        else:
+            globals[class_name] = gen_class
+            gen_class._parent_class = None
+        # TODO: comment
+        gen_class.SERIALIZER = make_serializer(adapter)

soialib/never.py

@@ -0,0 +1,4 @@
+from typing import NoReturn
+
+
+Never = NoReturn

soialib/serializer.py

@@ -0,0 +1,87 @@
+import io
+import json as jsonlib
+from collections.abc import Callable
+from dataclasses import FrozenInstanceError
+from typing import Any, Generic, TypeVar, cast, final
+
+from soialib.impl.function_maker import BodyBuilder, Expr, LineSpan, make_function
+from soialib.impl.type_adapter import TypeAdapter
+from soialib.never import Never
+
+T = TypeVar("T")
+
+
+@final
+class Serializer(Generic[T]):
+    __slots__ = (
+        "_to_dense_json_fn",
+        "_to_readable_json_fn",
+        "_from_json_fn",
+    )
+
+    _to_dense_json_fn: Callable[[T], Any]
+    _to_readable_json_fn: Callable[[T], Any]
+    _from_json_fn: Callable[[Any], T]
+
+    def __init__(self, adapter: Never):
+        # Use Never (^) as a trick to make the constructor internal.
+        object.__setattr__(
+            self, "_to_dense_json_fn", _make_to_json_fn(adapter, readable=False)
+        )
+        object.__setattr__(
+            self,
+            "_to_readable_json_fn",
+            _make_to_json_fn(adapter, readable=True),
+        )
+        object.__setattr__(self, "_from_json_fn", _make_from_json_fn(adapter))
+
+    def to_json(self, input: T, readable_flavor=False) -> Any:
+        if readable_flavor:
+            return self._to_readable_json_fn(input)
+        else:
+            return self._to_dense_json_fn(input)
+
+    def to_json_code(self, input: T, readable_flavor=False) -> str:
+        return jsonlib.dumps(self.to_json(input, readable_flavor))
+
+    def from_json(self, json: Any) -> T:
+        return self._from_json_fn(json)
+
+    def from_json_code(self, json_code: str) -> T:
+        return self._from_json_fn(jsonlib.loads(json_code))
+
+    def __setattr__(self, name: str, value: Any):
+        raise FrozenInstanceError(self.__class__.__qualname__)
+
+    def __delattr__(self, name: str):
+        raise FrozenInstanceError(self.__class__.__qualname__)
+
+
+def make_serializer(adapter: TypeAdapter) -> Serializer:
+    return Serializer(cast(Never, adapter))
+
+
+def _make_to_json_fn(adapter: TypeAdapter, readable: bool) -> Callable[[Any], Any]:
+    return make_function(
+        name="to_json",
+        params=["input"],
+        body=[
+            LineSpan.join(
+                "return ",
+                adapter.to_json_expr(
+                    adapter.to_frozen_expr(Expr.join("input")),
+                    readable=readable,
+                ),
+            ),
+        ],
+    )
+
+
+def _make_from_json_fn(adapter: TypeAdapter) -> Callable[[Any], Any]:
+    return make_function(
+        name="from_json",
+        params=["json"],
+        body=[
+            LineSpan.join("return ", adapter.from_json_expr(Expr.join("json"))),
+        ],
+    )

soialib/spec.py

@@ -0,0 +1,148 @@
+import enum
+from dataclasses import dataclass
+from typing import Optional, Union
+
+
+class PrimitiveType(enum.Enum):
+    BOOL = enum.auto()
+    INT32 = enum.auto()
+    INT64 = enum.auto()
+    UINT64 = enum.auto()
+    FLOAT32 = enum.auto()
+    FLOAT64 = enum.auto()
+    TIMESTAMP = enum.auto()
+    STRING = enum.auto()
+    BYTES = enum.auto()
+
+
+@dataclass(frozen=True)
+class ArrayType:
+    item: "Type"
+    # TODO: comment
+    key_attributes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class OptionalType:
+    value: "Type"
+
+
+# TODO: comment
+Type = Union[PrimitiveType, ArrayType, OptionalType, str]
+
+
+@dataclass(frozen=True)
+class Field:
+    """Field of a struct."""
+
+    name: str
+    number: int
+    type: Type
+    has_mutable_getter: bool = False
+    _attribute: str = ""  # If different from 'name'
+
+    @property
+    def attribute(self):
+        return self._attribute or self.name
+
+
+@dataclass(frozen=True)
+class Struct:
+    id: str
+    fields: tuple[Field, ...] = ()
+    removed_numbers: tuple[int, ...] = ()
+    _class_name: str = ""  # If different from the record name
+    _class_qualname: str = ""  # If different from the qualified name of the record
+
+    @property
+    def class_name(self):
+        return self._class_name or RecordId.parse(self.id).name
+
+    @property
+    def class_qualname(self):
+        return self._class_qualname or RecordId.parse(self.id).qualname
+
+
+@dataclass(frozen=True)
+class ConstantField:
+    """Constant field of an enum."""
+
+    name: str
+    number: int
+    _attribute: str = ""  # If different from 'name'
+
+    @property
+    def attribute(self):
+        return self._attribute or self.name
+
+
+@dataclass(frozen=True)
+class ValueField:
+    """Value field of an enum."""
+
+    name: str
+    number: int
+    type: Type
+
+
+@dataclass(frozen=True)
+class Enum:
+    id: str
+    constant_fields: tuple[ConstantField, ...] = ()
+    value_fields: tuple[ValueField, ...] = ()
+    removed_numbers: tuple[int, ...] = ()
+    _class_name: str = ""  # If different from the record name
+    _class_qualname: str = ""  # If different from the qualified name of the record
+
+    @property
+    def class_name(self):
+        return self._class_name or RecordId.parse(self.id).name
+
+    @property
+    def class_qualname(self):
+        return self._class_qualname or RecordId.parse(self.id).qualname
+
+
+Record = Union[Struct, Enum]
+
+
+@dataclass(frozen=True)
+class Module:
+    records: tuple[Record, ...] = ()
+
+
+@dataclass(frozen=True)
+class RecordId:
+    record_id: str
+    module_path: str
+    name: str
+    qualname: str
+    name_parts: tuple[str, ...]
+
+    @staticmethod
+    def parse(record_id: str) -> "RecordId":
+        colon_index = record_id.rfind(":")
+        module_path = record_id[0:colon_index]
+        qualname = record_id[colon_index + 1 :]
+        name_parts = tuple(qualname.split("."))
+        return RecordId(
+            record_id=record_id,
+            module_path=module_path,
+            name=name_parts[-1],
+            qualname=qualname,
+            name_parts=name_parts,
+        )
+
+    @property
+    def parent(self) -> Optional["RecordId"]:
+        if len(self.name_parts) == 1:
+            return None
+        parent_name_parts = self.name_parts[0:-1]
+        parent_qualname = ".".join(parent_name_parts)
+        return RecordId(
+            record_id=f"{self.module_path}:{parent_qualname}",
+            module_path=self.module_path,
+            name=parent_name_parts[-1],
+            qualname=parent_qualname,
+            name_parts=parent_name_parts,
+        )

soialib/timestamp.py

@@ -0,0 +1,127 @@
+import dataclasses
+import datetime
+from typing import Any, Final, Union, final, overload
+
+
+@final
+class Timestamp:
+    __slots__ = ("unix_millis",)
+
+    unix_millis: int
+
+    def __init__(self, unix_millis: int, _formatted: str = ""):
+        object.__setattr__(
+            self,
+            "unix_millis",
+            round(min(max(unix_millis, -8640000000000000), 8640000000000000)),
+        )
+
+    @staticmethod
+    def from_unix_millis(unix_millis: int) -> "Timestamp":
+        return Timestamp(unix_millis=unix_millis)
+
+    @staticmethod
+    def from_unix_seconds(unix_seconds: float) -> "Timestamp":
+        return Timestamp(unix_millis=round(unix_seconds * 1000))
+
+    @staticmethod
+    def from_datetime(dt: datetime.datetime) -> "Timestamp":
+        return Timestamp.from_unix_seconds(dt.timestamp())
+
+    @staticmethod
+    def now() -> "Timestamp":
+        return Timestamp.from_datetime(datetime.datetime.now(tz=datetime.timezone.utc))
+
+    EPOCH: Final["Timestamp"] = ...
+    MIN: Final["Timestamp"] = ...
+    MAX: Final["Timestamp"] = ...
+
+    @property
+    def unix_seconds(self) -> float:
+        return self.unix_millis / 1000.0
+
+    def to_datetime_or_raise(self) -> datetime.datetime:
+        return datetime.datetime.fromtimestamp(
+            self.unix_seconds, tz=datetime.timezone.utc
+        )
+
+    def __add__(self, td: datetime.timedelta) -> "Timestamp":
+        return Timestamp(
+            unix_millis=self.unix_millis + round(td.total_seconds() * 1000)
+        )
+
+    @overload
+    def __sub__(self, other: datetime.timedelta) -> "Timestamp": ...
+    @overload
+    def __sub__(self, other: "Timestamp") -> datetime.timedelta: ...
+    def __sub__(
+        self, other: Union["Timestamp", datetime.timedelta]
+    ) -> Union["Timestamp", datetime.timedelta]:
+        if isinstance(other, Timestamp):
+            return datetime.timedelta(milliseconds=self.unix_millis - other.unix_millis)
+        else:
+            return self.__add__(-other)
+
+    def __lt__(self, other: "Timestamp"):
+        return self.unix_millis < other.unix_millis
+
+    def __gt__(self, other: "Timestamp"):
+        return self.unix_millis > other.unix_millis
+
+    def __le__(self, other: "Timestamp"):
+        return self.unix_millis <= other.unix_millis
+
+    def __ge__(self, other: "Timestamp"):
+        return self.unix_millis >= other.unix_millis
+
+    def __eq__(self, other: Any):
+        if isinstance(other, Timestamp):
+            return other.unix_millis == self.unix_millis
+        return NotImplemented
+
+    def __hash__(self):
+        return hash(("ts", self.unix_millis))
+
+    def __repr__(self) -> str:
+        iso = self._iso_format()
+        if iso:
+            return f"Timestamp(\n  unix_millis={self.unix_millis},\n  _formatted='{iso}',\n)"
+        else:
+            return f"Timestamp(unix_millis={self.unix_millis})"
+
+    def __setattr__(self, name: str, value: Any):
+        raise dataclasses.FrozenInstanceError(self.__class__.__qualname__)
+
+    def __delattr__(self, name: str):
+        raise dataclasses.FrozenInstanceError(self.__class__.__qualname__)
+
+    def _trj(self) -> Any:
+        """To readable JSON."""
+        iso = self._iso_format
+        if iso:
+            return {
+                "unix_millis": self.unix_millis,
+                "formatted": iso,
+            }
+        else:
+            return {
+                "unix_millis": self.unix_millis,
+            }
+
+    def _iso_format(self) -> str:
+        try:
+            dt = self.to_datetime_or_raise()
+        except:
+            return ""
+        if dt:
+            ret = dt.isoformat()
+            bad_suffix = "+00:00"
+            if ret.endswith(bad_suffix):
+                ret = ret[0 : -len(bad_suffix)] + "Z"
+        return ret
+
+
+# Use 'setattr' because we marked these class attributes as Final.
+setattr(Timestamp, "EPOCH", Timestamp.from_unix_millis(0))
+setattr(Timestamp, "MIN", Timestamp.from_unix_millis(-8640000000000000))
+setattr(Timestamp, "MAX", Timestamp.from_unix_millis(8640000000000000))