ahi-core 0.2.0__py3-none-any.whl

ahi/core/__init__.py

@@ -0,0 +1,7 @@
+"""Cross-cutting helpers shared across AHI Python libraries."""
+
+from ahi.core.errors import AhiError, PollTimeoutError
+from ahi.core.logging import get_logger
+from ahi.core.polling import poll_until
+
+__all__ = ["AhiError", "PollTimeoutError", "get_logger", "poll_until"]

ahi/core/errors.py

@@ -0,0 +1,15 @@
+"""Base error types shared across AHI libraries."""
+
+from __future__ import annotations
+
+
+class AhiError(Exception):
+    """Base class for all errors raised by AHI libraries.
+
+    Catching ``AhiError`` lets callers handle anything this stack raises
+    without depending on the concrete subclasses.
+    """
+
+
+class PollTimeoutError(AhiError, TimeoutError):
+    """Raised when :func:`ahi.core.polling.poll_until` exceeds its deadline."""

ahi/core/logging.py

@@ -0,0 +1,30 @@
+"""Minimal logging helper.
+
+Libraries should not configure global logging; they should obtain a named
+logger and leave handler/level configuration to the consuming application.
+"""
+
+from __future__ import annotations
+
+import logging
+
+_PACKAGE_ROOT = "ahi"
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return a logger under the shared ``ahi`` namespace.
+
+    A :class:`~logging.NullHandler` is attached to the package-root logger so
+    that libraries never emit "No handlers could be found" warnings when the
+    host application has not configured logging.
+
+    Args:
+        name: Dotted suffix (for example ``"aws.redshift"``). When omitted, the
+            package-root logger is returned.
+    """
+    root = logging.getLogger(_PACKAGE_ROOT)
+    if not any(isinstance(h, logging.NullHandler) for h in root.handlers):
+        root.addHandler(logging.NullHandler())
+    if not name:
+        return root
+    return root.getChild(name)

ahi/core/polling.py

@@ -0,0 +1,61 @@
+"""A small, dependency-free poller for "start then wait for terminal state" APIs.
+
+Both the Redshift Data API and Athena follow the same shape: submit a statement,
+then poll a status endpoint until it reaches a terminal state. ``poll_until``
+captures that loop once, with exponential backoff and an injectable clock so it
+stays trivially testable.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import TypeVar
+
+from ahi.core.errors import PollTimeoutError
+
+T = TypeVar("T")
+
+
+def poll_until(
+    fetch: Callable[[], T],
+    is_done: Callable[[T], bool],
+    *,
+    timeout: float = 300.0,
+    interval: float = 1.0,
+    max_interval: float = 30.0,
+    backoff: float = 1.5,
+    sleep: Callable[[float], None] = time.sleep,
+    monotonic: Callable[[], float] = time.monotonic,
+) -> T:
+    """Call ``fetch`` until ``is_done`` returns ``True`` or ``timeout`` elapses.
+
+    The result is fetched once before the first sleep, so a call that is already
+    in a terminal state returns immediately without waiting.
+
+    Args:
+        fetch: Zero-arg callable returning the latest status payload.
+        is_done: Predicate deciding whether ``fetch``'s result is terminal.
+        timeout: Maximum seconds to wait before raising.
+        interval: Initial delay between polls, in seconds.
+        max_interval: Upper bound for the (growing) delay.
+        backoff: Multiplier applied to the delay after each poll.
+        sleep: Sleep function (injectable for tests).
+        monotonic: Monotonic clock (injectable for tests).
+
+    Returns:
+        The first ``fetch`` result for which ``is_done`` is ``True``.
+
+    Raises:
+        PollTimeoutError: If the deadline passes before a terminal state.
+    """
+    deadline = monotonic() + timeout
+    delay = interval
+    while True:
+        result = fetch()
+        if is_done(result):
+            return result
+        if monotonic() >= deadline:
+            raise PollTimeoutError(f"Polling exceeded timeout of {timeout:.1f}s")
+        sleep(min(delay, max_interval))
+        delay *= backoff

ahi_core-0.2.0.dist-info/METADATA

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: ahi-core
+Version: 0.2.0
+Summary: Cross-cutting helpers shared across AHI Python libraries (polling, errors, logging).
+Project-URL: Homepage, https://github.com/adaptivehealthintelligence/ahi-python-packages
+Project-URL: Documentation, https://adaptivehealthintelligence.github.io/ahi-python-packages/
+Project-URL: Repository, https://github.com/adaptivehealthintelligence/ahi-python-packages
+Author: Adaptive Health Intelligence
+License: MIT
+Keywords: ahi,utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ahi-core
+
+Cross-cutting helpers shared across the AHI Python libraries. Deliberately
+dependency-light — it should be safe to depend on from anywhere.
+
+```python
+from ahi.core import get_logger, poll_until, AhiError, PollTimeoutError
+```
+
+## What's here
+
+- `poll_until(...)` — a generic "submit then wait for a terminal state" loop with
+  exponential backoff and an injectable clock (used by `ahi-aws`).
+- `get_logger(name)` — a namespaced logger under `ahi.*` with a `NullHandler`
+  attached, so libraries never configure global logging.
+- `AhiError` — base exception for everything in the AHI stack;
+  `PollTimeoutError` is raised by `poll_until`.
+
+Part of [ahi-python-packages](https://github.com/adaptivehealthintelligence/ahi-python-packages).

ahi_core-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+ahi/core/__init__.py,sha256=h-rpeRSW2W47nMJ1r-0zYr6P9l7ksU-IcA8WNDoxAjk,272
+ahi/core/errors.py,sha256=VtP2ail9QDLaQb__eEmJ2sWdQgoh8wu9q5driB39fqs,437
+ahi/core/logging.py,sha256=cOc30bIJxCxWtn8eUF1z2fFTN2McPLmiYlymVeWbh-8,959
+ahi/core/polling.py,sha256=b3CevYoqLxSxdTqsX1j1_gL2T7KcQB0zmFC6ewS3TV8,2089
+ahi_core-0.2.0.dist-info/METADATA,sha256=vvQZgXmmS_bH1TJMJQP65J39MD_glC6GehRxU9Xesrw,1317
+ahi_core-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ahi_core-0.2.0.dist-info/RECORD,,

ahi_core-0.2.0.dist-info/WHEEL

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