braincraft 1.0.0__tar.gz

braincraft-1.0.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0 - 2026-06-19
+
+### Added
+
+- Initial release of braincraft.
+- Core package structure with `logenrich` logging integration.
+- `retry` module: `retry_rand_exp` async helper with full-jitter exponential back-off.
+- GitHub Actions CI workflow (`tests.yml`): lint (black, pylint) and pytest with 80% coverage gate on every push and pull request.

braincraft-1.0.0/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.

braincraft-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,66 @@
+# 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/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-1.0.0/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/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "braincraft"
+version = "1.0.0"
+description = "A workshop of small, sharp utilities - carefully shaped helpers you reuse across projects to keep everyday coding tasks fast, tidy, and consistent."
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Ron Webb"}
+]
+requires-python = ">=3.14"
+dependencies = [
+    "logenrich (>=1.0.1,<2.0.0)",
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [{include = "braincraft"}]
+include = ["CHANGELOG.md"]
+
+[dependency-groups]
+dev = [
+    "black (>=26.5.1,<27.0.0)",
+    "pylint (>=4.0.6,<5.0.0)",
+    "pytest (>=9.1.1,<10.0.0)",
+    "pytest-cov (>=7.1.0,<8.0.0)",
+    "pytest-asyncio (>=1.0.0,<2.0.0)"
+]