ahi-core 0.2.0__tar.gz

ahi_core-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+# Python artifacts
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+.dist/
+build/
+dist/
+
+# Virtual environments
+.venv/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDEs/OS
+.DS_Store
+.vscode/*.code-snippets
+
+# Docs build
+site/

ahi_core-0.2.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/adaptivehealthintelligence/ahi-python-packages/compare/ahi-core-v0.1.0...ahi-core-v0.2.0) (2026-06-27)
+
+
+### Features
+
+* scaffold uv workspace with core, sql, aws packages ([8c42f2f](https://github.com/adaptivehealthintelligence/ahi-python-packages/commit/8c42f2f371284180bf0569785837640e39deb80b))

ahi_core-0.2.0/PKG-INFO

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

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

@@ -0,0 +1,24 @@
+[project]
+name = "ahi-core"
+version = "0.2.0"
+description = "Cross-cutting helpers shared across AHI Python libraries (polling, errors, logging)."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Adaptive Health Intelligence" }]
+keywords = ["ahi", "utilities"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/adaptivehealthintelligence/ahi-python-packages"
+Documentation = "https://adaptivehealthintelligence.github.io/ahi-python-packages/"
+Repository = "https://github.com/adaptivehealthintelligence/ahi-python-packages"
+
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+# src-layout namespace package: ships the `ahi/core/` subtree under the shared
+# `ahi` namespace. There is intentionally no `ahi/__init__.py` (PEP 420).
+[tool.hatch.build.targets.wheel]
+packages = ["src/ahi"]

ahi_core-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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/tests/test_logging.py

@@ -0,0 +1,22 @@
+import logging
+
+from ahi.core import get_logger
+
+
+def test_root_logger_has_null_handler() -> None:
+    logger = get_logger()
+    assert logger.name == "ahi"
+    assert any(isinstance(h, logging.NullHandler) for h in logger.handlers)
+
+
+def test_child_logger_namespacing() -> None:
+    logger = get_logger("aws.redshift")
+    assert logger.name == "ahi.aws.redshift"
+
+
+def test_null_handler_added_once() -> None:
+    before = len(logging.getLogger("ahi").handlers)
+    get_logger()
+    get_logger("aws")
+    after = len(logging.getLogger("ahi").handlers)
+    assert after == before

ahi_core-0.2.0/tests/test_polling.py

@@ -0,0 +1,84 @@
+import pytest
+
+from ahi.core import PollTimeoutError, poll_until
+
+
+class FakeClock:
+    """Deterministic monotonic clock advanced by the injected sleep."""
+
+    def __init__(self) -> None:
+        self.t = 0.0
+
+    def monotonic(self) -> float:
+        return self.t
+
+    def sleep(self, seconds: float) -> None:
+        self.t += seconds
+
+
+def test_returns_immediately_when_already_done() -> None:
+    calls = []
+
+    def fetch() -> str:
+        calls.append(1)
+        return "FINISHED"
+
+    result = poll_until(fetch, lambda s: s == "FINISHED", sleep=lambda _: None)
+
+    assert result == "FINISHED"
+    assert len(calls) == 1  # no sleep, single fetch
+
+
+def test_polls_until_terminal_state() -> None:
+    states = iter(["RUNNING", "RUNNING", "FINISHED"])
+    clock = FakeClock()
+
+    result = poll_until(
+        lambda: next(states),
+        lambda s: s == "FINISHED",
+        interval=1.0,
+        backoff=2.0,
+        sleep=clock.sleep,
+        monotonic=clock.monotonic,
+    )
+
+    assert result == "FINISHED"
+    assert clock.t == pytest.approx(3.0)  # slept 1s then 2s
+
+
+def test_raises_on_timeout() -> None:
+    clock = FakeClock()
+
+    with pytest.raises(PollTimeoutError):
+        poll_until(
+            lambda: "RUNNING",
+            lambda s: s == "FINISHED",
+            timeout=5.0,
+            interval=1.0,
+            backoff=1.0,
+            sleep=clock.sleep,
+            monotonic=clock.monotonic,
+        )
+
+
+def test_delay_is_capped_at_max_interval() -> None:
+    clock = FakeClock()
+    slept: list[float] = []
+
+    def record_sleep(seconds: float) -> None:
+        slept.append(seconds)
+        clock.sleep(seconds)
+
+    states = iter(["RUNNING", "RUNNING", "RUNNING", "FINISHED"])
+    poll_until(
+        lambda: next(states),
+        lambda s: s == "FINISHED",
+        interval=10.0,
+        max_interval=15.0,
+        backoff=10.0,
+        timeout=1000.0,
+        sleep=record_sleep,
+        monotonic=clock.monotonic,
+    )
+
+    assert slept == [10.0, 15.0, 15.0]  # capped after the first poll