stranded 0.0.1__py3-none-any.whl

stranded/__init__.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import importlib as _importlib
+import typing as _typing
+
+if _typing.TYPE_CHECKING:
+    from . import abc
+    from . import argparse
+    from . import asyncio
+    from . import builtins
+    from . import composer_
+    from .composer_ import Composer
+    from . import execution
+    from . import functools
+    from . import logging
+    from . import sqlite3
+    from . import threading
+    from . import types
+
+
+def __getattr__(name: str) -> _typing.Any:
+    match name:
+        case 'abc': return _importlib.import_module('.abc', __name__)
+        case 'argparse': return _importlib.import_module('.argparse', __name__)
+        case 'asyncio': return _importlib.import_module('.asyncio', __name__)
+        case 'builtins': return _importlib.import_module('.builtins', __name__)
+        case 'composer_': return _importlib.import_module('.composer_', __name__)
+        case 'Composer': return _importlib.import_module('.composer_', __name__).Composer
+        case 'execution': return _importlib.import_module('.execution', __name__)
+        case 'functools': return _importlib.import_module('.functools', __name__)
+        case 'logging': return _importlib.import_module('.logging', __name__)
+        case 'sqlite3': return _importlib.import_module('.sqlite3', __name__)
+        case 'threading': return _importlib.import_module('.threading', __name__)
+        case 'types': return _importlib.import_module('.types', __name__)
+        case _: raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = (
+    'abc',
+    'argparse',
+    'asyncio',
+    'builtins',
+    'composer_',
+    'Composer',
+    'execution',
+    'functools',
+    'logging',
+    'sqlite3',
+    'threading',
+    'types',
+)

stranded/abc/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import importlib as _importlib
+import typing as _typing
+
+if _typing.TYPE_CHECKING:
+    from . import composer_
+    from .composer_ import Composer
+
+
+def __getattr__(name: str) -> _typing.Any:
+    match name:
+        case 'composer_': return _importlib.import_module('.composer_', __name__)
+        case 'Composer': return _importlib.import_module('.composer_', __name__).Composer
+        case _: raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = (
+    'composer_',
+    'Composer',
+)

stranded/abc/composer_.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import abc
+import annotationlib
+import dataclasses
+import inspect
+import types
+import typing
+
+type Instance = object
+
+type ValueT[**ParamT_, RetT_] = Param[ParamT_] | Raise | Return[RetT_] | Stop
+type StackT = tuple[
+    ValueT[typing.Any, typing.Any]
+    | Composee[typing.Any, typing.Any]
+    | Connect[typing.Any, typing.Any]
+    | Exit[typing.Any, typing.Any]
+    | Enter[typing.Any, typing.Any]
+    | Composed[typing.Any, typing.Any],
+    ...,
+]
+
+
+def replace[T](obj: T, /, **changes: typing.Any) -> T:
+    """Copy `obj` - a frozen dataclass - with `changes` applied.
+
+    `dataclasses.replace` re-runs `__init__`, which costs several times as much as copying the
+    instance dict does. Binding a composition to an instance happens on every attribute access, so
+    it is worth copying directly.
+    """
+    copy = object.__new__(type(obj))
+    copy.__dict__.update(obj.__dict__, **changes)
+    return copy
+
+
+@dataclasses.dataclass(frozen=True)
+class Raise:
+    exc_type: type[BaseException]
+    exc_val: BaseException
+    exc_tb: types.TracebackType | None
+
+
+@dataclasses.dataclass(frozen=True)
+class Stop(BaseException): ...
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Param[**ParamT]:
+    args: ParamT.args
+    kwargs: ParamT.kwargs
+
+
+@dataclasses.dataclass(frozen=True)
+class Return[RetT]:
+    ret: RetT
+
+
+class Composee[**ParamT, RetT](typing.Protocol):
+    __doc__: str
+    __module__: str
+    __name__: str
+    __qualname__: str
+    def __call__(self, *args: ParamT.args, **kwargs: ParamT.kwargs) -> RetT: ...
+    def __get__(self, instance: Instance, owner: type[object] | None) -> typing.Self: ...
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Connect[**ParamT, RetT](abc.ABC):
+    sender: Composed[ParamT, RetT]
+    receiver: Composed[typing.Any, typing.Any]
+    composer: Composer[ParamT, RetT]
+    
+    def __call__(self, value: ValueT[ParamT, RetT], /) -> StackT:
+        match value:
+            case Param() as param_: return *self.receiver.stack, param_
+            case Raise() as raise_: return raise_,
+            case Return() as return_: return *self.receiver.stack, Param(args=(return_.ret,), kwargs={}),
+            case Stop() as stop_: return stop_,
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Exit[**ParamT, RetT](abc.ABC):
+    enter: Enter[ParamT, RetT]
+
+    @property
+    def composer(self) -> Composer[typing.Any, typing.Any]: return self.enter.composer
+
+    def __call__(self, value: ValueT[ParamT, RetT], /) -> StackT:
+        return ()
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Enter[**ParamT, RetT](abc.ABC):
+    composer: Composer[ParamT, RetT]
+    composee: Composee[ParamT, RetT]
+
+    def __call__(self, value: ValueT[ParamT, RetT], /) -> StackT:
+        match value, self.composee:
+            case Param(), Composed() as composed_: return self.composer.Exit(enter=self), *composed_.stack
+            case Param(), composee_: return self.composer.Exit(enter=self), composee_,
+            case _: return ()
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Composed[**ParamT, RetT](abc.ABC):
+    __doc__: str
+    __module__: str
+    __name__: str
+    __qualname__: str
+    __signature__: inspect.Signature
+    composer: Composer[ParamT, RetT]
+    stack: StackT
+    owner: type[object] | None = None
+    name: str | None = None
+
+    @abc.abstractmethod
+    def __call__(self, *args: ParamT.args, **kwargs: ParamT.kwargs) -> RetT: ...
+
+    @property
+    def enter(self) -> Enter[ParamT, RetT]:
+        """The Enter at the bottom of the stack, which holds whatever state the composition has."""
+        match self.stack[-1]:
+            case Enter() as enter_: return enter_
+        assert False, "unreachable"
+
+    def create_enter(self, instance: Instance) -> Enter[ParamT, RetT]:
+        """Return the Enter that `instance`'s copy of this composition composes with.
+
+        Composers that keep per-instance state override this to hand each instance its own. Note
+        that whatever they hold it in must not refer back to `instance`, or the instance can never
+        be collected - which is why they hold Enters rather than whole bound compositions.
+        """
+        return self.enter
+
+    def __set_name__(self, owner: type[object], name: str) -> None:
+        object.__setattr__(self, 'owner', owner)
+        object.__setattr__(self, 'name', name)
+
+    def __get__(self, instance: Instance, owner: type[object] | None) -> typing.Self:
+        if instance is None:
+            return self
+        enter = self.create_enter(instance)
+        return replace(
+            self, stack=(*self.stack[:-1], replace(enter, composee=enter.composee.__get__(instance, owner))),
+        )
+
+    def __or__[**ReceiverParamT, ReceiverRetT](
+        self,
+        receiver: Composed[ReceiverParamT, ReceiverRetT],
+        /,
+    ) -> Composed[ParamT, ReceiverRetT]:
+        return dataclasses.replace(
+            self,
+            __doc__=f"{self.__doc__}\n\n{receiver.__doc__}",
+            __signature__=inspect.Signature().replace(
+                parameters=tuple(self.__signature__.parameters.values()),
+                return_annotation=receiver.__signature__.return_annotation,
+            ),
+            stack=(self.composer.Connect(composer=self.composer, receiver=receiver, sender=self), *self.stack),
+        )
+
+
+# Aliases for annotation use. The Composer ClassVars below shadow the class names
+# within Composer's scope, so annotations must reference these instead.
+type ComposeeT[**ParamT, RetT] = Composee[ParamT, RetT]
+type ConnectT[**ParamT, RetT] = Connect[ParamT, RetT]
+type ExitT[**ParamT, RetT] = Exit[ParamT, RetT]
+type EnterT[**ParamT, RetT] = Enter[ParamT, RetT]
+type ComposedT[**ParamT, RetT] = Composed[ParamT, RetT]
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Composer[**ParamT, RetT](abc.ABC):
+    Composee: typing.ClassVar[type[Composee[typing.Any, typing.Any]]]
+    Connect: typing.ClassVar[type[Connect[typing.Any, typing.Any]]]
+    Exit: typing.ClassVar[type[Exit[typing.Any, typing.Any]]]
+    Enter: typing.ClassVar[type[Enter[typing.Any, typing.Any]]]
+    Composed: typing.ClassVar[type[Composed[typing.Any, typing.Any]]]
+
+    def __call__[**CallParamT, CallRetT](
+        self, composee: ComposeeT[CallParamT, CallRetT], /,
+    ) -> ComposedT[CallParamT, CallRetT]:
+        return self.Composed(
+            __doc__=str(composee.__doc__),
+            __module__=str(composee.__module__),
+            __name__=str(composee.__name__),
+            __qualname__=str(composee.__qualname__),
+            __signature__=inspect.signature(composee, annotation_format=annotationlib.Format.FORWARDREF),
+            composer=self,
+            stack=(self.Enter(composer=self, composee=composee),)
+        )

stranded/argparse/__init__.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import importlib as _importlib
+import typing as _typing
+
+if _typing.TYPE_CHECKING:
+    from . import argument_parser_
+    from .argument_parser_ import ArgumentParser
+    from .argument_parser_ import argument_parser
+
+
+def __getattr__(name: str) -> _typing.Any:
+    match name:
+        case 'argument_parser_': return _importlib.import_module('.argument_parser_', __name__)
+        case 'ArgumentParser': return _importlib.import_module('.argument_parser_', __name__).ArgumentParser
+        case 'argument_parser': return _importlib.import_module('.argument_parser_', __name__).argument_parser
+        case _: raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = (
+    'argument_parser_',
+    'ArgumentParser',
+    'argument_parser',
+)

stranded/argparse/abc/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import importlib as _importlib
+import typing as _typing
+
+if _typing.TYPE_CHECKING:
+    from . import argument_parser_
+    from .argument_parser_ import ArgumentParser
+
+
+def __getattr__(name: str) -> _typing.Any:
+    match name:
+        case 'argument_parser_': return _importlib.import_module('.argument_parser_', __name__)
+        case 'ArgumentParser': return _importlib.import_module('.argument_parser_', __name__).ArgumentParser
+        case _: raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = (
+    'argument_parser_',
+    'ArgumentParser',
+)