gazebo 0.1.0__tar.gz

gazebo-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  # Keep the SHA-pinned GitHub Actions (and their version comments) up to date.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

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

@@ -0,0 +1,43 @@
+name: "Continuous integration"
+
+concurrency:
+  group: ${{ github.ref }}
+  cancel-in-progress: false
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  ci:
+    name: Continuous integration
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync
+        run: uv sync --locked --all-extras --all-packages --no-editable
+      - name: Pre-Commit Hooks
+        run: uv run pre-commit run --all-files
+      - name: Test
+        run: uv run pytest
+      - name: Test example
+        run: uv run --no-sync pytest
+        working-directory: examples/garden
+      - name: "Upload coverage to Codecov"
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        with:
+          fail_ci_if_error: false
+          verbose: true

gazebo-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,73 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+# Allow only one concurrent deployment, to avoid mike/gh-pages races.
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  # On pull requests, just confirm the docs build cleanly (no deploy).
+  build:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          python-version: "3.14"
+      - name: Sync
+        run: uv sync --locked --all-extras --group docs
+      - name: Build (strict)
+        run: uv run zensical build --strict --clean
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0  # full history so mike can update the gh-pages branch
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          python-version: "3.14"
+
+      - name: Sync
+        run: uv sync --locked --all-extras --group docs
+
+      # mike (squidfunk's Zensical-aware fork) builds via `zensical build` and
+      # commits each version to the gh-pages branch.
+      - name: Deploy dev version
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        run: uv run mike deploy --push --update-aliases dev latest
+
+      - name: Deploy release version
+        if: github.event_name == 'release' && !github.event.release.prerelease
+        run: |
+          VERSION="${{ github.event.release.tag_name }}"
+          uv run mike deploy --push --update-aliases "$VERSION" stable
+          uv run mike set-default --push stable
+
+      - name: Deploy pre-release version
+        if: github.event_name == 'release' && github.event.release.prerelease
+        run: |
+          VERSION="${{ github.event.release.tag_name }}"
+          uv run mike deploy --push "$VERSION"

gazebo-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Build and release
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  release:
+    types:
+      - published
+
+jobs:
+  build-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - name: Build package
+        run: uv build
+      - name: Upload artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: startsWith(github.ref, 'refs/tags')
+        with:
+          name: dist-${{ github.ref_name }}
+          path: dist/
+          overwrite: true
+          if-no-files-found: error
+
+  release-package:
+    if: startsWith(github.ref, 'refs/tags')
+    needs: build-package
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gazebo
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v5.0.0
+        with:
+          name: dist-${{ github.ref_name }}
+          path: dist/
+      - name: Upload release
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

gazebo-0.1.0/.gitignore

@@ -0,0 +1,127 @@
+__version__.py
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Environments
+.env
+.env.*
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

gazebo-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,58 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff_check
+        name: ruff check
+        entry: ruff check --force-exclude
+        language: python
+        'types_or': [python, pyi]
+        args: [--fix, --exit-non-zero-on-fix]
+        require_serial: true
+      - id: ruff_format
+        name: ruff format
+        entry: ruff format --force-exclude
+        language: python
+        'types_or': [python, pyi]
+        args: []
+        require_serial: true
+      - id: check-added-large-files
+        name: Check for added large files
+        entry: check-added-large-files
+        language: system
+      - id: check-toml
+        name: Check Toml
+        entry: check-toml
+        language: system
+        types: [toml]
+      - id: check-yaml
+        name: Check Yaml
+        entry: check-yaml
+        language: system
+        types: [yaml]
+      - id: end-of-file-fixer
+        name: Fix End of Files
+        entry: end-of-file-fixer
+        language: system
+        types: [text]
+        stages: [pre-commit, pre-push, manual]
+      - id: trailing-whitespace
+        name: Trim Trailing Whitespace
+        entry: trailing-whitespace-fixer
+        language: system
+        types: [text]
+        stages: [pre-commit, pre-push, manual]
+      - id: mypy
+        name: mypy
+        entry: mypy
+        language: python
+        'types_or': [python, pyi]
+        args: []
+        require_serial: true
+      - id: pyright
+        name: pyright
+        entry: pyright
+        language: system
+        'types_or': [python, pyi]
+        pass_filenames: false
+        args: [src, tests]
+        require_serial: true

gazebo-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.1.0] - XXXX-XX-XX
+
+Initial release 🎉
+
+[unreleased]: https://github.com/jkeifer/gazebo/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jkeifer/gazebo/releases/tag/v0.1.0

gazebo-0.1.0/CLAUDE.md

@@ -0,0 +1,173 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+gazebo packages the recurring machinery of OGC-style REST APIs (deferred links,
+collection envelopes, RFC 7807 problems, proxy-aware URLs, a typed DI container, and
+FastAPI glue) so it isn't re-implemented per project. The core depends only
+on `pydantic`; framework integration is opt-in via extras. Requires Python 3.12+.
+
+## Commands
+
+The project is `uv`-managed and is a `uv` workspace whose only member is
+`examples/garden`. Run everything through `uv`.
+
+```sh
+uv sync --all-extras --all-packages   # install (CI also uses --locked --no-editable)
+uv run pytest                          # run the library test suite (tests/)
+uv run pytest tests/test_link.py::test_name   # a single test
+uv run pre-commit run --all-files      # ruff check+format, mypy, pyright, file hygiene
+```
+
+`uv run pytest` always reports coverage on the `gazebo` package (`addopts=--cov=gazebo`
+in `pyproject.toml`) and treats warnings as errors (`filterwarnings = ['error']`).
+
+The example app is its **own** project under `examples/garden` with its own test suite
+and entry point; run them from that directory:
+
+```sh
+cd examples/garden
+uv run garden        # serve Gazebo Gardens on http://127.0.0.1:8000
+uv run pytest        # the example's tests
+```
+
+Type checking is enforced by **both** mypy and pyright (pyright runs over `src` and
+`tests`); both run in pre-commit and CI must be green on Python 3.12–3.14.
+
+## Architecture
+
+The codebase is strictly layered and **dependencies only ever point downward**. The
+two load-bearing ideas are *deferred links* and a *scoped DI container*; understand
+those two seams and the rest follows.
+
+### Layers (`src/gazebo/`)
+
+1. **Core** (`context.py`, `link.py`, `collection.py`, `pagination.py`, `rels.py`,
+   `problems.py`, `ogc.py`) — pydantic + stdlib only. **Never imports a web
+   framework.** Pure models and the context seam.
+2. **DI core** (`di/`) — stdlib only, no web framework. A standalone, extraction-ready
+   container behind a `Providers` interface.
+3. **Pure ASGI** (`asgi.py`) — proxy-header middleware and context-setting middleware;
+   no framework import.
+4. **Framework glue** (`ext/fastapi.py`) — the only module that imports `fastapi`.
+   Wires the DI container and the link context into a real app. Importing it requires
+   the `gazebo[fastapi]` extra.
+
+When adding code, respect the layer: anything a lower layer needs must not import
+upward, and the core must stay framework-free.
+
+### Deferred links (the central trick)
+
+A `Link.href` may be a plain URL **or** a callable taking a `RequestContext` and
+returning a URL. Callables are resolved at **JSON serialization time**, so links (and
+whole `LinkedCollection`s) are fully constructible in business logic with no request in
+hand.
+
+- `gazebo/context.py` defines the `RequestContext` Protocol (the minimal surface link
+  factories need: `base_url`, `url`, `query_params`, `url_for`) and delivers it
+  ambiently via the `link_context` ContextVar.
+- The framework glue sets that ContextVar per request (`use_context`). For manual dumps
+  / tests there is a fallback: `model_dump(context={'request': ctx})`, resolved by
+  `resolve_context`.
+- `Link` factories (`self_link`, `root_link`, `to_route`) build callable hrefs that
+  call back into the context — they stay framework-agnostic.
+
+A consequence: a callable-href link only serializes correctly inside an active request
+(or with an explicit dump context). Serializing one with no context raises a clear
+`ValueError` by design.
+
+### DI container (`di/`)
+
+- `providers.py` — registration. A **recipe** is a callable that builds a value, keyed
+  by the type it produces; it may be colocated as a `__provide__` classmethod on the
+  type, or supplied standalone for external types. **Scope is a wiring decision bound
+  at registration, never a property of the type** (`providers.app(T)` /
+  `providers.request(T)`). Recipes may be sync/async functions, (async) generators, or
+  (async) context managers; generators are auto-wrapped as CMs. `Qualify` disambiguates
+  duplicate types; `Overrides` is a typed replacement layer (the test-override
+  mechanism — by parameter, never by mutating a global).
+- `container.py` — the resolution engine. Resolves a recipe's dependencies by the
+  **types of its parameters**; a parameter typed as a scope's *root* (e.g. the request
+  object) receives that root. Each entered scope owns a resolution cache and an
+  `AsyncExitStack` for teardown. Errors are specific: `UnresolvedDependencyError`,
+  `ScopeMismatchError`, `CircularDependencyError`.
+
+### How the glue ties it together (`ext/fastapi.py`)
+
+`GazeboApp` enters the **app** scope in its lifespan and opens a **request** scope per
+request, publishing the link `RequestContext` for that request. Routes opt into
+bare-type injection by living on a `GazeboRouter` (or the app directly): any parameter
+whose type carries `__provide__`, or is marked `Annotated[T, Inject]`, is resolved from
+the per-request scope by rewriting the route signature into FastAPI `Depends`.
+
+`GazeboApp` + `GazeboRouter` are an **intended pair**. Putting an injectable-typed route
+on a plain `APIRouter` fails loudly at startup (naming the route) rather than silently
+treating the parameter as a request body. To add gazebo behavior to an app you didn't
+construct, use `upgrade(app, providers)` instead of subclassing; to mount a `GazeboApp`
+under a root app, forward its lifespan with `forward_lifespans`.
+
+## Docs
+
+- `working-docs/` — design specs and drafts: `design.md` (the OGC/web shapes),
+  `design-di.md` (the injection system), `roadmap.md` (post-v1 feature backlog). These
+  are the authoritative rationale for why things are shaped as they are; read the
+  relevant one before reworking a subsystem.
+- `docs/` — the published documentation site (zensical/mkdocs, versioned with mike).
+- `examples/garden/` — a complete standalone OGC-style API that exercises every feature;
+  the best end-to-end reference for how the pieces fit.
+
+```sh
+uv run --group docs zensical build --strict --clean   # build (CI gate; fails on issues)
+uv run --group docs zensical serve                     # live preview while writing
+```
+
+### Documentation style & guidelines
+
+- **Split by document type; never duplicate across the boundary.** *Reference* (what
+  each symbol is — signatures, params) lives in **docstrings** and is autogenerated into
+  `docs/reference.md` via mkdocstrings. *Explanation/how-to* (why you'd reach for it, how
+  pieces combine) lives in **handwritten Markdown**. Keep docstrings Google-style and
+  current — they are the single source of truth for the reference layer.
+- **Narrative pages must not restate the API.** No retyped signatures or param tables in
+  prose; link into the reference anchor instead (e.g. `reference.md#gazebo.link`, or a
+  per-symbol anchor like `#gazebo.link.Link.self_link`). Each page ends with a
+  **Reference** link.
+- **Structure is layered by architecture** (Core → DI → FastAPI integration), one page
+  per module, mirroring `src/gazebo/`. The nav lives in `zensical.toml`; update it when
+  adding a page.
+- **Page shape:** open with a one-line *why* blockquote, lead with the rationale (the
+  *why*) before the *how*, then concept sections. Prefer small, self-contained,
+  copy-pasteable snippets over one large example; the garden example is the
+  "see it all together" reference.
+- **All code snippets are tested.** Example code lives in `tests/examples/<page>.py` as
+  runnable modules with module-level `assert`s; `tests/test_examples.py` executes each
+  via `runpy`, so a broken snippet fails CI. Docs **include** the clean region with
+  pymdownx.snippets — ` ```python\n--8<-- "tests/examples/links.py:self_link"\n``` ` —
+  rather than pasting code, so what readers see is exactly what runs. Wrap the rendered
+  region in `# --8<-- [start:name]` / `# --8<-- [end:name]` markers and keep the driving
+  `assert`/`TestClient` code *outside* the markers so it doesn't render. `check_paths`
+  is on, so a bad include path or region name fails the strict build.
+
+## Landing a feature
+
+A new feature or behavior change is not complete until all three of these land with it:
+
+1. **Tests** in `tests/` covering the new behavior (coverage and warnings-as-errors are
+   enforced; CI runs the suite on Python 3.12–3.14).
+2. **Use in the garden example** — `examples/garden` is meant to exercise *every*
+   feature, so wire the new capability into the example app and its tests. CI runs the
+   garden suite separately, so this is load-bearing, not decorative.
+3. **Documentation** — update the relevant page under `docs/` (and the design spec in
+   `working-docs/` if the feature changes a subsystem's rationale or shape).
+
+## Conventions
+
+- Ruff is configured with single quotes and a 99-char line length, with a broad lint
+  rule set (see `[tool.ruff.lint]` in `pyproject.toml`). Match the surrounding style.
+- Every module starts with a docstring explaining its role in the layering; keep that
+  up to date when a module's responsibility shifts.
+</content>
+</invoke>
+</invoke>

gazebo-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing
+
+gazebo packages the recurring machinery of OGC-style REST APIs (deferred links,
+collection envelopes, RFC 7807 problems, proxy-aware URLs, a typed DI container,
+and FastAPI glue). The core depends only on `pydantic`; framework integration is
+opt-in via extras. **Requires Python 3.12+.**
+
+See [`CLAUDE.md`](CLAUDE.md) for a deeper tour of the architecture and layering.
+
+## Project Setup
+
+This project uses [uv](https://docs.astral.sh/uv) for project management. On a
+Mac it can be installed globally with `brew install uv`. `uv` manages its own
+virtual environment, so there is no separate venv step.
+
+The project is a `uv` workspace whose only member is `examples/garden`. Sync
+everything (all extras and all workspace packages) with:
+
+```commandline
+uv sync --all-extras --all-packages
+```
+
+CI installs with `--locked --no-editable` in addition to the flags above.
+
+## Pre-commit
+
+Install the pre-commit hooks so they run on every `git commit`:
+
+```commandline
+uv run pre-commit install
+```
+
+You can also run them explicitly against all files:
+
+```commandline
+uv run pre-commit run --all-files
+```
+
+The hooks cover `ruff` (lint + format), `mypy`, `pyright`, and a set of
+file-hygiene checks. The same hooks run in CI, so it's worth keeping them green
+locally.
+
+If for some reason you need to commit code that does not pass the pre-commit
+checks, this can be done with:
+
+```commandline
+git commit -m "message" --no-verify
+```
+
+## Type Checking
+
+Type checking is enforced by **both** mypy and pyright (pyright runs over `src`
+and `tests`). Both run in pre-commit and must be green in CI on Python
+3.12–3.14.
+
+## Testing
+
+Tests are run with `pytest`. Put test modules and resources in the `tests/`
+directory.
+
+```commandline
+uv run pytest
+```
+
+Run a single test by node id:
+
+```commandline
+uv run pytest tests/test_link.py::test_name
+```
+
+`uv run pytest` always reports coverage on the `gazebo` package
+(`addopts=--cov=gazebo` in `pyproject.toml`) and treats warnings as errors
+(`filterwarnings = ['error']`), so a stray warning fails the suite.
+
+### Tested documentation snippets
+
+All code snippets in the docs are tested. Example code lives in
+`tests/examples/<page>.py` as runnable modules with module-level `assert`s, and
+`tests/test_examples.py` executes each via `runpy`. The docs **include** the
+clean region with `pymdownx.snippets` rather than pasting code, so a broken
+snippet fails CI. See the documentation guidelines in `CLAUDE.md` for the marker
+conventions.
+
+## The Garden Example
+
+`examples/garden` is a complete, standalone OGC-style API that is meant to
+exercise *every* feature — it is the best end-to-end reference and is **load
+bearing**: CI runs its suite separately. It is its own project with its own
+entry point, so run it from that directory:
+
+```commandline
+cd examples/garden
+uv run garden        # serve Gazebo Gardens on http://127.0.0.1:8000
+uv run pytest        # the example's tests
+```
+
+## Documentation
+
+The published docs site is built with zensical/mkdocs (versioned with `mike`).
+
+```commandline
+uv run --group docs zensical serve                     # live preview while writing
+uv run --group docs zensical build --strict --clean    # build (CI gate; fails on issues)
+```
+
+*Reference* docs (signatures, params) are autogenerated from Google-style
+docstrings into `docs/reference.md` via mkdocstrings — keep docstrings as the
+single source of truth. *Explanation/how-to* lives in handwritten Markdown under
+`docs/`, one page per module, mirroring `src/gazebo/`. The nav lives in
+`zensical.toml`; update it when adding a page. See `CLAUDE.md` for the full
+documentation style guide.
+
+## Modifying Dependencies
+
+With `uv`, add a dependency by running `uv add` (add `--dev` for a dev
+dependency). Upgrade dependencies with `uv sync --upgrade`, optionally passing a
+package name to upgrade just one; by default it upgrades everything.
+
+## Landing a Feature
+
+A new feature or behavior change is not complete until all three of these land
+with it:
+
+1. **Tests** in `tests/` covering the new behavior (coverage and
+   warnings-as-errors are enforced; CI runs the suite on Python 3.12–3.14).
+2. **Use in the garden example** — wire the new capability into
+   `examples/garden` and its tests.
+3. **Documentation** — update the relevant page under `docs/` (and the design
+   spec in `working-docs/` if the feature changes a subsystem's rationale or
+   shape).