mirror of
https://github.com/kennethreitz/responder.git
synced 2026-06-05 23:00:17 +00:00
Andreas Motl
176 lines
6.4 KiB
ReStructuredText
176 lines
6.4 KiB
ReStructuredText
.. responder documentation master file, created by
|
|
sphinx-quickstart on Thu Oct 11 12:58:34 2018.
|
|
You can adapt this file completely to your liking, but it should at least
|
|
contain the root `toctree` directive.
|
|
|
|
A familiar HTTP Service Framework
|
|
=================================
|
|
|
|
|ci-tests| |version| |license| |python-versions| |downloads| |contributors| |say-thanks|
|
|
|
|
.. |ci-tests| image:: https://github.com/kennethreitz/responder/actions/workflows/test.yaml/badge.svg
|
|
:target: https://github.com/kennethreitz/responder/actions/workflows/test.yaml
|
|
.. |ci-docs| image:: https://github.com/kennethreitz/responder/actions/workflows/docs.yaml/badge.svg
|
|
:target: https://github.com/kennethreitz/responder/actions/workflows/docs.yaml
|
|
.. |version| image:: https://img.shields.io/pypi/v/responder.svg
|
|
:target: https://pypi.org/project/responder/
|
|
.. |license| image:: https://img.shields.io/pypi/l/responder.svg
|
|
:target: https://pypi.org/project/responder/
|
|
.. |python-versions| image:: https://img.shields.io/pypi/pyversions/responder.svg
|
|
:target: https://pypi.org/project/responder/
|
|
.. |downloads| image:: https://static.pepy.tech/badge/responder/month
|
|
:target: https://www.pepy.tech/projects/responder
|
|
.. |contributors| image:: https://img.shields.io/github/contributors/kennethreitz/responder.svg
|
|
:target: https://github.com/kennethreitz/responder/graphs/contributors
|
|
.. |say-thanks| image:: https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg
|
|
:target: https://saythanks.io/to/kennethreitz
|
|
|
|
.. code:: python
|
|
|
|
import responder
|
|
|
|
api = responder.API()
|
|
|
|
@api.route("/{greeting}")
|
|
async def greet_world(req, resp, *, greeting):
|
|
resp.text = f"{greeting}, world!"
|
|
|
|
if __name__ == '__main__':
|
|
api.run()
|
|
|
|
Powered by `Starlette`_. That ``async`` declaration is optional.
|
|
|
|
The little program demonstrates an `ASGI`_ application using `Responder`_,
|
|
including production-ready components like the `uvicorn`_ webserver, based
|
|
on `uvloop`_, the static files server `ServeStatic`_, and the `Jinja`_
|
|
templating library pre-installed.
|
|
|
|
Features
|
|
--------
|
|
|
|
- A pleasant API, with a single import statement.
|
|
- Class-based views without inheritance.
|
|
- `ASGI`_, the future of Python web services.
|
|
- Asynchronous Python frameworks and applications.
|
|
- Automatic gzip compression.
|
|
- WebSocket support!
|
|
- The ability to mount any ASGI / WSGI app at a subroute.
|
|
- `f-string syntax`_ route declaration.
|
|
- Mutable response object, passed into each view. No need to return anything.
|
|
- Background tasks, spawned off in a ``ThreadPoolExecutor``.
|
|
- GraphQL (with *GraphiQL*) support!
|
|
- OpenAPI schema generation, with interactive documentation!
|
|
- Single-page webapp support!
|
|
|
|
Testimonials
|
|
------------
|
|
|
|
“Pleasantly very taken with python-responder.
|
|
`@kennethreitz`_ at his absolute best.”
|
|
|
|
|
|
|
|
|
— Rudraksh M.K.
|
|
|
|
..
|
|
|
|
"ASGI is going to enable all sorts of new high-performance web services. It's awesome to see Responder starting to take advantage of that."
|
|
|
|
|
|
|
|
|
— Tom Christie, author of `Django REST Framework`_
|
|
|
|
..
|
|
|
|
“I love that you are exploring new patterns. Go go go!”
|
|
|
|
|
|
|
|
|
— Danny Greenfield, author of `Two Scoops of Django`_
|
|
|
|
|
|
User Guides
|
|
-----------
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
quickstart
|
|
tour
|
|
deployment
|
|
testing
|
|
api
|
|
cli
|
|
|
|
|
|
Installing Responder
|
|
--------------------
|
|
|
|
Use ``uv`` for fast installation.
|
|
|
|
.. code-block:: shell
|
|
|
|
uv pip install --upgrade 'responder'
|
|
|
|
Or use standard pip where ``uv`` is not available.
|
|
|
|
.. code-block:: shell
|
|
|
|
pip install --upgrade 'responder'
|
|
|
|
Responder supports **Python 3.6+**. If you are looking at installing Responder
|
|
for hacking on it, please refer to the :ref:`sandbox` documentation.
|
|
|
|
.. toctree::
|
|
:hidden:
|
|
|
|
sandbox
|
|
|
|
|
|
|
|
The Basic Idea
|
|
--------------
|
|
|
|
The primary concept here is to bring the niceties that are brought forth from both Flask and Falcon and unify them into a single framework, along with some new ideas I have. I also wanted to take some of the API primitives that are instilled in the Requests library and put them into a web framework. So, you'll find a lot of parallels here with Requests.
|
|
|
|
- Setting ``resp.content`` sends back bytes.
|
|
- Setting ``resp.text`` sends back unicode, while setting ``resp.html`` sends back HTML.
|
|
- Setting ``resp.media`` sends back JSON/YAML (``.text``/``.html``/``.content`` override this).
|
|
- Case-insensitive ``req.headers`` dict (from Requests directly).
|
|
- ``resp.status_code``, ``req.method``, ``req.url``, and other familiar friends.
|
|
|
|
Ideas
|
|
-----
|
|
|
|
- Flask-style route expression, with new capabilities -- all while using Python 3.6+'s new f-string syntax.
|
|
- I love Falcon's "every request and response is passed into each view and mutated" methodology, especially ``response.media``, and have used it here. In addition to supporting JSON, I have decided to support YAML as well, as Kubernetes is slowly taking over the world, and it uses YAML for all the things. Content-negotiation and all that.
|
|
- **A built in testing client that uses the actual Requests you know and love**.
|
|
- The ability to mount other WSGI apps easily.
|
|
- Automatic gzipped-responses.
|
|
- In addition to Falcon's ``on_get``, ``on_post``, etc methods, Responder features an ``on_request`` method, which gets called on every type of request, much like Requests.
|
|
- A production static files server is built-in.
|
|
- `uvicorn`_ is built-in as a production web server. I would have chosen Gunicorn, but it doesn't run on Windows. Plus, uvicorn serves well to protect against `Slowloris`_ attacks, making Nginx unnecessary in production.
|
|
- GraphQL support, via Graphene. The goal here is to have any GraphQL query exposable at any route, magically.
|
|
|
|
|
|
Indices and tables
|
|
==================
|
|
|
|
* :ref:`genindex`
|
|
* :ref:`modindex`
|
|
* :ref:`search`
|
|
|
|
|
|
.. _@kennethreitz: https://x.com/kennethreitz
|
|
.. _ASGI: https://en.wikipedia.org/wiki/Asynchronous_Server_Gateway_Interface
|
|
.. _Django REST Framework: https://www.django-rest-framework.org/
|
|
.. _f-string syntax: https://docs.python.org/3/whatsnew/3.6.html#pep-498-formatted-string-literals
|
|
.. _Jinja: https://jinja.palletsprojects.com/en/stable/
|
|
.. _ServeStatic: https://archmonger.github.io/ServeStatic/latest/
|
|
.. _Slowloris: https://en.wikipedia.org/wiki/Slowloris_(computer_security)
|
|
.. _Starlette: https://www.starlette.io/
|
|
.. _Responder: https://responder.kennethreitz.org/
|
|
.. _Two Scoops of Django: https://www.feldroy.com/two-scoops-press#two-scoops-of-django
|
|
.. _uvicorn: https://www.uvicorn.org/
|
|
.. _uvloop: https://uvloop.readthedocs.io/
|