stranded 0.0.1__py3-none-any.whl

stranded/functools/abc/__init__.py

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

stranded/functools/abc/herd_.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import abc
+import dataclasses
+import typing
+import weakref
+
+from ...abc import composer_
+
+
+type GenerateKey = typing.Callable[..., Key]
+type Key = typing.Hashable
+
+
+Raise = composer_.Raise
+Stop = composer_.Stop
+Param = composer_.Param
+Return = composer_.Return
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Future[RetT](abc.ABC):
+
+    @abc.abstractmethod
+    def set_value(self, value: Return[RetT] | Raise | Stop) -> None: ...
+
+    @abc.abstractmethod
+    def __call__(self, *args: typing.Any, **kwargs: typing.Any) -> typing.Any: ...
+
+    def __get__(self, instance: composer_.Instance, owner: type[object] | None) -> typing.Self:
+        return self
+
+
+@typing.runtime_checkable
+class Composee[**ParamT, RetT](composer_.Composee[ParamT, RetT], typing.Protocol): ...
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Connect[**ParamT, RetT](composer_.Connect[ParamT, RetT], abc.ABC): ...
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Exit[**ParamT, RetT, FutureT](composer_.Exit[ParamT, RetT], abc.ABC):
+    future: FutureT
+    key: Key
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Enter[**ParamT, RetT, FutureT](composer_.Enter[ParamT, RetT], abc.ABC):
+    # The in-flight-call cache lives on the Enter now that Enter/Exit no longer reach Composed.
+    future_by_key: dict[Key, FutureT] = dataclasses.field(default_factory=dict)
+
+    @staticmethod
+    def create_key(*args: ParamT.args, **kwargs: ParamT.kwargs) -> Key:
+        return tuple(args), tuple(sorted([*kwargs.items()]))
+
+    def _dispatch(
+        self, *args: ParamT.args, **kwargs: ParamT.kwargs,
+    ) -> tuple[Exit[ParamT, RetT, Future[RetT]], Composee[ParamT, RetT]] | tuple[Future[RetT]]:
+        key = self.create_key(*args, **kwargs)
+        future = self.future_by_key.get(key)
+        match future is None:
+            case True:
+                future = self.future_by_key[key] = self.composer.future_t()  # type: ignore[attr-defined]
+                return self.composer.Exit(enter=self, future=future, key=key), self.composee  # type: ignore[call-arg, return-value]
+            case False:
+                return future,
+        assert False, "Unreachable"
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Composed[**ParamT, RetT](composer_.Composed[ParamT, RetT], abc.ABC):
+    # Enters rather than whole bound compositions: a bound composition holds the bound composee,
+    # which refers back to the instance that keys it here, and so would outlive it forever.
+    enter_by_instance: weakref.WeakKeyDictionary[
+        composer_.Instance, composer_.EnterT[ParamT, RetT],
+    ] = dataclasses.field(default_factory=weakref.WeakKeyDictionary)
+
+    @typing.override
+    def create_enter(self, instance: composer_.Instance) -> composer_.EnterT[ParamT, RetT]:
+        if (enter := self.enter_by_instance.get(instance)) is not None:
+            return enter
+        match self.enter:
+            case Enter() as enter_:
+                return self.enter_by_instance.setdefault(instance, dataclasses.replace(enter_, future_by_key={}))
+        assert False, "unreachable"
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Herd[**ParamT, RetT](composer_.Composer[ParamT, RetT], abc.ABC):
+    @property
+    @abc.abstractmethod
+    def future_t(self) -> type: ...
+
+
+Composer = Herd

stranded/functools/abc/lru_cache_.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import abc
+import collections
+import contextlib
+import dataclasses
+import itertools
+import typing
+import weakref
+import sys
+
+from ...abc import composer_
+from ...builtins import exception_
+
+
+type GenerateKey = typing.Callable[..., Key]
+type FutureByKey = collections.OrderedDict[Key, typing.Any]
+
+
+Raise = composer_.Raise
+Stop = composer_.Stop
+Param = composer_.Param
+Return = composer_.Return
+
+
+class Exception(exception_.Exception): ...  # noqa
+
+
+@typing.final
+class Ref[T](weakref.ref[T]):
+    """Weak reference to a memoized argument that evicts its cache entry when the referent dies.
+
+    Hashes and compares like the referent while the referent is alive, so that `Key`s built from
+    equal arguments are equal. The referent's hash is cached at construction, which keeps the key
+    hashable - and therefore removable from the cache - after the referent is gone.
+    """
+    __slots__ = ('future_by_key', 'key')
+
+    future_by_key: weakref.ref[FutureByKey] | None
+    key: Key | None
+
+    def __new__(cls, referent: T) -> typing.Self:
+        return super().__new__(cls, referent, cls.__discard)
+
+    def __init__(self, referent: T) -> None:
+        super().__init__(referent, type(self).__discard)  # type: ignore[call-arg]
+        self.future_by_key = None
+        self.key = None
+        hash(self)  # Cache the referent's hash while the referent is still alive.
+
+    def __discard(self) -> None:
+        # Called with this (now dead) reference as `self` once the referent is garbage collected.
+        if (future_by_key_ref := self.future_by_key) is None or (key := self.key) is None:
+            return
+        if (future_by_key := future_by_key_ref()) is not None:
+            future_by_key.pop(key, None)
+
+    def bind(self, future_by_key: weakref.ref[FutureByKey], key: Key) -> None:
+        """Discard `key` from `future_by_key` once the referent dies."""
+        self.future_by_key = future_by_key
+        self.key = key
+
+
+def create_ref(value: typing.Any) -> typing.Hashable:
+    """Refer to `value` weakly if it supports weak references, and strongly otherwise."""
+    try:
+        return Ref(value)
+    except TypeError:
+        # `value` either does not support weak references (e.g. `int`, `str`, and `tuple`) or is
+        # unhashable, in which case caching it fails the same way an unhashable key always has.
+        return typing.cast(typing.Hashable, value)
+
+
+@typing.final
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Key:
+    """Cache key that refers to the memoized arguments weakly wherever it can.
+
+    Keeping arguments alive for as long as they are memoized would leak every argument that a cache
+    ever saw, so arguments that support weak references are stored as `Ref`s. Note that an argument
+    that supports weak references only indirectly - a `tuple` of objects, say - is still stored
+    strongly, since there is nothing to hang a reference on.
+    """
+    args: tuple[typing.Hashable, ...]
+    kwargs: tuple[tuple[str, typing.Hashable], ...]
+
+    @classmethod
+    def create(cls, *args: typing.Any, **kwargs: typing.Any) -> typing.Self:
+        return cls(
+            args=tuple(create_ref(arg) for arg in args),
+            kwargs=tuple((name, create_ref(kwargs[name])) for name in sorted(kwargs)),
+        )
+
+    @property
+    def refs(self) -> typing.Iterator[Ref[typing.Any]]:
+        """The weak references that this key is made of."""
+        return (
+            value
+            for value in itertools.chain(self.args, (value for _, value in self.kwargs))
+            if isinstance(value, Ref)
+        )
+
+    def bind(self, future_by_key: FutureByKey) -> None:
+        """Discard this key from `future_by_key` as soon as any of its weak arguments dies."""
+        future_by_key_ref = weakref.ref(future_by_key)
+        for ref in self.refs:
+            ref.bind(future_by_key_ref, self)
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Future[RetT](abc.ABC):
+
+    @abc.abstractmethod
+    def set_value(self, value: Return[RetT] | Raise | Stop) -> None: ...
+
+    @abc.abstractmethod
+    def __call__(self, *args: typing.Any, **kwargs: typing.Any) -> typing.Any: ...
+
+    def __get__(self, instance: composer_.Instance, owner: type[object] | None) -> typing.Self:
+        return self
+
+
+@typing.runtime_checkable
+class Composee[**ParamT, RetT](composer_.Composee[ParamT, RetT], typing.Protocol): ...
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Connect[**ParamT, RetT](composer_.Connect[ParamT, RetT], abc.ABC): ...
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Exit[**ParamT, RetT, FutureT](composer_.Exit[ParamT, RetT], abc.ABC):
+    future: FutureT
+    key: Key
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Enter[**ParamT, RetT, FutureT](composer_.Enter[ParamT, RetT], abc.ABC):
+    future_by_key: collections.OrderedDict[Key, FutureT] = dataclasses.field(default_factory=collections.OrderedDict)
+
+    @staticmethod
+    def create_key(*args: ParamT.args, **kwargs: ParamT.kwargs) -> Key:
+        return Key.create(*args, **kwargs)
+
+    def get_future(self, key: Key) -> FutureT | None:
+        """Return the future memoized for `key`, if any, marking it as the most recently used."""
+        if (future := self.future_by_key.get(key)) is not None:
+            # A weak argument may have died - taking its entry with it - since the get.
+            with contextlib.suppress(KeyError):
+                self.future_by_key.move_to_end(key)
+        return future
+
+    def set_future(self, key: Key) -> FutureT:
+        """Memoize and return a new future for `key`, evicting the least recently used entries."""
+        while self.composer.size <= len(self.future_by_key):  # type: ignore[attr-defined]
+            self.future_by_key.popitem(last=False)
+        future: FutureT = self.composer.future_t()  # type: ignore[attr-defined]
+        self.future_by_key[key] = future
+        key.bind(self.future_by_key)
+        return future
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Composed[**ParamT, RetT](composer_.Composed[ParamT, RetT], abc.ABC):
+    # Enters rather than whole bound compositions: a bound composition holds the bound composee,
+    # which refers back to the instance that keys it here, and so would outlive it forever.
+    enter_by_instance: weakref.WeakKeyDictionary[
+        composer_.Instance, composer_.EnterT[ParamT, RetT],
+    ] = dataclasses.field(default_factory=weakref.WeakKeyDictionary)
+
+    @typing.override
+    def create_enter(self, instance: composer_.Instance) -> composer_.EnterT[ParamT, RetT]:
+        if (enter := self.enter_by_instance.get(instance)) is not None:
+            return enter
+        match self.enter:
+            case Enter() as enter_:
+                return self.enter_by_instance.setdefault(
+                    instance, dataclasses.replace(enter_, future_by_key=collections.OrderedDict()),
+                )
+        assert False, "unreachable"
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class LruCache[**ParamT, RetT](composer_.Composer[ParamT, RetT], abc.ABC):
+    size: int = sys.maxsize
+
+    @property
+    @abc.abstractmethod
+    def future_t(self) -> type: ...
+
+
+Composer = LruCache

stranded/functools/abc/retry_.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import abc
+import dataclasses
+import sys
+import typing
+
+from ...abc import composer_
+from ...builtins import exception_
+
+
+class Exception(exception_.Exception): ...  # noqa
+
+
+@typing.runtime_checkable
+class Composee[**ParamT, RetT](composer_.Composee[ParamT, RetT], typing.Protocol): ...
+
+
+Param = composer_.Param
+Raise = composer_.Raise
+Return = composer_.Return
+Stop = composer_.Stop
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Connect[**ParamT, RetT](composer_.Connect[ParamT, RetT], abc.ABC): ...
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Exit[**ParamT, RetT](composer_.Exit[ParamT, RetT], abc.ABC):
+    def __call__(self, value: composer_.ValueT[ParamT, RetT], /) -> composer_.StackT:
+        if self.enter.n_retried < self.enter.composer.n and isinstance(value, Raise):  # type: ignore[attr-defined]
+            return dataclasses.replace(self.enter, n_retried=self.enter.n_retried + 1), self.enter.param  # type: ignore[attr-defined, call-arg]
+
+        return ()
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Enter[**ParamT, RetT](composer_.Enter[ParamT, RetT], abc.ABC):
+    n_retried: int = 0
+    param: Param[ParamT] | None = None
+
+    def __call__(self, value: composer_.ValueT[ParamT, RetT], /) -> composer_.StackT:
+        match value:
+            case Param() as param_:
+                new_self = dataclasses.replace(self, param=param_)
+                return new_self.composer.Exit(enter=new_self), self.composee
+            case _: return ()
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Composed[**ParamT, RetT](composer_.Composed[ParamT, RetT], abc.ABC): ...
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Retry[**ParamT, RetT](composer_.Composer[ParamT, RetT], abc.ABC):
+    n: int = sys.maxsize
+
+
+Composer = Retry

stranded/functools/abc/throttle_.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import abc
+import dataclasses
+import threading
+import sys
+import typing
+import weakref
+
+from ...abc import composer_
+from ...builtins import exception_
+
+
+class Exception(exception_.Exception): ...  # noqa
+
+
+@dataclasses.dataclass(kw_only=True)
+class State:
+    cap_running: int = 1
+    num_running: int = 0
+    num_waiting: int = 0
+
+
+@typing.runtime_checkable
+class Composee[**ParamT, RetT](composer_.Composee[ParamT, RetT], typing.Protocol): ...
+
+
+Param = composer_.Param
+Raise = composer_.Raise
+Return = composer_.Return
+Stop = composer_.Stop
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Connect[**ParamT, RetT](composer_.Connect[ParamT, RetT], abc.ABC): ...
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Exit[**ParamT, RetT](composer_.Exit[ParamT, RetT], abc.ABC):
+    def __call__(self, value: composer_.ValueT[ParamT, RetT], /) -> composer_.StackT:
+        state = self.enter.state  # type: ignore[attr-defined]
+        if isinstance(value, Raise) and state.num_running <= state.cap_running:
+            state.cap_running //= 2
+        elif (
+            not isinstance(value, Raise)
+            and state.num_running == state.cap_running < self.enter.composer.max_running  # type: ignore[attr-defined]
+        ):
+            state.cap_running += 1
+        state.num_running -= 1
+
+        if 0 < (n := state.cap_running - state.num_running):
+            self.enter.condition.notify(n=n)  # type: ignore[attr-defined]
+
+        return ()
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Enter[**ParamT, RetT](composer_.Enter[ParamT, RetT], abc.ABC):
+    # Per-composition state lives on the Enter now that Enter/Exit no longer reach Composed.
+    # Exit reads it back through self.enter; __get__ reinstalls a fresh-state Enter per instance.
+    state: State = dataclasses.field(default_factory=State)
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Composed[**ParamT, RetT](composer_.Composed[ParamT, RetT], abc.ABC):
+    # Enters rather than whole bound compositions: a bound composition holds the bound composee,
+    # which refers back to the instance that keys it here, and so would outlive it forever.
+    enter_by_instance: weakref.WeakKeyDictionary[
+        composer_.Instance, composer_.EnterT[ParamT, RetT],
+    ] = dataclasses.field(default_factory=weakref.WeakKeyDictionary)
+    lock: threading.Lock = dataclasses.field(default_factory=threading.Lock)
+
+    @typing.override
+    def create_enter(self, instance: composer_.Instance) -> composer_.EnterT[ParamT, RetT]:
+        with self.lock:
+            if (enter := self.enter_by_instance.get(instance)) is not None:
+                return enter
+            match self.enter:
+                case Enter() as enter_:
+                    return self.enter_by_instance.setdefault(instance, dataclasses.replace(
+                        enter_,
+                        condition=type(enter_.condition)(),  # type: ignore[attr-defined]
+                        state=State(),
+                    ))
+            assert False, "unreachable"
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Throttle[**ParamT, RetT](composer_.Composer[ParamT, RetT], abc.ABC):
+    # How many callees are allowed through concurrently before additional callees become waiters.
+    max_running: int = sys.maxsize
+
+    # How many callees are allowed through or to wait concurrently before additional callees are rejected.
+    max_waiting: int = sys.maxsize
+
+
+Composer = Throttle

stranded/functools/asyncio/__init__.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import importlib as _importlib
+import typing as _typing
+
+if _typing.TYPE_CHECKING:
+    from . import herd_
+    from .herd_ import Herd
+    from .herd_ import herd
+    from . import lru_cache_
+    from .lru_cache_ import LruCache
+    from .lru_cache_ import lru_cache
+    from . import retry_
+    from .retry_ import Retry
+    from .retry_ import retry
+    from . import throttle_
+    from .throttle_ import Throttle
+    from .throttle_ import throttle
+
+
+def __getattr__(name: str) -> _typing.Any:
+    match name:
+        case 'herd_': return _importlib.import_module('.herd_', __name__)
+        case 'Herd': return _importlib.import_module('.herd_', __name__).Herd
+        case 'herd': return _importlib.import_module('.herd_', __name__).herd
+        case 'lru_cache_': return _importlib.import_module('.lru_cache_', __name__)
+        case 'LruCache': return _importlib.import_module('.lru_cache_', __name__).LruCache
+        case 'lru_cache': return _importlib.import_module('.lru_cache_', __name__).lru_cache
+        case 'retry_': return _importlib.import_module('.retry_', __name__)
+        case 'Retry': return _importlib.import_module('.retry_', __name__).Retry
+        case 'retry': return _importlib.import_module('.retry_', __name__).retry
+        case 'throttle_': return _importlib.import_module('.throttle_', __name__)
+        case 'Throttle': return _importlib.import_module('.throttle_', __name__).Throttle
+        case 'throttle': return _importlib.import_module('.throttle_', __name__).throttle
+        case _: raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = (
+    'herd_',
+    'Herd',
+    'herd',
+    'lru_cache_',
+    'LruCache',
+    'lru_cache',
+    'retry_',
+    'Retry',
+    'retry',
+    'throttle_',
+    'Throttle',
+    'throttle',
+)

stranded/functools/asyncio/herd_.py

@@ -0,0 +1,89 @@
+import asyncio
+import dataclasses
+import typing
+
+from ..abc import herd_
+from ...asyncio import composer_
+
+
+Raise = composer_.Raise
+Stop = composer_.Stop
+Param = composer_.Param
+Return = composer_.Return
+
+
+@typing.runtime_checkable
+class Composee[**ParamT, RetT](composer_.Composee[ParamT, RetT], herd_.Composee[ParamT, RetT], typing.Protocol): ...
+
+
+@typing.final
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Future[RetT](herd_.Future[RetT]):
+    future: asyncio.Future[RetT] = dataclasses.field(default_factory=asyncio.Future)
+
+    @typing.override
+    def set_value(self, value: Return[RetT] | Raise | Stop) -> None:
+        match value:
+            case Return(ret=ret): self.future.set_result(ret)
+            case Raise() as raise_: self.future.set_exception(raise_.exc_val)
+            case Stop() as stop_: self.future.set_exception(stop_)
+
+    @typing.override
+    async def __call__(self, *args: typing.Any, **kwargs: typing.Any) -> RetT:
+        return await self.future
+
+
+@typing.final
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Connect[**ParamT, RetT](composer_.Connect[ParamT, RetT], herd_.Connect[ParamT, RetT]): ...
+
+
+@typing.final
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Exit[**ParamT, RetT](composer_.Exit[ParamT, RetT], herd_.Exit[ParamT, RetT, Future[RetT]]):
+    future: Future[RetT] = dataclasses.field(default_factory=Future)
+
+    @typing.override
+    async def __call__(self, value: composer_.ValueT[ParamT, RetT], /) -> composer_.StackT:  # type: ignore[override]
+        self.enter.future_by_key.pop(self.key, None)  # type: ignore[attr-defined]
+        match value:
+            case Param(): pass
+            case Return() | Raise() | Stop(): self.future.set_value(value)
+
+        return ()
+
+
+@typing.final
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Enter[**ParamT, RetT](composer_.Enter[ParamT, RetT], herd_.Enter[ParamT, RetT, Future[RetT]]):
+    @typing.override
+    async def __call__(  # type: ignore[override]
+        self, value: composer_.ValueT[ParamT, RetT], /,
+    ) -> composer_.StackT:
+        match value:
+            case Param(): return self._dispatch(*value.args, **value.kwargs)  # type: ignore[return-value]
+            case _: return ()
+
+
+@typing.final
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Composed[**ParamT, RetT](composer_.Composed[ParamT, RetT], herd_.Composed[ParamT, RetT]): ...
+
+
+@typing.final
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Herd[**ParamT = ..., RetT = typing.Any](composer_.Composer[ParamT, RetT], herd_.Herd[ParamT, RetT]):
+    Composee: typing.ClassVar = Composee
+    Connect: typing.ClassVar = Connect
+    Exit: typing.ClassVar = Exit  # type: ignore[assignment]
+    Enter: typing.ClassVar = Enter
+    Composed: typing.ClassVar = Composed
+
+    @property
+    @typing.override
+    def future_t(self) -> type[Future[RetT]]:
+        return Future
+
+
+Composer = Herd
+herd = Herd()