stranded 0.0.1__tar.gz

stranded-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cameron Evans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stranded-0.0.1/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: stranded
+Version: 0.0.1
+Summary: Composable decorators for caching, retrying, throttling, logging, and CLIs, for both sync and asyncio code
+Author-email: Cameron Evans <c.d.evans87@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cevans87/Stranded
+Project-URL: Issues, https://github.com/cevans87/Stranded/issues
+Project-URL: Repository, https://github.com/cevans87/Stranded.git
+Keywords: asyncio,back pressure,cache,memoize,rate limit,retry,throttle
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: mypy; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-mypy; extra == "test"
+Dynamic: license-file
+
+# Stranded
+
+Composable decorators for caching, retrying, throttling, logging, and building
+command-line interfaces. Every decorator works on both plain and `async def`
+functions, picking the threading or asyncio implementation from the function it
+wraps.
+
+Stranded is alpha software. The API changes between releases.
+
+## Install
+
+```bash
+pip install stranded
+```
+
+Python 3.13 or newer is required. There are no runtime dependencies.
+
+## Usage
+
+Each decorator is a frozen dataclass. Configure it with keyword arguments and
+apply it to a function. The same decorator works for sync and async code.
+
+```python
+import asyncio
+
+from stranded.functools import LruCache, Retry, Throttle
+
+
+@LruCache(size=128)
+def fib(n: int) -> int:
+    return n if n < 2 else fib(n - 1) + fib(n - 2)
+
+
+@Retry(n=3)
+@Throttle(max_running=4)
+async def fetch(url: str) -> str:
+    await asyncio.sleep(0)
+    return url
+
+
+print(fib(40))
+print(asyncio.run(fetch('https://example.com')))
+```
+
+### functools
+
+- `LruCache(size=...)` memoizes by argument, sharing one in-flight result
+  between concurrent callers.
+- `Herd()` collapses concurrent calls with the same arguments into one call,
+  without memoizing the result.
+- `Retry(n=...)` re-invokes the function when it raises, up to `n` times.
+- `Throttle(max_running=..., max_waiting=...)` bounds concurrency. The running
+  cap grows additively while calls succeed and halves when a call raises.
+
+Each also has an instance with default settings, spelled in lowercase:
+`lru_cache`, `herd`, `retry`, `throttle`.
+
+### logging
+
+`Logger` logs a function's call, return value, and exceptions at configurable
+levels.
+
+```python
+import logging
+
+from stranded.logging import Logger
+
+logging.basicConfig(level=logging.DEBUG)
+
+
+@Logger(call_level='DEBUG', return_level='INFO', exception_level='ERROR')
+def add(a: int, b: int) -> int:
+    return a + b
+
+
+add(1, 2)
+```
+
+### sqlite3
+
+`Db` memoizes a function's results to a SQLite database on disk, so results
+survive across processes.
+
+```python
+import pathlib
+import tempfile
+
+from stranded.sqlite3 import Db
+
+with tempfile.TemporaryDirectory() as tmp:
+
+    @Db(path=pathlib.Path(tmp) / 'db')
+    def expensive(key: str) -> str:
+        print('computing', key)
+        return key.upper()
+
+    print(expensive('a'))
+    print(expensive('a'))
+```
+
+### argparse
+
+`ArgumentParser` builds a command-line parser from a function's signature and
+type hints. Flags come before positionals, a boolean flag is spelled with one
+dash, and a valued flag with two. Parsers compose with `|`, so flags shared
+across subcommands can be written once.
+
+```python
+from stranded.argparse import ArgumentParser
+
+
+@ArgumentParser()
+def verbose_flag(*, verbose: bool = False) -> None:
+    if verbose:
+        print('verbose on')
+
+
+@ArgumentParser()
+def main(name: str, /, *, count: int = 1) -> None:
+    for _ in range(count):
+        print(f'hello, {name}')
+
+
+(verbose_flag | main)('-verbose', '--count', '2', 'world')
+```
+
+### Explicit sync and async variants
+
+The top-level decorators dispatch on whether the wrapped function is a
+coroutine function. To pin one, import from the `asyncio` or `threading`
+subpackage instead, for example `stranded.functools.asyncio.LruCache`.
+
+## Development
+
+```bash
+pip install -e '.[test]'
+pytest
+```
+
+## License
+
+MIT. See `LICENSE`.

stranded-0.0.1/README.md

@@ -0,0 +1,142 @@
+# Stranded
+
+Composable decorators for caching, retrying, throttling, logging, and building
+command-line interfaces. Every decorator works on both plain and `async def`
+functions, picking the threading or asyncio implementation from the function it
+wraps.
+
+Stranded is alpha software. The API changes between releases.
+
+## Install
+
+```bash
+pip install stranded
+```
+
+Python 3.13 or newer is required. There are no runtime dependencies.
+
+## Usage
+
+Each decorator is a frozen dataclass. Configure it with keyword arguments and
+apply it to a function. The same decorator works for sync and async code.
+
+```python
+import asyncio
+
+from stranded.functools import LruCache, Retry, Throttle
+
+
+@LruCache(size=128)
+def fib(n: int) -> int:
+    return n if n < 2 else fib(n - 1) + fib(n - 2)
+
+
+@Retry(n=3)
+@Throttle(max_running=4)
+async def fetch(url: str) -> str:
+    await asyncio.sleep(0)
+    return url
+
+
+print(fib(40))
+print(asyncio.run(fetch('https://example.com')))
+```
+
+### functools
+
+- `LruCache(size=...)` memoizes by argument, sharing one in-flight result
+  between concurrent callers.
+- `Herd()` collapses concurrent calls with the same arguments into one call,
+  without memoizing the result.
+- `Retry(n=...)` re-invokes the function when it raises, up to `n` times.
+- `Throttle(max_running=..., max_waiting=...)` bounds concurrency. The running
+  cap grows additively while calls succeed and halves when a call raises.
+
+Each also has an instance with default settings, spelled in lowercase:
+`lru_cache`, `herd`, `retry`, `throttle`.
+
+### logging
+
+`Logger` logs a function's call, return value, and exceptions at configurable
+levels.
+
+```python
+import logging
+
+from stranded.logging import Logger
+
+logging.basicConfig(level=logging.DEBUG)
+
+
+@Logger(call_level='DEBUG', return_level='INFO', exception_level='ERROR')
+def add(a: int, b: int) -> int:
+    return a + b
+
+
+add(1, 2)
+```
+
+### sqlite3
+
+`Db` memoizes a function's results to a SQLite database on disk, so results
+survive across processes.
+
+```python
+import pathlib
+import tempfile
+
+from stranded.sqlite3 import Db
+
+with tempfile.TemporaryDirectory() as tmp:
+
+    @Db(path=pathlib.Path(tmp) / 'db')
+    def expensive(key: str) -> str:
+        print('computing', key)
+        return key.upper()
+
+    print(expensive('a'))
+    print(expensive('a'))
+```
+
+### argparse
+
+`ArgumentParser` builds a command-line parser from a function's signature and
+type hints. Flags come before positionals, a boolean flag is spelled with one
+dash, and a valued flag with two. Parsers compose with `|`, so flags shared
+across subcommands can be written once.
+
+```python
+from stranded.argparse import ArgumentParser
+
+
+@ArgumentParser()
+def verbose_flag(*, verbose: bool = False) -> None:
+    if verbose:
+        print('verbose on')
+
+
+@ArgumentParser()
+def main(name: str, /, *, count: int = 1) -> None:
+    for _ in range(count):
+        print(f'hello, {name}')
+
+
+(verbose_flag | main)('-verbose', '--count', '2', 'world')
+```
+
+### Explicit sync and async variants
+
+The top-level decorators dispatch on whether the wrapped function is a
+coroutine function. To pin one, import from the `asyncio` or `threading`
+subpackage instead, for example `stranded.functools.asyncio.LruCache`.
+
+## Development
+
+```bash
+pip install -e '.[test]'
+pytest
+```
+
+## License
+
+MIT. See `LICENSE`.

stranded-0.0.1/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+build-backend = 'setuptools.build_meta'
+requires = ['setuptools>=77']
+
+[project]
+authors = [
+    {name = 'Cameron Evans', email = 'c.d.evans87@gmail.com'},
+]
+classifiers = [
+  'Development Status :: 3 - Alpha',
+  'Intended Audience :: Developers',
+  'Topic :: Software Development :: Libraries',
+  'Topic :: Software Development :: Libraries :: Python Modules',
+  'Topic :: System :: Logging',
+  'Framework :: AsyncIO',
+  'Programming Language :: Python :: 3',
+  'Programming Language :: Python :: 3.13',
+  'Programming Language :: Python :: 3.14',
+  'Typing :: Typed',
+]
+dependencies = []
+description = 'Composable decorators for caching, retrying, throttling, logging, and CLIs, for both sync and asyncio code'
+keywords = [
+    'asyncio',
+    'back pressure',
+    'cache',
+    'memoize',
+    'rate limit',
+    'retry',
+    'throttle',
+]
+license = 'MIT'
+license-files = ['LICENSE']
+name = 'stranded'
+readme = 'README.md'
+requires-python = '>=3.13'
+version = '0.0.1'
+
+[project.optional-dependencies]
+test = ['mypy', 'pytest', 'pytest-asyncio', 'pytest-cov', 'pytest-mypy']
+
+[project.urls]
+Homepage = 'https://github.com/cevans87/Stranded'
+Issues = 'https://github.com/cevans87/Stranded/issues'
+Repository = 'https://github.com/cevans87/Stranded.git'
+
+[tool.setuptools.packages.find]
+include = ['*']
+where = ['src']
+
+[tool.setuptools.package-data]
+stranded = ['py.typed']
+
+[tool.pytest.ini_options]
+addopts = [
+    '--cov=stranded',
+    '--cov-branch',
+    '--cov-report=term-missing',
+    '--mypy',
+]
+pythonpath = ['src']
+testpaths = ['test', 'src']
+
+[tool.coverage.run]
+branch = true
+source = ['stranded']
+
+[tool.coverage.report]
+exclude_also = [
+    'if typing\\.TYPE_CHECKING:',
+    '\\.\\.\\.\\s*$',
+    'raise NotImplementedError',
+    '@(abc\\.)?abstractmethod',
+]
+show_missing = true
+skip_covered = false
+
+[tool.mypy]
+strict = true
+files = ['src', 'test']
+mypy_path = '$MYPY_CONFIG_FILE_DIR/src'
+explicit_package_bases = true
+namespace_packages = true

stranded-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stranded-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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),)
+        )