tha-req-runner 0.1.0__tar.gz

tha_req_runner-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/

tha_req_runner-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install hatchling build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

tha_req_runner-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+*.egg

tha_req_runner-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: tha-req-runner
+Version: 0.1.0
+Summary: A Tabular Helper API library that wraps requests with thread-safe session reuse, automatic retries, and a normalized response dict.
+License: MIT
+Keywords: api,http,requests,retry,session
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tha-req-runner
+
+[![CI](https://github.com/tha-guy-nate/tha-req-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/tha-guy-nate/tha-req-runner/actions/workflows/ci.yml)
+
+A small Python library that provides a thread-safe `requests.Session` with automatic retries and a normalized response parser. Intended as the HTTP transport layer for other `tha-*` runners.
+
+## Install
+
+```bash
+pip install tha-req-runner
+```
+
+## Quick start
+
+```python
+from tha_req_runner import ThaReq
+
+req = ThaReq()
+session = req.get_session()
+
+# safe_call wraps the try/except for you
+result = req.safe_call(session.get, "https://api.example.com/students", params={"limit": 100})
+# {"status": 200, "data": [...], "message": None, "raw_response": <Response>}
+
+# network errors return the same shape — no try/except needed
+result = req.safe_call(session.get, "https://unreachable.example.com")
+# {"status": None, "data": None, "message": "Connection refused", "raw_response": None}
+```
+
+## Response dict
+
+Every method returns the same shape whether the call succeeded or raised:
+
+| Key | Type | Description |
+|---|---|---|
+| `status` | `int \| None` | HTTP status code, or `None` on network error |
+| `data` | `object` | Parsed JSON body, or `None` if not JSON |
+| `message` | `str \| None` | Exception message on error, otherwise `None` |
+| `raw_response` | `Response \| None` | The raw `requests.Response` object |
+
+## API
+
+### `ThaReq`
+
+```python
+ThaReq()
+```
+
+### `req.get_session()`
+
+```python
+req.get_session(
+    *,
+    status_forcelist: tuple[int, ...] = (500, 502, 503, 504),
+    allowed_methods: Collection[str] | None = None,
+) -> requests.Session
+```
+
+Returns a `requests.Session` configured with automatic retries (`total=3`, `backoff_factor=0.5`). Config is applied only on the **first call per thread** — subsequent calls on the same thread return the cached session regardless of args. Two `ThaReq` instances never share a session.
+
+`allowed_methods=None` uses urllib3's safe-method default, which **excludes POST**. To retry POST (e.g. token endpoints):
+
+```python
+session = req.get_session(
+    status_forcelist=(429, 500, 502, 503, 504),
+    allowed_methods=frozenset(["GET", "POST"]),
+)
+```
+
+### `ThaReq.parse_response()`
+
+```python
+ThaReq.parse_response(result: requests.Response | Exception) -> dict[str, Any]
+```
+
+Normalizes a `requests.Response` or a caught `Exception` into a consistent dict. Also callable as `req.parse_response(result)` without instantiation.
+
+### `req.safe_call()`
+
+```python
+req.safe_call(fn, *args, **kwargs) -> dict[str, Any]
+```
+
+Calls `fn(*args, **kwargs)`, catches any exception, and returns a normalized response dict. Equivalent to:
+
+```python
+try:
+    result = req.parse_response(fn(*args, **kwargs))
+except Exception as exc:
+    result = req.parse_response(exc)
+```
+
+```python
+result = req.safe_call(session.get, url, params={"limit": 100})
+result = req.safe_call(session.post, token_url, data={"grant_type": "client_credentials"})
+```
+
+## Session and retries
+
+- **Thread-safe**: each thread gets its own session via `threading.local` on the instance
+- **Retry defaults**: `total=3`, `backoff_factor=0.5` (delays: 0.5s → 1s → 2s)
+- **Retry statuses**: `500`, `502`, `503`, `504` by default
+- **POST not retried by default** — pass `allowed_methods` explicitly to enable it
+- Sessions are reused across calls on the same thread
+
+## Used by
+
+- `tha-edfi-runner` — uses `ThaReq` as its HTTP transport layer
+
+## License
+
+MIT

tha_req_runner-0.1.0/README.md

@@ -0,0 +1,112 @@
+# tha-req-runner
+
+[![CI](https://github.com/tha-guy-nate/tha-req-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/tha-guy-nate/tha-req-runner/actions/workflows/ci.yml)
+
+A small Python library that provides a thread-safe `requests.Session` with automatic retries and a normalized response parser. Intended as the HTTP transport layer for other `tha-*` runners.
+
+## Install
+
+```bash
+pip install tha-req-runner
+```
+
+## Quick start
+
+```python
+from tha_req_runner import ThaReq
+
+req = ThaReq()
+session = req.get_session()
+
+# safe_call wraps the try/except for you
+result = req.safe_call(session.get, "https://api.example.com/students", params={"limit": 100})
+# {"status": 200, "data": [...], "message": None, "raw_response": <Response>}
+
+# network errors return the same shape — no try/except needed
+result = req.safe_call(session.get, "https://unreachable.example.com")
+# {"status": None, "data": None, "message": "Connection refused", "raw_response": None}
+```
+
+## Response dict
+
+Every method returns the same shape whether the call succeeded or raised:
+
+| Key | Type | Description |
+|---|---|---|
+| `status` | `int \| None` | HTTP status code, or `None` on network error |
+| `data` | `object` | Parsed JSON body, or `None` if not JSON |
+| `message` | `str \| None` | Exception message on error, otherwise `None` |
+| `raw_response` | `Response \| None` | The raw `requests.Response` object |
+
+## API
+
+### `ThaReq`
+
+```python
+ThaReq()
+```
+
+### `req.get_session()`
+
+```python
+req.get_session(
+    *,
+    status_forcelist: tuple[int, ...] = (500, 502, 503, 504),
+    allowed_methods: Collection[str] | None = None,
+) -> requests.Session
+```
+
+Returns a `requests.Session` configured with automatic retries (`total=3`, `backoff_factor=0.5`). Config is applied only on the **first call per thread** — subsequent calls on the same thread return the cached session regardless of args. Two `ThaReq` instances never share a session.
+
+`allowed_methods=None` uses urllib3's safe-method default, which **excludes POST**. To retry POST (e.g. token endpoints):
+
+```python
+session = req.get_session(
+    status_forcelist=(429, 500, 502, 503, 504),
+    allowed_methods=frozenset(["GET", "POST"]),
+)
+```
+
+### `ThaReq.parse_response()`
+
+```python
+ThaReq.parse_response(result: requests.Response | Exception) -> dict[str, Any]
+```
+
+Normalizes a `requests.Response` or a caught `Exception` into a consistent dict. Also callable as `req.parse_response(result)` without instantiation.
+
+### `req.safe_call()`
+
+```python
+req.safe_call(fn, *args, **kwargs) -> dict[str, Any]
+```
+
+Calls `fn(*args, **kwargs)`, catches any exception, and returns a normalized response dict. Equivalent to:
+
+```python
+try:
+    result = req.parse_response(fn(*args, **kwargs))
+except Exception as exc:
+    result = req.parse_response(exc)
+```
+
+```python
+result = req.safe_call(session.get, url, params={"limit": 100})
+result = req.safe_call(session.post, token_url, data={"grant_type": "client_credentials"})
+```
+
+## Session and retries
+
+- **Thread-safe**: each thread gets its own session via `threading.local` on the instance
+- **Retry defaults**: `total=3`, `backoff_factor=0.5` (delays: 0.5s → 1s → 2s)
+- **Retry statuses**: `500`, `502`, `503`, `504` by default
+- **POST not retried by default** — pass `allowed_methods` explicitly to enable it
+- Sessions are reused across calls on the same thread
+
+## Used by
+
+- `tha-edfi-runner` — uses `ThaReq` as its HTTP transport layer
+
+## License
+
+MIT

tha_req_runner-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "tha-req-runner"
+version = "0.1.0"
+description = "A Tabular Helper API library that wraps requests with thread-safe session reuse, automatic retries, and a normalized response dict."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["http", "requests", "api", "retry", "session"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = ["requests"]
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "mypy"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tha_req_runner"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+strict = true

tha_req_runner-0.1.0/src/tha_req_runner/__init__.py

@@ -0,0 +1,7 @@
+"""tha-req-runner: thread-safe HTTP requests with automatic retries and normalized responses."""
+
+from .errors import ReqError
+from .runner import ThaReq
+
+__version__ = "0.1.0"
+__all__ = ["ReqError", "ThaReq"]

tha_req_runner-0.1.0/src/tha_req_runner/errors.py

@@ -0,0 +1,2 @@
+class ReqError(Exception):
+    pass

tha_req_runner-0.1.0/src/tha_req_runner/runner.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Collection
+from typing import Any, Callable
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+_DEFAULT_RETRIES = 3
+_DEFAULT_BACKOFF = 0.5
+_DEFAULT_STATUS_FORCELIST = (500, 502, 503, 504)
+
+
+class ThaReq:
+    def __init__(self) -> None:
+        self._local = threading.local()
+
+    def get_session(
+        self,
+        *,
+        status_forcelist: tuple[int, ...] = _DEFAULT_STATUS_FORCELIST,
+        allowed_methods: Collection[str] | None = None,  # None → urllib3 safe-method default; POST excluded
+    ) -> requests.Session:
+        # config applies only on first call per thread; subsequent calls return the cached session
+        if not hasattr(self._local, "session"):
+            session = requests.Session()
+            retry = Retry(
+                total=_DEFAULT_RETRIES,
+                backoff_factor=_DEFAULT_BACKOFF,
+                status_forcelist=status_forcelist,
+                allowed_methods=allowed_methods,
+            )
+            adapter = HTTPAdapter(max_retries=retry)
+            session.mount("https://", adapter)
+            session.mount("http://", adapter)
+            self._local.session = session
+        return self._local.session  # type: ignore[no-any-return]
+
+    @staticmethod
+    def parse_response(result: requests.Response | Exception) -> dict[str, Any]:
+        if isinstance(result, Exception):
+            raw = getattr(result, "response", None)
+            if not isinstance(raw, requests.Response):
+                raw = None
+            return {
+                "status": raw.status_code if raw is not None else None,
+                "data": None,
+                "message": str(result),
+                "raw_response": raw,
+            }
+        try:
+            data: Any = result.json()
+        except Exception:
+            data = None
+        return {
+            "status": result.status_code,
+            "data": data,
+            "message": None,
+            "raw_response": result,
+        }
+
+    def safe_call(
+        self,
+        fn: Callable[..., requests.Response],
+        *args: Any,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        try:
+            return self.parse_response(fn(*args, **kwargs))
+        except Exception as exc:
+            return self.parse_response(exc)

tha_req_runner-0.1.0/tests/conftest.py

@@ -0,0 +1,8 @@
+import pytest
+
+from tha_req_runner import ThaReq
+
+
+@pytest.fixture
+def req() -> ThaReq:
+    return ThaReq()

tha_req_runner-0.1.0/tests/test_runner.py

@@ -0,0 +1,158 @@
+import threading
+from unittest.mock import MagicMock
+
+import pytest
+import requests
+
+from tha_req_runner import ThaReq
+
+
+# --- helpers ---
+
+def _mock_resp(status_code: int = 200, json_data: object = None) -> MagicMock:
+    resp = MagicMock(spec=requests.Response)
+    resp.status_code = status_code
+    if json_data is not None:
+        resp.json.return_value = json_data
+    else:
+        resp.json.side_effect = ValueError("no json")
+    return resp
+
+
+# --- get_session ---
+
+def test_get_session_returns_session(req: ThaReq) -> None:
+    assert isinstance(req.get_session(), requests.Session)
+
+
+def test_get_session_same_instance_per_thread(req: ThaReq) -> None:
+    assert req.get_session() is req.get_session()
+
+
+def test_get_session_thread_local(req: ThaReq) -> None:
+    sessions: list[requests.Session] = []
+
+    def capture() -> None:
+        sessions.append(req.get_session())
+
+    t1 = threading.Thread(target=capture)
+    t2 = threading.Thread(target=capture)
+    t1.start()
+    t2.start()
+    t1.join()
+    t2.join()
+
+    assert len(sessions) == 2
+    assert sessions[0] is not sessions[1]
+
+
+def test_get_session_instances_independent() -> None:
+    assert ThaReq().get_session() is not ThaReq().get_session()
+
+
+def test_get_session_default_status_forcelist(req: ThaReq) -> None:
+    adapter = req.get_session().get_adapter("https://example.com")
+    for code in (500, 502, 503, 504):
+        assert code in adapter.max_retries.status_forcelist
+
+
+def test_get_session_custom_status_forcelist() -> None:
+    req = ThaReq()
+    adapter = req.get_session(status_forcelist=(429, 503)).get_adapter("https://example.com")
+    assert 429 in adapter.max_retries.status_forcelist
+    assert 503 in adapter.max_retries.status_forcelist
+    assert 500 not in adapter.max_retries.status_forcelist
+
+
+def test_get_session_allowed_methods_frozenset() -> None:
+    req = ThaReq()
+    adapter = req.get_session(allowed_methods=frozenset(["GET", "POST"])).get_adapter("https://example.com")
+    assert "POST" in adapter.max_retries.allowed_methods
+
+
+def test_get_session_allowed_methods_list() -> None:
+    req = ThaReq()
+    adapter = req.get_session(allowed_methods=["GET", "POST"]).get_adapter("https://example.com")
+    assert "POST" in adapter.max_retries.allowed_methods
+
+
+def test_get_session_mounts_http_and_https(req: ThaReq) -> None:
+    session = req.get_session()
+    assert session.get_adapter("https://example.com") is not None
+    assert session.get_adapter("http://example.com") is not None
+
+
+# --- parse_response ---
+
+def test_parse_success_json() -> None:
+    resp = _mock_resp(200, {"id": 1})
+    result = ThaReq.parse_response(resp)
+    assert result["status"] == 200
+    assert result["data"] == {"id": 1}
+    assert result["message"] is None
+    assert result["raw_response"] is resp
+
+
+def test_parse_success_non_json() -> None:
+    resp = _mock_resp(200)
+    result = ThaReq.parse_response(resp)
+    assert result["status"] == 200
+    assert result["data"] is None
+    assert result["message"] is None
+
+
+def test_parse_exception_no_response() -> None:
+    exc = ConnectionError("timed out")
+    result = ThaReq.parse_response(exc)
+    assert result["status"] is None
+    assert result["data"] is None
+    assert "timed out" in result["message"]
+    assert result["raw_response"] is None
+
+
+def test_parse_exception_with_response() -> None:
+    raw = _mock_resp(401)
+    exc = requests.HTTPError("401 Unauthorized", response=raw)
+    result = ThaReq.parse_response(exc)
+    assert result["status"] == 401
+    assert result["raw_response"] is raw
+    assert result["data"] is None
+
+
+def test_parse_callable_as_static(req: ThaReq) -> None:
+    result = req.parse_response(_mock_resp(204))
+    assert result["status"] == 204
+
+
+# --- safe_call ---
+
+def test_safe_call_success(req: ThaReq) -> None:
+    resp = _mock_resp(200, {"id": 1})
+    result = req.safe_call(lambda: resp)
+    assert result["status"] == 200
+    assert result["data"] == {"id": 1}
+
+
+def test_safe_call_exception(req: ThaReq) -> None:
+    def boom() -> requests.Response:
+        raise ConnectionError("refused")
+
+    result = req.safe_call(boom)
+    assert result["status"] is None
+    assert "refused" in result["message"]
+
+
+def test_safe_call_passes_args_and_kwargs(req: ThaReq) -> None:
+    calls: list[tuple[object, ...]] = []
+
+    def fn(url: str, **kwargs: object) -> requests.Response:
+        calls.append((url, kwargs))
+        return _mock_resp(200, {})
+
+    req.safe_call(fn, "https://example.com", headers={"X-Key": "v"})
+    assert calls[0] == ("https://example.com", {"headers": {"X-Key": "v"}})
+
+
+def test_safe_call_stores_nothing_on_instance(req: ThaReq) -> None:
+    req.safe_call(lambda: _mock_resp(200, {}))
+    assert not hasattr(req, "result")