mirror of
https://github.com/kennethreitz/responder.git
synced 2026-07-21 18:39:29 +00:00
103 lines
3.1 KiB
ReStructuredText
103 lines
3.1 KiB
ReStructuredText
Examples
|
|
========
|
|
|
|
The ``examples/`` directory is the quickest way to see Responder's pieces
|
|
working together. Each file is a small app you can run directly, poke with
|
|
``curl``, and copy from when you need the same pattern in your own service.
|
|
|
|
|
|
Running an Example
|
|
------------------
|
|
|
|
From an installed environment, run an example with the Responder CLI::
|
|
|
|
$ responder run examples/helloworld.py
|
|
|
|
Then call it from another terminal::
|
|
|
|
$ curl http://127.0.0.1:5042/hello
|
|
hello, world!
|
|
|
|
When you are working from a checkout of this repository, prefix the command
|
|
with ``uv run`` so the project environment is used::
|
|
|
|
$ uv run responder run examples/rest_api.py
|
|
|
|
Most examples expose interactive OpenAPI docs at ``/docs``. Open
|
|
``http://127.0.0.1:5042/docs`` in a browser after starting one of the API
|
|
examples.
|
|
|
|
|
|
Where to Start
|
|
--------------
|
|
|
|
``helloworld.py``
|
|
The smallest useful app: one index route, one route parameter, and no
|
|
sessions. Start here if you want to see the request/response shape.
|
|
|
|
``rest_api.py``
|
|
A compact book catalog with Pydantic input models, response models,
|
|
OpenAPI metadata, ``resp.created()``, ``resp.no_content()``, and
|
|
``resp.problem()``.
|
|
|
|
``todo.py``
|
|
The practical all-around example: typed input, filtering, bearer-token
|
|
auth, named auth policies, request IDs, and richer OpenAPI examples.
|
|
|
|
``atelier.py``
|
|
The contract-test fixture. It is intentionally polished because the test
|
|
suite validates its generated OpenAPI document and drives a generated
|
|
client against it.
|
|
|
|
|
|
Focused Patterns
|
|
----------------
|
|
|
|
``user.py``
|
|
A smaller typed CRUD-style API for users.
|
|
|
|
``shortlinks.py``
|
|
Redirects, conflict responses, generated short codes, and click tracking.
|
|
|
|
``webhooks.py``
|
|
Raw-body signature verification before JSON validation, useful for
|
|
Stripe-style webhook receivers.
|
|
|
|
``fortunes.py``
|
|
A local-command wrapper that turns the ``fortune`` CLI into an API and
|
|
reports command failures as problem-details responses. Install the
|
|
``fortune`` command, or set ``FORTUNE_COMMAND`` to a compatible command.
|
|
|
|
``lifespan.py``
|
|
Startup and shutdown work with an async lifespan context manager.
|
|
|
|
``sse_stream.py``
|
|
Server-Sent Events with heartbeat support and a tiny browser page.
|
|
|
|
``websocket_chat.py``
|
|
A minimal WebSocket chat room with a shared in-memory hub.
|
|
|
|
``marimo_mount.py``
|
|
Mounts a marimo notebook under ``/notebooks/`` while keeping normal
|
|
Responder routes and OpenAPI docs on the parent app. Install marimo first::
|
|
|
|
$ uv pip install marimo
|
|
|
|
``tarot.py``
|
|
A larger read/browse/deal API with Pydantic models and repeatable example
|
|
data.
|
|
|
|
|
|
Testing Examples
|
|
----------------
|
|
|
|
Several examples expose a ``create_api()`` function so tests can build a fresh
|
|
app with a fake store or fake external dependency. For example,
|
|
``examples/fortunes.py`` accepts a ``fortune_reader`` callable, which lets the
|
|
test suite verify the API contract without depending on the local
|
|
``fortune`` binary.
|
|
|
|
That shape is a good habit for your own apps too: keep route wiring in
|
|
``create_api()``, pass real dependencies in production, and pass fakes in
|
|
tests.
|