lothc 0.0.1__tar.gz

lothc-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras --group dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run basedpyright .
+      - run: uv run pytest tests

lothc-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: pip install zensical
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

lothc-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Trusted Publishing (OIDC) — no PyPI token/secret needed. The environment name here must
+    # match the one configured as the trusted publisher on the PyPI project settings ("pypi").
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lothc
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # hatch-vcs derives the version from git tags — needs full history to see them,
+          # not just the single commit a shallow checkout would give it.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+
+      - run: uv build
+
+      - run: uv publish
+
+  deploy-docs:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+
+      - run: uv sync --group docs
+      - run: uv run zensical build
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+      - id: deployment
+        uses: actions/deploy-pages@v5

lothc-0.0.1/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+.venv/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+*.egg-info/
+.DS_Store
+
+# Handy for temporary run scripts
+tmp_*.py
+run_*.py
+
+# Local environment and scratch input files
+.env
+.in
+
+# perf.py run output (JSON per run, named by ms-timestamp run id)
+/results/
+
+# zensical docs build output
+/site/
+
+# asv (airspeed velocity) benchmark environments/results/generated test data
+/.asv/
+/asv_bench/_data/
+/asv_bench/.quick_check_history.json

lothc-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,52 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+
+      - id: basedpyright
+        name: basedpyright
+        entry: uv run basedpyright .
+        language: system
+        files: \.py$
+        pass_filenames: false
+
+      - id: deptry
+        name: deptry
+        entry: uv run deptry .
+        language: system
+        files: \.py$
+        pass_filenames: false
+
+      - id: vulture
+        name: vulture
+        entry: uv run vulture --min-confidence 100 lothc tests examples benchmarks perf.py vulture_whitelist.py
+        language: system
+        files: \.py$
+        pass_filenames: false
+
+      - id: pylint
+        name: pylint
+        entry: uv run pylint lothc
+        language: system
+        files: \.py$
+        pass_filenames: false

lothc-0.0.1/AGENTS.md

@@ -0,0 +1,77 @@
+# lothc — agent reference
+
+Typed HTTP client on pyreqwest. `HTTPClient` (async) / `SyncHTTPClient` (sync) — identical API,
+mirror methods 1:1 (drop `await`, `async with` → `with`, async iterators → sync iterators).
+
+## Build
+
+```python
+async with HTTPClient.build(
+    base_url=None,
+    bearer_token=None,
+    bearer_auth=None,
+    default_headers=None,
+    timeout=30.0,
+    cookie_store=False,
+    follow_redirects=True,
+    max_redirects=None,
+    proxy=None,
+    max_retries=0,
+    retry_methods=None,
+) as client:
+    ...
+```
+
+`bearer_token: str` (static) xor `bearer_auth: Callable[[], Awaitable[str]]` (sync client:
+`Callable[[], str]`) — resolved fresh per request, at most one of the two. `default_headers`
+sent on every request. `cookie_store=True` = in-memory jar. `proxy: str | None`.
+
+## Decode targets (`response_data_type`, default `bytes`)
+
+- `bytes` — raw, default
+- `lothc.JSON` — `dict[str, Any]` subclass, zero validation
+- pydantic `BaseModel` subclass
+- msgspec `Struct` subclass
+- `TypedDict` subclass — validated via typeguard if installed, else warns once
+  (`LOTHC_SUPPRESS_TYPEGUARD_WARNING=1` to silence)
+- bare `dict` / `dict[str, Any]` — NOT allowed, raises `TypeError`
+
+## Verbs
+
+- `get(path, *, params=None, headers=None, response_data_type=bytes, error_for_status=True) -> Data`
+- `get_result(path, *, params=None, headers=None, response_data_type=bytes, headers_type=None, error_for_status=True) -> Result` —
+  `.data .status .headers .typed_headers`
+- `post/put/patch(path, *, params=None, headers=None, json=None, form=None, content=None, response_data_type=bytes, error_for_status=True) -> Data` —
+  at most one of `json`/`form`/`content`, else `ValueError`
+- `delete(path, *, params=None, headers=None, response_data_type=bytes, error_for_status=True) -> Data`
+- `head(path, *, params=None, headers=None, headers_type=None, error_for_status=True) -> Result[None]`
+- `sse(path, *, params=None, headers=None, response_data_type=None, id_type=str, error_for_status=True) -> Iterator[SSEEvent[TData, TId]]` —
+  always yields `SSEEvent(id=, event=, data=)` (kw-only, `SSEEvent[TData, TId=str]`).
+  `response_data_type` controls `.data`'s type only (default `str`); class | pydantic
+  `TypeAdapter` | msgspec `Decoder`. `.event` is always `str`, never `None` (spec defaults it to
+  `"message"` when absent from the wire). `.id` is genuinely `str | None` per spec — `id_type` is
+  the single knob for both requiredness and type: `str` (default, required, no coercion) | any
+  other bare type e.g. `int`/`uuid.UUID` (required, coerced via `id_type(raw)`) | that type
+  unioned with `None` e.g. `int | None` (optional, coerced when present, `None` when absent) |
+  bare `None` (optional, `.id: str | None`, never coerced) — pass a union the same way you'd
+  write `response_data_type=A | B` for a discriminated union, `TId` binds to whatever you pass
+- `stream_get(path, *, params=None, headers=None, response_data_type=None, error_for_status=True) -> Iterator[bytes | TLine]` —
+  raw unbuffered bytes by default (safe for binary); `response_data_type` switches to
+  newline-buffered per-line decode
+- `stream_post(path, *, params=None, headers=None, json=None, form=None, content=None, response_data_type=None, error_for_status=True) -> Iterator[bytes | TLine]`
+
+`params`/`headers`: `dict`/`Mapping[str, str]`, or `BaseModel`/`Struct` (`None` fields omitted).
+`json`: `dict` | `BaseModel` | `Struct`. `form`: `dict[str, int | bytes | str | File]`, `File =
+tuple[str, bytes] | Path | BufferedIOBase`. `content`: raw `str | bytes` body.
+
+## Errors
+
+- `ResponseError(status, body_start)` — 4xx/5xx, raised when `error_for_status=True` (default)
+- `TransportError` base; `TimeoutError`, `ConnectionError` subclasses — no response received
+- pydantic/msgspec/typeguard validation errors propagate unwrapped (not translated)
+
+## Retries
+
+`max_retries` (default `0` = off), `retry_methods` (default `{GET,PUT,DELETE,HEAD}` — `POST`/
+`PATCH` need explicit opt-in). Exponential backoff; retries on transport error or status in
+`{429,500,502,503,504}`; honors `Retry-After`.