soia-client 1.0.30__py3-none-any.whl → 1.1.1__py3-none-any.whl

soia/__init__.py

@@ -1,5 +1,6 @@
 import typing as _typing
 
+from soia._impl.keep import KEEP, Keep
 from soia._impl.keyed_items import KeyedItems
 from soia._impl.method import Method
 from soia._impl.serializer import Serializer
@@ -16,6 +17,8 @@ _: _typing.Final[_typing.Any] = None
 
 __all__ = [
     "_",
+    "Keep",
+    "KEEP",
     "KeyedItems",
     "Method",
     "RawServiceResponse",

soia/_impl/keep.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from typing import Final, cast, final
+
+from soia._impl.never import Never
+
+
+@final
+@dataclass(frozen=True)
+class Keep:
+    """
+    Type of the KEEP constant, which indicates that a value should not be replaced.
+
+    Do not instantiate.
+    """
+
+    def __init__(self, never: Never):
+        pass
+
+
+KEEP: Final = Keep(cast(Never, None))

soia/_impl/primitives.py

@@ -3,11 +3,12 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any, Final, final
 
-from soia import _spec, reflection
 from soia._impl.function_maker import Expr, ExprLike
 from soia._impl.timestamp import Timestamp
 from soia._impl.type_adapter import TypeAdapter
 
+from soia import _spec, reflection
+
 
 class AbstractPrimitiveAdapter(TypeAdapter):
     @final
@@ -296,7 +297,9 @@ class _BytesAdapter(AbstractPrimitiveAdapter):
     ) -> Expr:
         return Expr.join(
             Expr.local("b64encode", base64.b64encode),
-            "(", in_expr, ").decode('utf-8')",
+            "(",
+            in_expr,
+            ").decode('utf-8')",
         )
 
     def from_json_expr(self, json_expr: ExprLike) -> Expr:

soia/_impl/structs.py

@@ -14,6 +14,7 @@ from soia._impl.function_maker import (
     Params,
     make_function,
 )
+from soia._impl.keep import KEEP
 from soia._impl.repr import repr_impl
 from soia._impl.type_adapter import TypeAdapter
 
@@ -134,8 +135,12 @@ class StructAdapter(TypeAdapter):
                 simple_class=simple_class,
             ),
         )
-        mutable_class.__init__ = cast(Any, _make_mutable_class_init_fn(fields))
-        frozen_class.whole = _make_whole_static_factory_method(frozen_class)
+        mutable_class.__init__ = _make_mutable_class_init_fn(fields)
+        frozen_class.partial = _make_partial_static_factory_method(
+            fields,
+            frozen_class,
+        )
+        frozen_class.replace = _make_replace_method(fields, frozen_class)
 
         frozen_class.__eq__ = _make_eq_fn(fields)
         frozen_class.__hash__ = cast(Any, _make_hash_fn(fields, self.record_hash))
@@ -270,13 +275,7 @@ def _make_frozen_class_init_fn(
     params: Params = ["_self"]
     if fields:
         params.append("*")
-    for field in fields:
-        params.append(
-            Param(
-                name=field.field.attribute,
-                default=field.type.default_expr(),
-            )
-        )
+    params.extend(field.field.attribute for field in fields)
 
     builder = BodyBuilder()
     # Since __setattr__() was overridden to raise errors in order to make the class
@@ -384,10 +383,85 @@ def _make_mutable_class_init_fn(fields: Sequence[_Field]) -> Callable[..., None]
     )
 
 
-def _make_whole_static_factory_method(frozen_class: type) -> Callable[..., Any]:
-    def whole(**kwargs):
-        return frozen_class(**kwargs)
-    return whole
+def _make_partial_static_factory_method(
+    fields: Sequence[_Field],
+    frozen_class: type,
+) -> Callable[..., None]:
+    """
+    Returns the implementation of the partial() method of the frozen class.
+    """
+
+    params: Params = []
+    if fields:
+        params.append("*")
+    params.extend(
+        Param(
+            name=field.field.attribute,
+            default=field.type.default_expr(),
+        )
+        for field in fields
+    )
+
+    builder = BodyBuilder()
+    builder.append_ln(
+        "return ",
+        Expr.local("Frozen", frozen_class),
+        "(",
+        ", ".join(
+            f"{field.field.attribute}={field.field.attribute}" for field in fields
+        ),
+        ")",
+    )
+
+    return make_function(
+        name="partial",
+        params=params,
+        body=builder.build(),
+    )
+
+
+def _make_replace_method(
+    fields: Sequence[_Field],
+    frozen_class: type,
+) -> Callable[..., None]:
+    """
+    Returns the implementation of the replace() method of the frozen class.
+    """
+
+    keep_local = Expr.local("KEEP", KEEP)
+    params: Params = ["_self"]
+    if fields:
+        params.append("*")
+    params.extend(
+        Param(
+            name=field.field.attribute,
+            default=keep_local,
+        )
+        for field in fields
+    )
+
+    def field_to_arg_assigment(attr: str) -> LineSpan:
+        return LineSpan.join(
+            f"{attr}=_self.{attr} if {attr} is ", keep_local, f" else {attr}"
+        )
+
+    builder = BodyBuilder()
+    builder.append_ln(
+        "return ",
+        Expr.local("Frozen", frozen_class),
+        "(",
+        LineSpan.join(
+            *(field_to_arg_assigment(field.field.attribute) for field in fields),
+            separator=", ",
+        ),
+        ")",
+    )
+
+    return make_function(
+        name="replace",
+        params=params,
+        body=builder.build(),
+    )
 
 
 def _make_to_mutable_fn(
@@ -549,14 +623,9 @@ def _make_repr_fn(fields: Sequence[_Field]) -> Callable[[Any], str]:
     for field in fields:
         attribute = field.field.attribute
         # is_not_default_expr only works on a frozen expression.
-        to_frozen_expr = field.type.to_frozen_expr(f"(self.{attribute})")
-        is_not_default_expr = field.type.is_not_default_expr(
-            to_frozen_expr, to_frozen_expr
-        )
-        builder.append_ln("if is_mutable or ", is_not_default_expr, ":")
-        builder.append_ln("  r = ", repr_local, f"(self.{attribute})")
-        builder.append_ln(f"  assignments.append(f'{attribute}={{r.indented}}')")
-        builder.append_ln("  any_complex = any_complex or r.complex")
+        builder.append_ln("r = ", repr_local, f"(self.{attribute})")
+        builder.append_ln(f"assignments.append(f'{attribute}={{r.indented}}')")
+        builder.append_ln("any_complex = any_complex or r.complex")
     builder.append_ln("if len(assignments) <= 1 and not any_complex:")
     builder.append_ln("  body = ''.join(assignments)")
     builder.append_ln("else:")

soia/_impl/timestamp.py

@@ -5,6 +5,14 @@ from typing import Any, Final, Union, cast, final, overload
 
 @final
 class Timestamp:
+    """
+    A number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).
+
+    Does not contain any timezone information.
+    Convertible to and from datetime objects.
+    Immutable.
+    """
+
     __slots__ = ("unix_millis",)
 
     unix_millis: int
@@ -26,7 +34,14 @@ class Timestamp:
 
     @staticmethod
     def from_datetime(dt: datetime.datetime) -> "Timestamp":
-        return Timestamp.from_unix_seconds(dt.timestamp())
+        # dt.timestamp() mail fail if the year is not in [1970, 2038]
+        if dt.tzinfo is None:
+            timestamp = (
+                dt - _EPOCH_DT.astimezone().replace(tzinfo=None)
+            ).total_seconds()
+        else:
+            timestamp = (dt - _EPOCH_DT).total_seconds()
+        return Timestamp.from_unix_seconds(timestamp)
 
     @staticmethod
     def now() -> "Timestamp":
@@ -41,9 +56,26 @@ class Timestamp:
         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
-        )
+        """
+        Returns a datetime object representing the timestamp in UTC timezone.
+
+        Raises an exception if the timestamp is out of bounds for datetime.
+        If you don't want the exception, use 'to_datetime_or_limit()' instead.
+        """
+        return _EPOCH_DT + datetime.timedelta(seconds=self.unix_seconds)
+
+    def to_datetime_or_limit(self) -> datetime.datetime:
+        """
+        Returns a datetime object representing the timestamp in UTC timezone.
+
+        Clamps the timestamp to the minimum or maximum datetime if it is out of bounds.
+        """
+        if self.unix_seconds <= (_MIN_DT_UTC - _EPOCH_DT).total_seconds():
+            return datetime.datetime.min.replace(tzinfo=datetime.timezone.utc)
+        elif self.unix_seconds >= (_MAX_DT_UTC - _EPOCH_DT).total_seconds():
+            return datetime.datetime.max.replace(tzinfo=datetime.timezone.utc)
+        else:
+            return self.to_datetime_or_raise()
 
     def __add__(self, td: datetime.timedelta) -> "Timestamp":
         return Timestamp(
@@ -126,3 +158,8 @@ class Timestamp:
 setattr(Timestamp, "EPOCH", Timestamp.from_unix_millis(0))
 setattr(Timestamp, "MIN", Timestamp.from_unix_millis(-8640000000000000))
 setattr(Timestamp, "MAX", Timestamp.from_unix_millis(8640000000000000))
+
+
+_EPOCH_DT: Final = datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc)
+_MIN_DT_UTC: Final = datetime.datetime.min.replace(tzinfo=datetime.timezone.utc)
+_MAX_DT_UTC: Final = datetime.datetime.max.replace(tzinfo=datetime.timezone.utc)

{soia_client-1.0.30.dist-info → soia_client-1.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soia-client
-Version: 1.0.30
+Version: 1.1.1
 Author-email: Tyler Fibonacci <gepheum@gmail.com>
 License: MIT License
         

{soia_client-1.0.30.dist-info → soia_client-1.1.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-soia/__init__.py,sha256=GFsFZjzbElOC3AJHoaiI_eb3SRXu0-ooE0QXusL-O1k,724
+soia/__init__.py,sha256=WPhdlu7zKBSWd4DVFWXQKQoptD0gU7xGFm4tbQHrVc8,787
 soia/_module_initializer.py,sha256=1TWnc0qUO7_iljQR2ywVERrrkY5jIkT3zucc-AYZyrQ,4221
 soia/_spec.py,sha256=Y5EHHQa6qNeJc29aaqGrFPnPFXxlL7TED9_AXUGBjf0,3663
 soia/reflection.py,sha256=U5knJGmawARCdcEhNxek4dvx48WLPETLqIqKBPWwT4Q,8771
@@ -6,21 +6,22 @@ soia/_impl/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soia/_impl/arrays.py,sha256=C3j3RZdSvqmogbGAi3EprLkUYMFfO-IJhoCOte5blAw,5477
 soia/_impl/enums.py,sha256=jlg2YYGgMg6BMmSy0v0MBgZmZYzLvVS0j68TxOCiSm8,17039
 soia/_impl/function_maker.py,sha256=MvCDv1WwzKGJzZbNCnJ_8-MP3m1xTIabumXA-9Ydd9M,5639
+soia/_impl/keep.py,sha256=GDeMKKUcvUFXWJVzBPB9CuLkcQb93sWKvo0PcyKUBzg,370
 soia/_impl/keyed_items.py,sha256=EoPrdeLJ8i7zCH-oW-7qOcyadyrzykB6lkrf3xRVmyk,337
 soia/_impl/method.py,sha256=C6ygh-Li4zADxFR_gfeBTuPUzLjZ1XHCp0ZI4-uiRYs,455
 soia/_impl/never.py,sha256=T7PHtIipuXlici4wa0yuJKrn9JgcT-ODC3QVCwsPprY,46
 soia/_impl/optionals.py,sha256=KTgmbfYLJLrju5v10jgnnnW98QG6NYw2We3gdgi9i2E,2414
-soia/_impl/primitives.py,sha256=jH8MVhD2GSZx7TYXVBgzd0wzXEAEapyBFU8vozE_LbE,9000
+soia/_impl/primitives.py,sha256=r-55rO12TwwWCQJgzEEgVpXMVGg0dRhGvFWX_rGeqsQ,9025
 soia/_impl/repr.py,sha256=7WX0bEAVENTjlyZIcbT8TcJylS7IRIyafGCmqaIMxFM,1413
 soia/_impl/serializer.py,sha256=28IwkjtUnLpbnPQfVNfJXkApCK4JhXHwLkC5MVhF8xo,3529
 soia/_impl/serializers.py,sha256=IL9jHHMo11pgrL1-crarOEElvTyV5YM6FTcgumjW6IU,2564
 soia/_impl/service.py,sha256=3dpcH4XEBTEShyjzxMA_zDGg9_amTFF5A49U6hivAdQ,14792
 soia/_impl/service_client.py,sha256=0WgiN6Stg548FAdZQMuezZoooe4MYw2frEQ5KUE7xag,5311
-soia/_impl/structs.py,sha256=KrqucOqSxXda4-3gKyCmx_Oj4osTFBLk9ORyRkV_7dk,26785
-soia/_impl/timestamp.py,sha256=lXBNH8mPmzflkNjSKZSBl2XS-ot9N8N92B_zGO2SMtU,4078
+soia/_impl/structs.py,sha256=1XhjZmqtD7IMURdSVR0DwMdrIhWPZft1eCfwVW84c0E,28230
+soia/_impl/timestamp.py,sha256=upnEkvW-7AaMJ9_nNqntvhJ4pFWWCAXNjEOPtszdwgE,5645
 soia/_impl/type_adapter.py,sha256=RyIyh4Fnt9rMy0HRzC-a2v2JAdZsV9FBzoGEUVygVRE,2101
-soia_client-1.0.30.dist-info/licenses/LICENSE,sha256=SaAftKkX6hfSOiPdENQPS70tifH3PDHgazq8eK2Pwfw,1064
-soia_client-1.0.30.dist-info/METADATA,sha256=wDHdwHbIjPphBsvbyABOZrRKISu3cfzbQ9Rlwdol1LA,2122
-soia_client-1.0.30.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-soia_client-1.0.30.dist-info/top_level.txt,sha256=lsYG9JrvauFe1oIV5zvnwsS9hsx3ztwfK_937op9mxc,5
-soia_client-1.0.30.dist-info/RECORD,,
+soia_client-1.1.1.dist-info/licenses/LICENSE,sha256=SaAftKkX6hfSOiPdENQPS70tifH3PDHgazq8eK2Pwfw,1064
+soia_client-1.1.1.dist-info/METADATA,sha256=WqVO1QsXh3w0mjkhuPC71WcCWlwSOnKeAX40_Mt2zFU,2121
+soia_client-1.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+soia_client-1.1.1.dist-info/top_level.txt,sha256=lsYG9JrvauFe1oIV5zvnwsS9hsx3ztwfK_937op9mxc,5
+soia_client-1.1.1.dist-info/RECORD,,