braincraft 1.0.0__py3-none-any.whl

braincraft/__init__.py

@@ -0,0 +1,13 @@
+"""
+braincraft - A workshop of small, sharp utilities - carefully shaped helpers
+you reuse across projects to keep everyday coding tasks fast, tidy, and consistent.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+__version__ = "1.0.0"
+
+from braincraft.retry import retry_rand_exp
+
+__all__ = ["retry_rand_exp"]

braincraft/retry.py

@@ -0,0 +1,86 @@
+"""
+braincraft.retry - Retry utilities with exponential back-off and full jitter.
+
+Provides a generic async retry helper and a function that computes the next
+sleep interval using the "Full Jitter" algorithm described in the AWS
+Architecture Blog (exponential back-off + full random jitter).
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+import asyncio
+import random
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from logenrich import setup_logger
+
+_logger = setup_logger(__name__)
+
+
+def _compute_delay(attempt: int, base_delay: float, max_delay: float) -> float:
+    """Computes the next sleep interval using full-jitter exponential back-off.
+
+    The formula is: ``random.uniform(0, min(max_delay, base_delay * 2 ** attempt))``.
+
+    :param attempt: Zero-based attempt index (0 = first retry).
+    :param base_delay: Initial delay in seconds before jitter is applied.
+    :param max_delay: Upper cap in seconds for the computed sleep interval.
+    :return: A non-negative float representing the number of seconds to sleep.
+    """
+    ceiling = min(max_delay, base_delay * (2**attempt))
+    return random.uniform(0, ceiling)
+
+
+async def retry_rand_exp[T](  # pylint: disable=invalid-name
+    func: Callable[..., Coroutine[Any, Any, T]],
+    *args: Any,
+    max_attempts: int,
+    base_delay: float,
+    max_delay: float,
+    **kwargs: Any,
+) -> T:
+    """Calls an async coroutine function with retry and exponential-jitter back-off.
+
+    Retries on any :class:`Exception` up to *max_attempts* times.  After each
+    failure the caller sleeps for a jittered duration before the next attempt.
+    If all attempts are exhausted the last exception is re-raised.
+
+    :param func: Async callable to invoke.
+    :param args: Positional arguments forwarded to *func*.
+    :param max_attempts: Total number of attempts (must be >= 1).
+    :param base_delay: Base delay in seconds used for back-off calculation.
+    :param max_delay: Maximum sleep duration cap in seconds.
+    :param kwargs: Keyword arguments forwarded to *func*.
+    :return: The return value of a successful *func* invocation.
+    :raises ValueError: If *max_attempts* is less than 1.
+    :raises Exception: Re-raises the last exception when all attempts fail.
+    """
+    if max_attempts < 1:
+        raise ValueError(f"max_attempts must be >= 1, got {max_attempts}")
+    last_exc: Exception | None = None
+    for attempt in range(max_attempts):
+        try:
+            return await func(*args, **kwargs)
+        except Exception as exc:  # pylint: disable=broad-exception-caught
+            last_exc = exc
+            if attempt < max_attempts - 1:
+                delay = _compute_delay(attempt, base_delay, max_delay)
+                _logger.warning(
+                    "Attempt %d/%d failed (%s). Retrying in %.2fs.",
+                    attempt + 1,
+                    max_attempts,
+                    exc,
+                    delay,
+                )
+                await asyncio.sleep(delay)
+            else:
+                _logger.error(
+                    "Attempt %d/%d failed (%s). No more retries.",
+                    attempt + 1,
+                    max_attempts,
+                    exc,
+                )
+    assert last_exc is not None  # guaranteed when max_attempts >= 1
+    raise last_exc

braincraft-1.0.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: braincraft
+Version: 1.0.0
+Summary: A workshop of small, sharp utilities - carefully shaped helpers you reuse across projects to keep everyday coding tasks fast, tidy, and consistent.
+License: MIT License
+         
+         Copyright (c) 2026 Ron Webb
+         
+         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.
+License-File: LICENSE
+Author: Ron Webb
+Requires-Python: >=3.14
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: logenrich (>=1.0.1,<2.0.0)
+Description-Content-Type: text/markdown
+
+# braincraft
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](CHANGELOG.md)
+
+A workshop of small, sharp utilities - carefully shaped helpers you reuse across projects to keep everyday coding tasks fast, tidy, and consistent.
+
+## Requirements
+
+- Python `>=3.14`
+
+## Usage
+
+### `retry_rand_exp`
+
+Calls an async coroutine with automatic retry and full-jitter exponential back-off.
+Retries on any exception up to `max_attempts` times, sleeping a random jittered
+duration between attempts. Re-raises the last exception when all attempts are exhausted.
+
+```python
+from braincraft import retry_rand_exp
+
+async def fetch_data(url: str) -> str:
+    # your async operation here
+    ...
+
+result = await retry_rand_exp(
+    fetch_data,
+    "https://example.com/api",
+    max_attempts=5,
+    base_delay=1.0,
+    max_delay=30.0,
+)
+```
+
+## Development
+
+### Prerequisites
+
+- [Poetry](https://python-poetry.org/) `2.2+`
+
+### Install dependencies
+
+```bash
+poetry install
+```
+
+### Format and lint
+
+```bash
+poetry run black braincraft; poetry run pylint braincraft
+```
+
+### Run tests with coverage
+
+```bash
+poetry run pytest --cov=braincraft tests --cov-report html
+```
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a full history of changes.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+

braincraft-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+braincraft/__init__.py,sha256=s7D2bzZyOWvTPBfVYU5gWgT8rzEwM-KdBaPlxw295zI,313
+braincraft/retry.py,sha256=HXrov2fdCJ8YGOhBDbd4Zkv9WZZxJAxfG5c2MVu9VU4,3385
+braincraft-1.0.0.dist-info/licenses/LICENSE,sha256=2cmui6TBSfJF5E2Qr0xNS8x4ZY0grz8qLEBEW1CgpjA,1086
+braincraft-1.0.0.dist-info/METADATA,sha256=_a0SuHlN5SfOjiLjmlw1AFdHYK54IaYY4KlrsElhAro,3194
+braincraft-1.0.0.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+braincraft-1.0.0.dist-info/RECORD,,

braincraft-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.2
+Root-Is-Purelib: true
+Tag: py3-none-any

braincraft-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ron Webb
+
+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.