{"id":51433281,"url":"https://github.com/tha-guy-nate/tha-req-runner","last_synced_at":"2026-07-05T05:04:09.518Z","repository":{"id":358342337,"uuid":"1241010556","full_name":"tha-guy-nate/tha-req-runner","owner":"tha-guy-nate","description":"A Tabular Helper API library that wraps requests/httpx with thread-safe session reuse, automatic retries, and a normalized response dict.","archived":false,"fork":false,"pushed_at":"2026-07-02T04:10:44.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T06:12:42.368Z","etag":null,"topics":["http","python","requests","rest-api","tabular-helper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tha-guy-nate.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T21:12:01.000Z","updated_at":"2026-07-02T04:10:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tha-guy-nate/tha-req-runner","commit_stats":null,"previous_names":["tha-guy-nate/tha-req-runner"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/tha-guy-nate/tha-req-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tha-guy-nate%2Ftha-req-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tha-guy-nate%2Ftha-req-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tha-guy-nate%2Ftha-req-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tha-guy-nate%2Ftha-req-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tha-guy-nate","download_url":"https://codeload.github.com/tha-guy-nate/tha-req-runner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tha-guy-nate%2Ftha-req-runner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35143837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http","python","requests","rest-api","tabular-helper"],"created_at":"2026-07-05T05:04:09.040Z","updated_at":"2026-07-05T05:04:09.503Z","avatar_url":"https://github.com/tha-guy-nate.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tha-req-runner\n\n[![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)\n[![codecov](https://codecov.io/gh/tha-guy-nate/tha-req-runner/graph/badge.svg)](https://codecov.io/gh/tha-guy-nate/tha-req-runner)\n[![PyPI](https://img.shields.io/pypi/v/tha-req-runner)](https://pypi.org/project/tha-req-runner/)\n[![Python](https://img.shields.io/pypi/pyversions/tha-req-runner)](https://pypi.org/project/tha-req-runner/)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n[![wheel size](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Ftha-req-runner%2Fjson\u0026label=wheel%20size\u0026query=%24.urls%5B0%5D.size\u0026suffix=%20B)](https://pypi.org/project/tha-req-runner/#files)\n\nA Tabular Helper API library that wraps requests/httpx with thread-safe session reuse, automatic retries, and a normalized response dict. Supports both `requests` (default) and `httpx` backends. Intended as the HTTP transport layer for other `tha-*` runners.\n\n## Install\n\n```bash\npip install tha-req-runner           # requests backend (default)\npip install tha-req-runner[httpx]    # adds httpx backend support\n```\n\n## Quick start\n\n```python\nfrom tha_req_runner import ThaReq\n\n# requests backend (default)\nreq = ThaReq()\nsession = req.get_session()\n\n# httpx backend\nreq = ThaReq(backend=\"httpx\")\nclient = req.get_session()\n\n# safe_call wraps the try/except for you — same API regardless of backend\nresult = req.safe_call(session.get, \"https://api.example.com/students\", params={\"limit\": 100})\n# {\"status\": None, \"code\": 200, \"data\": [...], \"message\": None, \"raw_response\": \u003cResponse\u003e}\n\n# network errors return the same shape — no try/except needed\nresult = req.safe_call(session.get, \"https://unreachable.example.com\")\n# {\"status\": \"error\", \"code\": None, \"data\": None, \"message\": \"Connection refused\", \"raw_response\": None}\n```\n\n## Response dict\n\nEvery call returns the same shape whether it succeeded or raised:\n\n| Key | Type | Description |\n|---|---|---|\n| `status` | `\"error\" \\| None` | `\"error\"` on any failure (HTTP error or network error). `None` on success |\n| `code` | `int \\| None` | HTTP status code, or `None` on network error |\n| `data` | `object` | Parsed JSON body. Populated on success **and** on HTTP errors if the API returned a JSON error body |\n| `message` | `str \\| None` | HTTP error or exception message. `None` on success |\n| `raw_response` | `Response \\| None` | The raw response object (`requests.Response` or `httpx.Response`) |\n\n`safe_call` automatically calls `raise_for_status()`, so 4xx/5xx responses are treated as errors:\n\n```python\n# 200 → success path\n{\"status\": None, \"code\": 200, \"data\": {\"id\": 1}, \"message\": None, \"raw_response\": \u003cResponse\u003e}\n\n# 422 with JSON error body → error path, data preserved\n{\"status\": \"error\", \"code\": 422, \"data\": {\"detail\": \"field required\"}, \"message\": \"422 Unprocessable Entity\", \"raw_response\": \u003cResponse\u003e}\n\n# network error → no code or data\n{\"status\": \"error\", \"code\": None, \"data\": None, \"message\": \"Connection refused\", \"raw_response\": None}\n```\n\n## API\n\n### `ThaReq`\n\n```python\nThaReq(*, backend: Literal[\"requests\", \"httpx\"] = \"requests\")\n```\n\n`backend=\"httpx\"` requires `pip install tha-req-runner[httpx]`.\n\n### `req.get_session()`\n\n```python\nreq.get_session(\n    *,\n    status_forcelist: tuple[int, ...] = (500, 502, 503, 504),  # requests only\n    allowed_methods: Collection[str] | None = None,             # requests only\n    headers: dict[str, str] | None = None,\n    timeout: float = 30,\n) -\u003e requests.Session | httpx.Client\n```\n\nReturns a session configured with automatic retries. 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.\n\n`allowed_methods=None` uses urllib3's safe-method default, which **excludes POST**. To retry POST (e.g. token endpoints):\n\n```python\nsession = req.get_session(\n    status_forcelist=(429, 500, 502, 503, 504),\n    allowed_methods=frozenset([\"GET\", \"POST\"]),\n)\n```\n\n\u003e **httpx note**: `status_forcelist` and `allowed_methods` are ignored for the httpx backend. httpx retry is connection-level only (no status-based retry).\n\n### `req.reset_session()` / `req.close_session()`\n\nCloses and discards the current thread's session. The next `get_session()` call creates a fresh one. Useful when auth tokens rotate or a session enters a bad state. Both methods are equivalent.\n\n### `ThaReq.parse_response()`\n\n```python\nThaReq.parse_response(result) -\u003e dict[str, Any]\n```\n\nNormalizes a response object or a caught exception into a consistent dict. Works with both `requests.Response` and `httpx.Response`. Also callable as an instance method.\n\n### `req.safe_call()`\n\n```python\nreq.safe_call(fn, *args, **kwargs) -\u003e dict[str, Any]\n```\n\nCalls `fn(*args, **kwargs)`, calls `raise_for_status()` on the response, catches any exception, and returns a normalized response dict. Automatically injects the session `timeout` unless the caller provides one. JSON error bodies from 4xx/5xx responses are preserved in `data`.\n\n```python\nresult = req.safe_call(session.get, url, params={\"limit\": 100})\nresult = req.safe_call(session.post, token_url, data={\"grant_type\": \"client_credentials\"})\nresult = req.safe_call(session.get, url, timeout=5)  # override per-call\n```\n\n## Session and retries\n\n- **Thread-safe**: each thread gets its own session via `threading.local` on the instance\n- **Retry defaults**: `total=3`, `backoff_factor=0.5` (delays: 0.5s → 1s → 2s)\n- **Retry statuses**: `500`, `502`, `503`, `504` by default (requests backend only)\n- **POST not retried by default** — pass `allowed_methods` explicitly to enable it (requests backend only)\n- **Default timeout**: 30s, injected automatically by `safe_call`\n- Sessions are reused across calls on the same thread\n\n## Backend comparison\n\n| Feature | `requests` (default) | `httpx` |\n|---|---|---|\n| Status-based retry | Yes (`status_forcelist`) | No |\n| Allowed methods config | Yes | No |\n| Default timeout | Yes | Yes |\n| Default headers | Yes | Yes |\n| Thread-safe sessions | Yes | Yes |\n| HTTP/2 | No | Yes |\n| Async support | No | Yes (use `httpx.AsyncClient` directly) |\n\n## Alternatives\n\nThis library is intentionally limited in scope — it provides a thin, thread-safe wrapper around `requests` or `httpx` with automatic retries and a normalized response dict. If you need more control:\n\n- [**httpx**](https://www.python-httpx.org) — modern HTTP client with async support and HTTP/2 built in; use directly if you don't need the session wrapper or normalized response shape\n- [**requests**](https://requests.readthedocs.io) — the underlying sync HTTP library; sufficient on its own for simple, single-threaded use\n- [**tenacity**](https://tenacity.readthedocs.io) — standalone retry library that wraps any function; more configurable than urllib3's built-in retry for complex retry strategies\n\nChoose this library when you need thread-safe sessions, automatic retries, and a normalized response dict that fits the `tha-*` error pattern — none of the alternatives give you all three out of the box.\n\n## Used by\n\n- `tha-edfi-runner` — uses `ThaReq` as its HTTP transport layer\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftha-guy-nate%2Ftha-req-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftha-guy-nate%2Ftha-req-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftha-guy-nate%2Ftha-req-runner/lists"}