beavercore 0.1.0__tar.gz

beavercore-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.envrc
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+.DS_Store
+.idea/
+.vscode/
+*.swp
+uv.lock

beavercore-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kalyan Ram Chimmili
+
+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.

beavercore-0.1.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.5
+Name: beavercore
+Version: 0.1.0
+Summary: An opinionated HTTP client framework on top of requests — retries, backoff, 429 handling, session refresh, typed exceptions, observability hooks.
+Project-URL: Homepage, https://github.com/kalyanramchimmili/beaverCore
+Project-URL: Repository, https://github.com/kalyanramchimmili/beaverCore
+Project-URL: Issues, https://github.com/kalyanramchimmili/beaverCore/issues
+Author: Kalyan Ram Chimmili
+License: MIT License
+        
+        Copyright (c) 2026 Kalyan Ram Chimmili
+        
+        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
+Keywords: client,framework,http,rate-limit,requests,retry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: requests<3,>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=7.0; extra == 'dev'
+Requires-Dist: responses<1,>=0.24; extra == 'dev'
+Requires-Dist: ruff<1,>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# beaverCore
+
+[![PyPI](https://img.shields.io/pypi/v/beavercore.svg)](https://pypi.org/project/beavercore/)
+[![Python](https://img.shields.io/pypi/pyversions/beavercore.svg)](https://pypi.org/project/beavercore/)
+[![License](https://img.shields.io/pypi/l/beavercore.svg)](LICENSE)
+
+A HTTP client wrapper on top of `requests`. You bring the URL and the credentials — beaverCore handles the parts of every HTTP client you'd otherwise copy-paste: retries with exponential backoff, 429 rate-limit compliance, one-shot session-token refresh on 401, typed exceptions, connection pooling, and an observability hook.
+
+```bash
+pip install beavercore
+```
+
+## The idea
+
+Every time someone writes a new HTTP client in Python — for an internal service, a vendor API, a third-party integration — they solve the same six problems:
+
+1. Turning transient failures (5xx, connection resets, timeouts) into retries with backoff.
+2. Respecting `Retry-After` when the upstream throttles them.
+3. Refreshing an expired session token *once*, transparently, on a 401.
+4. Distinguishing "auth broke" from "server sad" from "the request itself is wrong" without callers having to inspect status codes.
+5. Pooling the underlying TCP connections instead of tearing them down every call.
+6. Wiring the whole thing into logs/metrics without turning every method into a callback tree.
+
+beavercore does all six once. Downstream clients become endpoint code and nothing else — the GitHub client in `example.py` is exactly that shape: a factory function plus the endpoints, no retry code, no error classification, no rate-limit code.
+
+## Quick start
+
+```python
+from beavercore import Client, RetryPolicy
+
+def auth(request_kwargs: dict) -> None:
+    request_kwargs.setdefault("headers", {})["Authorization"] = f"Bearer {TOKEN}"
+
+with Client(
+    "https://api.example.com",
+    auth=auth,
+    retry=RetryPolicy(max_attempts=4),
+) as client:
+    things = client.get("/things").json()
+```
+
+Extension is via callables — no subclassing required. If you need to refresh a session token on a 401:
+
+```python
+def refresh() -> bool:
+    global TOKEN
+    TOKEN = login()
+    return True   # tells beavercore to retry the original request once
+
+Client("https://api.example.com", auth=auth, refresh=refresh)
+```
+
+`refresh` runs at most once per request. If the retry also 401s, you get `AuthError`.
+
+## Exception hierarchy
+
+```
+HttpError                base — carries .status, .response, .attempts
+├── AuthError            401/403 (extra: .refresh_attempted)
+├── RateLimitError       429 after retries exhausted (extra: .retry_after)
+└── TransientError       5xx or network fault, retries exhausted (extra: .last_reason)
+```
+
+Every exception carries `.response` (the raw `requests.Response`, or `None` for network faults) and `.attempts` (how many tries were made). Non-retryable non-2xx that doesn't fit one of the subclasses (e.g. 404, 418, 400) raises the base `HttpError`.
+
+## Design decisions
+
+The choices worth explaining because they're not obvious from the code.
+
+### Built on `requests`, not transport-agnostic
+
+beavercore is a *policy* layer — retries, backoff, error classification, session refresh, observability. The *transport* is [`requests`](https://requests.readthedocs.io/). A transport-agnostic version (pluggable `requests`/`httpx`) is possible but doubles the surface area for one real use case (async, via `httpx`), so it's deferred. If you need async today, use `httpx` directly — that's the correct answer.
+
+### Compose with callables, don't subclass
+
+The old shape of this library required subclassing `BaseClient` and overriding `_apply_auth` / `_refresh_auth`. It's gone. `Client` takes `auth` and `refresh` as callables at construction. Reasons:
+
+- **One class, one instance per upstream.** No `GitHubClient(BaseClient)` boilerplate per API.
+- **Auth is state, not behavior.** Making it a callable makes token rotation, environment-driven auth, and testing trivial.
+- **Composition scales.** Wrap the callable, don't subclass the class.
+
+### Raise, don't return
+
+Most Python HTTP wrappers return `{"success": bool, "response": ..., "error": ...}` dicts. beavercore raises typed exceptions instead. Reasons:
+
+- **Composes with `try/except`.** Callers can catch `AuthError` in one place instead of checking `result["success"]` on every call.
+- **Doesn't collide with success payloads.** If the API you're calling returns `{"success": false, ...}` as *data*, dict-based error contracts get confusing.
+- **Matches the ecosystem.** `requests.HTTPError`, `httpx.HTTPStatusError`, `openai.APIError` — every mature Python HTTP library raises.
+
+### Session refresh runs *once*, not forever
+
+On a 401, the `refresh` callable runs exactly once. If it returns `True`, the original request is retried once. If the retry also 401s (or `refresh` returned `False`), you get `AuthError`. Reasons:
+
+- **Bounded blast radius.** A misconfigured refresh function can't turn a single failed call into an infinite refresh loop.
+- **Refresh failures surface immediately.** If the refresh itself is broken (bad refresh token, revoked session), you see it now, not after N retries.
+- **Refresh is expensive.** Most upstreams charge for refresh calls (rate-limit budget, database write, OAuth roundtrip). Don't spam it.
+
+### Retries only on genuinely retryable failures
+
+Retryable: connection error, timeout, 500/502/503/504, 429. Not retryable: 4xx (except 401, which becomes a refresh path). Reasons:
+
+- **4xx is your bug.** `400 Bad Request`, `403 Forbidden`, `422 Unprocessable Entity` — retrying won't fix them. Fail fast, surface loud.
+- **5xx and network faults are upstream's bug.** Retrying with jitter is the right response.
+- **429 is a special case.** Technically "your fault" for exceeding a quota, but the upstream's `Retry-After` header tells you exactly how to fix it.
+
+### Bring-your-own rate limiter
+
+`Client` accepts a `throttle: Callable[[], None]` argument. It's called before every attempt. That's the whole contract. Reasons:
+
+- **Different upstreams have different rules.** Some are per-second, some per-minute, some per-user, some token-bucket, some sliding-window. One shipped limiter would only fit one shape.
+- **Optional by default.** Most APIs don't advertise a client-side limit — you only add one when the upstream tells you or 429s you.
+- **You already have one.** Every real project has a rate-limit primitive (Redis, in-memory semaphore, third-party lib). Pass it as a callable.
+
+### One observer, not three hooks
+
+The client emits events to a single `observer(event: dict)` callable. Events include `request`, `response`, `retry`, `auth_refresh`, each carrying `method`, `url`, `attempt`, and event-specific fields. Reasons:
+
+- **One signal path, not three.** Log aggregation, tracing, and metrics all speak dict.
+- **Extensible.** Adding a new event kind doesn't change the API.
+- **Zero cost when unused.** `observer` defaults to `None`; the fast path has one `is not None` check.
+
+## Constructor options
+
+| arg | default | notes |
+|---|---|---|
+| `base_url` | required | Trailing slash optional. |
+| `auth` | `None` | `(request_kwargs) -> None`. Mutate to attach credentials. |
+| `refresh` | `None` | `() -> bool`. Return `True` to retry once after a 401. |
+| `retry` | `RetryPolicy()` | See below. |
+| `throttle` | `None` | `() -> None`. Called before every attempt. |
+| `observer` | `None` | `(event_dict) -> None`. Fires for `request`, `response`, `retry`, `auth_refresh`. |
+| `timeout` | `30` | Seconds. Applied to every request. |
+| `verify_ssl` | `True` | Set `False` for self-signed internal endpoints. |
+| `session` | `None` | Provide a preconfigured `requests.Session` for custom adapters. |
+
+## RetryPolicy
+
+```python
+RetryPolicy(
+    max_attempts=3,    # total attempts including the first
+    backoff_base=0.5,  # seconds — multiplier for 2^attempt
+    backoff_cap=30.0,  # seconds — upper bound on any single sleep
+    jitter=0.5,        # 0 = no jitter, 1 = full jitter of backoff_base
+)
+```
+
+Immutable dataclass. `delay_for(attempt)` returns the sleep duration for a given attempt index.
+
+## Observability
+
+```python
+def observer(event: dict) -> None:
+    if event["event"] == "retry":
+        logger.warning(
+            "retrying %s %s (attempt %d): %s",
+            event["method"], event["url"], event["attempt"] + 1, event["reason"],
+        )
+
+client = Client("https://api.example.com", auth=auth, observer=observer)
+```
+
+One hook, one signal path — enough to wire beavercore into any log aggregator, Prometheus histogram, or OpenTelemetry span.
+
+## Worked example
+
+`example.py` at the repo root is a small GitHub REST API client built on beavercore — bearer auth, real 429s, real 404s. It's the reference implementation for what a client on top of beavercore should look like. Try it:
+
+```bash
+export GITHUB_TOKEN=ghp_your_token
+python example.py
+```
+
+## Repository layout
+
+```
+beaverCore/
+├── pyproject.toml       # package + dev tools + all config
+├── README.md            # this file (also the PyPI description)
+├── LICENSE
+├── beavercore/
+│   ├── __init__.py      # public API re-exports
+│   ├── client.py        # Client
+│   ├── retry.py         # RetryPolicy
+│   └── exceptions.py    # HttpError, AuthError, RateLimitError, TransientError
+├── tests/
+│   └── test_client.py
+├── example.py           # runnable GitHub API demo
+└── .github/workflows/
+    └── publish.yml      # manual: Actions tab → Run workflow → PyPI
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## Publishing
+
+Published to PyPI via GitHub Actions using [trusted publishing](https://docs.pypi.org/trusted-publishers/). Releases are **manual** — trigger the `publish` workflow from the Actions tab (click **Run workflow**). It publishes whatever version is set in `pyproject.toml` at that commit.
+
+## Sibling projects
+
+- [beaverWeb](https://github.com/kalyanramchimmili/beaverWeb) — A micro web framework for building the services beaverCore *calls*.
+
+## License
+
+MIT
+

beavercore-0.1.0/README.md

@@ -0,0 +1,211 @@
+# beaverCore
+
+[![PyPI](https://img.shields.io/pypi/v/beavercore.svg)](https://pypi.org/project/beavercore/)
+[![Python](https://img.shields.io/pypi/pyversions/beavercore.svg)](https://pypi.org/project/beavercore/)
+[![License](https://img.shields.io/pypi/l/beavercore.svg)](LICENSE)
+
+A HTTP client wrapper on top of `requests`. You bring the URL and the credentials — beaverCore handles the parts of every HTTP client you'd otherwise copy-paste: retries with exponential backoff, 429 rate-limit compliance, one-shot session-token refresh on 401, typed exceptions, connection pooling, and an observability hook.
+
+```bash
+pip install beavercore
+```
+
+## The idea
+
+Every time someone writes a new HTTP client in Python — for an internal service, a vendor API, a third-party integration — they solve the same six problems:
+
+1. Turning transient failures (5xx, connection resets, timeouts) into retries with backoff.
+2. Respecting `Retry-After` when the upstream throttles them.
+3. Refreshing an expired session token *once*, transparently, on a 401.
+4. Distinguishing "auth broke" from "server sad" from "the request itself is wrong" without callers having to inspect status codes.
+5. Pooling the underlying TCP connections instead of tearing them down every call.
+6. Wiring the whole thing into logs/metrics without turning every method into a callback tree.
+
+beavercore does all six once. Downstream clients become endpoint code and nothing else — the GitHub client in `example.py` is exactly that shape: a factory function plus the endpoints, no retry code, no error classification, no rate-limit code.
+
+## Quick start
+
+```python
+from beavercore import Client, RetryPolicy
+
+def auth(request_kwargs: dict) -> None:
+    request_kwargs.setdefault("headers", {})["Authorization"] = f"Bearer {TOKEN}"
+
+with Client(
+    "https://api.example.com",
+    auth=auth,
+    retry=RetryPolicy(max_attempts=4),
+) as client:
+    things = client.get("/things").json()
+```
+
+Extension is via callables — no subclassing required. If you need to refresh a session token on a 401:
+
+```python
+def refresh() -> bool:
+    global TOKEN
+    TOKEN = login()
+    return True   # tells beavercore to retry the original request once
+
+Client("https://api.example.com", auth=auth, refresh=refresh)
+```
+
+`refresh` runs at most once per request. If the retry also 401s, you get `AuthError`.
+
+## Exception hierarchy
+
+```
+HttpError                base — carries .status, .response, .attempts
+├── AuthError            401/403 (extra: .refresh_attempted)
+├── RateLimitError       429 after retries exhausted (extra: .retry_after)
+└── TransientError       5xx or network fault, retries exhausted (extra: .last_reason)
+```
+
+Every exception carries `.response` (the raw `requests.Response`, or `None` for network faults) and `.attempts` (how many tries were made). Non-retryable non-2xx that doesn't fit one of the subclasses (e.g. 404, 418, 400) raises the base `HttpError`.
+
+## Design decisions
+
+The choices worth explaining because they're not obvious from the code.
+
+### Built on `requests`, not transport-agnostic
+
+beavercore is a *policy* layer — retries, backoff, error classification, session refresh, observability. The *transport* is [`requests`](https://requests.readthedocs.io/). A transport-agnostic version (pluggable `requests`/`httpx`) is possible but doubles the surface area for one real use case (async, via `httpx`), so it's deferred. If you need async today, use `httpx` directly — that's the correct answer.
+
+### Compose with callables, don't subclass
+
+The old shape of this library required subclassing `BaseClient` and overriding `_apply_auth` / `_refresh_auth`. It's gone. `Client` takes `auth` and `refresh` as callables at construction. Reasons:
+
+- **One class, one instance per upstream.** No `GitHubClient(BaseClient)` boilerplate per API.
+- **Auth is state, not behavior.** Making it a callable makes token rotation, environment-driven auth, and testing trivial.
+- **Composition scales.** Wrap the callable, don't subclass the class.
+
+### Raise, don't return
+
+Most Python HTTP wrappers return `{"success": bool, "response": ..., "error": ...}` dicts. beavercore raises typed exceptions instead. Reasons:
+
+- **Composes with `try/except`.** Callers can catch `AuthError` in one place instead of checking `result["success"]` on every call.
+- **Doesn't collide with success payloads.** If the API you're calling returns `{"success": false, ...}` as *data*, dict-based error contracts get confusing.
+- **Matches the ecosystem.** `requests.HTTPError`, `httpx.HTTPStatusError`, `openai.APIError` — every mature Python HTTP library raises.
+
+### Session refresh runs *once*, not forever
+
+On a 401, the `refresh` callable runs exactly once. If it returns `True`, the original request is retried once. If the retry also 401s (or `refresh` returned `False`), you get `AuthError`. Reasons:
+
+- **Bounded blast radius.** A misconfigured refresh function can't turn a single failed call into an infinite refresh loop.
+- **Refresh failures surface immediately.** If the refresh itself is broken (bad refresh token, revoked session), you see it now, not after N retries.
+- **Refresh is expensive.** Most upstreams charge for refresh calls (rate-limit budget, database write, OAuth roundtrip). Don't spam it.
+
+### Retries only on genuinely retryable failures
+
+Retryable: connection error, timeout, 500/502/503/504, 429. Not retryable: 4xx (except 401, which becomes a refresh path). Reasons:
+
+- **4xx is your bug.** `400 Bad Request`, `403 Forbidden`, `422 Unprocessable Entity` — retrying won't fix them. Fail fast, surface loud.
+- **5xx and network faults are upstream's bug.** Retrying with jitter is the right response.
+- **429 is a special case.** Technically "your fault" for exceeding a quota, but the upstream's `Retry-After` header tells you exactly how to fix it.
+
+### Bring-your-own rate limiter
+
+`Client` accepts a `throttle: Callable[[], None]` argument. It's called before every attempt. That's the whole contract. Reasons:
+
+- **Different upstreams have different rules.** Some are per-second, some per-minute, some per-user, some token-bucket, some sliding-window. One shipped limiter would only fit one shape.
+- **Optional by default.** Most APIs don't advertise a client-side limit — you only add one when the upstream tells you or 429s you.
+- **You already have one.** Every real project has a rate-limit primitive (Redis, in-memory semaphore, third-party lib). Pass it as a callable.
+
+### One observer, not three hooks
+
+The client emits events to a single `observer(event: dict)` callable. Events include `request`, `response`, `retry`, `auth_refresh`, each carrying `method`, `url`, `attempt`, and event-specific fields. Reasons:
+
+- **One signal path, not three.** Log aggregation, tracing, and metrics all speak dict.
+- **Extensible.** Adding a new event kind doesn't change the API.
+- **Zero cost when unused.** `observer` defaults to `None`; the fast path has one `is not None` check.
+
+## Constructor options
+
+| arg | default | notes |
+|---|---|---|
+| `base_url` | required | Trailing slash optional. |
+| `auth` | `None` | `(request_kwargs) -> None`. Mutate to attach credentials. |
+| `refresh` | `None` | `() -> bool`. Return `True` to retry once after a 401. |
+| `retry` | `RetryPolicy()` | See below. |
+| `throttle` | `None` | `() -> None`. Called before every attempt. |
+| `observer` | `None` | `(event_dict) -> None`. Fires for `request`, `response`, `retry`, `auth_refresh`. |
+| `timeout` | `30` | Seconds. Applied to every request. |
+| `verify_ssl` | `True` | Set `False` for self-signed internal endpoints. |
+| `session` | `None` | Provide a preconfigured `requests.Session` for custom adapters. |
+
+## RetryPolicy
+
+```python
+RetryPolicy(
+    max_attempts=3,    # total attempts including the first
+    backoff_base=0.5,  # seconds — multiplier for 2^attempt
+    backoff_cap=30.0,  # seconds — upper bound on any single sleep
+    jitter=0.5,        # 0 = no jitter, 1 = full jitter of backoff_base
+)
+```
+
+Immutable dataclass. `delay_for(attempt)` returns the sleep duration for a given attempt index.
+
+## Observability
+
+```python
+def observer(event: dict) -> None:
+    if event["event"] == "retry":
+        logger.warning(
+            "retrying %s %s (attempt %d): %s",
+            event["method"], event["url"], event["attempt"] + 1, event["reason"],
+        )
+
+client = Client("https://api.example.com", auth=auth, observer=observer)
+```
+
+One hook, one signal path — enough to wire beavercore into any log aggregator, Prometheus histogram, or OpenTelemetry span.
+
+## Worked example
+
+`example.py` at the repo root is a small GitHub REST API client built on beavercore — bearer auth, real 429s, real 404s. It's the reference implementation for what a client on top of beavercore should look like. Try it:
+
+```bash
+export GITHUB_TOKEN=ghp_your_token
+python example.py
+```
+
+## Repository layout
+
+```
+beaverCore/
+├── pyproject.toml       # package + dev tools + all config
+├── README.md            # this file (also the PyPI description)
+├── LICENSE
+├── beavercore/
+│   ├── __init__.py      # public API re-exports
+│   ├── client.py        # Client
+│   ├── retry.py         # RetryPolicy
+│   └── exceptions.py    # HttpError, AuthError, RateLimitError, TransientError
+├── tests/
+│   └── test_client.py
+├── example.py           # runnable GitHub API demo
+└── .github/workflows/
+    └── publish.yml      # manual: Actions tab → Run workflow → PyPI
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## Publishing
+
+Published to PyPI via GitHub Actions using [trusted publishing](https://docs.pypi.org/trusted-publishers/). Releases are **manual** — trigger the `publish` workflow from the Actions tab (click **Run workflow**). It publishes whatever version is set in `pyproject.toml` at that commit.
+
+## Sibling projects
+
+- [beaverWeb](https://github.com/kalyanramchimmili/beaverWeb) — A micro web framework for building the services beaverCore *calls*.
+
+## License
+
+MIT
+

beavercore-0.1.0/beavercore/__init__.py

@@ -0,0 +1,25 @@
+"""beavercore — a small HTTP client wrapper.
+
+One class (:class:`Client`) that runs the request, retries transient failures,
+respects ``Retry-After``, refreshes stale auth once, and raises typed errors.
+Compose with callables — no subclassing required.
+"""
+
+from beavercore.client import Client
+from beavercore.exceptions import (
+    AuthError,
+    HttpError,
+    RateLimitError,
+    TransientError,
+)
+from beavercore.retry import RetryPolicy
+
+__all__ = [
+    "AuthError",
+    "Client",
+    "HttpError",
+    "RateLimitError",
+    "RetryPolicy",
+    "TransientError",
+]
+__version__ = "0.1.0"

beavercore-0.1.0/beavercore/client.py

@@ -0,0 +1,204 @@
+"""The Client — runs the request, retries transient failures, refreshes auth."""
+
+import time
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+
+from beavercore.exceptions import AuthError, HttpError, RateLimitError, TransientError
+from beavercore.retry import RetryPolicy
+
+_RETRYABLE_STATUS = frozenset({500, 502, 503, 504})
+
+AuthHook = Callable[[dict], None]
+RefreshHook = Callable[[], bool]
+ThrottleHook = Callable[[], None]
+ObserverHook = Callable[[dict], None]
+
+
+class Client:
+    """HTTP client with retry, backoff, 429 handling, one-shot auth refresh.
+
+    All extension points are callables passed at construction — no subclassing.
+
+    :param auth: mutates ``request_kwargs`` before each attempt to attach credentials.
+    :param refresh: called once on the first 401; return ``True`` to retry, ``False``
+        (or omit) to raise :class:`AuthError`.
+    :param throttle: called before every attempt (bring your own rate limiter).
+    :param observer: called with an event dict (``event``, ``method``, ``url`` and
+        event-specific fields). Events: ``request``, ``response``, ``retry``,
+        ``auth_refresh``.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        auth: AuthHook | None = None,
+        refresh: RefreshHook | None = None,
+        retry: RetryPolicy | None = None,
+        throttle: ThrottleHook | None = None,
+        observer: ObserverHook | None = None,
+        timeout: float = 30.0,
+        verify_ssl: bool = True,
+        session: requests.Session | None = None,
+    ):
+        if not base_url:
+            raise ValueError("base_url is required")
+
+        self._base_url = base_url.rstrip("/") + "/"
+        self._auth = auth
+        self._refresh = refresh
+        self._retry = retry or RetryPolicy()
+        self._throttle = throttle
+        self._observer = observer
+        self._timeout = timeout
+        self._verify_ssl = verify_ssl
+        self._session = session or requests.Session()
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def get(self, path: str, **kw: Any) -> requests.Response:
+        return self._request("GET", path, **kw)
+
+    def post(self, path: str, **kw: Any) -> requests.Response:
+        return self._request("POST", path, **kw)
+
+    def put(self, path: str, **kw: Any) -> requests.Response:
+        return self._request("PUT", path, **kw)
+
+    def patch(self, path: str, **kw: Any) -> requests.Response:
+        return self._request("PATCH", path, **kw)
+
+    def delete(self, path: str, **kw: Any) -> requests.Response:
+        return self._request("DELETE", path, **kw)
+
+    def _emit(self, event: str, **fields: Any) -> None:
+        if self._observer is not None:
+            self._observer({"event": event, **fields})
+
+    def _sleep(self, attempt: int, delay: float) -> None:
+        # Skip the sleep after the last attempt — nothing else is going to run.
+        if attempt < self._retry.max_attempts - 1 and delay > 0:
+            time.sleep(delay)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> requests.Response:
+        url = urljoin(self._base_url, path.lstrip("/"))
+        kwargs.setdefault("timeout", self._timeout)
+        kwargs.setdefault("verify", self._verify_ssl)
+
+        refresh_tried = False
+        last_response: requests.Response | None = None
+        last_reason: str = ""
+
+        for attempt in range(self._retry.max_attempts):
+            if self._throttle is not None:
+                self._throttle()
+
+            request_kwargs = dict(kwargs)
+            if self._auth is not None:
+                self._auth(request_kwargs)
+
+            self._emit("request", method=method, url=url, attempt=attempt)
+
+            try:
+                response = self._session.request(method, url, **request_kwargs)
+            except (requests.ConnectionError, requests.Timeout) as exc:
+                last_reason = f"network:{type(exc).__name__}"
+                self._emit("retry", method=method, url=url, attempt=attempt, reason=last_reason)
+                self._sleep(attempt, self._retry.delay_for(attempt))
+                continue
+
+            self._emit(
+                "response", method=method, url=url, status=response.status_code, attempt=attempt
+            )
+
+            status = response.status_code
+
+            if status == 401 and self._refresh is not None and not refresh_tried:
+                refresh_tried = True
+                if self._refresh():
+                    self._emit("auth_refresh", method=method, url=url, attempt=attempt)
+                    continue
+                raise AuthError(
+                    f"authentication failed for {method} {url}",
+                    status=status,
+                    response=response,
+                    attempts=attempt + 1,
+                    refresh_attempted=True,
+                )
+
+            if status in (401, 403):
+                raise AuthError(
+                    f"authentication failed for {method} {url} ({status})",
+                    status=status,
+                    response=response,
+                    attempts=attempt + 1,
+                    refresh_attempted=refresh_tried,
+                )
+
+            if status == 429:
+                last_response = response
+                last_reason = "rate_limit:429"
+                retry_after = _parse_retry_after(response)
+                self._emit("retry", method=method, url=url, attempt=attempt, reason=last_reason)
+                delay = (
+                    min(retry_after, self._retry.backoff_cap)
+                    if retry_after is not None
+                    else self._retry.delay_for(attempt)
+                )
+                self._sleep(attempt, delay)
+                continue
+
+            if status in _RETRYABLE_STATUS:
+                last_response = response
+                last_reason = f"5xx:{status}"
+                self._emit("retry", method=method, url=url, attempt=attempt, reason=last_reason)
+                self._sleep(attempt, self._retry.delay_for(attempt))
+                continue
+
+            if not response.ok:
+                raise HttpError(
+                    f"unexpected {status} from {method} {url}",
+                    status=status,
+                    response=response,
+                    attempts=attempt + 1,
+                )
+
+            return response
+
+        attempts = self._retry.max_attempts
+        if last_response is not None and last_response.status_code == 429:
+            raise RateLimitError(
+                f"rate limit not cleared after {attempts} attempts",
+                status=429,
+                response=last_response,
+                attempts=attempts,
+                retry_after=_parse_retry_after(last_response),
+            )
+        raise TransientError(
+            f"transient failure persisted after {attempts} attempts ({last_reason})",
+            status=last_response.status_code if last_response is not None else None,
+            response=last_response,
+            attempts=attempts,
+            last_reason=last_reason,
+        )
+
+
+def _parse_retry_after(response: requests.Response) -> float | None:
+    value = response.headers.get("Retry-After")
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None

beavercore-0.1.0/beavercore/exceptions.py

@@ -0,0 +1,59 @@
+"""Typed exception hierarchy raised by :class:`beavercore.Client`.
+
+Every exception carries the raw :class:`requests.Response` (when a response was
+received), the HTTP status, and the total attempts made. Subclasses add fields
+specific to why they were raised — ``retry_after`` on 429, ``last_reason`` on
+transient failures, ``refresh_attempted`` on 401/403.
+"""
+
+from typing import Any
+
+import requests
+
+
+class HttpError(Exception):
+    """Base for every error raised by :class:`Client`."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        response: requests.Response | None = None,
+        attempts: int = 1,
+    ):
+        super().__init__(message)
+        self.status = status
+        self.response = response
+        self.attempts = attempts
+
+    @property
+    def status_code(self) -> int | None:
+        return self.status
+
+
+class AuthError(HttpError):
+    """401/403. ``refresh_attempted`` records whether the refresh hook ran."""
+
+    def __init__(self, message: str, *, refresh_attempted: bool = False, **kwargs: Any):
+        super().__init__(message, **kwargs)
+        self.refresh_attempted = refresh_attempted
+
+
+class RateLimitError(HttpError):
+    """429 that outlasted the retry budget. ``retry_after`` from the last response."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kwargs: Any):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class TransientError(HttpError):
+    """5xx or network fault that outlasted the retry budget.
+
+    ``last_reason`` is a short tag like ``"5xx:503"`` or ``"network:Timeout"``.
+    """
+
+    def __init__(self, message: str, *, last_reason: str = "", **kwargs: Any):
+        super().__init__(message, **kwargs)
+        self.last_reason = last_reason

beavercore-0.1.0/beavercore/retry.py

@@ -0,0 +1,31 @@
+"""Retry policy for :class:`beavercore.Client` — exponential backoff with jitter."""
+
+import random
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Immutable retry configuration.
+
+    :param max_attempts: total attempts including the first.
+    :param backoff_base: seconds — multiplier for ``2 ** attempt``.
+    :param backoff_cap: seconds — upper bound on any single sleep.
+    :param jitter: 0 = deterministic backoff, 1 = up to a full ``backoff_base``
+        of extra jitter on top of the exponential term.
+    """
+
+    max_attempts: int = 3
+    backoff_base: float = 0.5
+    backoff_cap: float = 30.0
+    jitter: float = 0.5
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be >= 1")
+        if self.backoff_base < 0 or self.backoff_cap < 0 or self.jitter < 0:
+            raise ValueError("backoff_base, backoff_cap, jitter must be >= 0")
+
+    def delay_for(self, attempt: int) -> float:
+        base = min(self.backoff_base * (2**attempt), self.backoff_cap)
+        return base + random.uniform(0, self.jitter * self.backoff_base)

beavercore-0.1.0/example.py

@@ -0,0 +1,73 @@
+"""GitHub REST API client — a worked example built on beavercore.
+
+The whole file is business logic. Retries, exponential backoff, 429 handling,
+connection pooling, and error classification are inherited from ``Client``.
+"""
+
+import os
+
+from beavercore import Client, RetryPolicy
+
+
+def github_client(
+    token: str,
+    *,
+    base_url: str = "https://api.github.com",
+    api_version: str = "2022-11-28",
+) -> Client:
+    if not token:
+        raise ValueError("token is required")
+
+    def apply_auth(request_kwargs: dict) -> None:
+        headers = request_kwargs.setdefault("headers", {})
+        headers["Authorization"] = f"Bearer {token}"
+        headers.setdefault("Accept", "application/vnd.github+json")
+        headers.setdefault("X-GitHub-Api-Version", api_version)
+
+    return Client(
+        base_url=base_url,
+        auth=apply_auth,
+        retry=RetryPolicy(max_attempts=4),
+    )
+
+
+def get_authenticated_user(client: Client) -> dict:
+    return client.get("/user").json()
+
+
+def get_user(client: Client, username: str) -> dict:
+    return client.get(f"/users/{username}").json()
+
+
+def list_repos(
+    client: Client,
+    username: str,
+    *,
+    per_page: int = 30,
+    page: int = 1,
+) -> list[dict]:
+    return client.get(
+        f"/users/{username}/repos",
+        params={"per_page": per_page, "page": page},
+    ).json()
+
+
+def get_repo(client: Client, owner: str, repo: str) -> dict:
+    return client.get(f"/repos/{owner}/{repo}").json()
+
+
+def rate_limit(client: Client) -> dict:
+    return client.get("/rate_limit").json()
+
+
+if __name__ == "__main__":
+    try:
+        token = os.environ["GITHUB_TOKEN"]
+    except KeyError:
+        raise SystemExit("GITHUB_TOKEN environment variable is required") from None
+
+    with github_client(token) as gh:
+        me = get_authenticated_user(gh)
+        print(f"logged in as {me['login']}")
+        for repo in list_repos(gh, me["login"], per_page=10):
+            print(f"  - {repo['full_name']}")

beavercore-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "beavercore"
+version = "0.1.0"
+description = "An opinionated HTTP client framework on top of requests — retries, backoff, 429 handling, session refresh, typed exceptions, observability hooks."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "Kalyan Ram Chimmili" }]
+keywords = ["http", "client", "retry", "rate-limit", "requests", "framework"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "requests>=2.31,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0,<10",
+    "responses>=0.24,<1",
+    "ruff>=0.4,<1",
+]
+
+[project.urls]
+Homepage = "https://github.com/kalyanramchimmili/beaverCore"
+Repository = "https://github.com/kalyanramchimmili/beaverCore"
+Issues = "https://github.com/kalyanramchimmili/beaverCore/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["beavercore"]
+
+[tool.hatch.build.targets.sdist]
+include = ["beavercore/", "tests/", "example.py", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+pythonpath = ["."]

beavercore-0.1.0/tests/test_client.py

@@ -0,0 +1,258 @@
+import pytest
+import requests
+import responses
+
+from beavercore import (
+    AuthError,
+    Client,
+    HttpError,
+    RateLimitError,
+    RetryPolicy,
+    TransientError,
+)
+
+BASE = "https://api.example.com"
+
+
+@pytest.fixture
+def fast() -> RetryPolicy:
+    return RetryPolicy(max_attempts=3, backoff_base=0.0, backoff_cap=0.0, jitter=0.0)
+
+
+def _url(path: str) -> str:
+    return f"{BASE}/{path.lstrip('/')}"
+
+
+# ─── constructor validation ──────────────────────────────────────────────────
+
+
+def test_base_url_required():
+    with pytest.raises(ValueError):
+        Client(base_url="")
+
+
+def test_retry_policy_validates_max_attempts():
+    with pytest.raises(ValueError):
+        RetryPolicy(max_attempts=0)
+
+
+def test_retry_policy_delay_grows_and_caps():
+    p = RetryPolicy(max_attempts=10, backoff_base=1.0, backoff_cap=4.0, jitter=0.0)
+    assert p.delay_for(0) == 1.0
+    assert p.delay_for(1) == 2.0
+    assert p.delay_for(2) == 4.0
+    assert p.delay_for(9) == 4.0  # capped
+
+
+# ─── happy path ──────────────────────────────────────────────────────────────
+
+
+@responses.activate
+def test_get_200(fast):
+    responses.get(_url("/things"), json={"ok": True})
+    with Client(BASE, retry=fast) as c:
+        r = c.get("/things")
+    assert r.status_code == 200
+    assert r.json() == {"ok": True}
+
+
+@responses.activate
+def test_auth_callable_mutates_kwargs(fast):
+    responses.get(_url("/x"), json={})
+
+    def auth(kw: dict) -> None:
+        kw.setdefault("headers", {})["Authorization"] = "Bearer xyz"
+
+    with Client(BASE, retry=fast, auth=auth) as c:
+        c.get("/x")
+
+    assert responses.calls[0].request.headers["Authorization"] == "Bearer xyz"
+
+
+# ─── 5xx retry / exhaustion ──────────────────────────────────────────────────
+
+
+@responses.activate
+def test_5xx_retried_then_succeeds(fast):
+    responses.get(_url("/x"), status=503)
+    responses.get(_url("/x"), status=502)
+    responses.get(_url("/x"), json={"ok": True})
+    with Client(BASE, retry=fast) as c:
+        r = c.get("/x")
+    assert r.status_code == 200
+    assert len(responses.calls) == 3
+
+
+@responses.activate
+def test_5xx_exhausts_raises_transient(fast):
+    for _ in range(3):
+        responses.get(_url("/x"), status=500)
+    with Client(BASE, retry=fast) as c, pytest.raises(TransientError) as ei:
+        c.get("/x")
+    assert ei.value.attempts == 3
+    assert ei.value.last_reason == "5xx:500"
+    assert ei.value.status == 500
+
+
+# ─── 429 rate limit ──────────────────────────────────────────────────────────
+
+
+@responses.activate
+def test_429_retry_after_then_succeeds(fast):
+    responses.get(_url("/x"), status=429, headers={"Retry-After": "0"})
+    responses.get(_url("/x"), json={"ok": True})
+    with Client(BASE, retry=fast) as c:
+        r = c.get("/x")
+    assert r.status_code == 200
+
+
+@responses.activate
+def test_429_exhausts_raises_rate_limit(fast):
+    for _ in range(3):
+        responses.get(_url("/x"), status=429, headers={"Retry-After": "0"})
+    with Client(BASE, retry=fast) as c, pytest.raises(RateLimitError) as ei:
+        c.get("/x")
+    assert ei.value.attempts == 3
+    assert ei.value.retry_after == 0.0
+    assert ei.value.status == 429
+
+
+# ─── 401 auth refresh ────────────────────────────────────────────────────────
+
+
+@responses.activate
+def test_401_refresh_true_retries_once(fast):
+    responses.get(_url("/x"), status=401)
+    responses.get(_url("/x"), json={"ok": True})
+    calls = {"n": 0}
+
+    def refresh() -> bool:
+        calls["n"] += 1
+        return True
+
+    with Client(BASE, retry=fast, refresh=refresh) as c:
+        r = c.get("/x")
+    assert r.status_code == 200
+    assert calls["n"] == 1
+
+
+@responses.activate
+def test_401_refresh_false_raises_auth(fast):
+    responses.get(_url("/x"), status=401)
+    with Client(BASE, retry=fast, refresh=lambda: False) as c, pytest.raises(AuthError) as ei:
+        c.get("/x")
+    assert ei.value.refresh_attempted is True
+    assert ei.value.status == 401
+
+
+@responses.activate
+def test_401_without_refresh_hook_raises_auth(fast):
+    responses.get(_url("/x"), status=401)
+    with Client(BASE, retry=fast) as c, pytest.raises(AuthError) as ei:
+        c.get("/x")
+    assert ei.value.refresh_attempted is False
+
+
+@responses.activate
+def test_403_raises_auth(fast):
+    responses.get(_url("/x"), status=403)
+    with Client(BASE, retry=fast) as c, pytest.raises(AuthError) as ei:
+        c.get("/x")
+    assert ei.value.status == 403
+
+
+@responses.activate
+def test_401_refresh_only_runs_once_even_if_still_401(fast):
+    for _ in range(3):
+        responses.get(_url("/x"), status=401)
+    calls = {"n": 0}
+
+    def refresh() -> bool:
+        calls["n"] += 1
+        return True
+
+    with Client(BASE, retry=fast, refresh=refresh) as c, pytest.raises(AuthError):
+        c.get("/x")
+    assert calls["n"] == 1
+
+
+# ─── non-retryable 4xx ───────────────────────────────────────────────────────
+
+
+@responses.activate
+def test_404_raises_httperror_and_stops(fast):
+    responses.get(_url("/x"), status=404)
+    with Client(BASE, retry=fast) as c, pytest.raises(HttpError) as ei:
+        c.get("/x")
+    assert ei.value.status == 404
+    assert not isinstance(ei.value, (AuthError, RateLimitError, TransientError))
+    assert len(responses.calls) == 1
+
+
+@responses.activate
+def test_418_raises_httperror(fast):
+    responses.get(_url("/x"), status=418)
+    with Client(BASE, retry=fast) as c, pytest.raises(HttpError) as ei:
+        c.get("/x")
+    assert ei.value.status == 418
+
+
+# ─── network faults ──────────────────────────────────────────────────────────
+
+
+@responses.activate
+def test_connection_error_retried_then_exhausted(fast):
+    for _ in range(3):
+        responses.get(_url("/x"), body=requests.ConnectionError("boom"))
+    with Client(BASE, retry=fast) as c, pytest.raises(TransientError) as ei:
+        c.get("/x")
+    assert "network:" in ei.value.last_reason
+    assert ei.value.attempts == 3
+
+
+# ─── observer ────────────────────────────────────────────────────────────────
+
+
+@responses.activate
+def test_observer_receives_lifecycle_events(fast):
+    responses.get(_url("/x"), status=500)
+    responses.get(_url("/x"), json={"ok": True})
+
+    events: list[dict] = []
+    with Client(BASE, retry=fast, observer=events.append) as c:
+        c.get("/x")
+
+    kinds = [e["event"] for e in events]
+    assert kinds.count("request") == 2
+    assert kinds.count("response") == 2
+    assert kinds.count("retry") == 1
+
+
+# ─── throttle ────────────────────────────────────────────────────────────────
+
+
+@responses.activate
+def test_throttle_called_before_every_attempt(fast):
+    responses.get(_url("/x"), status=500)
+    responses.get(_url("/x"), status=500)
+    responses.get(_url("/x"), json={"ok": True})
+
+    calls = {"n": 0}
+
+    def throttle() -> None:
+        calls["n"] += 1
+
+    with Client(BASE, retry=fast, throttle=throttle) as c:
+        c.get("/x")
+
+    assert calls["n"] == 3
+
+
+# ─── session lifecycle ───────────────────────────────────────────────────────
+
+
+def test_context_manager_closes_session():
+    with Client(BASE) as c:
+        session = c._session
+    # After close(), further requests would fail — we just verify close was reached.
+    assert session is not None