mirror of
https://github.com/kennethreitz/responder.git
synced 2026-06-05 23:00:17 +00:00
kennethreitz
0cbcaf9c4f
## Summary
Comprehensive post-v3.0.0 modernization: new features, bug fixes,
dependency cleanup, docs, and test coverage.
**New features:**
- **HTTP method filtering** — `@api.route("/data", methods=["GET"])`
- **Lifespan context manager** — modern async startup/shutdown
- **`api.exception_handler()`** — custom error handling per exception
type
- **`api.graphql()`** — one-liner GraphQL setup
- **`resp.file()`** — serve files from disk with auto content-type
- **before_request short-circuit** — set status code to skip route
handler
- **`req.path_params`** / **`req.client`** / **`req.is_json`** — new
request properties
- **`uuid`** and **`path`** route convertors
- **PEP 561 `py.typed`** marker
**Bug fixes:**
- Fix multipart parser losing headers
- Fix `url_for()` with typed params (`{id:int}`)
- Fix `resp.body` encoding crash on bytes content
- Fix Python 3.9 type syntax (`from __future__ import annotations`)
- Fix broken session test and no-op file upload test
- Fix helloworld example 404 on root path
**Dependencies:**
- Flattened — `pip install responder` gets everything
- Core: just starlette + uvicorn (down from 10 deps)
**Docs & README:**
- All new features documented in tour
- Modernized README features list
- Deployment guide: Docker, cloud, uvicorn
- Removed Pipenv, extras, stale references throughout
**Tests & quality:**
- 117 tests (up from 92), 91% coverage, 0 warnings
- CaseInsensitiveDict, GraphQL edge cases, staticfiles tests
- Ruff clean, all `tmpdir` → `tmp_path`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
175 lines
5.9 KiB
ReStructuredText
175 lines
5.9 KiB
ReStructuredText
Responder CLI
|
|
=============
|
|
|
|
Responder installs a command line program ``responder``. Use it to launch
|
|
a Responder application from a file or module, either located on a local
|
|
or remote filesystem, or object store.
|
|
|
|
Launch Module Entrypoint
|
|
------------------------
|
|
|
|
For loading a Responder application from a Python module, you will refer to
|
|
its ``API()`` instance using a `Python entry point object reference`_ that
|
|
points to a Python object. It is either in the form ``importable.module``,
|
|
or ``importable.module:object.attr``.
|
|
|
|
A basic invocation command to launch a Responder application:
|
|
|
|
.. code-block:: shell
|
|
|
|
responder run acme.app
|
|
|
|
The command above assumes a Python package ``acme`` including an ``app``
|
|
module ``acme/app.py`` that includes an attribute ``api`` that refers
|
|
to a ``responder.API`` instance, reflecting the typical layout of
|
|
a standard Responder application.
|
|
|
|
Loading a Responder application using an entrypoint specification will
|
|
inherit the capacities of `Python's import system`_, as implemented by
|
|
`importlib`_.
|
|
|
|
Launch Local File
|
|
-----------------
|
|
|
|
Acquire a minimal example single-file application, ``helloworld.py`` [1]_,
|
|
to your local filesystem, giving you the chance to edit it, and launch the
|
|
Responder HTTP service.
|
|
|
|
.. code-block:: shell
|
|
|
|
wget https://github.com/kennethreitz/responder/raw/refs/heads/main/examples/helloworld.py
|
|
responder run helloworld.py
|
|
|
|
.. note::
|
|
|
|
To validate the example application, invoke a HTTP request, for example using
|
|
`curl`_, `HTTPie`_, or your favourite browser at hand.
|
|
|
|
.. code-block:: shell
|
|
|
|
http http://127.0.0.1:5042/Hello
|
|
|
|
The response is no surprise.
|
|
|
|
::
|
|
|
|
HTTP/1.1 200 OK
|
|
content-length: 13
|
|
content-type: text/plain
|
|
date: Sat, 26 Oct 2024 13:16:55 GMT
|
|
encoding: utf-8
|
|
server: uvicorn
|
|
|
|
Hello, world!
|
|
|
|
.. [1] The Responder application `helloworld.py`_ implements a basic echo handler.
|
|
|
|
Launch Remote File
|
|
------------------
|
|
|
|
You can also launch a single-file application where its Python file is stored
|
|
on a remote location.
|
|
|
|
Responder supports all filesystem adapters compatible with `fsspec`_, and
|
|
installs the adapters for Azure Blob Storage (az), Google Cloud Storage (gs),
|
|
GitHub, HTTP, and AWS S3 by default.
|
|
|
|
.. code-block:: shell
|
|
|
|
# Works 1:1.
|
|
responder run https://github.com/kennethreitz/responder/raw/refs/heads/main/examples/helloworld.py
|
|
responder run github://kennethreitz:responder@/examples/helloworld.py
|
|
|
|
If you need access other kinds of remote targets, see the `list of
|
|
fsspec-supported filesystems and protocols`_. The next section enumerates
|
|
a few synthetic examples. The corresponding storage buckets do not even
|
|
exist, so don't expect those commands to work.
|
|
|
|
.. code-block:: shell
|
|
|
|
# Azure Blob Storage, Google Cloud Storage, and AWS S3.
|
|
responder run az://kennethreitz-assets/responder/examples/helloworld.py
|
|
responder run gs://kennethreitz-assets/responder/examples/helloworld.py
|
|
responder run s3://kennethreitz-assets/responder/examples/helloworld.py
|
|
|
|
# Hadoop Distributed File System (hdfs), SSH File Transfer Protocol (sftp),
|
|
# Common Internet File System (smb), Web-based Distributed Authoring and
|
|
# Versioning (webdav).
|
|
responder run hdfs://kennethreitz-assets/responder/examples/helloworld.py
|
|
responder run sftp://user@host/kennethreitz/responder/examples/helloworld.py
|
|
responder run smb://workgroup;user:password@server:port/responder/examples/helloworld.py
|
|
responder run webdav+https://user:password@server:port/responder/examples/helloworld.py
|
|
|
|
.. tip::
|
|
|
|
In order to install support for all filesystem types supported by fsspec, run:
|
|
|
|
.. code-block:: shell
|
|
|
|
uv pip install 'fsspec[full]'
|
|
|
|
When using ``uv``, this concludes within an acceptable time of approx.
|
|
25 seconds. If you need to be more selectively instead of using ``full``,
|
|
choose from one or multiple of the available `fsspec extras`_, which are:
|
|
|
|
abfs, arrow, dask, dropbox, fuse, gcs, git, github, hdfs, http, oci, s3,
|
|
sftp, smb, ssh.
|
|
|
|
Launch with Non-Standard Instance Name
|
|
--------------------------------------
|
|
|
|
By default, Responder will acquire an ``responder.API`` instance using the
|
|
symbol name ``api`` from the specified Python module.
|
|
|
|
If your main application file uses a different name than ``api``, please
|
|
append the designated symbol name to the launch target address.
|
|
|
|
It works like this for module entrypoints and local files:
|
|
|
|
.. code-block:: shell
|
|
|
|
responder run acme.app:service
|
|
responder run /path/to/acme/app.py:service
|
|
|
|
It works like this for URLs:
|
|
|
|
.. code-block:: shell
|
|
|
|
responder run http://app.server.local/path/to/acme/app.py#service
|
|
|
|
Within your ``app.py``, the instance would have been defined to use
|
|
the ``service`` symbol name instead of ``api``, like this:
|
|
|
|
.. code-block:: python
|
|
|
|
service = responder.API()
|
|
|
|
Build JavaScript Application
|
|
----------------------------
|
|
|
|
The ``build`` subcommand invokes ``npm run build``, optionally accepting
|
|
a target directory. By default, it uses the current working directory,
|
|
where it expects a regular NPM ``package.json`` file.
|
|
|
|
.. code-block:: shell
|
|
|
|
responder build
|
|
|
|
When specifying a target directory, Responder will change to that
|
|
directory beforehand.
|
|
|
|
.. code-block:: shell
|
|
|
|
responder build /path/to/project
|
|
|
|
|
|
.. _curl: https://curl.se/
|
|
.. _fsspec: https://filesystem-spec.readthedocs.io/en/latest/
|
|
.. _fsspec extras: https://github.com/fsspec/filesystem_spec/blob/2024.12.0/pyproject.toml#L27-L69
|
|
.. _helloworld.py: https://github.com/kennethreitz/responder/blob/main/examples/helloworld.py
|
|
.. _HTTPie: https://httpie.io/docs/cli
|
|
.. _importlib: https://docs.python.org/3/library/importlib.html
|
|
.. _list of fsspec-supported filesystems and protocols: https://github.com/fsspec/universal_pathlib#currently-supported-filesystems-and-protocols
|
|
.. _Python entry point object reference: https://packaging.python.org/en/latest/specifications/entry-points/
|
|
.. _Python's import system: https://docs.python.org/3/reference/import.html
|