Bump version to 3.3.0

New documentation pages:
- Authentication: API keys, JWT tokens, session auth, custom exceptions
- WebSocket Tutorial: echo server, chat room, HTML client, data formats
- Writing Middleware: hooks vs middleware, Starlette integration, ordering
- Configuration: env vars, .env files, secret keys, debug mode, production setup

Also:
- Complete working example at end of quickstart with cross-references
- Three new example files: rest_api.py, websocket_chat.py, sse_stream.py
- Changelog updated for v3.2.0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+github: kennethreitz
+thanks_dev: kennethreitz
+custom: https://cash.app/$KennethReitz

.github/dependabot.yml

@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

.github/workflows/docs.yaml

@@ -0,0 +1,53 @@
+name: "Documentation"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request: ~
+  workflow_dispatch:
+
+# Cancel redundant in-progress jobs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+
+  documentation:
+    name: "Documentation"
+    runs-on: ubuntu-latest
+    env:
+      UV_SYSTEM_PYTHON: true
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "latest"
+        enable-cache: true
+        cache-dependency-glob: |
+          pyproject.toml
+
+    - name: Install package and documentation dependencies
+      run: uv pip install '.[docs]'
+
+    - name: Build static HTML documentation
+      run: sphinx-build -W --keep-going docs/source docs/build
+
+    - name: Deploy to GitHub Pages
+      if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/build
+        cname: responder.kennethreitz.org

.github/workflows/test.yaml

@@ -0,0 +1,56 @@
+name: "Tests"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request: ~
+  workflow_dispatch:
+
+# Cancel redundant in-progress jobs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+
+  test:
+    name: "Python ${{ matrix.python-version }}"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [
+          "3.9",
+          "3.10",
+          "3.11",
+          "3.12",
+          "3.13",
+        ]
+    env:
+      UV_SYSTEM_PYTHON: true
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 22
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "latest"
+        enable-cache: true
+        cache-suffix: ${{ matrix.python-version }}
+        cache-dependency-glob: |
+          pyproject.toml
+
+    - name: Install package
+      run: uv pip install '.[develop,test]'
+
+    - name: Run tests
+      run: pytest

.gitignore

@@ -1,5 +1,19 @@
+.venv*
 .vscode/
+.cache
+.idea
+.python-version
+.coverage
+.pytest_cache
+.DS_Store
+coverage.xml
+.coverage*
+
+__pycache__
+tests/__pycache__
+
 build
 responder.egg-info/
 dist/
 app.py
+app2.py

.readthedocs.yml

@@ -0,0 +1,33 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+
+# Details
+# - https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+# Required
+version: 2
+
+build:
+  os: "ubuntu-24.04"
+  tools:
+    python: "3.12"
+
+python:
+  install:
+      - method: pip
+        path: .
+        extra_requirements:
+          - docs
+
+sphinx:
+  configuration: docs/source/conf.py
+
+  # Use standard HTML builder.
+  builder: html
+
+  # Fail on all warnings to avoid broken references.
+  fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF
+#formats:
+#  - pdf

.travis.yml

@@ -1,12 +0,0 @@
-language: python
-python:
-  - "3.6"
-
-# command to install dependencies
-install:
-  - "pip install pipenv --upgrade-strategy=only-if-needed"
-  - "pipenv install --dev"
-
-# command to run the dependencies
-script:
-  - "pytest"

CHANGELOG.md

@@ -0,0 +1,460 @@
+# 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.0.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [v3.2.0] - 2026-03-22
+
+### Added
+
+- Pydantic auto-validation: `request_model` validates input, returns 422 on failure
+- Pydantic auto-serialization: `response_model` strips extra fields from responses
+- Server-Sent Events: `@resp.sse` for real-time streaming
+- `resp.stream_file()` for streaming large files without loading into memory
+- `@api.after_request()` hooks
+- `api.group("/prefix")` for route groups and API versioning
+- `api.graphql("/path", schema=schema)` one-liner GraphQL setup
+- `api = responder.API(request_id=True)` for automatic request ID generation
+- Built-in rate limiter: `RateLimiter(requests=100, period=60).install(api)`
+- MessagePack format support: `await req.media("msgpack")`
+- `req.is_json`, `req.path_params`, `req.client` properties
+- `api.exception_handler()` decorator for custom error handling
+- Lifespan context manager support
+- `uuid` and `path` route convertors
+- PEP 561 `py.typed` marker
+- Pydantic support for OpenAPI schema generation
+
+### Changed
+
+- Dependencies flattened: `pip install responder` gets everything
+- Core deps reduced to starlette + uvicorn
+- TestClient lazy-loaded (no httpx import in production)
+- Before-request hooks can short-circuit by setting status code
+- Removed poethepoet task runner
+
+### Fixed
+
+- Multipart parser losing headers when parts have multiple headers
+- `url_for()` with typed route params (`{id:int}`)
+- `resp.body` encoding crash on bytes content
+- GraphQL text query missing `await`
+- Streaming responses not sending Content-Type headers
+- Python 3.9 compatibility for union type syntax
+
+## [v3.0.0] - 2026-03-22
+
+### Added
+
+- Platform: Added support for Python 3.10 - Python 3.13
+- CLI: `responder run` now also accepts a filesystem path on its `<target>`
+  argument, enabling usage on single-file applications.
+- CLI: `responder run` now also accepts URLs.
+
+### Changed
+
+- Platform: Minimum Python version is now 3.9 (dropped 3.6, 3.7, 3.8)
+- Dependencies: Dramatically reduced core dependency count (10 → 5)
+  - Removed `requests`, `requests-toolbelt`, `rfc3986`, `whitenoise`
+  - Moved `apispec` and `marshmallow` to `openapi` optional extra
+  - Replaced `rfc3986` with stdlib `urllib.parse`
+  - Replaced `requests-toolbelt` multipart decoder with `python-multipart`
+  - Replaced deprecated `starlette.middleware.wsgi` with `a2wsgi`
+  - Switched from WhiteNoise to ServeStatic
+- Dependencies: Pinned `starlette[full]>=0.40` (was unpinned)
+- GraphQL: Upgraded to `graphene>=3` and `graphql-core>=3.1`
+  (from `graphene<3` and `graphql-server-core`, which is unmaintained)
+- GraphQL: Updated GraphiQL UI from 0.12.0 (2018) to 3.0.6 with React 18
+- Extensions: All of CLI-, GraphQL-, and OpenAPI-Support modules are
+  extensions now, found within the `responder.ext` module namespace.
+- Packaging: Migrated from `setup.py` to declarative `pyproject.toml`
+
+### Removed
+
+- Platform: Removed support for EOL Python 3.6, 3.7, 3.8
+- Status codes: Removed deprecated `resume_incomplete` and `resume`
+  aliases for HTTP 308 (marked for removal in 3.0)
+- CLI: `responder run --build` ceased to exist
+
+### Fixed
+
+- Routing: Fixed dispatching `static_route=None` on Windows
+- uvicorn: `--debug` now maps to uvicorn's `log_level = "debug"`
+- Tests: Fixed deprecated httpx TestClient usage
+
+## [v2.0.5] - 2019-12-15
+
+### Added
+
+- Update requirements to support python 3.8
+
+## [v2.0.4] - 2019-11-19
+
+### Fixed
+
+- Fix static app resolving
+
+## [v2.0.3] - 2019-09-20
+
+### Fixed
+
+- Fix template conflicts
+
+## [v2.0.2] - 2019-09-20
+
+### Fixed
+
+- Fix template conflicts
+
+## [v2.0.1] - 2019-09-20
+
+### Fixed
+
+- Fix template import
+
+## [v2.0.0] - 2019-09-19
+
+### Changed
+
+- Refactor Router and Schema
+
+## [v1.3.2] - 2019-08-15
+
+### Added
+
+- ASGI 3 support
+- CI tests for python 3.8-dev
+- Now requests have `state` a mapping object
+
+### Deprecated
+
+- ASGI 2
+
+## [v1.3.1] - 2019-04-28
+
+### Added
+
+- Route params Converters
+- Add search for documentation pages
+
+### Changed
+
+- Bump dependencies
+
+## [v1.3.0] - 2019-02-22
+
+### Fixed
+
+- Versioning issue
+- Multiple cookies.
+- Whitenoise returns not found.
+- Other bugfixes.
+
+### Added
+
+- Stream support via `resp.stream`.
+- Cookie directives via `resp.set_cookie`.
+- Add `resp.html` to send HTML.
+- Other improvements.
+
+## [v1.1.3] - 2019-01-12
+
+### Changed
+
+- Refactor `_route_for`
+
+### Fixed
+
+- Resolve startup/shutdwown events
+
+## [v1.2.0] - 2018-12-29
+
+### Added
+
+- Documentations
+
+### Changed
+
+- Use Starlette's LifeSpan middleware
+- Update denpendencies
+
+### Fixed
+
+- Fix route.is_class_based
+- Fix test_500
+- Typos
+
+## [v1.1.2] - 2018-11-11
+
+### Fixed
+
+- Minor fixes for Open API
+- Typos
+
+## [v1.1.1] - 2018-10-29
+
+### Changed
+
+- Run sync views in a threadpoolexecutor.
+
+## [v1.1.0] - 2018-10-27
+
+### Added
+
+- Support for `before_request`.
+
+## [v1.0.5]- 2018-10-27
+
+### Fixed
+
+- Fix sessions.
+
+## [v1.0.4] - 2018-10-27
+
+### Fixed
+
+- Potential bufix for cookies.
+
+## [v1.0.3] - 2018-10-27
+
+### Fixed
+
+- Bugfix for redirects.
+
+## [v1.0.2] - 2018-10-27
+
+### Changed
+
+- Improvement for static file hosting.
+
+## [v1.0.1] - 2018-10-26
+
+### Changed
+
+- Improve cors configuration settings.
+
+## [v1.0.0] - 2018-10-26
+
+### Changed
+
+- Move GraphQL support into a built-in plugin.
+
+## [v0.3.3] - 2018-10-25
+
+### Added
+
+- CORS support
+
+### Changed
+
+- Improved exceptions.
+
+## [v0.3.2] - 2018-10-25
+
+### Changed
+
+- Subtle improvements.
+
+## [v0.3.1] - 2018-10-24
+
+### Fixed
+
+- Packaging fix.
+
+## [v0.3.0] - 2018-10-24
+
+### Changed
+
+- Interactive Documentation endpoint.
+- Minor improvements.
+
+## [v0.2.3] - 2018-10-24
+
+### Changed
+
+- Overall improvements.
+
+## [v0.2.2] - 2018-10-23
+
+### Added
+
+- Show traceback info when background tasks raise exceptions.
+
+## [v0.2.1] - 2018-10-23
+
+### Added
+
+- api.requests.
+
+## [v0.2.0] - 2018-10-22
+
+### Added
+
+- WebSocket support.
+
+## [v0.1.6] - 2018-10-20
+
+### Added
+
+- 500 support.
+
+## [v0.1.5] - 2018-10-20
+
+### Added
+
+- File upload support
+
+### Changed
+
+- Improvements to sequential media reading.
+
+## [v0.1.4] - 2018-10-19
+
+### Fixed
+
+- Stability.
+
+## [v0.1.3] - 2018-10-18
+
+### Added
+
+- Sessions support.
+
+## [v0.1.2] - 2018-10-18
+
+### Added
+
+- Cookies support.
+
+## [v0.1.1] - 2018-10-17
+
+### Changed
+
+- Default routes.
+
+## [v0.1.0] - 2018-10-17
+
+### Added
+
+- Prototype of static application support.
+
+## [v0.0.10] - 2018-10-17
+
+### Fixed
+
+- Bugfix for async class-based views.
+
+## [v0.0.9] - 2018-10-17
+
+### Fixed
+
+- Bugfix for async class-based views.
+
+## [v0.0.8] - 2018-10-17
+
+### Added
+
+- GraphiQL Support.
+
+### Changed
+
+- Improvement to route selection.
+
+## [v0.0.7] - 2018-10-16
+
+### Changed
+
+- Immutable Request object.
+
+## [v0.0.6] - 2018-10-16
+
+### Added
+
+- Ability to mount WSGI apps.
+- Supply content-type when serving up the schema.
+
+## [v0.0.5] - 2018-10-15
+
+### Added
+
+- OpenAPI Schema support.
+- Safe load/dump yaml.
+
+## [v0.0.4] - 2018-10-15
+
+### Added
+
+- Asynchronous support for data uploads.
+
+### Fixed
+
+- Bug fixes.
+
+## [v0.0.3] - 2018-10-13
+
+### Fixed
+
+- Bug fixes.
+
+## [v0.0.2] - 2018-10-13
+
+### Changed
+
+- Switch to ASGI/Starlette.
+
+## [v0.0.1] - 2018-10-12
+
+### Added
+
+- Conception!
+
+[unreleased]: https://github.com/kennethreitz/responder/compare/v3.0.0..HEAD
+[v3.0.0]: https://github.com/kennethreitz/responder/compare/v2.0.5..v3.0.0
+[v2.0.5]: https://github.com/kennethreitz/responder/compare/v2.0.4..v2.0.5
+[v2.0.4]: https://github.com/kennethreitz/responder/compare/v2.0.3..v2.0.4
+[v2.0.3]: https://github.com/kennethreitz/responder/compare/v2.0.2..v2.0.3
+[v2.0.2]: https://github.com/kennethreitz/responder/compare/v2.0.1..v2.0.2
+[v2.0.1]: https://github.com/kennethreitz/responder/compare/v2.0.0..v2.0.1
+[v2.0.0]: https://github.com/kennethreitz/responder/compare/v1.3.2..v2.0.0
+[v1.3.2]: https://github.com/kennethreitz/responder/compare/v1.3.1..v1.3.2
+[v1.3.1]: https://github.com/kennethreitz/responder/compare/v1.3.0..v1.3.1
+[v1.3.0]: https://github.com/kennethreitz/responder/compare/v1.2.0..v1.3.0
+[v1.2.0]: https://github.com/kennethreitz/responder/compare/v1.1.3..v1.2.0
+[v1.1.3]: https://github.com/kennethreitz/responder/compare/v1.1.2..v1.1.3
+[v1.1.2]: https://github.com/kennethreitz/responder/compare/v1.1.1..v1.1.2
+[v1.1.1]: https://github.com/kennethreitz/responder/compare/v1.1.0..v1.1.1
+[v1.1.0]: https://github.com/kennethreitz/responder/compare/v1.0.5..v1.1.0
+[v1.0.5]: https://github.com/kennethreitz/responder/compare/v1.0.4..v1.0.5
+[v1.0.4]: https://github.com/kennethreitz/responder/compare/v1.0.3..v1.0.4
+[v1.0.3]: https://github.com/kennethreitz/responder/compare/v1.0.2..v1.0.3
+[v1.0.2]: https://github.com/kennethreitz/responder/compare/v1.0.1..v1.0.2
+[v1.0.1]: https://github.com/kennethreitz/responder/compare/v1.0.0..v1.0.1
+[v1.0.0]: https://github.com/kennethreitz/responder/compare/v0.3.3..v1.0.0
+[v0.3.3]: https://github.com/kennethreitz/responder/compare/v0.3.2..v0.3.3
+[v0.3.2]: https://github.com/kennethreitz/responder/compare/v0.3.1..v0.3.2
+[v0.3.1]: https://github.com/kennethreitz/responder/compare/v0.3.0..v0.3.1
+[v0.3.0]: https://github.com/kennethreitz/responder/compare/v0.2.3..v0.3.0
+[v0.2.3]: https://github.com/kennethreitz/responder/compare/v0.2.2..v0.2.3
+[v0.2.2]: https://github.com/kennethreitz/responder/compare/v0.2.1..v0.2.2
+[v0.2.1]: https://github.com/kennethreitz/responder/compare/v0.2.0..v0.2.1
+[v0.2.0]: https://github.com/kennethreitz/responder/compare/v0.1.6..v0.2.0
+[v0.1.6]: https://github.com/kennethreitz/responder/compare/v0.1.5..v0.1.6
+[v0.1.5]: https://github.com/kennethreitz/responder/compare/v0.1.4..v0.1.5
+[v0.1.4]: https://github.com/kennethreitz/responder/compare/v0.1.3..v0.1.4
+[v0.1.3]: https://github.com/kennethreitz/responder/compare/v0.1.2..v0.1.3
+[v0.1.2]: https://github.com/kennethreitz/responder/compare/v0.1.1..v0.1.2
+[v0.1.1]: https://github.com/kennethreitz/responder/compare/v0.1.0..v0.1.1
+[v0.1.0]: https://github.com/kennethreitz/responder/compare/v0.0.10..v0.1.0
+[v0.0.10]: https://github.com/kennethreitz/responder/compare/v0.0.9..v0.0.10
+[v0.0.9]: https://github.com/kennethreitz/responder/compare/v0.0.8..v0.0.9
+[v0.0.8]: https://github.com/kennethreitz/responder/compare/v0.0.7..v0.0.8
+[v0.0.7]: https://github.com/kennethreitz/responder/compare/v0.0.6..v0.0.7
+[v0.0.6]: https://github.com/kennethreitz/responder/compare/v0.0.5..v0.0.6
+[v0.0.5]: https://github.com/kennethreitz/responder/compare/v0.0.4..v0.0.5
+[v0.0.4]: https://github.com/kennethreitz/responder/compare/v0.0.3..v0.0.4
+[v0.0.3]: https://github.com/kennethreitz/responder/compare/v0.0.2..v0.0.3
+[v0.0.2]: https://github.com/kennethreitz/responder/compare/v0.0.1..v0.0.2
+[v0.0.1]: https://github.com/kennethreitz/responder/compare/v0.0.0..v0.0.1

CONTRIBUTORS.md

@@ -1,4 +0,0 @@
-- Kenneth Reitz (primary)
-- Tom Christie
-- Bruno Oliveira
-- serhii73

LICENSE

@@ -1,13 +1,178 @@
-Copyright 2018 Kenneth Reitz
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
 
-    http://www.apache.org/licenses/LICENSE-2.0
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

Pipfile

@@ -1,26 +0,0 @@
-[[source]]
-url = "https://pypi.org/simple"
-verify_ssl = true
-name = "pypi"
-
-[packages]
-responder = {editable = true, path = "."}
-uvicorn = "*"
-starlette = "*"
-aiofiles = "*"
-
-[dev-packages]
-pytest = "*"
-"flake8" = "*"
-black = "*"
-twine = "*"
-flask = "*"
-sphinx = "*"
-locust = "*"
-locustio = "*"
-
-[requires]
-python_version = "3.7"
-
-[pipenv]
-allow_prereleases = true

Pipfile.lock

@@ -1,735 +0,0 @@
-{
-    "_meta": {
-        "hash": {
-            "sha256": "620c4b82d439a27e1afdbe54a6a77130cc52060846d4a6e322a5b064ff68e8fd"
-        },
-        "pipfile-spec": 6,
-        "requires": {
-            "python_version": "3.7"
-        },
-        "sources": [
-            {
-                "name": "pypi",
-                "url": "https://pypi.org/simple",
-                "verify_ssl": true
-            }
-        ]
-    },
-    "default": {
-        "aiofiles": {
-            "hashes": [
-                "sha256:021ea0ba314a86027c166ecc4b4c07f2d40fc0f4b3a950d1868a0f2571c2bbee",
-                "sha256:1e644c2573f953664368de28d2aa4c89dfd64550429d0c27c4680ccd3aa4985d"
-            ],
-            "index": "pypi",
-            "version": "==0.4.0"
-        },
-        "aniso8601": {
-            "hashes": [
-                "sha256:7849749cf00ae0680ad2bdfe4419c7a662bef19c03691a19e008c8b9a5267802",
-                "sha256:94f90871fcd314a458a3d4eca1c84448efbd200e86f55fe4c733c7a40149ef50"
-            ],
-            "version": "==3.0.2"
-        },
-        "certifi": {
-            "hashes": [
-                "sha256:376690d6f16d32f9d1fe8932551d80b23e9d393a8578c5633a2ed39a64861638",
-                "sha256:456048c7e371c089d0a77a5212fb37a2c2dce1e24146e3b7e0261736aaeaa22a"
-            ],
-            "version": "==2018.8.24"
-        },
-        "chardet": {
-            "hashes": [
-                "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae",
-                "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691"
-            ],
-            "version": "==3.0.4"
-        },
-        "click": {
-            "hashes": [
-                "sha256:2335065e6395b9e67ca716de5f7526736bfa6ceead690adf616d925bdc622b13",
-                "sha256:5b94b49521f6456670fdb30cd82a4eca9412788a93fa6dd6df72c94d5a8ff2d7"
-            ],
-            "version": "==7.0"
-        },
-        "graphene": {
-            "hashes": [
-                "sha256:b8ec446d17fa68721636eaad3d6adc1a378cb6323e219814c8f98c9928fc9642",
-                "sha256:faa26573b598b22ffd274e2fd7a4c52efa405dcca96e01a62239482246248aa3"
-            ],
-            "version": "==2.1.3"
-        },
-        "graphql-core": {
-            "hashes": [
-                "sha256:889e869be5574d02af77baf1f30b5db9ca2959f1c9f5be7b2863ead5a3ec6181",
-                "sha256:9462e22e32c7f03b667373ec0a84d95fba10e8ce2ead08f29fbddc63b671b0c1"
-            ],
-            "version": "==2.1"
-        },
-        "graphql-relay": {
-            "hashes": [
-                "sha256:2716b7245d97091af21abf096fabafac576905096d21ba7118fba722596f65db"
-            ],
-            "version": "==0.4.5"
-        },
-        "graphql-server-core": {
-            "hashes": [
-                "sha256:e5f82add4b3d5580aa1f1e7d9f00e944ad3abe1b65eb337e611d6a77cc20f231"
-            ],
-            "version": "==1.1.1"
-        },
-        "h11": {
-            "hashes": [
-                "sha256:acca6a44cb52a32ab442b1779adf0875c443c689e9e028f8d831a3769f9c5208",
-                "sha256:f2b1ca39bfed357d1f19ac732913d5f9faa54a5062eca7d2ec3a916cfb7ae4c7"
-            ],
-            "version": "==0.8.1"
-        },
-        "idna": {
-            "hashes": [
-                "sha256:156a6814fb5ac1fc6850fb002e0852d56c0c8d2531923a51032d1b70760e186e",
-                "sha256:684a38a6f903c1d71d6d5fac066b58d7768af4de2b832e426ec79c30daa94a16"
-            ],
-            "version": "==2.7"
-        },
-        "jinja2": {
-            "hashes": [
-                "sha256:74c935a1b8bb9a3947c50a54766a969d4846290e1e788ea44c1392163723c3bd",
-                "sha256:f84be1bb0040caca4cea721fcbbbbd61f9be9464ca236387158b0feea01914a4"
-            ],
-            "version": "==2.10"
-        },
-        "markupsafe": {
-            "hashes": [
-                "sha256:a6be69091dac236ea9c6bc7d012beab42010fa914c459791d627dad4910eb665"
-            ],
-            "version": "==1.0"
-        },
-        "parse": {
-            "hashes": [
-                "sha256:9dd6048ea212cd032a342f9f6aa2b7bc222f7407c7e37bdc2777fecd36897437"
-            ],
-            "version": "==1.9.0"
-        },
-        "promise": {
-            "hashes": [
-                "sha256:2ebbfc10b7abf6354403ed785fe4f04b9dfd421eb1a474ac8d187022228332af",
-                "sha256:348f5f6c3edd4fd47c9cd65aed03ac1b31136d375aa63871a57d3e444c85655c"
-            ],
-            "version": "==2.2.1"
-        },
-        "python-multipart": {
-            "hashes": [
-                "sha256:f7bb5f611fc600d15fa47b3974c8aa16e93724513b49b5f95c81e6624c83fa43"
-            ],
-            "version": "==0.0.5"
-        },
-        "pyyaml": {
-            "hashes": [
-                "sha256:254bf6fda2b7c651837acb2c718e213df29d531eebf00edb54743d10bcb694eb",
-                "sha256:3108529b78577327d15eec243f0ff348a0640b0c3478d67ad7f5648f93bac3e2",
-                "sha256:3c17fb92c8ba2f525e4b5f7941d850e7a48c3a59b32d331e2502a3cdc6648e76",
-                "sha256:8d6d96001aa7f0a6a4a95e8143225b5d06e41b1131044913fecb8f85a125714b",
-                "sha256:c8a88edd93ee29ede719080b2be6cb2333dfee1dccba213b422a9c8e97f2967b"
-            ],
-            "version": "==4.2b4"
-        },
-        "requests": {
-            "hashes": [
-                "sha256:63b52e3c866428a224f97cab011de738c36aec0185aa91cfacd418b5d58911d1",
-                "sha256:ec22d826a36ed72a7358ff3fe56cbd4ba69dd7a6718ffd450ff0e9df7a47ce6a"
-            ],
-            "version": "==2.19.1"
-        },
-        "responder": {
-            "editable": true,
-            "path": "."
-        },
-        "rfc3986": {
-            "hashes": [
-                "sha256:632b8fcd2ac37f24334316227f909be4f9d0738cbf409404cff6fa5f69a24093",
-                "sha256:8458571c4c57e1cf23593ad860bb601b6a604df6217f829c2bc70dc4b5af941b"
-            ],
-            "version": "==1.1.0"
-        },
-        "rx": {
-            "hashes": [
-                "sha256:13a1d8d9e252625c173dc795471e614eadfe1cf40ffc684e08b8fff0d9748c23",
-                "sha256:7357592bc7e881a95e0c2013b73326f704953301ab551fbc8133a6fadab84105"
-            ],
-            "version": "==1.6.1"
-        },
-        "six": {
-            "hashes": [
-                "sha256:70e8a77beed4562e7f14fe23a786b54f6296e34344c23bc42f07b15018ff98e9",
-                "sha256:832dc0e10feb1aa2c68dcc57dbb658f1c7e65b9b61af69048abc87a2db00a0eb"
-            ],
-            "version": "==1.11.0"
-        },
-        "starlette": {
-            "hashes": [
-                "sha256:9f42bba2c3140402df7fe645b79aadc694cca80140d7bdd43b8a7175f84a8a70"
-            ],
-            "index": "pypi",
-            "version": "==0.4.1"
-        },
-        "urllib3": {
-            "hashes": [
-                "sha256:a68ac5e15e76e7e5dd2b8f94007233e01effe3e50e8daddf69acfd81cb686baf",
-                "sha256:b5725a0bd4ba422ab0e66e89e030c806576753ea3ee08554382c14e685d117b5"
-            ],
-            "version": "==1.23"
-        },
-        "uvicorn": {
-            "hashes": [
-                "sha256:8de03999a936d8704f07cc3b1d3a3edb6922a068b64d84b4f5e49604c8b70a11"
-            ],
-            "index": "pypi",
-            "version": "==0.3.12"
-        },
-        "websockets": {
-            "hashes": [
-                "sha256:0e2f7d6567838369af074f0ef4d0b802d19fa1fee135d864acc656ceefa33136",
-                "sha256:2a16dac282b2fdae75178d0ed3d5b9bc3258dabfae50196cbb30578d84b6f6a6",
-                "sha256:5a1fa6072405648cb5b3688e9ed3b94be683ce4a4e5723e6f5d34859dee495c1",
-                "sha256:5c1f55a1274df9d6a37553fef8cff2958515438c58920897675c9bc70f5a0538",
-                "sha256:669d1e46f165e0ad152ed8197f7edead22854a6c90419f544e0f234cc9dac6c4",
-                "sha256:695e34c4dbea18d09ab2c258994a8bf6a09564e762655408241f6a14592d2908",
-                "sha256:6b2e03d69afa8d20253455e67b64de1a82ff8612db105113cccec35d3f8429f0",
-                "sha256:79ca7cdda7ad4e3663ea3c43bfa8637fc5d5604c7737f19a8964781abbd1148d",
-                "sha256:7fd2dd9a856f72e6ed06f82facfce01d119b88457cd4b47b7ae501e8e11eba9c",
-                "sha256:82c0354ac39379d836719a77ee360ef865377aa6fdead87909d50248d0f05f4d",
-                "sha256:8f3b956d11c5b301206382726210dc1d3bee1a9ccf7aadf895aaf31f71c3716c",
-                "sha256:91ec98640220ae05b34b79ee88abf27f97ef7c61cf525eec57ea8fcea9f7dddb",
-                "sha256:952be9540d83dba815569d5cb5f31708801e0bbfc3a8c5aef1890b57ed7e58bf",
-                "sha256:99ac266af38ba1b1fe13975aea01ac0e14bb5f3a3200d2c69f05385768b8568e",
-                "sha256:9fa122e7adb24232247f8a89f2d9070bf64b7869daf93ac5e19546b409e47e96",
-                "sha256:a0873eadc4b8ca93e2e848d490809e0123eea154aa44ecd0109c4d0171869584",
-                "sha256:cb998bd4d93af46b8b49ecf5a72c0a98e5cc6d57fdca6527ba78ad89d6606484",
-                "sha256:e02e57346f6a68523e3c43bbdf35dde5c440318d1f827208ae455f6a2ace446d",
-                "sha256:e79a5a896bcee7fff24a788d72e5c69f13e61369d055f28113e71945a7eb1559",
-                "sha256:ee55eb6bcf23ecc975e6b47c127c201b913598f38b6a300075f84eeef2d3baff",
-                "sha256:f1414e6cbcea8d22843e7eafdfdfae3dd1aba41d1945f6ca66e4806c07c4f454"
-            ],
-            "version": "==6.0"
-        }
-    },
-    "develop": {
-        "alabaster": {
-            "hashes": [
-                "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359",
-                "sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02"
-            ],
-            "version": "==0.7.12"
-        },
-        "appdirs": {
-            "hashes": [
-                "sha256:9e5896d1372858f8dd3344faf4e5014d21849c756c8d5701f78f8a103b372d92",
-                "sha256:d8b24664561d0d34ddfaec54636d502d7cea6e29c3eaf68f3df6180863e2166e"
-            ],
-            "version": "==1.4.3"
-        },
-        "atomicwrites": {
-            "hashes": [
-                "sha256:0312ad34fcad8fac3704d441f7b317e50af620823353ec657a53e981f92920c0",
-                "sha256:ec9ae8adaae229e4f8446952d204a3e4b5fdd2d099f9be3aaf556120135fb3ee"
-            ],
-            "version": "==1.2.1"
-        },
-        "attrs": {
-            "hashes": [
-                "sha256:10cbf6e27dbce8c30807caf056c8eb50917e0eaafe86347671b57254006c3e69",
-                "sha256:ca4be454458f9dec299268d472aaa5a11f67a4ff70093396e1ceae9c76cf4bbb"
-            ],
-            "version": "==18.2.0"
-        },
-        "babel": {
-            "hashes": [
-                "sha256:6778d85147d5d85345c14a26aada5e478ab04e39b078b0745ee6870c2b5cf669",
-                "sha256:8cba50f48c529ca3fa18cf81fa9403be176d374ac4d60738b839122dfaaa3d23"
-            ],
-            "version": "==2.6.0"
-        },
-        "black": {
-            "hashes": [
-                "sha256:817243426042db1d36617910df579a54f1afd659adb96fc5032fcf4b36209739",
-                "sha256:e030a9a28f542debc08acceb273f228ac422798e5215ba2a791a6ddeaaca22a5"
-            ],
-            "index": "pypi",
-            "version": "==18.9b0"
-        },
-        "bleach": {
-            "hashes": [
-                "sha256:48d39675b80a75f6d1c3bdbffec791cf0bbbab665cf01e20da701c77de278718",
-                "sha256:73d26f018af5d5adcdabf5c1c974add4361a9c76af215fe32fdec8a6fc5fb9b9"
-            ],
-            "version": "==3.0.2"
-        },
-        "certifi": {
-            "hashes": [
-                "sha256:376690d6f16d32f9d1fe8932551d80b23e9d393a8578c5633a2ed39a64861638",
-                "sha256:456048c7e371c089d0a77a5212fb37a2c2dce1e24146e3b7e0261736aaeaa22a"
-            ],
-            "version": "==2018.8.24"
-        },
-        "cffi": {
-            "hashes": [
-                "sha256:151b7eefd035c56b2b2e1eb9963c90c6302dc15fbd8c1c0a83a163ff2c7d7743",
-                "sha256:1553d1e99f035ace1c0544050622b7bc963374a00c467edafac50ad7bd276aef",
-                "sha256:1b0493c091a1898f1136e3f4f991a784437fac3673780ff9de3bcf46c80b6b50",
-                "sha256:2ba8a45822b7aee805ab49abfe7eec16b90587f7f26df20c71dd89e45a97076f",
-                "sha256:3bb6bd7266598f318063e584378b8e27c67de998a43362e8fce664c54ee52d30",
-                "sha256:3c85641778460581c42924384f5e68076d724ceac0f267d66c757f7535069c93",
-                "sha256:3eb6434197633b7748cea30bf0ba9f66727cdce45117a712b29a443943733257",
-                "sha256:495c5c2d43bf6cebe0178eb3e88f9c4aa48d8934aa6e3cddb865c058da76756b",
-                "sha256:4c91af6e967c2015729d3e69c2e51d92f9898c330d6a851bf8f121236f3defd3",
-                "sha256:57b2533356cb2d8fac1555815929f7f5f14d68ac77b085d2326b571310f34f6e",
-                "sha256:770f3782b31f50b68627e22f91cb182c48c47c02eb405fd689472aa7b7aa16dc",
-                "sha256:79f9b6f7c46ae1f8ded75f68cf8ad50e5729ed4d590c74840471fc2823457d04",
-                "sha256:7a33145e04d44ce95bcd71e522b478d282ad0eafaf34fe1ec5bbd73e662f22b6",
-                "sha256:857959354ae3a6fa3da6651b966d13b0a8bed6bbc87a0de7b38a549db1d2a359",
-                "sha256:87f37fe5130574ff76c17cab61e7d2538a16f843bb7bca8ebbc4b12de3078596",
-                "sha256:95d5251e4b5ca00061f9d9f3d6fe537247e145a8524ae9fd30a2f8fbce993b5b",
-                "sha256:9d1d3e63a4afdc29bd76ce6aa9d58c771cd1599fbba8cf5057e7860b203710dd",
-                "sha256:a36c5c154f9d42ec176e6e620cb0dd275744aa1d804786a71ac37dc3661a5e95",
-                "sha256:a6a5cb8809091ec9ac03edde9304b3ad82ad4466333432b16d78ef40e0cce0d5",
-                "sha256:ae5e35a2c189d397b91034642cb0eab0e346f776ec2eb44a49a459e6615d6e2e",
-                "sha256:b0f7d4a3df8f06cf49f9f121bead236e328074de6449866515cea4907bbc63d6",
-                "sha256:b75110fb114fa366b29a027d0c9be3709579602ae111ff61674d28c93606acca",
-                "sha256:ba5e697569f84b13640c9e193170e89c13c6244c24400fc57e88724ef610cd31",
-                "sha256:be2a9b390f77fd7676d80bc3cdc4f8edb940d8c198ed2d8c0be1319018c778e1",
-                "sha256:ca1bd81f40adc59011f58159e4aa6445fc585a32bb8ac9badf7a2c1aa23822f2",
-                "sha256:d5d8555d9bfc3f02385c1c37e9f998e2011f0db4f90e250e5bc0c0a85a813085",
-                "sha256:e55e22ac0a30023426564b1059b035973ec82186ddddbac867078435801c7801",
-                "sha256:e90f17980e6ab0f3c2f3730e56d1fe9bcba1891eeea58966e89d352492cc74f4",
-                "sha256:ecbb7b01409e9b782df5ded849c178a0aa7c906cf8c5a67368047daab282b184",
-                "sha256:ed01918d545a38998bfa5902c7c00e0fee90e957ce036a4000a88e3fe2264917",
-                "sha256:edabd457cd23a02965166026fd9bfd196f4324fe6032e866d0f3bd0301cd486f",
-                "sha256:fdf1c1dc5bafc32bc5d08b054f94d659422b05aba244d6be4ddc1c72d9aa70fb"
-            ],
-            "markers": "sys_platform == 'win32' and platform_python_implementation == 'CPython'",
-            "version": "==1.11.5"
-        },
-        "chardet": {
-            "hashes": [
-                "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae",
-                "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691"
-            ],
-            "version": "==3.0.4"
-        },
-        "click": {
-            "hashes": [
-                "sha256:2335065e6395b9e67ca716de5f7526736bfa6ceead690adf616d925bdc622b13",
-                "sha256:5b94b49521f6456670fdb30cd82a4eca9412788a93fa6dd6df72c94d5a8ff2d7"
-            ],
-            "version": "==7.0"
-        },
-        "cmarkgfm": {
-            "hashes": [
-                "sha256:0186dccca79483e3405217993b83b914ba4559fe9a8396efc4eea56561b74061",
-                "sha256:1a625afc6f62da428df96ec325dc30866cc5781520cbd904ff4ec44cf018171c",
-                "sha256:207b7673ff4e177374c572feeae0e4ef33be620ec9171c08fd22e2b796e03e3d",
-                "sha256:275905bb371a99285c74931700db3f0c078e7603bed383e8cf1a09f3ee05a3de",
-                "sha256:50098f1c4950722521f0671e54139e0edc1837d63c990cf0f3d2c49607bb51a2",
-                "sha256:50ed116d0b60a07df0dc7b180c28569064b9d37d1578d4c9021cff04d725cb63",
-                "sha256:61a72def110eed903cd1848245897bcb80d295cd9d13944d4f9f30cba5b76655",
-                "sha256:64186fb75d973a06df0e6ea12879533b71f6e7ba1ab01ffee7fc3e7534758889",
-                "sha256:665303d34d7f14f10d7b0651082f25ebf7107f29ef3d699490cac16cdc0fc8ce",
-                "sha256:70b18f843aec58e4e64aadce48a897fe7c50426718b7753aaee399e72df64190",
-                "sha256:761ee7b04d1caee2931344ac6bfebf37102ffb203b136b676b0a71a3f0ea3c87",
-                "sha256:811527e9b7280b136734ed6cb6845e5fbccaeaa132ddf45f0246cbe544016957",
-                "sha256:987b0e157f70c72a84f3c2f9ef2d7ab0f26c08f2bf326c12c087ff9eebcb3ff5",
-                "sha256:9fc6a2183d0a9b0974ec7cdcdad42bd78a3be674cc3e65f87dd694419b3b0ab7",
-                "sha256:a3d17ee4ae739fe16f7501a52255c2e287ac817cfd88565b9859f70520afffea",
-                "sha256:ba5b5488719c0f2ced0aa1986376f7baff1a1653a8eb5fdfcf3f84c7ce46ef8d",
-                "sha256:c573ea89dd95d41b6d8cf36799c34b6d5b1eac4aed0212dee0f0a11fb7b01e8f",
-                "sha256:c5f1b9e8592d2c448c44e6bc0d91224b16ea5f8293908b1561de1f6d2d0658b1",
-                "sha256:cbe581456357d8f0674d6a590b1aaf46c11d01dd0a23af147a51a798c3818034",
-                "sha256:cf219bec69e601fe27e3974b7307d2f06082ab385d42752738ad2eb630a47d65",
-                "sha256:cf5014eb214d814a83a7a47407272d5db10b719dbeaf4d3cfe5969309d0fcf4b",
-                "sha256:d08bad67fa18f7e8ff738c090628ee0cbf0505d74a991c848d6d04abfe67b697",
-                "sha256:d6f716d7b1182bf35862b5065112f933f43dd1aa4f8097c9bcfb246f71528a34",
-                "sha256:e08e479102627641c7cb4ece421c6ed4124820b1758765db32201136762282d9",
-                "sha256:e20ac21418af0298437d29599f7851915497ce9f2866bc8e86b084d8911ee061",
-                "sha256:e25f53c37e319241b9a412382140dffac98ca756ba8f360ac7ab5e30cad9670a",
-                "sha256:e8932bddf159064f04e946fbb64693753488de21586f20e840b3be51745c8c09",
-                "sha256:f20900f16377f2109783ae9348d34bc80530808439591c3d3df73d5c7ef1a00c"
-            ],
-            "version": "==0.4.2"
-        },
-        "colorama": {
-            "hashes": [
-                "sha256:a3d89af5db9e9806a779a50296b5fdb466e281147c2c235e8225ecc6dbf7bbf3",
-                "sha256:c9b54bebe91a6a803e0772c8561d53f2926bfeb17cd141fbabcb08424086595c"
-            ],
-            "markers": "sys_platform == 'win32'",
-            "version": "==0.4.0"
-        },
-        "docutils": {
-            "hashes": [
-                "sha256:02aec4bd92ab067f6ff27a38a38a41173bf01bed8f89157768c1573f53e474a6",
-                "sha256:51e64ef2ebfb29cae1faa133b3710143496eca21c530f3f71424d77687764274",
-                "sha256:7a4bd47eaf6596e1295ecb11361139febe29b084a87bf005bf899f9a42edc3c6"
-            ],
-            "version": "==0.14"
-        },
-        "flake8": {
-            "hashes": [
-                "sha256:7253265f7abd8b313e3892944044a365e3f4ac3fcdcfb4298f55ee9ddf188ba0",
-                "sha256:c7841163e2b576d435799169b78703ad6ac1bbb0f199994fc05f700b2a90ea37"
-            ],
-            "index": "pypi",
-            "version": "==3.5.0"
-        },
-        "flask": {
-            "hashes": [
-                "sha256:2271c0070dbcb5275fad4a82e29f23ab92682dc45f9dfbc22c02ba9b9322ce48",
-                "sha256:a080b744b7e345ccfcbc77954861cb05b3c63786e93f2b3875e0913d44b43f05"
-            ],
-            "index": "pypi",
-            "version": "==1.0.2"
-        },
-        "future": {
-            "hashes": [
-                "sha256:e39ced1ab767b5936646cedba8bcce582398233d6a627067d4c6a454c90cfedb"
-            ],
-            "version": "==0.16.0"
-        },
-        "gevent": {
-            "hashes": [
-                "sha256:1f277c5cf060b30313c5f9b91588f4c645e11839e14a63c83fcf6f24b1bc9b95",
-                "sha256:298a04a334fb5e3dcd6f89d063866a09155da56041bc94756da59db412cb45b1",
-                "sha256:30e9b2878d5b57c68a40b3a08d496bcdaefc79893948989bb9b9fab087b3f3c0",
-                "sha256:33533bc5c6522883e4437e901059fe5afa3ea74287eeea27a130494ff130e731",
-                "sha256:3f06f4802824c577272960df003a304ce95b3e82eea01dad2637cc8609c80e2c",
-                "sha256:419fd562e4b94b91b58cccb3bd3f17e1a11f6162fca6c591a7822bc8a68f023d",
-                "sha256:4ea938f44b882e02cca9583069d38eb5f257cc15a03e918980c307e7739b1038",
-                "sha256:51143a479965e3e634252a0f4a1ea07e5307cf8dc773ef6bf9dfe6741785fb4c",
-                "sha256:5bf9bd1dd4951552d9207af3168f420575e3049016b9c10fe0c96760ce3555b7",
-                "sha256:6004512833707a1877cc1a5aea90fd182f569e089bc9ab22a81d480dad018f1b",
-                "sha256:640b3b52121ab519e0980cb38b572df0d2bc76941103a697e828c13d76ac8836",
-                "sha256:6951655cc18b8371d823e81c700883debb0f633aae76f425dfeb240f76b95a67",
-                "sha256:71eeb8d9146e8131b65c3364bb760b097c21b7b9fdbec91bf120685a510f997a",
-                "sha256:7c899e5a6f94d6310352716740f05e41eb8c52d995f27fc01e90380913aa8f22",
-                "sha256:8465f84ba31aaf52a080837e9c5ddd592ab0a21dfda3212239ce1e1796f4d503",
-                "sha256:99de2e38dde8669dd30a8a1261bdb39caee6bd00a5f928d01dfdb85ab0502562",
-                "sha256:9fa4284b44bc42bef6e437488d000ae37499ccee0d239013465638504c4565b7",
-                "sha256:a1beea0443d3404c03e069d4c4d9fc13d8ec001771c77f9a23f01911a41f0e49",
-                "sha256:a66a26b78d90d7c4e9bf9efb2b2bd0af49234604ac52eaca03ea79ac411e3f6d",
-                "sha256:a94e197bd9667834f7bb6bd8dff1736fab68619d0f8cd78a9c1cebe3c4944677",
-                "sha256:ac0331d3a3289a3d16627742be9c8969f293740a31efdedcd9087dadd6b2da57",
-                "sha256:d26b57c50bf52fb38dadf3df5bbecd2236f49d7ac98f3cf32d6b8a2d25afc27f",
-                "sha256:fd23b27387d76410eb6a01ea13efc7d8b4b95974ba212c336e8b1d6ab45a9578"
-            ],
-            "version": "==1.3.7"
-        },
-        "greenlet": {
-            "hashes": [
-                "sha256:000546ad01e6389e98626c1367be58efa613fa82a1be98b0c6fc24b563acc6d0",
-                "sha256:0d48200bc50cbf498716712129eef819b1729339e34c3ae71656964dac907c28",
-                "sha256:23d12eacffa9d0f290c0fe0c4e81ba6d5f3a5b7ac3c30a5eaf0126bf4deda5c8",
-                "sha256:37c9ba82bd82eb6a23c2e5acc03055c0e45697253b2393c9a50cef76a3985304",
-                "sha256:51503524dd6f152ab4ad1fbd168fc6c30b5795e8c70be4410a64940b3abb55c0",
-                "sha256:8041e2de00e745c0e05a502d6e6db310db7faa7c979b3a5877123548a4c0b214",
-                "sha256:81fcd96a275209ef117e9ec91f75c731fa18dcfd9ffaa1c0adbdaa3616a86043",
-                "sha256:853da4f9563d982e4121fed8c92eea1a4594a2299037b3034c3c898cb8e933d6",
-                "sha256:8b4572c334593d449113f9dc8d19b93b7b271bdbe90ba7509eb178923327b625",
-                "sha256:9416443e219356e3c31f1f918a91badf2e37acf297e2fa13d24d1cc2380f8fbc",
-                "sha256:9854f612e1b59ec66804931df5add3b2d5ef0067748ea29dc60f0efdcda9a638",
-                "sha256:99a26afdb82ea83a265137a398f570402aa1f2b5dfb4ac3300c026931817b163",
-                "sha256:a19bf883b3384957e4a4a13e6bd1ae3d85ae87f4beb5957e35b0be287f12f4e4",
-                "sha256:a9f145660588187ff835c55a7d2ddf6abfc570c2651c276d3d4be8a2766db490",
-                "sha256:ac57fcdcfb0b73bb3203b58a14501abb7e5ff9ea5e2edfa06bb03035f0cff248",
-                "sha256:bcb530089ff24f6458a81ac3fa699e8c00194208a724b644ecc68422e1111939",
-                "sha256:beeabe25c3b704f7d56b573f7d2ff88fc99f0138e43480cecdfcaa3b87fe4f87",
-                "sha256:d634a7ea1fc3380ff96f9e44d8d22f38418c1c381d5fac680b272d7d90883720",
-                "sha256:d97b0661e1aead761f0ded3b769044bb00ed5d33e1ec865e891a8b128bf7c656"
-            ],
-            "markers": "platform_python_implementation == 'CPython'",
-            "version": "==0.4.15"
-        },
-        "idna": {
-            "hashes": [
-                "sha256:156a6814fb5ac1fc6850fb002e0852d56c0c8d2531923a51032d1b70760e186e",
-                "sha256:684a38a6f903c1d71d6d5fac066b58d7768af4de2b832e426ec79c30daa94a16"
-            ],
-            "version": "==2.7"
-        },
-        "imagesize": {
-            "hashes": [
-                "sha256:3f349de3eb99145973fefb7dbe38554414e5c30abd0c8e4b970a7c9d09f3a1d8",
-                "sha256:f3832918bc3c66617f92e35f5d70729187676313caa60c187eb0f28b8fe5e3b5"
-            ],
-            "version": "==1.1.0"
-        },
-        "itsdangerous": {
-            "hashes": [
-                "sha256:cbb3fcf8d3e33df861709ecaf89d9e6629cff0a217bc2848f1b41cd30d360519"
-            ],
-            "version": "==0.24"
-        },
-        "jinja2": {
-            "hashes": [
-                "sha256:74c935a1b8bb9a3947c50a54766a969d4846290e1e788ea44c1392163723c3bd",
-                "sha256:f84be1bb0040caca4cea721fcbbbbd61f9be9464ca236387158b0feea01914a4"
-            ],
-            "version": "==2.10"
-        },
-        "locust": {
-            "hashes": [
-                "sha256:aaa38b525795e9c1a35ac3620543cf4e62f82948714f60a32023ea8c9b8edc2e"
-            ],
-            "index": "pypi",
-            "version": "==0.0"
-        },
-        "locustio": {
-            "hashes": [
-                "sha256:be7b44468b8683def983e7451ab505cd85fff8d06f6b75ad7c899cedbbf789ac",
-                "sha256:c77b471e0e08e215c93a7af9a95b79193268072873fbbc0effca40f3d9b58be4"
-            ],
-            "index": "pypi",
-            "version": "==0.9.0"
-        },
-        "markupsafe": {
-            "hashes": [
-                "sha256:a6be69091dac236ea9c6bc7d012beab42010fa914c459791d627dad4910eb665"
-            ],
-            "version": "==1.0"
-        },
-        "mccabe": {
-            "hashes": [
-                "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
-                "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"
-            ],
-            "version": "==0.6.1"
-        },
-        "more-itertools": {
-            "hashes": [
-                "sha256:c187a73da93e7a8acc0001572aebc7e3c69daf7bf6881a2cea10650bd4420092",
-                "sha256:c476b5d3a34e12d40130bc2f935028b5f636df8f372dc2c1c01dc19681b2039e",
-                "sha256:fcbfeaea0be121980e15bc97b3817b5202ca73d0eae185b4550cbfce2a3ebb3d"
-            ],
-            "version": "==4.3.0"
-        },
-        "msgpack": {
-            "hashes": [
-                "sha256:0b3b1773d2693c70598585a34ca2715873ba899565f0a7c9a1545baef7e7fbdc",
-                "sha256:0bae5d1538c5c6a75642f75a1781f3ac2275d744a92af1a453c150da3446138b",
-                "sha256:0ee8c8c85aa651be3aa0cd005b5931769eaa658c948ce79428766f1bd46ae2c3",
-                "sha256:1369f9edba9500c7a6489b70fdfac773e925342f4531f1e3d4c20ac3173b1ae0",
-                "sha256:22d9c929d1d539f37da3d1b0e16270fa9d46107beab8c0d4d2bddffffe895cee",
-                "sha256:2ff43e3247a1e11d544017bb26f580a68306cec7a6257d8818893c1fda665f42",
-                "sha256:31a98047355d34d047fcdb55b09cb19f633cf214c705a765bd745456c142130c",
-                "sha256:8767eb0032732c3a0da92cbec5ac186ef89a3258c6edca09161472ca0206c45f",
-                "sha256:8acc8910218555044e23826980b950e96685dc48124a290c86f6f41a296ea172",
-                "sha256:ab189a6365be1860a5ecf8159c248f12d33f79ea799ae9695fa6a29896dcf1d4",
-                "sha256:cfd6535feb0f1cf1c7cdb25773e965cc9f92928244a8c3ef6f8f8a8e1f7ae5c4",
-                "sha256:e274cd4480d8c76ec467a85a9c6635bbf2258f0649040560382ab58cabb44bcf",
-                "sha256:f86642d60dca13e93260187d56c2bef2487aa4d574a669e8ceefcf9f4c26fd00",
-                "sha256:f8a57cbda46a94ed0db55b73e6ab0c15e78b4ede8690fa491a0e55128d552bb0",
-                "sha256:fcea97a352416afcbccd7af9625159d80704a25c519c251c734527329bb20d0e"
-            ],
-            "version": "==0.5.6"
-        },
-        "packaging": {
-            "hashes": [
-                "sha256:0886227f54515e592aaa2e5a553332c73962917f2831f1b0f9b9f4380a4b9807",
-                "sha256:f95a1e147590f204328170981833854229bb2912ac3d5f89e2a8ccd2834800c9"
-            ],
-            "version": "==18.0"
-        },
-        "pkginfo": {
-            "hashes": [
-                "sha256:5878d542a4b3f237e359926384f1dde4e099c9f5525d236b1840cf704fa8d474",
-                "sha256:a39076cb3eb34c333a0dd390b568e9e1e881c7bf2cc0aee12120636816f55aee"
-            ],
-            "version": "==1.4.2"
-        },
-        "pluggy": {
-            "hashes": [
-                "sha256:6e3836e39f4d36ae72840833db137f7b7d35105079aee6ec4a62d9f80d594dd1",
-                "sha256:95eb8364a4708392bae89035f45341871286a333f749c3141c20573d2b3876e1"
-            ],
-            "version": "==0.7.1"
-        },
-        "py": {
-            "hashes": [
-                "sha256:bf92637198836372b520efcba9e020c330123be8ce527e535d185ed4b6f45694",
-                "sha256:e76826342cefe3c3d5f7e8ee4316b80d1dd8a300781612ddbc765c17ba25a6c6"
-            ],
-            "version": "==1.7.0"
-        },
-        "pycodestyle": {
-            "hashes": [
-                "sha256:682256a5b318149ca0d2a9185d365d8864a768a28db66a84a2ea946bcc426766",
-                "sha256:6c4245ade1edfad79c3446fadfc96b0de2759662dc29d07d80a6f27ad1ca6ba9"
-            ],
-            "version": "==2.3.1"
-        },
-        "pycparser": {
-            "hashes": [
-                "sha256:a988718abfad80b6b157acce7bf130a30876d27603738ac39f140993246b25b3"
-            ],
-            "version": "==2.19"
-        },
-        "pyflakes": {
-            "hashes": [
-                "sha256:08bd6a50edf8cffa9fa09a463063c425ecaaf10d1eb0335a7e8b1401aef89e6f",
-                "sha256:8d616a382f243dbf19b54743f280b80198be0bca3a5396f1d2e1fca6223e8805"
-            ],
-            "version": "==1.6.0"
-        },
-        "pygments": {
-            "hashes": [
-                "sha256:78f3f434bcc5d6ee09020f92ba487f95ba50f1e3ef83ae96b9d5ffa1bab25c5d",
-                "sha256:dbae1046def0efb574852fab9e90209b23f556367b5a320c0bcb871c77c3e8cc"
-            ],
-            "version": "==2.2.0"
-        },
-        "pyparsing": {
-            "hashes": [
-                "sha256:bc6c7146b91af3f567cf6daeaec360bc07d45ffec4cf5353f4d7a208ce7ca30a",
-                "sha256:d29593d8ebe7b57d6967b62494f8c72b03ac0262b1eed63826c6f788b3606401"
-            ],
-            "version": "==2.2.2"
-        },
-        "pytest": {
-            "hashes": [
-                "sha256:7e258ee50338f4e46957f9e09a0f10fb1c2d05493fa901d113a8dafd0790de4e",
-                "sha256:9332147e9af2dcf46cd7ceb14d5acadb6564744ddff1fe8c17f0ce60ece7d9a2"
-            ],
-            "index": "pypi",
-            "version": "==3.8.2"
-        },
-        "pytz": {
-            "hashes": [
-                "sha256:a061aa0a9e06881eb8b3b2b43f05b9439d6583c206d0a6c340ff72a7b6669053",
-                "sha256:ffb9ef1de172603304d9d2819af6f5ece76f2e85ec10692a524dd876e72bf277"
-            ],
-            "version": "==2018.5"
-        },
-        "pyzmq": {
-            "hashes": [
-                "sha256:25a0715c8f69cf72f67cfe5a68a3f3ed391c67c063d2257bec0fe7fc2c7f08f8",
-                "sha256:2bab63759632c6b9e0d5bf19cc63c3b01df267d660e0abcf230cf0afaa966349",
-                "sha256:30ab49d99b24bf0908ebe1cdfa421720bfab6f93174e4883075b7ff38cc555ba",
-                "sha256:32c7ca9fc547a91e3c26fc6080b6982e46e79819e706eb414dd78f635a65d946",
-                "sha256:41219ae72b3cc86d97557fe5b1ef5d1adc1057292ec597b50050874a970a39cf",
-                "sha256:4b8c48a9a13cea8f1f16622f9bd46127108af14cd26150461e3eab71e0de3e46",
-                "sha256:55724997b4a929c0d01b43c95051318e26ddbae23565018e138ae2dc60187e59",
-                "sha256:65f0a4afae59d4fc0aad54a917ab599162613a761b760ba167d66cc646ac3786",
-                "sha256:6f88591a8b246f5c285ee6ce5c1bf4f6bd8464b7f090b1333a446b6240a68d40",
-                "sha256:75022a4c60dcd8765bb9ca32f6de75a0ec83b0d96e0309dc479f4c7b21f26cb7",
-                "sha256:76ea493bfab18dcb090d825f3662b5612e2def73dffc196d51a5194b0294a81d",
-                "sha256:7b60c045b80709e4e3c085bab9b691e71761b44c2b42dbb047b8b498e7bc16b3",
-                "sha256:8e6af2f736734aef8ed6f278f9f552ec7f37b1a6b98e59b887484a840757f67d",
-                "sha256:9ac2298e486524331e26390eac14e4627effd3f8e001d4266ed9d8f1d2d31cce",
-                "sha256:9ba650f493a9bc1f24feca1d90fce0e5dd41088a252ac9840131dfbdbf3815ca",
-                "sha256:a02a4a385e394e46012dc83d2e8fd6523f039bb52997c1c34a2e0dd49ed839c1",
-                "sha256:a3ceee84114d9f5711fa0f4db9c652af0e4636c89eabc9b7f03a3882569dd1ed",
-                "sha256:a72b82ac1910f2cf61a49139f4974f994984475f771b0faa730839607eeedddf",
-                "sha256:ab136ac51027e7c484c53138a0fab4a8a51e80d05162eb7b1585583bcfdbad27",
-                "sha256:c095b224300bcac61e6c445e27f9046981b1ac20d891b2f1714da89d34c637c8",
-                "sha256:c5cc52d16c06dc2521340d69adda78a8e1031705924e103c0eb8fc8af861d810",
-                "sha256:d612e9833a89e8177f8c1dc68d7b4ff98d3186cd331acd616b01bbdab67d3a7b",
-                "sha256:e828376a23c66c6fe90dcea24b4b72cd774f555a6ee94081670872918df87a19",
-                "sha256:e9767c7ab2eb552796440168d5c6e23a99ecaade08dda16266d43ad461730192",
-                "sha256:ebf8b800d42d217e4710d1582b0c8bff20cdcb4faad7c7213e52644034300924"
-            ],
-            "version": "==17.1.2"
-        },
-        "readme-renderer": {
-            "hashes": [
-                "sha256:237ca8705ffea849870de41101dba41543561da05c0ae45b2f1c547efa9843d2",
-                "sha256:f75049a3a7afa57165551e030dd8f9882ebf688b9600535a3f7e23596651875d"
-            ],
-            "version": "==22.0"
-        },
-        "requests": {
-            "hashes": [
-                "sha256:63b52e3c866428a224f97cab011de738c36aec0185aa91cfacd418b5d58911d1",
-                "sha256:ec22d826a36ed72a7358ff3fe56cbd4ba69dd7a6718ffd450ff0e9df7a47ce6a"
-            ],
-            "version": "==2.19.1"
-        },
-        "requests-toolbelt": {
-            "hashes": [
-                "sha256:42c9c170abc2cacb78b8ab23ac957945c7716249206f90874651971a4acff237",
-                "sha256:f6a531936c6fa4c6cfce1b9c10d5c4f498d16528d2a54a22ca00011205a187b5"
-            ],
-            "version": "==0.8.0"
-        },
-        "six": {
-            "hashes": [
-                "sha256:70e8a77beed4562e7f14fe23a786b54f6296e34344c23bc42f07b15018ff98e9",
-                "sha256:832dc0e10feb1aa2c68dcc57dbb658f1c7e65b9b61af69048abc87a2db00a0eb"
-            ],
-            "version": "==1.11.0"
-        },
-        "snowballstemmer": {
-            "hashes": [
-                "sha256:919f26a68b2c17a7634da993d91339e288964f93c274f1343e3bbbe2096e1128",
-                "sha256:9f3bcd3c401c3e862ec0ebe6d2c069ebc012ce142cce209c098ccb5b09136e89"
-            ],
-            "version": "==1.2.1"
-        },
-        "sphinx": {
-            "hashes": [
-                "sha256:652eb8c566f18823a022bb4b6dbc868d366df332a11a0226b5bc3a798a479f17",
-                "sha256:d222626d8356de702431e813a05c68a35967e3d66c6cd1c2c89539bb179a7464"
-            ],
-            "index": "pypi",
-            "version": "==1.8.1"
-        },
-        "sphinxcontrib-websupport": {
-            "hashes": [
-                "sha256:68ca7ff70785cbe1e7bccc71a48b5b6d965d79ca50629606c7861a21b206d9dd",
-                "sha256:9de47f375baf1ea07cdb3436ff39d7a9c76042c10a769c52353ec46e4e8fc3b9"
-            ],
-            "version": "==1.1.0"
-        },
-        "toml": {
-            "hashes": [
-                "sha256:229f81c57791a41d65e399fc06bf0848bab550a9dfd5ed66df18ce5f05e73d5c",
-                "sha256:235682dd292d5899d361a811df37e04a8828a5b1da3115886b73cf81ebc9100e"
-            ],
-            "version": "==0.10.0"
-        },
-        "tqdm": {
-            "hashes": [
-                "sha256:18f1818ce951aeb9ea162ae1098b43f583f7d057b34d706f66939353d1208889",
-                "sha256:df02c0650160986bac0218bb07952245fc6960d23654648b5d5526ad5a4128c9"
-            ],
-            "version": "==4.26.0"
-        },
-        "twine": {
-            "hashes": [
-                "sha256:7d89bc6acafb31d124e6e5b295ef26ac77030bf098960c2a4c4e058335827c5c",
-                "sha256:fad6f1251195f7ddd1460cb76d6ea106c93adb4e56c41e0da79658e56e547d2c"
-            ],
-            "index": "pypi",
-            "version": "==1.12.1"
-        },
-        "urllib3": {
-            "hashes": [
-                "sha256:a68ac5e15e76e7e5dd2b8f94007233e01effe3e50e8daddf69acfd81cb686baf",
-                "sha256:b5725a0bd4ba422ab0e66e89e030c806576753ea3ee08554382c14e685d117b5"
-            ],
-            "version": "==1.23"
-        },
-        "webencodings": {
-            "hashes": [
-                "sha256:a0af1213f3c2226497a97e2b3aa01a7e4bee4f403f95be16fc9acd2947514a78",
-                "sha256:b36a1c245f2d304965eb4e0a82848379241dc04b865afcc4aab16748587e1923"
-            ],
-            "version": "==0.5.1"
-        },
-        "werkzeug": {
-            "hashes": [
-                "sha256:c3fd7a7d41976d9f44db327260e263132466836cef6f91512889ed60ad26557c",
-                "sha256:d5da73735293558eb1651ee2fddc4d0dedcfa06538b8813a2e20011583c9e49b"
-            ],
-            "version": "==0.14.1"
-        }
-    }
-}

README.md

@@ -1,18 +1,6 @@
-# Responder: a familiar HTTP Service Framework for Python
+# Responder
 
-[![Build Status](https://travis-ci.org/kennethreitz/responder.svg?branch=master)](https://travis-ci.org/kennethreitz/responder)
-[![Documentation Status](https://readthedocs.org/projects/mybinder/badge/?version=latest)](https://responder.readthedocs.io/en/latest/)
-[![image](https://img.shields.io/pypi/v/responder.svg)](https://pypi.org/project/responder/)
-[![image](https://img.shields.io/pypi/l/responder.svg)](https://pypi.org/project/responder/)
-[![image](https://img.shields.io/pypi/pyversions/responder.svg)](https://pypi.org/project/responder/)
-[![image](https://img.shields.io/github/contributors/kennethreitz/responder.svg)](https://github.com/kennethreitz/responder/graphs/contributors)
-[![image](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/kennethreitz)
-
-[![](https://github.com/kennethreitz/responder/raw/master/ext/small.jpg)](http://python-responder.org/)
-
-The Python world certainly doesn't need more web frameworks. But, it does need more creativity, so I thought I'd spread some [Hacktoberfest](https://hacktoberfest.digitalocean.com/) spirit around, bring some of my ideas to the table, and see what I could come up with.
-
-## An Example Web Service:
+A familiar HTTP Service Framework for Python, powered by [Starlette](https://www.starlette.io/).
 
 ```python
 import responder
@@ -23,195 +11,99 @@ api = responder.API()
 async def greet_world(req, resp, *, greeting):
     resp.text = f"{greeting}, world!"
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     api.run()
 ```
 
-That `async` declaration is optional.
+    $ pip install responder
 
-This gets you a ASGI app, with a production static files server pre-installed, jinja2 templating (without additional imports), and a production webserver based on uvloop, serving up requests with gzip compression automatically.
+That's it. Supports Python 3.9+.
 
+## The Basics
 
-## Testimonials
+- `resp.text` sends back text. `resp.html` sends back HTML. `resp.content` sends back bytes.
+- `resp.media` sends back JSON (or YAML, with content negotiation).
+- `resp.file("path.pdf")` serves a file with automatic content-type detection.
+- `req.headers` is case-insensitive. `req.params` gives you query parameters.
+- Both sync and async views work — the `async` is optional.
 
-> "Pleasantly very taken with python-responder. [@kennethreitz](https://twitter.com/kennethreitz) at his absolute best." —Rudraksh M.K.
-
-> "Buckle up!" —Tom Christie of [APIStar](https://github.com/encode/apistar) and [Django REST Framework](https://www.django-rest-framework.org/)
-
-> "I love that you are exploring new patterns. Go go go!" — Danny Greenfield, author of [Two Scoops of Django]()
-
-> "Love what I have seen while it's in progress! Many features of Responder are from my wishlist for Flask, and it's even faster and even easier than Flask!" — Luna C.
-
-> "The most ambitious crossover event in history." —Pablo Cabezas, [on Tom Christie joining the project](https://twitter.com/pabloteleco/status/1050841098321620992?s=20)
-
-
-## More Examples
-
-Class-based views (and setting some headers and stuff):
+## Highlights
 
 ```python
-@api.route("/{greeting}")
-class GreetingResource:
-    def on_request(req, resp, *, greeting):   # or on_get...
-        resp.text = f"{greeting}, world!"
-        resp.headers.update({'X-Life': '42'})
-        resp.status_code = api.status_codes.HTTP_416
-```
+# Type-safe route parameters
+@api.route("/users/{user_id:int}")
+async def get_user(req, resp, *, user_id):
+    resp.media = {"id": user_id}
 
-Render a template, with arguments:
+# HTTP method filtering
+@api.route("/items", methods=["POST"])
+async def create_item(req, resp):
+    data = await req.media()
+    resp.media = {"created": data}
 
-```python
-@api.route("/{greeting}")
-def greet_world(req, resp, *, greeting):
-    resp.content = api.template("index.html", greeting=greeting)
-```
+# Class-based views
+@api.route("/things/{id}")
+class ThingResource:
+    def on_get(self, req, resp, *, id):
+        resp.media = {"id": id}
+    def on_post(self, req, resp, *, id):
+        resp.text = "created"
 
-The `api` instance is available as an object during template rendering.
+# Before-request hooks (auth, rate limiting, etc.)
+@api.route(before_request=True)
+def check_auth(req, resp):
+    if not req.headers.get("Authorization"):
+        resp.status_code = 401
+        resp.media = {"error": "unauthorized"}
 
-Here, you can spawn off a background thread to run any function, out-of-request:
+# Custom error handling
+@api.exception_handler(ValueError)
+async def handle_error(req, resp, exc):
+    resp.status_code = 400
+    resp.media = {"error": str(exc)}
 
-```python
-@api.route("/")
-def hello(req, resp):
+# Lifespan events
+from contextlib import asynccontextmanager
 
-    @api.background.task
-    def sleep(s=10):
-        time.sleep(s)
-        print("slept!")
+@asynccontextmanager
+async def lifespan(app):
+    print("starting up")
+    yield
+    print("shutting down")
 
-    sleep()
-    resp.content = "processing"
-```
+api = responder.API(lifespan=lifespan)
 
-And even serve a GraphQL API:
-
-```python
+# GraphQL
 import graphene
+api.graphql("/graphql", schema=graphene.Schema(query=Query))
 
-class Query(graphene.ObjectType):
-    hello = graphene.String(name=graphene.String(default_value="stranger"))
+# WebSockets
+@api.route("/ws", websocket=True)
+async def websocket(ws):
+    await ws.accept()
+    while True:
+        name = await ws.receive_text()
+        await ws.send_text(f"Hello {name}!")
 
-    def resolve_hello(self, info, name):
-        return "Hello " + name
+# Mount WSGI/ASGI apps
+from flask import Flask
+flask_app = Flask(__name__)
+api.mount("/flask", flask_app)
 
-api.add_route("/graph", graphene.Schema(query=Query))
+# Background tasks
+@api.route("/work")
+def do_work(req, resp):
+    @api.background.task
+    def process():
+        import time; time.sleep(10)
+    process()
+    resp.media = {"status": "processing"}
 ```
 
-We can then send a query to our service:
+Built-in OpenAPI docs, cookie-based sessions, gzip compression, static file serving, Jinja2 templates, and a production uvicorn server.
 
-```pycon
->>> requests = api.session()
->>> r = requests.get("http://;/graph", params={"query": "{ hello }"})
->>> r.json()
-{'data': {'hello': 'Hello stranger'}}
-```
+Route convertors: `str`, `int`, `float`, `uuid`, `path`.
 
-Or, request YAML back:
+## Documentation
 
-```pycon
->>> r = requests.get("http://;/graph", params={"query": "{ hello(name:\"john\") }"}, headers={"Accept": "application/x-yaml"})
->>> print(r.text)
-data: {hello: Hello john}
-
-```
-
-Want HSTS?
-
-```
-api = responder.API(enable_hsts=True)
-```
-
-Boom.
-
-
-# Installing Responder
-
-Install the latest release (might be out of date with the docs a bit):
-
-
-    $ pipenv install responder
-    ✨🍰✨
-
-
-Or, install from the development branch:
-
-    $ pipenv install -e git+https://github.com/kennethreitz/responder.git#egg=responder
-
-Only **Python 3.6+** is supported.
-
-# Web Service Performance Charecteristics
-The objective of these benchmark tests is not testing deployment (like uwsgi vs gunicorn vs uvicorn etc) but instead test the performance of python-response against other popular Python web frameworks.
-
-### Methodology
-The results below were gotten running the performance tests on a Lenovo W530, Intel(R) Core(TM) i7-3740QM CPU @ 2.70GHz, MEM: 32GB, Linux Mint 19. I used Python 3.7.0 with the WRK utility with params:
-wrk -d20s -t10 -c200 (i.e. 10 threads and 200 connections).
-
-1. #### Simple "Hello World" benchmark
-
-    python-responder v0.0.1 (Master branch)
-    Requests/sec:   1368.23
-    Transfer/sec:    163.01KB
-
-
-
-
-    Django v2.1.2 (i18n == False)
-    Requests/sec:    544.54
-    Transfer/sec:    103.18KB
-
-
-
-
-    Django v2.1.2 (i18n == True)
-    Requests/sec:    535.12
-    Transfer/sec:    101.38KB
-
-
-
-    Django v2.1.2 (Minimal 1 file Django Application)
-    https://gist.github.com/aitoehigie/ebcc1d3e460e66cd51e5501fa2636798
-    Requests/sec:    701.53
-    Transfer/sec:     99.34KB
-
-
-
-
-    Flask v1.0.2
-    Requests/sec:    896.24
-    Transfer/sec:    144.41KB
-
-
-# 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.text` sends back unicode, while setting `resp.content` sends back bytes.
-- Setting `resp.media` sends back JSON/YAML (`.text`/`.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 to 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 file server is built-in.
-- Uvicorn 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.
-
-## Future Ideas
-
-- Cookie-based sessions are currently an afterthought, as this is an API framework, but websites are APIs too.
-- If frontend websites are supported, provide an official way to run webpack.
-
-# The Goal
-
-The primary goal here is to learn, not to get adoption. Though, who knows how these things will pan out.
-
-
-----------
-
-[![hacktoberfest](https://hacktoberfest.digitalocean.com/assets/hacktoberfest-2018-social-card-c8d2e1489f647f2e0a26e6f598adeb760872818905b34cd437afc7ac2857ceab.png)](https://hacktoberfest.digitalocean.com/)
+https://responder.kennethreitz.org

docs/requirements.txt

@@ -1,48 +0,0 @@
-alabaster==0.7.12
-appdirs==1.4.3
-atomicwrites==1.2.1
-attrs==18.2.0
-babel==2.6.0
-black==18.9b0
-bleach==3.0.2
-certifi==2018.8.24
-cffi==1.11.5
-chardet==3.0.4
-click==7.0
-cmarkgfm==0.4.2
-colorama==0.4.0 ; sys_platform == 'win32'
-docutils==0.14
-flake8==3.5.0
-flask==1.0.2
-future==0.16.0
-idna==2.7
-imagesize==1.1.0
-itsdangerous==0.24
-jinja2==2.10
-markupsafe==1.0
-mccabe==0.6.1
-more-itertools==4.3.0
-packaging==18.0
-pkginfo==1.4.2
-pluggy==0.7.1
-py==1.7.0
-pycodestyle==2.3.1
-pycparser==2.19
-pyflakes==1.6.0
-pygments==2.2.0
-pyparsing==2.2.2
-pytest==3.8.2
-pytz==2018.5
-readme-renderer==22.0
-requests-toolbelt==0.8.0
-requests==2.19.1
-six==1.11.0
-snowballstemmer==1.2.1
-sphinx==1.8.1
-sphinxcontrib-websupport==1.1.0
-toml==0.10.0
-tqdm==4.26.0
-twine==1.12.1
-urllib3==1.23
-webencodings==0.5.1
-werkzeug==0.14.1

docs/source/_static/custom.css

@@ -1,7 +0,0 @@
-/* Hide module name and default value for environment variable section */
-div[id$='environment-variables'] code.descclassname {
-    display: none;
-}
-div[id$='environment-variables'] em.property {
-    display: none;
-}

docs/source/_static/fonts/692185/07B3028D11D5A1878.css

@@ -1,19 +0,0 @@
-
-/*
-	Copyright (C) 2011-2018 Hoefler & Co.
-	This software is the property of Hoefler & Co. (H&Co).
-	Your right to access and use this software is subject to the
-	applicable License Agreement, or Terms of Service, that exists
-	between you and H&Co. If no such agreement exists, you may not
-	access or use this software for any purpose.
-	This software may only be hosted at the locations specified in
-	the applicable License Agreement or Terms of Service, and only
-	for the purposes expressly set forth therein. You may not copy,
-	modify, convert, create derivative works from or distribute this
-	software in any way, or make it accessible to any third party,
-	without first obtaining the written permission of H&Co.
-	For more information, please visit us at http://typography.com.
-	148887-130097-20181011
-*/
-
-<!-- sorry your browser is not supported. -->

docs/source/_static/fonts/692185/FDCC918E4493D6D80.css

@@ -1,19 +0,0 @@
-
-/*
-	Copyright (C) 2011-2018 Hoefler & Co.
-	This software is the property of Hoefler & Co. (H&Co).
-	Your right to access and use this software is subject to the
-	applicable License Agreement, or Terms of Service, that exists
-	between you and H&Co. If no such agreement exists, you may not
-	access or use this software for any purpose.
-	This software may only be hosted at the locations specified in
-	the applicable License Agreement or Terms of Service, and only
-	for the purposes expressly set forth therein. You may not copy,
-	modify, convert, create derivative works from or distribute this
-	software in any way, or make it accessible to any third party,
-	without first obtaining the written permission of H&Co.
-	For more information, please visit us at http://typography.com.
-	148887-130097-20181011
-*/
-
-<!-- sorry your browser is not supported. -->

docs/source/_static/konami.js

@@ -1,151 +0,0 @@
-/*
- * Konami-JS ~
- * :: Now with support for touch events and multiple instances for
- * :: those situations that call for multiple easter eggs!
- * Code: https://github.com/snaptortoise/konami-js
- * Copyright (c) 2009 George Mandis (georgemandis.com, snaptortoise.com)
- * Version: 1.6.2 (7/17/2018)
- * Licensed under the MIT License (http://opensource.org/licenses/MIT)
- * Tested in: Safari 4+, Google Chrome 4+, Firefox 3+, IE7+, Mobile Safari 2.2.1+ and Android
- */
-
-var Konami = function (callback) {
-    var konami = {
-        addEvent: function (obj, type, fn, ref_obj) {
-            if (obj.addEventListener)
-                obj.addEventListener(type, fn, false);
-            else if (obj.attachEvent) {
-                // IE
-                obj["e" + type + fn] = fn;
-                obj[type + fn] = function () {
-                    obj["e" + type + fn](window.event, ref_obj);
-                }
-                obj.attachEvent("on" + type, obj[type + fn]);
-            }
-        },
-        removeEvent: function (obj, eventName, eventCallback) {
-            if (obj.removeEventListener) {
-                obj.removeEventListener(eventName, eventCallback);
-            } else if (obj.attachEvent) {
-                obj.detachEvent(eventName);
-            }
-        },
-        input: "",
-        pattern: "38384040373937396665",
-        keydownHandler: function (e, ref_obj) {
-            if (ref_obj) {
-                konami = ref_obj;
-            } // IE
-            konami.input += e ? e.keyCode : event.keyCode;
-            if (konami.input.length > konami.pattern.length) {
-                konami.input = konami.input.substr((konami.input.length - konami.pattern.length));
-            }
-            if (konami.input === konami.pattern) {
-                konami.code(konami._currentLink);
-                konami.input = '';
-                e.preventDefault();
-                return false;
-            }
-        },
-        load: function (link) {
-            this._currentLink = link;
-            this.addEvent(document, "keydown", this.keydownHandler, this);
-            this.iphone.load(link);
-        },
-        unload: function () {
-            this.removeEvent(document, 'keydown', this.keydownHandler);
-            this.iphone.unload();
-        },
-        code: function (link) {
-            window.location = link
-        },
-        iphone: {
-            start_x: 0,
-            start_y: 0,
-            stop_x: 0,
-            stop_y: 0,
-            tap: false,
-            capture: false,
-            orig_keys: "",
-            keys: ["UP", "UP", "DOWN", "DOWN", "LEFT", "RIGHT", "LEFT", "RIGHT", "TAP", "TAP"],
-            input: [],
-            code: function (link) {
-                konami.code(link);
-            },
-            touchmoveHandler: function (e) {
-                if (e.touches.length === 1 && konami.iphone.capture === true) {
-                    var touch = e.touches[0];
-                    konami.iphone.stop_x = touch.pageX;
-                    konami.iphone.stop_y = touch.pageY;
-                    konami.iphone.tap = false;
-                    konami.iphone.capture = false;
-                    konami.iphone.check_direction();
-                }
-            },
-            touchendHandler: function () {
-                konami.iphone.input.push(konami.iphone.check_direction());
-                
-                if (konami.iphone.input.length > konami.iphone.keys.length) konami.iphone.input.shift();
-                
-                if (konami.iphone.input.length === konami.iphone.keys.length) {
-                    var match = true;
-                    for (var i = 0; i < konami.iphone.keys.length; i++) {
-                        if (konami.iphone.input[i] !== konami.iphone.keys[i]) {
-                            match = false;
-                        }
-                    }
-                    if (match) {
-                        konami.iphone.code(konami._currentLink);
-                    }
-                }
-            },
-            touchstartHandler: function (e) {
-                konami.iphone.start_x = e.changedTouches[0].pageX;
-                konami.iphone.start_y = e.changedTouches[0].pageY;
-                konami.iphone.tap = true;
-                konami.iphone.capture = true;
-            },
-            load: function (link) {
-                this.orig_keys = this.keys;
-                konami.addEvent(document, "touchmove", this.touchmoveHandler);
-                konami.addEvent(document, "touchend", this.touchendHandler, false);
-                konami.addEvent(document, "touchstart", this.touchstartHandler);
-            },
-            unload: function () {
-                konami.removeEvent(document, 'touchmove', this.touchmoveHandler);
-                konami.removeEvent(document, 'touchend', this.touchendHandler);
-                konami.removeEvent(document, 'touchstart', this.touchstartHandler);
-            },
-            check_direction: function () {
-                x_magnitude = Math.abs(this.start_x - this.stop_x);
-                y_magnitude = Math.abs(this.start_y - this.stop_y);
-                x = ((this.start_x - this.stop_x) < 0) ? "RIGHT" : "LEFT";
-                y = ((this.start_y - this.stop_y) < 0) ? "DOWN" : "UP";
-                result = (x_magnitude > y_magnitude) ? x : y;
-                result = (this.tap === true) ? "TAP" : result;
-                return result;
-            }
-        }
-    }
-
-    typeof callback === "string" && konami.load(callback);
-    if (typeof callback === "function") {
-        konami.code = callback;
-        konami.load();
-    }
-
-    return konami;
-};
-
-
-if (typeof module !== 'undefined' && typeof module.exports !== 'undefined') {
-        module.exports = Konami;
-} else {
-        if (typeof define === 'function' && define.amd) {
-                define([], function() {
-                        return Konami;
-                });
-        } else {
-                window.Konami = Konami;
-        }
-}

docs/source/_templates/hacks.html

@@ -1,200 +1,21 @@
-<link rel="stylesheet" type="text/css" href="https://cloud.typography.com/7584432/7586812/css/fonts.css" />
-<script type="text/javascript">$('#searchbox').hide(0);</script>
-<!--Alabaster (krTheme++) Hacks -->
-
-<!-- CSS Adjustments (I'm very picky.) -->
 <style type="text/css">
-  /* Rezzy requires precise alignment. */
-  img.logo {
-    margin-left: -20px !important;
-  }
-
-  h1 {
-    font-family: "Mercury Text G1 A", "Mercury Text G1 B" !important;
-    font-style: normal !important;
-    font-weight: 600 !important;
-  }
-
-  .section {
-    font-family: "Mercury Text G1 A", "Mercury Text G1 B" !important;
-    font-style: normal !important;
-    font-weight: 400 !important;
-  }
-
-  pre,
-  .class em,
-  .descname,
-  .method em {
-    font-family: "Operator Mono SSm A", "Operator Mono SSm B" !important;
-    font-weight: 400 !important;
-  }
-
-  .property {
-    color: lightgrey !important;
-  }
-
-  .method .descname {
-    color: #220a54;
-  }
-
-  .method {
-
-    margin-bottom: 2em;
-
-  }
-
-  .si,
-  .s2,
-  .s1,
-  .method em,
-  .class em {
-    font-style: italic !important;
-    color: grey;
-  }
-
-  .method em,
-  .class em {
-    margin-left: 0.3em;
-    margin-right: 0.3em;
-  }
-
-  .method p,
-  .class p {
-    font-family: "Mercury Text G1 A", "Mercury Text G1 B";
-    font-style: italic !important;
-    font-weight: 400 !important;
-    font-size: 1.15em;
-  }
-
-  .method p:first,
-  .class p:first {
-    background: #fffcbf;
-  }
-
-  .class .property {
-    display: none;
-  }
-
-
-  /* "Quick Search" should be not be shown for now. */
-  div#searchbox h3 {
-    display: none;
-  }
-
-  /* Make the document a little wider, less code is cut-off. */
+  /* Make the document a little wider. */
   div.document {
     width: 1008px;
   }
 
-  /* Much-improved spacing around code blocks. */
+  /* Better spacing around code blocks. */
   div.highlight pre {
     padding: 11px 14px;
   }
 
-  /* Remain Responsive! */
+  /* Responsive layout. */
   @media screen and (max-width: 1008px) {
     div.sphinxsidebar {
       display: none;
     }
-
     div.document {
       width: 100% !important;
     }
-
-    /* Have code blocks escape the document right-margin. */
-    div.highlight pre {
-      margin-right: -30px;
-    }
   }
 </style>
-
-<!-- Analytics tracking for Kenneth. -->
-<script async src="https://www.googletagmanager.com/gtag/js?id=UA-127383416-1"></script>
-<script>
-  window.dataLayer = window.dataLayer || [];
-  function gtag() { dataLayer.push(arguments); }
-  gtag('js', new Date());
-
-  gtag('config', 'UA-127383416-1');
-</script>
-
-<!-- There are no more hacks. -->
-<!--         இڿڰۣ-ڰۣ—         -->
-<!--   Love, Kenneth Reitz    -->
-
-<script src="{{ pathto('_static/', 1) }}/konami.js"></script>
-<script>
-  var easter_egg = new Konami('https://www.myfortunecookie.co.uk/fortunes/' + (Math.floor(Math.random() * 152) + 1));
-</script>
-
-<style>
-  .injected {
-    display: none !important;
-  }
-</style>
-
-<!-- GitHub Logo -->
-<a href="https://github.com/kennethreitz/responder" class="github-corner" aria-label="View source on GitHub">
-  <svg width="80" height="80" viewBox="0 0 250 250" style="fill:#151513; color:#fff; position: absolute; top: 0; border: 0; right: 0;"
-    aria-hidden="true">
-    <path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path>
-    <path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2"
-      fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path>
-    <path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z"
-      fill="currentColor" class="octo-body"></path>
-  </svg>
-</a>
-<style>
-  .github-corner:hover .octo-arm {
-    animation: octocat-wave 560ms ease-in-out
-  }
-
-  @keyframes octocat-wave {
-
-    0%,
-    100% {
-      transform: rotate(0)
-    }
-
-    20%,
-    60% {
-      transform: rotate(-25deg)
-    }
-
-    40%,
-    80% {
-      transform: rotate(10deg)
-    }
-  }
-
-  @media (max-width:500px) {
-    .github-corner:hover .octo-arm {
-      animation: none
-    }
-
-    .github-corner .octo-arm {
-      animation: octocat-wave 560ms ease-in-out
-    }
-  }
-</style>
-
-
-<!-- That was not a hack. That was art.
-
-<!-- UserVoice JavaScript SDK (only needed once on a page) -->
-<script>(function () { var uv = document.createElement('script'); uv.type = 'text/javascript'; uv.async = true; uv.src = '//widget.uservoice.com/f4AQraEfwInlMzkexfRLg.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(uv, s) })()</script>
-
-<!-- A tab to launch the Classic Widget -->
-<script>
-  UserVoice = window.UserVoice || [];
-  UserVoice.push(['showTab', 'classic_widget', {
-    mode: 'feedback',
-    primary_color: '#fa8c28',
-    link_color: '#0a8cc6',
-    forum_id: 913660,
-    tab_label: 'Got feedback?',
-    tab_color: '#00994f',
-    tab_position: 'bottom-left',
-    tab_inverted: true
-  }]);
-</script>

docs/source/_templates/sidebarintro.html

@@ -1,34 +1,14 @@
 <p class="logo">
   <a href="{{ pathto(master_doc) }}">
-    <img class="logo" src="{{ pathto('_static/responder.png', 1) }}" title="https://kennethreitz.org/tattoos" />
+    <img class="logo" src="{{ pathto('_static/responder.png', 1) }}" />
   </a>
 </p>
-
 <p>
-  <iframe src="https://ghbtns.com/github-btn.html?user=kennethreitz&repo=responder&type=watch&count=true&size=large"
-    allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+  <strong>Responder</strong> — a familiar HTTP service framework for Python.
 </p>
-
-<p>
-  <strong>Responder</strong> is a web service framework, written for human beings.
-</p>
-
-<h3>Stay Informed</h3>
-<p>Receive updates on new releases and upcoming projects.</p>
-
-<p><iframe src="https://ghbtns.com/github-btn.html?user=kennethreitz&type=follow&count=true" allowtransparency="true"
-    frameborder="0" scrolling="0" width="200" height="20"></iframe></p>
-
-<p><a href="https://twitter.com/kennethreitz" class="twitter-follow-button" data-show-count="false">Follow
-    @kennethreitz</a>
-  <script>!function (d, s, id) { var js, fjs = d.getElementsByTagName(s)[0], p = /^http:/.test(d.location) ? 'http' : 'https'; if (!d.getElementById(id)) { js = d.createElement(s); js.id = id; js.src = p + '://platform.twitter.com/widgets.js'; fjs.parentNode.insertBefore(js, fjs); } }(document, 'script', 'twitter-wjs');</script>
-</p>
-
-
 <h3>Useful Links</h3>
 <ul>
-
-  <li><a href="http://github.com/kennethreitz/responder">Responder @ GitHub</a></li>
-  <li><a href="http://pypi.python.org/pypi/responder">Responder @ PyPI</a></li>
-  <li><a href="http://github.com/kennethreitz/responder/issues">Issue Tracker</a></li>
+  <li><a href="https://github.com/kennethreitz/responder">Responder @ GitHub</a></li>
+  <li><a href="https://pypi.org/project/responder/">Responder @ PyPI</a></li>
+  <li><a href="https://github.com/kennethreitz/responder/issues">Issue Tracker</a></li>
 </ul>

docs/source/_templates/sidebarlogo.html

@@ -1,34 +0,0 @@
-<p class="logo">
-  <a href="{{ pathto(master_doc) }}">
-    <img class="logo" src="{{ pathto('_static/responder.png', 1) }}" title="https://kennethreitz.org/tattoos" />
-  </a>
-</p>
-
-<p>
-  <iframe src="https://ghbtns.com/github-btn.html?user=kennethreitz&repo=responder&type=watch&count=true&size=large"
-    allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
-</p>
-
-<p>
-  <strong>Responder</strong> is a web service framework, written for human beings.
-</p>
-
-<h3>Stay Informed</h3>
-<p>Receive updates on new releases and upcoming projects.</p>
-
-<p><iframe src="https://ghbtns.com/github-btn.html?user=kennethreitz&type=follow&count=true" allowtransparency="true"
-    frameborder="0" scrolling="0" width="200" height="20"></iframe></p>
-
-<p><a href="https://twitter.com/kennethreitz" class="twitter-follow-button" data-show-count="false">Follow
-    @kennethreitz</a>
-  <script>!function (d, s, id) { var js, fjs = d.getElementsByTagName(s)[0], p = /^http:/.test(d.location) ? 'http' : 'https'; if (!d.getElementById(id)) { js = d.createElement(s); js.id = id; js.src = p + '://platform.twitter.com/widgets.js'; fjs.parentNode.insertBefore(js, fjs); } }(document, 'script', 'twitter-wjs');</script>
-</p>
-
-
-<h3>Useful Links</h3>
-<ul>
-
-  <li><a href="http://github.com/kennethreitz/responder">Responder @ GitHub</a></li>
-  <li><a href="http://pypi.python.org/pypi/responder">Responder @ PyPI</a></li>
-  <li><a href="http://github.com/kennethreitz/responder/issues">Issue Tracker</a></li>
-</ul>

docs/source/api.rst

@@ -0,0 +1,60 @@
+API Reference
+=============
+
+This page documents Responder's public Python API. For usage examples
+and explanations, see the :doc:`quickstart` and :doc:`tour`.
+
+
+The API Class
+-------------
+
+The central object of every Responder application. It holds your routes,
+middleware, templates, and configuration. Create one at the top of your
+module and use it to define your entire web service.
+
+.. module:: responder
+
+.. autoclass:: API
+    :inherited-members:
+
+
+Request
+-------
+
+The request object is passed into every view as the first argument. It
+gives you access to everything the client sent — headers, query
+parameters, the request body, cookies, and more.
+
+Most properties are synchronous, but reading the body requires ``await``
+because it involves I/O.
+
+.. autoclass:: Request
+    :inherited-members:
+
+
+Response
+--------
+
+The response object is passed into every view as the second argument.
+Mutate it to control what gets sent back to the client — the body,
+status code, headers, and cookies.
+
+.. autoclass:: Response
+    :inherited-members:
+
+
+Status Code Helpers
+-------------------
+
+Convenience functions for checking which category a status code falls
+into. Useful in middleware and after-request hooks.
+
+.. autofunction:: responder.status_codes.is_100
+
+.. autofunction:: responder.status_codes.is_200
+
+.. autofunction:: responder.status_codes.is_300
+
+.. autofunction:: responder.status_codes.is_400
+
+.. autofunction:: responder.status_codes.is_500

docs/source/backlog.md

@@ -0,0 +1,7 @@
+# Backlog
+
+## Future Ideas
+- Consider adding `after_request` hooks (complement to `before_request`)
+- Explore WebSocket before_request short-circuit support
+- Add rate limiting middleware
+- Consider async template rendering by default

docs/source/changes.md

@@ -0,0 +1 @@
+../../CHANGELOG.md

docs/source/cli.rst

@@ -0,0 +1,81 @@
+Command Line Interface
+======================
+
+Responder installs a ``responder`` command that lets you launch
+applications from the terminal. You can point it at a Python module,
+a local file, or even a URL — and it will find your ``API`` instance
+and start serving.
+
+
+Launching from a Module
+-----------------------
+
+The most common way to run a Responder application in production. Use
+Python's standard dotted module path::
+
+    $ responder run acme.app
+
+This imports ``acme.app`` and looks for an attribute called ``api``
+(a ``responder.API`` instance). It's the same import system Python
+uses everywhere — your ``PYTHONPATH`` and virtual environment are
+respected.
+
+
+Launching from a File
+---------------------
+
+During development, you often have a single file you want to run::
+
+    $ responder run helloworld.py
+
+This loads the file directly and starts the server. Quick and easy for
+prototyping and single-file applications.
+
+You can test it with a simple HTTP request::
+
+    $ curl http://127.0.0.1:5042/hello
+    hello, world!
+
+
+Launching from a URL
+--------------------
+
+Responder can fetch and run a Python file from any URL — great for
+demos, sharing examples, and running code from GitHub::
+
+    $ responder run https://github.com/kennethreitz/responder/raw/refs/heads/main/examples/helloworld.py
+
+This also works with ``github://`` URLs and any filesystem protocol
+supported by `fsspec <https://filesystem-spec.readthedocs.io/>`_::
+
+    $ responder run github://kennethreitz:responder@/examples/helloworld.py
+
+Cloud storage is supported too — Azure Blob Storage, Google Cloud
+Storage, S3, HDFS, SFTP, and more. Install ``fsspec[full]`` for all
+protocols::
+
+    $ uv pip install 'fsspec[full]'
+
+
+Custom Instance Names
+---------------------
+
+By default, Responder looks for an attribute called ``api``. If your
+application uses a different name, specify it with a colon::
+
+    $ responder run acme.app:service
+    $ responder run myapp.py:application
+
+For URLs, use a fragment::
+
+    $ responder run https://example.com/app.py#service
+
+
+Building Frontend Assets
+-------------------------
+
+If your project includes a JavaScript frontend with a ``package.json``,
+the ``build`` subcommand runs ``npm run build``::
+
+    $ responder build
+    $ responder build /path/to/frontend

docs/source/conf.py

@@ -1,103 +1,35 @@
-# -*- coding: utf-8 -*-
-#
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+# Sphinx configuration for Responder documentation.
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-
-# -- Project information -----------------------------------------------------
-
-project = "responder"
-copyright = "2018, A Kenneth Reitz project"
-author = "Kenneth Reitz"
-
-# The short X.Y version
 import os
 
-# Path hackery to get current version number.
-here = os.path.abspath(os.path.dirname(__file__))
+project = "responder"
+copyright = "2018-2026, Kenneth Reitz"
+author = "Kenneth Reitz"
 
+here = os.path.abspath(os.path.dirname(__file__))
 about = {}
 with open(os.path.join(here, "..", "..", "responder", "__version__.py")) as f:
     exec(f.read(), about)
 
 version = about["__version__"]
-# The full version, including alpha/beta/rc tags
 release = about["__version__"]
 
-
-# -- General configuration ---------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.doctest",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.todo",
-    "sphinx.ext.coverage",
-    "sphinx.ext.mathjax",
-    "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
-    "sphinx.ext.githubpages",
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_design_elements",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
-
-# The master toctree document.
+source_suffix = {".rst": "restructuredtext"}
 master_doc = "index"
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
+language = "en"
 exclude_patterns = []
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
-
-
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
+# Theme
 html_theme = "alabaster"
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
 html_theme_options = {
     "show_powered_by": False,
     "github_user": "kennethreitz",
@@ -105,118 +37,16 @@ html_theme_options = {
     "github_banner": False,
     "show_related": False,
 }
-
-
-html_sidebars = {
-    "index": ["sidebarintro.html", "sourcelink.html", "searchbox.html", "hacks.html"],
-    "**": [
-        "sidebarlogo.html",
-        "localtoc.html",
-        "relations.html",
-        "sourcelink.html",
-        "searchbox.html",
-        "hacks.html",
-    ],
-}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-# html_sidebars = {}
-
-
-# -- Options for HTMLHelp output ---------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "responderdoc"
-
-
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
+html_sidebars = {
+    "index": ["sidebarintro.html", "searchbox.html"],
+    "**": ["sidebarintro.html", "localtoc.html", "searchbox.html"],
 }
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, "responder.tex", "responder Documentation", "Kenneth Reitz", "manual")
-]
+# MyST
+myst_heading_anchors = 3
 
-
-# -- Options for manual page output ------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "responder", "responder Documentation", [author], 1)]
-
-
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "responder",
-        "responder Documentation",
-        author,
-        "responder",
-        "One line description of project.",
-        "Miscellaneous",
-    )
-]
-
-
-# -- Options for Epub output -------------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = project
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#
-# epub_identifier = ''
-
-# A unique identification for the text.
-#
-# epub_uid = ''
-
-# A list of files that should not be packed into the epub file.
-epub_exclude_files = ["search.html"]
-
-
-# -- Extension configuration -------------------------------------------------
-
-# -- Options for intersphinx extension ---------------------------------------
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
-
-# -- Options for todo extension ----------------------------------------------
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+# Copybutton
+copybutton_remove_prompts = True
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True

docs/source/deployment.rst

@@ -0,0 +1,103 @@
+Deployment
+==========
+
+Responder applications are standard `ASGI <https://asgi.readthedocs.io/>`_
+apps. ASGI (Asynchronous Server Gateway Interface) is the modern successor
+to WSGI — it supports async, WebSockets, and HTTP/2. This means you can
+deploy a Responder app anywhere that runs Python, using any ASGI server.
+
+
+Running Locally
+---------------
+
+During development, ``api.run()`` is all you need::
+
+    if __name__ == "__main__":
+        api.run()
+
+This starts a `uvicorn <https://www.uvicorn.org/>`_ server on
+``127.0.0.1:5042``. Uvicorn is a lightning-fast ASGI server built on
+`uvloop <https://uvloop.readthedocs.io/>`_ — it handles thousands of
+concurrent connections efficiently and protects against slowloris attacks,
+making a reverse proxy like nginx optional for many deployments.
+
+
+Docker
+------
+
+Docker is the most common way to package and deploy web applications.
+Here's a minimal Dockerfile::
+
+    FROM python:3.13-slim
+    WORKDIR /app
+    COPY . .
+    RUN pip install responder
+    ENV PORT=80
+    EXPOSE 80
+    CMD ["python", "api.py"]
+
+Build and run::
+
+    $ docker build -t myapi .
+    $ docker run -p 8000:80 myapi
+
+The ``python:3.13-slim`` image is about 150MB — small enough for fast
+deploys but includes everything you need. For even smaller images, you
+can use ``python:3.13-alpine``, though some packages may need extra
+build dependencies.
+
+
+Cloud Platforms
+---------------
+
+Responder automatically honors the ``PORT`` environment variable. When
+``PORT`` is set, the server binds to ``0.0.0.0`` on that port — this is
+the convention that virtually every cloud platform uses.
+
+This means zero configuration on:
+
+- **Fly.io** — ``fly launch`` and you're done
+- **Railway** — push your code, Railway sets ``PORT``
+- **Render** — set start command to ``python api.py``
+- **Google Cloud Run** — containerize and deploy
+- **Azure Container Apps** — same pattern
+- **AWS App Runner** — and here too
+
+The pattern is always the same: deploy your code, set the start command
+to ``python api.py``, and the platform handles the rest.
+
+
+Uvicorn Directly
+----------------
+
+For production deployments where you want more control, bypass
+``api.run()`` and use uvicorn directly::
+
+    $ uvicorn api:api --host 0.0.0.0 --port 8000 --workers 4
+
+The ``--workers`` flag spawns multiple processes, each handling requests
+independently. A good starting point is 2-4 workers per CPU core.
+
+Uvicorn supports many options — SSL certificates, access logging, graceful
+shutdown timeouts, and more. See the
+`uvicorn documentation <https://www.uvicorn.org/deployment/>`_ for details.
+
+
+Reverse Proxy
+-------------
+
+For high-traffic production deployments, you may want a reverse proxy like
+`nginx <https://nginx.org/>`_ or `Caddy <https://caddyserver.com/>`_ in
+front of your application for:
+
+- **SSL/TLS termination** — let the proxy handle HTTPS certificates
+- **Load balancing** — distribute traffic across multiple app instances
+- **Static asset serving** — offload static files to the proxy
+- **Rate limiting** — at the infrastructure level
+
+Responder's ``TrustedHostMiddleware`` and ``HTTPSRedirectMiddleware`` work
+correctly behind proxies that set standard forwarding headers
+(``X-Forwarded-For``, ``X-Forwarded-Proto``).
+
+That said, uvicorn is production-ready on its own. Many applications run
+uvicorn directly without a reverse proxy and do just fine.

docs/source/guide-config.rst

@@ -0,0 +1,172 @@
+Configuration
+=============
+
+Every application needs different settings for different environments —
+debug mode in development, real secrets in production, different database
+URLs for testing. This guide covers how to manage configuration cleanly.
+
+
+Environment Variables
+---------------------
+
+The simplest and most universal approach. Environment variables work
+everywhere — locally, in Docker, on cloud platforms — and keep secrets
+out of your source code::
+
+    import os
+    import responder
+
+    api = responder.API(
+        debug=os.getenv("DEBUG", "false").lower() == "true",
+        secret_key=os.environ["SECRET_KEY"],
+        cors=os.getenv("CORS_ENABLED", "false").lower() == "true",
+    )
+
+Some variables Responder handles automatically:
+
+- ``PORT`` — when set, the server binds to ``0.0.0.0`` on this port
+
+Set variables in your shell::
+
+    $ export SECRET_KEY="your-secret-here"
+    $ export DEBUG=true
+    $ python app.py
+
+Or in a ``.env`` file (don't commit this to git)::
+
+    SECRET_KEY=your-secret-here
+    DEBUG=true
+
+
+Using .env Files
+----------------
+
+For local development, a ``.env`` file is convenient. Install
+``python-dotenv`` and load it at the top of your app::
+
+    $ uv pip install python-dotenv
+
+::
+
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    import os
+    import responder
+
+    api = responder.API(
+        secret_key=os.environ["SECRET_KEY"],
+    )
+
+Add ``.env`` to your ``.gitignore`` — never commit secrets.
+
+
+Configuration Class Pattern
+----------------------------
+
+For larger applications, a configuration class keeps things organized::
+
+    import os
+
+    class Config:
+        SECRET_KEY = os.environ.get("SECRET_KEY", "dev-secret")
+        DEBUG = os.environ.get("DEBUG", "false").lower() == "true"
+        DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///dev.db")
+        CORS_ORIGINS = os.environ.get("CORS_ORIGINS", "").split(",")
+
+    config = Config()
+
+    api = responder.API(
+        debug=config.DEBUG,
+        secret_key=config.SECRET_KEY,
+        cors=bool(config.CORS_ORIGINS[0]),
+        cors_params={"allow_origins": config.CORS_ORIGINS},
+    )
+
+This makes it easy to see all your settings in one place.
+
+
+Secret Key
+----------
+
+The ``secret_key`` is used to sign session cookies. If someone knows your
+secret key, they can forge session data and impersonate any user.
+
+Rules:
+
+- **Never use the default** in production
+- **Generate a random key**: ``python -c "import secrets; print(secrets.token_hex(32))"``
+- **Store it in an environment variable**, not in code
+- **Rotate it** if it's ever compromised (this invalidates all sessions)
+
+::
+
+    api = responder.API(secret_key=os.environ["SECRET_KEY"])
+
+
+Debug Mode
+----------
+
+Debug mode controls error page behavior:
+
+- **On** (``debug=True``): detailed error pages with tracebacks. Never
+  use this in production — it exposes your source code.
+- **Off** (``debug=False``): generic error pages. This is the default.
+
+::
+
+    api = responder.API(debug=True)  # development only
+
+A common pattern is to read it from the environment::
+
+    api = responder.API(debug=os.getenv("DEBUG") == "true")
+
+
+Allowed Hosts
+-------------
+
+In production, always set ``allowed_hosts`` to prevent Host header
+attacks. This should match the domain names your application serves::
+
+    api = responder.API(
+        allowed_hosts=["example.com", "www.example.com"],
+    )
+
+In development, you can use ``["*"]`` (the default) or specific local
+addresses::
+
+    api = responder.API(allowed_hosts=["localhost", "127.0.0.1"])
+
+
+Putting It All Together
+-----------------------
+
+A production-ready configuration setup::
+
+    import os
+    from dotenv import load_dotenv
+
+    load_dotenv()
+
+    import responder
+
+    api = responder.API(
+        debug=os.getenv("DEBUG", "false") == "true",
+        secret_key=os.environ["SECRET_KEY"],
+        allowed_hosts=os.getenv("ALLOWED_HOSTS", "*").split(","),
+        cors=bool(os.getenv("CORS_ORIGINS")),
+        cors_params={
+            "allow_origins": os.getenv("CORS_ORIGINS", "").split(","),
+            "allow_methods": ["GET", "POST", "PUT", "DELETE"],
+        },
+    )
+
+With a ``.env`` file for local development::
+
+    SECRET_KEY=dev-secret-do-not-use-in-prod
+    DEBUG=true
+    ALLOWED_HOSTS=localhost,127.0.0.1
+    CORS_ORIGINS=http://localhost:3000
+
+And environment variables set properly in production (via your cloud
+platform's dashboard, Docker secrets, or a secrets manager).

docs/source/index.rst

@@ -1,31 +1,7 @@
-.. 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.
+Responder
+=========
 
-A familiar HTTP Service Framework
-=================================
-
-|Build Status| |image1| |image2| |image3| |image4| |image5|
-
-.. |Build Status| image:: https://travis-ci.org/kennethreitz/responder.svg?branch=master
-   :target: https://travis-ci.org/kennethreitz/responder
-.. |image1| image:: https://img.shields.io/pypi/v/responder.svg
-   :target: https://pypi.org/project/responder/
-.. |image2| image:: https://img.shields.io/pypi/l/responder.svg
-   :target: https://pypi.org/project/responder/
-.. |image3| image:: https://img.shields.io/pypi/pyversions/responder.svg
-   :target: https://pypi.org/project/responder/
-.. |image4| image:: https://img.shields.io/github/contributors/kennethreitz/responder.svg
-   :target: https://github.com/kennethreitz/responder/graphs/contributors
-.. |image5| image:: https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg
-   :target: https://saythanks.io/to/kennethreitz
-
-The Python world certainly doesn't need more web frameworks. But, it does need more creativity, so I thought I'd
-spread some `Hacktoberfest <https://hacktoberfest.digitalocean.com/>`_ spirit around, bring some of my ideas to the table, and see what I could come up with.
-
-An Example Web Service:
------------------------
+A familiar HTTP Service Framework for Python.
 
 .. code:: python
 
@@ -40,248 +16,115 @@ An Example Web Service:
    if __name__ == '__main__':
        api.run()
 
-That ``async`` declaration is optional.
+Powered by `Starlette`_, `uvicorn`_, and good intentions. The ``async`` is optional.
 
-This gets you a ASGI app, with a production static files server
-pre-installed, jinja2 templating (without additional imports), and a
-production webserver based on uvloop, serving up requests with gzip
-compression automatically.
 
-Testimonials
+The Idea
+--------
+
+If you've ever used `Flask`_, the routing will look familiar. If you've
+used `Falcon`_, the request/response pattern will click immediately. And
+if you've used `Requests`_ — well, you'll feel right at home.
+
+Responder takes these ideas and brings them together. Every view receives
+a request and a response. You read from one and write to the other. No
+return values, no special response classes, no boilerplate.
+
+- ``resp.text`` sends text. ``resp.html`` sends HTML. ``resp.media`` sends JSON.
+- ``resp.file("path")`` serves a file. ``resp.content`` sends raw bytes.
+- ``req.headers`` is case-insensitive. ``req.params`` holds query parameters.
+- ``resp.status_code``, ``req.method``, ``req.url`` — the familiar ones.
+
+Set ``resp.media`` to a dict and the right thing happens. If the client
+asks for YAML, it gets YAML. Content negotiation is automatic.
+
+Responder and `FastAPI`_ are siblings — both built on Starlette, both
+born around the same time, both part of the push that made ASGI the
+future of Python web services. FastAPI went deep on type annotations
+and automatic validation. Responder went for simplicity and a mutable
+request/response pattern. Both projects are better for the other
+existing. Use whichever feels right.
+
+This is a passion project. It exists because building a web framework
+from scratch is one of the best ways to understand how the web works.
+It's a great fit for personal projects, prototyping, teaching, research,
+and anyone who values a clean API over a sprawling ecosystem. If you
+need battle-tested infrastructure at scale, FastAPI and Django will
+serve you well. If you want something small, expressive, and fun to
+work with — welcome.
+
+
+What You Get
 ------------
 
-   “Pleasantly very taken with python-responder.
-   `@kennethreitz <https://twitter.com/kennethreitz>`_ at his absolute
-   best.” —Rudraksh M.K.
+One ``pip install``, batteries included:
 
-..
-
-   “Buckle up!” —Tom Christie of `APIStar`_ and `Django REST Framework`_
-
-   “I love that you are exploring new patterns. Go go go!” — Danny
-   Greenfield, author of `Two Scoops of Django`_
-
-..
-
-   “Love what I have seen while it’s in progress! Many features of
-   Responder are from my wishlist for Flask, and it’s even faster and
-   even easier than Flask!” — Luna C.
+- Mount Flask, Django, or any WSGI/ASGI app at a subroute.
+- Gzip compression, HSTS, CORS, and trusted host validation.
+- Before-request hooks that can short-circuit for auth guards.
+- A test client for fast, in-process testing with pytest.
+- Route parameters with f-string syntax and type convertors.
+- Lifespan context managers for startup and shutdown logic.
+- Custom exception handlers for clean error responses.
+- `GraphQL`_ with Graphene and a built-in GraphiQL IDE.
+- File serving with automatic content-type detection.
+- Sync and async views — ``async`` is always optional.
+- Class-based views with ``on_get``, ``on_post``, ``on_request``.
+- A pleasant API with a single import statement.
+- OpenAPI schema generation with Swagger UI.
+- A production `uvicorn`_ server, ready to deploy.
+- HTTP method filtering for REST APIs.
+- Signed cookie-based sessions.
+- Background tasks in a thread pool.
+- WebSocket support.
 
 
-..
-
-
-   “The most ambitious crossover event in history.” —Pablo Cabezas, `on
-   Tom Christie joining the project`_
-
-.. _APIStar: https://github.com/encode/apistar
-.. _Django REST Framework: https://www.django-rest-framework.org/
-.. _Two Scoops of Django:
-.. _on Tom Christie joining the project: https://twitter.com/pabloteleco/status/1050841098321620992?s=20
-
-More Examples
--------------
-
-Class-based views (and setting some headers and stuff)::
-
-    @api.route("/{greeting}")
-    class GreetingResource:
-        def on_request(req, resp, *, greeting):   # or on_get...
-            resp.text = f"{greeting}, world!"
-            resp.headers.update({'X-Life': '42'})
-            resp.status_code = api.status_codes.HTTP_416
-
-
-Render a template, with arguments::
-
-
-    @api.route("/{greeting}")
-    def greet_world(req, resp, *, greeting):
-        resp.content = api.template("index.html", greeting=greeting)
-
-
-The ``api`` instance is available as an object during template rendering.
-
-Here, you can spawn off a background thread to run any function, out-of-request::
-
-    @api.route("/")
-    def hello(req, resp):
-
-        @api.background.task
-        def sleep(s=10):
-            time.sleep(s)
-            print("slept!")
-
-        sleep()
-        resp.content = "processing"
-
-
-Serve a GraphQL API::
-
-    import graphene
-
-    class Query(graphene.ObjectType):
-        hello = graphene.String(name=graphene.String(default_value="stranger"))
-
-        def resolve_hello(self, info, name):
-            return "Hello " + name
-
-    api.add_route("/graph", graphene.Schema(query=Query))
-
-
-We can then send a query to our service::
-
-    >>> requests = api.session()
-    >>> r = requests.get("http://;/graph", params={"query": "{ hello }"})
-    >>> r.json()
-    {'data': {'hello': 'Hello stranger'}}
-
-
-Or, request YAML back::
-
-    >>> r = requests.get("http://;/graph", params={"query": "{ hello(name:\"john\") }"}, headers={"Accept": "application/x-yaml"})
-    >>> print(r.text)
-    data: {hello: Hello john}
-
-
-
-Want HSTS?
-
-::
-
-    api = responder.API(enable_hsts=True)
-
-
-Boom.
-
-
-Installing Responder
-====================
-
-Install the latest release (might be out of date with the docs a bit):
+Installation
+------------
 
 .. code-block:: shell
 
-    $ pipenv install git+https://github.com/kennethreitz/responder.git#egg=responder
-    ✨🍰✨
+    $ uv pip install responder
+
+Python 3.9 and above. That's it.
 
 
-Or, install from the development branch:
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
 
-.. code-block:: shell
+   quickstart
+   tour
+   deployment
+   testing
+   api
+   cli
 
-    $ pipenv install -e git+https://github.com/kennethreitz/responder.git#egg=responder
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   tutorial-rest
+   tutorial-sqlalchemy
+   tutorial-auth
+   tutorial-websockets
+   tutorial-middleware
+   tutorial-flask
+   guide-config
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Project
+
+   changes
+   Sandbox <sandbox>
+   backlog
 
 
-Only **Python 3.6+** is supported.
-
-
-
-Web Service Performance Charecteristics
----------------------------------------
-
-The objective of these benchmark tests is not testing deployment (like uwsgi vs gunicorn vs uvicorn etc) but instead test the performance of python-response against other popular Python web frameworks.
-
-Methodology
-~~~~~~~~~~~
-
-The results below were gotten running the performance tests on a Lenovo
-W530, Intel(R) Core(TM) i7-3740QM CPU @ 2.70GHz, MEM: 32GB, Linux Mint
-19. I used Python 3.7.0 with the WRK utility with params: wrk -d20s -t10
--c200 (i.e. 10 threads and 200 connections).
-
-1. .. rubric:: Simple “Hello World” benchmark
-      :name: simple-hello-world-benchmark
-
-   | python-responder v0.0.1 (Master branch)
-   | Requests/sec: 1368.23
-   | Transfer/sec: 163.01KB
-
-   | Django v2.1.2 (i18n == False)
-   | Requests/sec: 544.54
-   | Transfer/sec: 103.18KB
-
-   | Django v2.1.2 (i18n == True)
-   | Requests/sec: 535.12
-   | Transfer/sec: 101.38KB
-
-   | Django v2.1.2 (Minimal 1 file Django Application)
-   | https://gist.github.com/aitoehigie/ebcc1d3e460e66cd51e5501fa2636798
-   | Requests/sec: 701.53
-   | Transfer/sec: 99.34KB
-
-   | Flask v1.0.2
-   | Requests/sec: 896.24
-   | Transfer/sec: 144.41KB
-The Basic Idea
---------------
-
-The primary concept here is to bring the nicities 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.text`` sends back unicode, while setting ``resp.content`` sends back bytes.
-- Setting `resp.media` sends back JSON/YAML (``.text``/``.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 to 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 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 unneccessary in production.
-- GraphQL support, via Graphene. The goal here is to have any GraphQL query exposable at any route, magically.
-
-
-Future Ideas
-------------
-
-- Cookie-based sessions are currently an afterthrought, as this is an API framework, but websites are APIs too.
-- If frontend websites are supported, provide an official way to run webpack.
-
-
-API Documentation
-=================
-
-
-Web Service (API) Class
------------------------
-.. module:: responder
-
-.. autoclass:: API
-    :inherited-members:
-
-Requests & Responses
---------------------
-
-
-.. autoclass:: Request
-    :inherited-members:
-
-.. autoclass:: Response
-    :inherited-members:
-
-
-Utility Functions
------------------
-
-.. autofunction:: responder.API.status_codes.is_100
-
-.. autofunction:: responder.API.status_codes.is_200
-
-.. autofunction:: responder.API.status_codes.is_300
-
-.. autofunction:: responder.API.status_codes.is_400
-
-.. autofunction:: responder.API.status_codes.is_500
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. _Starlette: https://www.starlette.io/
+.. _uvicorn: https://www.uvicorn.org/
+.. _Flask: https://flask.palletsprojects.com/
+.. _Falcon: https://falconframework.org/
+.. _FastAPI: https://fastapi.tiangolo.com/
+.. _GraphQL: https://graphql.org/
+.. _Requests: https://requests.readthedocs.io/

docs/source/quickstart.rst

@@ -0,0 +1,378 @@
+Quick Start
+===========
+
+This guide will walk you through the basics of building a web service with
+Responder. By the end, you'll understand how HTTP requests and responses
+work, how to define routes, read data from clients, send data back, render
+HTML templates, and process work in the background.
+
+
+Create a Web Service
+--------------------
+
+Every web application starts with a single object — the application
+instance. In Responder, this is the ``API`` class. It holds your routes,
+middleware, templates, and configuration. Think of it as the central
+nervous system of your web service::
+
+    import responder
+
+    api = responder.API()
+
+That's it. One import, one line. You now have a fully functional ASGI
+application with gzip compression, static file serving, session support,
+and a production-ready server — all wired up and ready to go.
+
+
+Hello World
+-----------
+
+A web service isn't very useful until it can respond to requests. In HTTP,
+a *route* maps a URL path to a function that handles it. When a client
+(like a browser or ``curl``) sends a request to that path, your function
+runs and produces a response.
+
+Here's the simplest possible route::
+
+    @api.route("/")
+    def hello_world(req, resp):
+        resp.text = "hello, world!"
+
+Two things to notice:
+
+1. Every view function receives two arguments: ``req`` (the incoming
+   request) and ``resp`` (the outgoing response).
+2. You don't return anything. Instead, you *mutate* the response object
+   directly. This is a deliberate design choice — it keeps the API
+   consistent whether you're setting text, JSON, headers, cookies, or
+   status codes.
+
+
+Run the Server
+--------------
+
+Start your web service with a single call::
+
+    api.run()
+
+This spins up a production-grade `uvicorn <https://www.uvicorn.org/>`_
+server on port ``5042``, ready for incoming HTTP requests. Open
+``http://localhost:5042`` in your browser and you'll see your hello world
+response.
+
+You can customize the port with ``api.run(port=8000)``. The ``PORT``
+environment variable is also honored automatically — when set, Responder
+binds to ``0.0.0.0`` on that port, which is what cloud platforms expect.
+
+.. note::
+
+   Both sync and async views are supported. The ``async`` keyword is always
+   optional — use it when you need to ``await`` something, like reading a
+   request body or querying a database.
+
+
+Route Parameters
+----------------
+
+Static URLs like ``/about`` are useful, but most applications need dynamic
+routes — URLs that contain variable data, like a user ID or a product slug.
+
+In Responder, you declare route parameters using Python's f-string syntax::
+
+    @api.route("/hello/{who}")
+    def hello_to(req, resp, *, who):
+        resp.text = f"hello, {who}!"
+
+A ``GET`` request to ``/hello/world`` will respond with ``hello, world!``.
+A request to ``/hello/guido`` will respond with ``hello, guido!``.
+
+Route parameters are passed as *keyword-only* arguments (after the ``*``
+in the function signature). This is a Python feature that makes the
+interface explicit — you always know which arguments come from the URL.
+
+
+Type Convertors
+^^^^^^^^^^^^^^^
+
+By default, route parameters are strings. But often you want them as
+integers, UUIDs, or other types. Responder can convert them automatically
+using type annotations in the route pattern::
+
+    @api.route("/add/{a:int}/{b:int}")
+    async def add(req, resp, *, a, b):
+        resp.text = f"{a} + {b} = {a + b}"
+
+Here, ``a`` and ``b`` will arrive as Python ``int`` objects, not strings.
+If someone requests ``/add/3/hello``, they'll get a 404 — the route won't
+match because ``hello`` isn't a valid integer.
+
+Supported types:
+
+- ``str`` — matches any string without slashes (this is the default)
+- ``int`` — matches digits and converts to ``int``
+- ``float`` — matches decimal numbers and converts to ``float``
+- ``uuid`` — matches UUID strings like ``550e8400-e29b-41d4-a716-446655440000``
+- ``path`` — matches any string *including* slashes, useful for file paths
+  like ``/files/{filepath:path}``
+
+
+Sending Responses
+-----------------
+
+When an HTTP server receives a request, it must send back a response. Every
+HTTP response has three parts: a status code (like ``200 OK`` or ``404 Not
+Found``), headers (metadata like ``Content-Type``), and a body (the actual
+data).
+
+Responder lets you set all three by mutating the response object.
+
+**Text and HTML** — the simplest response types. ``resp.text`` sets the
+``Content-Type`` to ``text/plain``, while ``resp.html`` sets it to
+``text/html``::
+
+    resp.text = "plain text response"
+    resp.html = "<h1>HTML response</h1>"
+
+**JSON** — the lingua franca of web APIs. Set ``resp.media`` to any
+JSON-serializable Python object — a dict, a list, whatever — and Responder
+will serialize it to JSON and set the right headers::
+
+    @api.route("/hello/{who}/json")
+    def hello_json(req, resp, *, who):
+        resp.media = {"hello": who}
+
+If the client sends an ``Accept: application/x-yaml`` header, the same data
+will be returned as YAML instead. This is called *content negotiation* —
+the server and client agree on a format. It happens automatically.
+
+**Files** — serve a file from disk. Responder uses Python's ``mimetypes``
+module to figure out the ``Content-Type`` from the file extension::
+
+    resp.file("reports/annual.pdf")
+
+**Raw bytes** — for binary data like images or protocol buffers::
+
+    resp.content = b"\x89PNG\r\n..."
+
+**Status codes** — HTTP status codes tell the client what happened. ``200``
+means success, ``201`` means something was created, ``404`` means not found,
+``500`` means the server broke. Set it directly::
+
+    resp.status_code = 201
+
+**Headers** — HTTP headers carry metadata. Common ones include
+``Content-Type``, ``Cache-Control``, ``Authorization``, and custom
+application headers::
+
+    resp.headers["X-Custom"] = "value"
+
+**Redirects** — tell the client to go somewhere else::
+
+    api.redirect(resp, location="/new-url")
+
+This sends a ``301 Moved Permanently`` response by default. The client's
+browser will automatically follow the redirect.
+
+
+Reading Requests
+----------------
+
+The other half of HTTP is the request — the data the client sends to your
+server. This includes the HTTP method (GET, POST, PUT, DELETE), the URL,
+headers, query parameters, cookies, and optionally a body.
+
+Responder wraps all of this in the ``req`` object.
+
+**Method and URL** — every HTTP request has a method (what the client wants
+to do) and a URL (what resource it's about)::
+
+    req.method      # "get", "post", etc. (lowercase)
+    req.full_url    # "http://example.com/path?q=1"
+    req.url         # parsed URL object
+
+**Headers** — HTTP headers carry metadata from the client, like what
+content types it accepts, authentication tokens, and more. Responder's
+headers dict is case-insensitive, because the HTTP spec says header names
+are case-insensitive::
+
+    req.headers["Content-Type"]
+    req.headers["content-type"]  # same thing
+
+**Query parameters** — the part of the URL after the ``?``. These are
+commonly used for search, filtering, and pagination::
+
+    # GET /search?q=python&page=2
+    req.params["q"]     # "python"
+    req.params["page"]  # "2"
+
+Note that query parameters are always strings. If you need an integer,
+you'll need to convert it yourself: ``int(req.params["page"])``.
+
+**Path parameters** — the dynamic parts of the URL that matched your route
+pattern. These are also available on the request object, which is useful
+in before-request hooks where they aren't passed as function arguments::
+
+    req.path_params["user_id"]  # same as the keyword argument
+
+**Request body** — for POST, PUT, and PATCH requests, the client sends
+data in the body. Since reading the body is an I/O operation, you need to
+``await`` it::
+
+    # JSON body (the most common format for APIs)
+    data = await req.media()
+
+    # Form data (from HTML forms)
+    data = await req.media("form")
+
+    # File uploads (multipart)
+    files = await req.media("files")
+
+    # Raw bytes
+    body = await req.content
+
+    # Raw text
+    text = await req.text
+
+**Other useful properties**::
+
+    req.is_json     # True if the content type is JSON
+    req.cookies     # dict of cookies sent by the client
+    req.session     # session data (a signed, server-side dict)
+    req.client      # (host, port) tuple — the client's IP address
+    req.is_secure   # True if the request came over HTTPS
+
+
+Rendering Templates
+-------------------
+
+While APIs typically return JSON, many web applications need to render
+HTML pages. Responder includes built-in support for
+`Jinja2 <https://jinja.palletsprojects.com/>`_, one of the most popular
+templating engines in the Python ecosystem.
+
+Templates let you write HTML with placeholders that get filled in with
+dynamic data. This keeps your presentation logic (HTML) separate from
+your application logic (Python) — a pattern called
+*separation of concerns*.
+
+The simplest way to render a template is ``api.template()``. Templates
+are loaded from the ``templates/`` directory by default::
+
+    @api.route("/hello/{name}/html")
+    def hello_html(req, resp, *, name):
+        resp.html = api.template("hello.html", name=name)
+
+The template file ``templates/hello.html`` might look like::
+
+    <h1>Hello, {{ name }}!</h1>
+
+The ``{{ name }}`` part is a Jinja2 expression — it gets replaced with
+the value you passed in.
+
+You can also use the ``Templates`` class directly for more control over
+the template directory and configuration::
+
+    from responder.templates import Templates
+
+    templates = Templates(directory="my_templates")
+
+    @api.route("/page")
+    def page(req, resp):
+        resp.html = templates.render("page.html", title="Hello")
+
+For applications that need non-blocking template rendering (rare, but
+useful under extreme load), async rendering is supported::
+
+    templates = Templates(directory="templates", enable_async=True)
+    resp.html = await templates.render_async("page.html", title="Hello")
+
+And for quick one-off templates, you can render a string directly without
+a file::
+
+    resp.html = api.template_string("Hello, {{ name }}!", name="world")
+
+
+Background Tasks
+----------------
+
+Sometimes you want to accept a request, respond immediately, and do the
+actual processing later. This is a common pattern for operations that take
+a long time — sending emails, processing images, updating caches, or
+calling slow external APIs.
+
+Responder makes this easy with background tasks. Decorate any function
+with ``@api.background.task`` and it will run in a thread pool, separate
+from the request/response cycle::
+
+    @api.route("/incoming")
+    async def receive_incoming(req, resp):
+        data = await req.media()
+
+        @api.background.task
+        def process_data(data):
+            """This runs in a background thread."""
+            import time
+            time.sleep(10)  # simulate heavy work
+
+        process_data(data)
+
+        # This response is sent immediately, while process_data
+        # continues running in the background.
+        resp.media = {"status": "accepted"}
+
+The client gets an instant response — the heavy lifting happens after.
+This is the same pattern used by task queues like Celery, but much simpler
+for lightweight use cases where you don't need a full message broker.
+
+.. note::
+
+   Background tasks run in threads, not processes. They share memory with
+   your application, which makes them fast to start but means CPU-intensive
+   work will block the event loop. For heavy computation, consider a proper
+   task queue.
+
+
+Putting It All Together
+-----------------------
+
+Here's a complete, working Responder application that combines everything
+from this guide::
+
+    import responder
+
+    api = responder.API()
+
+    @api.route("/")
+    def index(req, resp):
+        resp.text = "Welcome to the API"
+
+    @api.route("/hello/{name}")
+    def greet(req, resp, *, name):
+        resp.media = {"message": f"hello, {name}!"}
+
+    @api.route("/add/{a:int}/{b:int}")
+    def add(req, resp, *, a, b):
+        resp.media = {"result": a + b}
+
+    @api.route("/echo", methods=["POST"])
+    async def echo(req, resp):
+        data = await req.media()
+        resp.media = {"received": data}
+
+    if __name__ == "__main__":
+        api.run()
+
+Save this as ``app.py``, run it with ``python app.py``, and try::
+
+    $ curl http://localhost:5042/
+    $ curl http://localhost:5042/hello/world
+    $ curl http://localhost:5042/add/3/4
+    $ curl -X POST http://localhost:5042/echo \
+        -H "Content-Type: application/json" -d '{"key": "value"}'
+
+From here, explore the :doc:`tour` for the full range of features, or
+jump into the tutorials:
+
+- :doc:`tutorial-rest` — build a full CRUD API with validation
+- :doc:`tutorial-sqlalchemy` — connect to a database
+- :doc:`tutorial-auth` — add authentication

docs/source/sandbox.md

@@ -0,0 +1,36 @@
+(sandbox)=
+# Development Sandbox
+
+## Setup
+Set up a development sandbox.
+
+Acquire sources and create virtualenv.
+```shell
+git clone https://github.com/kennethreitz/responder.git
+cd responder
+uv venv
+```
+
+Install project in editable mode, including
+all development tools.
+```shell
+uv pip install --upgrade --editable '.[develop,docs,release,test]'
+```
+
+## Operations
+Run tests.
+```shell
+source .venv/bin/activate
+pytest
+```
+
+Format code.
+```shell
+ruff format .
+ruff check --fix .
+```
+
+Documentation authoring.
+```shell
+sphinx-autobuild --open-browser --watch docs/source docs/source docs/build
+```

docs/source/testing.rst

@@ -0,0 +1,286 @@
+Testing
+=======
+
+Responder includes a built-in test client powered by Starlette's
+``TestClient``. You don't need to start a server — tests run in-process,
+making them fast and reliable. There's no separate test server to manage,
+no ports to allocate, and no race conditions to worry about. Just import
+your app and start making requests.
+
+
+Getting Started
+---------------
+
+Given a simple application in ``api.py``::
+
+    import responder
+
+    api = responder.API()
+
+    @api.route("/")
+    def hello(req, resp):
+        resp.text = "hello, world!"
+
+    if __name__ == "__main__":
+        api.run()
+
+You can test it with pytest. Every Responder ``API`` instance has a
+``requests`` property that gives you a test client — use it exactly like
+you'd use ``requests`` or ``httpx``::
+
+    # test_api.py
+    import api as service
+
+    def test_hello():
+        r = service.api.requests.get("/")
+        assert r.text == "hello, world!"
+
+Run your tests::
+
+    $ pytest
+
+That's really all there is to it. No configuration, no test server setup.
+
+
+Using Fixtures
+--------------
+
+For larger test suites, pytest fixtures keep things organized. Create a
+fixture that returns your API instance, and every test gets a fresh
+reference to it::
+
+    import pytest
+    import api as service
+
+    @pytest.fixture
+    def api():
+        return service.api
+
+    def test_hello(api):
+        r = api.requests.get("/")
+        assert r.text == "hello, world!"
+
+    def test_json(api):
+        @api.route("/data")
+        def data(req, resp):
+            resp.media = {"key": "value"}
+
+        r = api.requests.get(api.url_for(data))
+        assert r.json() == {"key": "value"}
+
+The ``api.url_for()`` method generates a URL for a given route endpoint,
+so you don't have to hard-code paths in your tests. If you rename a route
+later, your tests won't break.
+
+
+Testing JSON APIs
+-----------------
+
+Most APIs send and receive JSON. The test client makes this natural — pass
+``json=`` to send a JSON body, and call ``.json()`` on the response to
+parse it::
+
+    def test_create_item(api):
+        @api.route("/items")
+        async def create(req, resp):
+            data = await req.media()
+            resp.media = {"created": data}
+            resp.status_code = 201
+
+        r = api.requests.post(api.url_for(create), json={"name": "widget"})
+        assert r.status_code == 201
+        assert r.json() == {"created": {"name": "widget"}}
+
+You can also test content negotiation by setting the ``Accept`` header::
+
+    r = api.requests.get("/data", headers={"Accept": "application/x-yaml"})
+    assert "key: value" in r.text
+
+
+Testing Request Validation
+--------------------------
+
+If you're using Pydantic models for request validation, you can test
+that invalid inputs are properly rejected::
+
+    from pydantic import BaseModel
+
+    class Item(BaseModel):
+        name: str
+        price: float
+
+    def test_validation(api):
+        @api.route("/items", methods=["POST"], request_model=Item)
+        async def create(req, resp):
+            data = await req.media()
+            resp.media = data
+
+        # Valid request
+        r = api.requests.post("/items", json={"name": "thing", "price": 9.99})
+        assert r.status_code == 200
+
+        # Missing required field
+        r = api.requests.post("/items", json={"name": "thing"})
+        assert r.status_code == 422
+        assert "errors" in r.json()
+
+
+Testing File Uploads
+--------------------
+
+File uploads use the ``files`` parameter, just like the ``requests``
+library. Each file is a tuple of ``(filename, content, content_type)``::
+
+    def test_upload(api):
+        @api.route("/upload")
+        async def upload(req, resp):
+            files = await req.media("files")
+            resp.media = {"received": list(files.keys())}
+
+        files = {"doc": ("report.pdf", b"content", "application/pdf")}
+        r = api.requests.post(api.url_for(upload), files=files)
+        assert r.json() == {"received": ["doc"]}
+
+
+Testing Headers and Cookies
+----------------------------
+
+Check response headers and cookies just like you would with any HTTP
+client::
+
+    def test_headers(api):
+        @api.route("/")
+        def view(req, resp):
+            resp.headers["X-Custom"] = "hello"
+            resp.cookies["session"] = "abc123"
+
+        r = api.requests.get("/")
+        assert r.headers["X-Custom"] == "hello"
+        assert "session" in r.cookies
+
+
+Testing WebSockets
+------------------
+
+WebSocket tests use Starlette's ``TestClient`` directly, since WebSocket
+connections require a different protocol. The ``websocket_connect`` context
+manager gives you a connection you can send and receive on::
+
+    from starlette.testclient import TestClient
+
+    def test_websocket(api):
+        @api.route("/ws", websocket=True)
+        async def ws(ws):
+            await ws.accept()
+            name = await ws.receive_text()
+            await ws.send_text(f"hello, {name}!")
+            await ws.close()
+
+        client = TestClient(api)
+        with client.websocket_connect("/ws") as ws:
+            ws.send_text("world")
+            assert ws.receive_text() == "hello, world!"
+
+
+Testing Error Handling
+----------------------
+
+By default, the test client raises exceptions from your route handlers,
+which is usually what you want — it makes bugs obvious. But when you're
+testing error handling specifically, you want to see the error response
+instead. Disable exception propagation with ``raise_server_exceptions``::
+
+    from starlette.testclient import TestClient
+
+    def test_500(api):
+        @api.route("/fail")
+        def fail(req, resp):
+            raise ValueError("something broke")
+
+        client = TestClient(api, raise_server_exceptions=False)
+        r = client.get(api.url_for(fail))
+        assert r.status_code == 500
+
+If you've registered a custom exception handler, you can test that too::
+
+    def test_custom_error(api):
+        @api.exception_handler(ValueError)
+        async def handle(req, resp, exc):
+            resp.status_code = 400
+            resp.media = {"error": str(exc)}
+
+        @api.route("/fail")
+        def fail(req, resp):
+            raise ValueError("bad input")
+
+        client = TestClient(api, raise_server_exceptions=False)
+        r = client.get(api.url_for(fail))
+        assert r.status_code == 400
+        assert r.json() == {"error": "bad input"}
+
+
+Testing Lifespan Events
+-----------------------
+
+If your app uses startup and shutdown events (for database connections,
+caches, etc.), you need the test client to trigger them. Wrap the client
+in a ``with`` block — startup runs on enter, shutdown runs on exit::
+
+    def test_with_lifespan(api):
+        started = {"value": False}
+
+        @api.on_event("startup")
+        async def on_startup():
+            started["value"] = True
+
+        @api.route("/")
+        def check(req, resp):
+            resp.media = {"started": started["value"]}
+
+        with api.requests as session:
+            r = session.get("http://;/")
+            assert r.json() == {"started": True}
+
+Without the ``with`` block, lifespan events won't fire, which can lead to
+confusing test failures if your routes depend on startup initialization.
+
+
+Testing Before and After Hooks
+------------------------------
+
+Before-request and after-request hooks run automatically during tests,
+just like in production. You can verify their effects on the response::
+
+    def test_hooks(api):
+        @api.route(before_request=True)
+        def add_version(req, resp):
+            resp.headers["X-Version"] = "3.2"
+
+        @api.after_request()
+        def add_timing(req, resp):
+            resp.headers["X-Served-By"] = "responder"
+
+        @api.route("/")
+        def view(req, resp):
+            resp.text = "ok"
+
+        r = api.requests.get("/")
+        assert r.headers["X-Version"] == "3.2"
+        assert r.headers["X-Served-By"] == "responder"
+
+
+Tips
+----
+
+- **Keep tests fast.** The in-process test client is already fast — no
+  network overhead. Avoid ``time.sleep()`` in tests.
+
+- **One API per test** when testing configuration. If you need a specific
+  ``API()`` configuration (like ``cors=True``), create a new instance
+  in the test rather than sharing the fixture.
+
+- Use ``api.url_for()`` instead of hard-coded paths. It's a small
+  thing, but it makes refactoring painless.
+
+- **Test the contract, not the implementation.** Assert on status codes,
+  response bodies, and headers — not on internal state.

docs/source/tour.rst

@@ -0,0 +1,597 @@
+Feature Tour
+============
+
+This section walks through Responder's features in depth. Each section
+explains the concept, shows working code, and explains the design choices
+behind it. If you're new to web development, this is a good place to learn
+how modern web frameworks work under the hood.
+
+
+Method Filtering
+----------------
+
+HTTP defines several *methods* (also called verbs) that describe what a
+client wants to do with a resource. The most common are:
+
+- ``GET`` — retrieve data
+- ``POST`` — create something new
+- ``PUT`` — replace something entirely
+- ``PATCH`` — update part of something
+- ``DELETE`` — remove something
+
+By default, a Responder route matches all methods. This is fine for simple
+endpoints, but REST APIs typically map different methods to different
+operations. Use the ``methods`` parameter to restrict a route::
+
+    @api.route("/items", methods=["GET"])
+    def list_items(req, resp):
+        resp.media = {"items": []}
+
+    @api.route("/items", methods=["POST"], check_existing=False)
+    async def create_item(req, resp):
+        data = await req.media()
+        resp.media = {"created": data}
+
+Note the ``check_existing=False`` — Responder normally prevents you from
+registering two routes with the same path (to catch typos). When you
+intentionally want multiple handlers for the same path with different
+methods, you need to opt in.
+
+
+Class-Based Views
+-----------------
+
+Function-based views are great for simple endpoints, but sometimes you want
+to group related HTTP methods together into a single resource. This is
+where class-based views come in — a pattern popularized by
+`Falcon <https://falconframework.org/>`_.
+
+Responder dispatches to the appropriate method handler based on the HTTP
+method::
+
+    @api.route("/{greeting}")
+    class GreetingResource:
+        def on_get(self, req, resp, *, greeting):
+            resp.text = f"{greeting}, world!"
+
+        def on_post(self, req, resp, *, greeting):
+            resp.media = {"received": greeting}
+
+        def on_request(self, req, resp, *, greeting):
+            """Called on EVERY request, before the method-specific handler."""
+            resp.headers["X-Greeting"] = greeting
+
+The ``on_request`` method is called for all HTTP methods, much like
+middleware scoped to a single route. Method-specific handlers (``on_get``,
+``on_post``, ``on_put``, ``on_delete``, etc.) are called after.
+
+No inheritance required — just define a class with the right method names.
+This is simpler than Django's ``View`` classes and more Pythonic than
+framework-specific base classes.
+
+
+Lifespan Events
+---------------
+
+Real applications need to set up resources when they start (database
+connection pools, ML models, caches) and tear them down when they stop.
+This is called the application *lifespan*.
+
+The modern approach is the *context manager* pattern, where startup and
+shutdown are two halves of the same block::
+
+    from contextlib import asynccontextmanager
+
+    @asynccontextmanager
+    async def lifespan(app):
+        # Startup — runs before the first request
+        print("connecting to database...")
+        yield
+        # Shutdown — runs after the server stops
+        print("closing connections...")
+
+    api = responder.API(lifespan=lifespan)
+
+Everything before ``yield`` runs at startup. Everything after runs at
+shutdown. If startup fails, the server won't start. If shutdown raises,
+it's logged but the server still exits.
+
+The traditional event decorator style also works::
+
+    @api.on_event("startup")
+    async def startup():
+        print("starting up")
+
+    @api.on_event("shutdown")
+    async def shutdown():
+        print("shutting down")
+
+The context manager is preferred for new code — it keeps related startup
+and shutdown logic together and makes resource cleanup more explicit.
+
+
+Serving Files
+-------------
+
+Web applications often need to serve files — downloads, reports, images.
+Responder makes this simple with ``resp.file()``, which reads a file from
+disk and sets the ``Content-Type`` header automatically using Python's
+``mimetypes`` module::
+
+    @api.route("/download")
+    def download(req, resp):
+        resp.file("reports/annual.pdf")
+
+You can override the content type if the automatic detection isn't right::
+
+    @api.route("/image")
+    def image(req, resp):
+        resp.file("photos/cat.jpg", content_type="image/jpeg")
+
+For large files, use ``resp.stream_file()`` to avoid loading the entire
+file into memory. This streams the file in chunks::
+
+    @api.route("/export")
+    def export(req, resp):
+        resp.stream_file("data/export.csv")
+
+
+Custom Error Handling
+---------------------
+
+In production, you don't want your users to see raw Python tracebacks.
+Responder lets you register custom handlers for specific exception types,
+so you can return clean, structured error responses::
+
+    @api.exception_handler(ValueError)
+    async def handle_value_error(req, resp, exc):
+        resp.status_code = 400
+        resp.media = {"error": str(exc)}
+
+Now, any route that raises a ``ValueError`` will return a clean JSON
+response with a 400 status code instead of a generic 500 error page.
+
+This is a common pattern in API development — you define your own exception
+classes for different error conditions, register handlers for each, and
+your API always returns consistent, machine-readable error responses.
+
+
+Before-Request Hooks
+--------------------
+
+Sometimes you need to run the same code before every request —
+authentication checks, request logging, adding common headers, or setting
+up per-request state. Before-request hooks let you do this without
+duplicating code in every route::
+
+    @api.route(before_request=True)
+    def add_headers(req, resp):
+        resp.headers["X-API-Version"] = "3.2"
+
+**Short-circuiting** is the really powerful part. If your hook sets
+``resp.status_code``, the route handler is skipped entirely and the
+response is sent immediately. This is the pattern for authentication::
+
+    @api.route(before_request=True)
+    def auth_check(req, resp):
+        if "Authorization" not in req.headers:
+            resp.status_code = 401
+            resp.media = {"error": "unauthorized"}
+
+If the ``Authorization`` header is missing, the client gets a 401 response
+and the actual route handler never runs. This is cleaner than adding
+auth checks to every individual route.
+
+
+After-Request Hooks
+-------------------
+
+The complement to before-request hooks. After-request hooks run after the
+route handler completes but before the response is sent. They're useful
+for logging, adding response headers, or any post-processing::
+
+    @api.after_request()
+    def log_response(req, resp):
+        print(f"{req.method} {req.full_url} -> {resp.status_code}")
+
+    @api.after_request()
+    async def add_timing(req, resp):
+        resp.headers["X-Served-By"] = "responder"
+
+
+WebSocket Support
+-----------------
+
+HTTP is a request-response protocol — the client asks, the server answers.
+But some applications need real-time, bidirectional communication: chat
+apps, live dashboards, multiplayer games, collaborative editors.
+
+`WebSockets <https://en.wikipedia.org/wiki/WebSocket>`_ solve this by
+upgrading an HTTP connection into a persistent, full-duplex channel where
+both sides can send messages at any time::
+
+    @api.route("/ws", websocket=True)
+    async def websocket(ws):
+        await ws.accept()
+        while True:
+            name = await ws.receive_text()
+            await ws.send_text(f"Hello {name}!")
+        await ws.close()
+
+You can send and receive in multiple formats:
+
+- ``send_text`` / ``receive_text`` — plain text strings
+- ``send_json`` / ``receive_json`` — JSON objects (auto-serialized)
+- ``send_bytes`` / ``receive_bytes`` — raw binary data
+
+WebSocket routes are marked with ``websocket=True`` in the route decorator.
+They receive a ``ws`` object instead of ``req`` and ``resp``.
+
+
+Server-Sent Events (SSE)
+-------------------------
+
+SSE is a simpler alternative to WebSockets for *one-way* real-time
+communication — the server pushes events to the client, but the client
+can't send messages back. This is perfect for live feeds, progress bars,
+notification streams, and AI response streaming.
+
+Unlike WebSockets, SSE works over plain HTTP, is automatically reconnected
+by the browser, and doesn't require any special client-side libraries::
+
+    @api.route("/events")
+    async def events(req, resp):
+        @resp.sse
+        async def stream():
+            for i in range(10):
+                yield {"data": f"message {i}"}
+
+On the client side, you consume SSE events with JavaScript's built-in
+``EventSource`` API::
+
+    const source = new EventSource("/events");
+    source.onmessage = (event) => {
+        console.log(event.data);
+    };
+
+Each yielded value can be a string (treated as data) or a dict with the
+standard SSE fields::
+
+    yield {"event": "update", "data": "hello", "id": "1", "retry": "5000"}
+    yield "simple string message"
+
+
+GraphQL
+-------
+
+`GraphQL <https://graphql.org/>`_ is a query language for APIs that lets
+clients request exactly the data they need — no more, no less. Instead of
+multiple REST endpoints, you define a schema and let clients query it.
+
+Responder includes built-in GraphQL support via
+`Graphene <https://graphene-python.org/>`_. Set up a full GraphQL endpoint
+with a single method call::
+
+    import graphene
+
+    class Query(graphene.ObjectType):
+        hello = graphene.String(name=graphene.String(default_value="stranger"))
+
+        def resolve_hello(self, info, name):
+            return f"Hello {name}"
+
+    api.graphql("/graphql", schema=graphene.Schema(query=Query))
+
+Visiting ``/graphql`` in a browser renders the
+`GraphiQL <https://github.com/graphql/graphiql>`_ interactive IDE, where
+you can explore your schema, write queries, and see results in real-time.
+Programmatic clients can POST JSON queries to the same endpoint.
+
+You can access the Responder request and response objects in your resolvers
+through ``info.context["request"]`` and ``info.context["response"]``.
+
+
+OpenAPI Documentation
+---------------------
+
+`OpenAPI <https://www.openapis.org/>`_ (formerly Swagger) is the industry
+standard for describing REST APIs. An OpenAPI specification lets you
+auto-generate interactive documentation, client libraries, and validation
+logic.
+
+Responder generates OpenAPI specs from your code::
+
+    api = responder.API(
+        title="Pet Store",
+        version="1.0",
+        openapi="3.0.2",
+        docs_route="/docs",
+    )
+
+This gives you:
+
+- An OpenAPI schema at ``/schema.yml``
+- Interactive Swagger UI documentation at ``/docs``
+
+There are three ways to document your endpoints.
+
+**Pydantic models** — the recommended approach. Use ``request_model`` and
+``response_model`` to annotate your routes, and Responder generates the
+schema automatically. When ``request_model`` is set, request bodies are
+also validated automatically — invalid inputs get a ``422`` response with
+detailed error messages::
+
+    from pydantic import BaseModel
+
+    class PetIn(BaseModel):
+        name: str
+        age: int = 0
+
+    class PetOut(BaseModel):
+        id: int
+        name: str
+        age: int
+
+    @api.route("/pets", methods=["POST"],
+               request_model=PetIn, response_model=PetOut)
+    async def create_pet(req, resp):
+        data = await req.media()
+        resp.media = {"id": 1, **data}
+
+When ``response_model`` is set, the response is serialized through the
+model — extra fields are stripped and types are enforced.
+
+**YAML docstrings** — for full control, embed OpenAPI YAML in the
+docstring::
+
+    @api.route("/pets")
+    def list_pets(req, resp):
+        """A list of pets.
+        ---
+        get:
+            description: Get all pets
+            responses:
+                200:
+                    description: A list of pets
+        """
+        resp.media = [{"name": "Fido"}]
+
+**Marshmallow schemas** — if you're already using marshmallow::
+
+    from marshmallow import Schema, fields
+
+    @api.schema("Pet")
+    class PetSchema(Schema):
+        name = fields.Str()
+
+All three approaches can be mixed in the same API. You can choose from
+multiple documentation themes: ``swagger_ui`` (default), ``redoc``,
+``rapidoc``, or ``elements``.
+
+
+Route Groups
+------------
+
+As your application grows, you'll want to organize routes logically.
+Route groups let you share a URL prefix across related endpoints — a
+common pattern for API versioning::
+
+    v1 = api.group("/v1")
+
+    @v1.route("/users")
+    def list_users(req, resp):
+        resp.media = []
+
+    @v1.route("/users/{user_id:int}")
+    def get_user(req, resp, *, user_id):
+        resp.media = {"id": user_id}
+
+    v2 = api.group("/v2")
+
+    @v2.route("/users")
+    def list_users_v2(req, resp):
+        resp.media = {"users": [], "total": 0}
+
+This keeps your code organized without affecting the routing logic.
+
+
+Mounting Other Apps
+-------------------
+
+Responder can mount any WSGI or ASGI application at a subroute. This is
+incredibly useful for gradual migrations — you can run Flask and Responder
+side by side, moving routes over one at a time::
+
+    from flask import Flask
+
+    flask_app = Flask(__name__)
+
+    @flask_app.route("/")
+    def hello():
+        return "Hello from Flask!"
+
+    api.mount("/flask", flask_app)
+
+Requests to ``/flask/`` will be handled by Flask. Everything else goes
+through Responder. Both WSGI and ASGI apps are supported — Responder
+wraps WSGI apps in an ASGI adapter automatically.
+
+
+Cookies
+-------
+
+`Cookies <https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies>`_ are
+small pieces of data that the server asks the browser to store and send
+back with every subsequent request. They're the foundation of sessions,
+authentication tokens, and user preferences on the web.
+
+Reading and writing cookies is straightforward::
+
+    # Read cookies from the request
+    session_id = req.cookies.get("session_id")
+
+    # Set a cookie on the response
+    resp.cookies["hello"] = "world"
+
+For production use, you'll want to set security directives. The
+``httponly`` flag prevents JavaScript from reading the cookie (defending
+against XSS attacks), and ``secure`` ensures it's only sent over HTTPS::
+
+    resp.set_cookie(
+        "token",
+        value="abc123",
+        max_age=3600,        # expires in 1 hour
+        secure=True,         # HTTPS only
+        httponly=True,        # no JavaScript access
+        path="/",
+    )
+
+
+Cookie-Based Sessions
+---------------------
+
+Sessions let you store per-user data across multiple requests. Responder's
+built-in sessions are cookie-based — the session data is serialized, signed
+with your secret key, and stored in a cookie. The signature prevents
+tampering: if someone modifies the cookie, the signature won't match and
+the data will be rejected::
+
+    @api.route("/login")
+    def login(req, resp):
+        resp.session["username"] = "alice"
+
+    @api.route("/profile")
+    def profile(req, resp):
+        resp.media = {"user": req.session.get("username")}
+
+.. warning::
+
+   Always set a secret key in production. The default key is not secret::
+
+       api = responder.API(secret_key="your-secret-key-here")
+
+
+Static Files
+------------
+
+Most web applications serve static assets — CSS stylesheets, JavaScript
+files, images, fonts. Responder serves these from the ``static/`` directory
+by default::
+
+    api = responder.API(static_dir="static", static_route="/static")
+
+Place your assets in the ``static/`` directory and they'll be served
+automatically at ``/static/style.css``, ``/static/app.js``, etc.
+
+For single-page applications (React, Vue, Angular), you can serve
+``index.html`` as the default response for all unmatched routes::
+
+    api.add_route("/", static=True)
+
+
+CORS
+----
+
+`CORS <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_ (Cross-
+Origin Resource Sharing) is a security mechanism that controls which
+websites can make requests to your API. Browsers enforce this — if your
+API is at ``api.example.com`` and your frontend is at ``app.example.com``,
+the browser will block requests unless your API explicitly allows it.
+
+Enable CORS and configure which origins are allowed::
+
+    api = responder.API(cors=True, cors_params={
+        "allow_origins": ["https://app.example.com"],
+        "allow_methods": ["GET", "POST"],
+        "allow_headers": ["*"],
+        "allow_credentials": True,
+        "max_age": 600,
+    })
+
+The default policy is restrictive — you must explicitly allow each origin.
+Using ``["*"]`` for allow_origins permits any website to call your API,
+which is fine for public APIs but not for private ones.
+
+
+HSTS
+----
+
+`HSTS <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security>`_
+(HTTP Strict Transport Security) tells browsers to always use HTTPS when
+communicating with your server. Once a browser sees the HSTS header, it
+will refuse to connect over plain HTTP, even if the user types ``http://``
+in the address bar::
+
+    api = responder.API(enable_hsts=True)
+
+
+Trusted Hosts
+-------------
+
+The ``Host`` header in an HTTP request tells the server which domain name
+the client used. Attackers can forge this header to trick your application
+into generating URLs to malicious domains (a class of attack called *Host
+header injection*).
+
+Restrict which hostnames your application accepts::
+
+    api = responder.API(allowed_hosts=["example.com", "*.example.com"])
+
+Requests with unrecognized hosts get a ``400 Bad Request``. Wildcard
+patterns are supported. By default, all hostnames are allowed.
+
+
+Request ID
+----------
+
+In distributed systems, tracing a single request across multiple services
+is essential for debugging. Request IDs are unique identifiers attached to
+each request — if something goes wrong, you can search your logs for that
+ID and find every related event.
+
+Responder can auto-generate request IDs. If the client sends an
+``X-Request-ID`` header (common in microservice architectures), it's
+forwarded. Otherwise, a new UUID is generated::
+
+    api = responder.API(request_id=True)
+
+The ID appears in the ``X-Request-ID`` response header.
+
+
+Rate Limiting
+-------------
+
+Rate limiting prevents individual clients from overwhelming your API with
+too many requests. It's essential for public APIs, and good practice even
+for internal ones.
+
+Responder includes a built-in token bucket rate limiter::
+
+    from responder.ext.ratelimit import RateLimiter
+
+    limiter = RateLimiter(requests=100, period=60)  # 100 req/min
+    limiter.install(api)
+
+When the limit is exceeded, clients receive a ``429 Too Many Requests``
+response with a ``Retry-After`` header. Every response includes
+``X-RateLimit-Limit`` and ``X-RateLimit-Remaining`` headers so clients
+can pace themselves.
+
+The rate limiter is per-client, keyed by IP address.
+
+
+MessagePack
+-----------
+
+`MessagePack <https://msgpack.org/>`_ is a binary serialization format
+that's more compact and faster to parse than JSON. It's useful for
+high-throughput APIs, IoT devices, and anywhere bandwidth matters.
+
+Responder supports MessagePack alongside JSON and YAML::
+
+    # Decode a MessagePack request body
+    data = await req.media("msgpack")
+
+Content negotiation works too — clients can send
+``Accept: application/x-msgpack`` to receive MessagePack responses
+instead of JSON.

docs/source/tutorial-auth.rst

@@ -0,0 +1,191 @@
+Authentication
+==============
+
+Every API that handles user data needs authentication — a way to verify
+who is making a request. This guide covers the most common patterns:
+API keys, JWT tokens, and how to build reusable auth guards with
+Responder's before-request hooks.
+
+
+API Key Authentication
+----------------------
+
+The simplest approach. The client sends a secret key in a header, and
+your server checks it against a known value. This is common for
+server-to-server communication and simple APIs::
+
+    API_KEYS = {"sk-abc123", "sk-def456"}
+
+    @api.route(before_request=True)
+    def check_api_key(req, resp):
+        key = req.headers.get("X-API-Key")
+        if key not in API_KEYS:
+            resp.status_code = 401
+            resp.media = {"error": "Invalid or missing API key"}
+
+Because the before-request hook sets ``resp.status_code``, the route
+handler is skipped entirely for unauthorized requests. The client never
+reaches your endpoint — the guard catches them first.
+
+The client sends the key like this::
+
+    $ curl -H "X-API-Key: sk-abc123" http://localhost:5042/protected
+
+
+Bearer Token Authentication
+----------------------------
+
+Bearer tokens are the standard for modern APIs. The client sends a token
+in the ``Authorization`` header, and the server validates it. The most
+common format is `JWT <https://jwt.io/>`_ (JSON Web Tokens).
+
+Install PyJWT::
+
+    $ uv pip install pyjwt
+
+Create a helper to encode and decode tokens::
+
+    import jwt
+    from datetime import datetime, timedelta
+
+    SECRET = "your-secret-key"
+
+    def create_token(user_id: int) -> str:
+        payload = {
+            "sub": user_id,
+            "exp": datetime.utcnow() + timedelta(hours=24),
+        }
+        return jwt.encode(payload, SECRET, algorithm="HS256")
+
+    def verify_token(token: str) -> dict | None:
+        try:
+            return jwt.decode(token, SECRET, algorithms=["HS256"])
+        except jwt.InvalidTokenError:
+            return None
+
+Add a login endpoint that issues tokens, and a before-request hook that
+verifies them::
+
+    @api.route("/login", methods=["POST"])
+    async def login(req, resp):
+        data = await req.media()
+        # In a real app, check credentials against a database
+        if data.get("username") == "admin" and data.get("password") == "secret":
+            token = create_token(user_id=1)
+            resp.media = {"token": token}
+        else:
+            resp.status_code = 401
+            resp.media = {"error": "Invalid credentials"}
+
+    @api.route(before_request=True)
+    def auth_guard(req, resp):
+        # Skip auth for the login endpoint itself
+        if req.url.path == "/login":
+            return
+
+        auth = req.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            resp.status_code = 401
+            resp.media = {"error": "Missing bearer token"}
+            return
+
+        token = auth[7:]  # Strip "Bearer "
+        payload = verify_token(token)
+        if payload is None:
+            resp.status_code = 401
+            resp.media = {"error": "Invalid or expired token"}
+            return
+
+        # Store the authenticated user on the request state
+        req.state.user_id = payload["sub"]
+
+Now any route can access the authenticated user::
+
+    @api.route("/me")
+    def get_me(req, resp):
+        resp.media = {"user_id": req.state.user_id}
+
+The client flow:
+
+1. ``POST /login`` with credentials → receive a token
+2. Include ``Authorization: Bearer <token>`` on every subsequent request
+3. The token expires after 24 hours — the client must log in again
+
+
+Skipping Auth for Public Routes
+--------------------------------
+
+The example above skips auth for ``/login`` by checking the path. For
+more control, you can use a set of public paths::
+
+    PUBLIC_PATHS = {"/login", "/signup", "/health", "/docs", "/schema.yml"}
+
+    @api.route(before_request=True)
+    def auth_guard(req, resp):
+        if req.url.path in PUBLIC_PATHS:
+            return
+        # ... check token
+
+
+Custom Exception for Auth Errors
+---------------------------------
+
+For cleaner code, define a custom exception and register a handler::
+
+    class AuthError(Exception):
+        def __init__(self, message="Unauthorized", status_code=401):
+            self.message = message
+            self.status_code = status_code
+
+    @api.exception_handler(AuthError)
+    async def handle_auth_error(req, resp, exc):
+        resp.status_code = exc.status_code
+        resp.media = {"error": exc.message}
+
+Now your auth guard can simply raise::
+
+    @api.route(before_request=True)
+    def auth_guard(req, resp):
+        if req.url.path in PUBLIC_PATHS:
+            return
+        if "Authorization" not in req.headers:
+            raise AuthError("Missing authorization header")
+
+
+Using Sessions for Web Apps
+----------------------------
+
+For traditional web applications (with HTML pages and forms), cookie-based
+sessions are simpler than tokens. The browser handles cookies automatically
+— no client-side token management needed::
+
+    @api.route("/login", methods=["POST"])
+    async def login(req, resp):
+        data = await req.media("form")
+        if data["username"] == "admin" and data["password"] == "secret":
+            resp.session["user"] = data["username"]
+            api.redirect(resp, location="/dashboard")
+        else:
+            resp.status_code = 401
+            resp.html = "<p>Invalid credentials</p>"
+
+    @api.route("/dashboard")
+    def dashboard(req, resp):
+        user = req.session.get("user")
+        if not user:
+            api.redirect(resp, location="/login")
+            return
+        resp.html = f"<h1>Welcome, {user}!</h1>"
+
+    @api.route("/logout")
+    def logout(req, resp):
+        resp.session.clear()
+        api.redirect(resp, location="/login")
+
+Remember to set a proper secret key::
+
+    api = responder.API(secret_key="your-production-secret-key")
+
+The session data is signed (not encrypted) — users can read it but
+can't tamper with it. Don't store sensitive data like passwords in
+sessions.

docs/source/tutorial-flask.rst

@@ -0,0 +1,192 @@
+Migrating from Flask
+====================
+
+If you're coming from Flask, you'll find Responder familiar but different
+in a few key ways. This guide maps Flask concepts to their Responder
+equivalents and shows you how to translate common patterns.
+
+
+The Big Differences
+-------------------
+
+**No return values.** In Flask, you return a response. In Responder, you
+mutate it. This is the single biggest difference:
+
+Flask::
+
+    @app.route("/")
+    def hello():
+        return "hello, world!"
+
+Responder::
+
+    @api.route("/")
+    def hello(req, resp):
+        resp.text = "hello, world!"
+
+**Explicit request and response.** Flask uses a global ``request`` object
+(via thread-local magic). Responder passes ``req`` and ``resp`` explicitly.
+No magic, no import needed — they're right there in the function signature.
+
+**ASGI, not WSGI.** Flask runs on WSGI, which is synchronous. Responder
+runs on ASGI, which supports async natively. You can still write sync
+views — Responder runs them in a thread pool automatically.
+
+
+Quick Reference
+---------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Flask
+     - Responder
+   * - ``Flask(__name__)``
+     - ``responder.API()``
+   * - ``return "text"``
+     - ``resp.text = "text"``
+   * - ``return jsonify(data)``
+     - ``resp.media = data``
+   * - ``return render_template("t.html", x=1)``
+     - ``resp.html = api.template("t.html", x=1)``
+   * - ``request.args["q"]``
+     - ``req.params["q"]``
+   * - ``request.json``
+     - ``await req.media()``
+   * - ``request.form``
+     - ``await req.media("form")``
+   * - ``request.headers["X"]``
+     - ``req.headers["X"]``
+   * - ``request.method``
+     - ``req.method``
+   * - ``request.cookies["x"]``
+     - ``req.cookies["x"]``
+   * - ``session["x"] = 1``
+     - ``resp.session["x"] = 1``
+   * - ``abort(404)``
+     - ``resp.status_code = 404``
+   * - ``redirect("/new")``
+     - ``api.redirect(resp, location="/new")``
+   * - ``@app.before_request``
+     - ``@api.route(before_request=True)``
+   * - ``@app.errorhandler(404)``
+     - ``@api.exception_handler(ValueError)``
+   * - ``app.run(debug=True)``
+     - ``api.run(debug=True)``
+
+
+Route Parameters
+----------------
+
+Flask uses ``<angle_brackets>``. Responder uses ``{curly_braces}``
+with the same type convertor idea:
+
+Flask::
+
+    @app.route("/users/<int:user_id>")
+    def get_user(user_id):
+        return jsonify({"id": user_id})
+
+Responder::
+
+    @api.route("/users/{user_id:int}")
+    def get_user(req, resp, *, user_id):
+        resp.media = {"id": user_id}
+
+Note the ``*`` — route parameters are keyword-only arguments in
+Responder. This makes the interface explicit about which arguments
+come from the URL.
+
+
+JSON APIs
+---------
+
+Flask::
+
+    @app.route("/api/items", methods=["POST"])
+    def create_item():
+        data = request.json
+        # ... create item
+        return jsonify(item), 201
+
+Responder::
+
+    @api.route("/api/items", methods=["POST"])
+    async def create_item(req, resp):
+        data = await req.media()
+        # ... create item
+        resp.media = item
+        resp.status_code = 201
+
+The ``await`` is needed because reading the request body is an async
+I/O operation. This is more explicit than Flask's approach, and it
+means the event loop isn't blocked while waiting for the body to arrive.
+
+
+Templates
+---------
+
+Both use Jinja2. The syntax is nearly identical:
+
+Flask::
+
+    @app.route("/hello/<name>")
+    def hello(name):
+        return render_template("hello.html", name=name)
+
+Responder::
+
+    @api.route("/hello/{name}")
+    def hello(req, resp, *, name):
+        resp.html = api.template("hello.html", name=name)
+
+
+Blueprints → Route Groups
+--------------------------
+
+Flask uses Blueprints to organize routes. Responder has route groups:
+
+Flask::
+
+    bp = Blueprint("api", __name__, url_prefix="/api")
+
+    @bp.route("/users")
+    def list_users():
+        return jsonify([])
+
+    app.register_blueprint(bp)
+
+Responder::
+
+    api_v1 = api.group("/api")
+
+    @api_v1.route("/users")
+    def list_users(req, resp):
+        resp.media = []
+
+
+Gradual Migration
+-----------------
+
+You don't have to migrate all at once. Responder can mount your existing
+Flask app at a subroute, so you can move endpoints over one at a time::
+
+    from flask import Flask
+
+    flask_app = Flask(__name__)
+
+    # Your existing Flask routes stay here
+    @flask_app.route("/legacy")
+    def legacy():
+        return "old endpoint"
+
+    # Mount Flask under /old, new routes go on Responder
+    api.mount("/old", flask_app)
+
+    @api.route("/new")
+    def new_endpoint(req, resp):
+        resp.media = {"modern": True}
+
+Requests to ``/old/legacy`` go to Flask. Everything else goes to
+Responder. When you've moved everything over, remove the mount.

docs/source/tutorial-middleware.rst

@@ -0,0 +1,129 @@
+Writing Middleware
+=================
+
+Middleware sits between the server and your route handlers, processing
+every request and response that flows through your application. It's the
+right tool for cross-cutting concerns — things that apply to *all*
+requests, not just specific routes.
+
+Common middleware use cases:
+
+- Request logging and timing
+- Authentication and authorization
+- Adding security headers
+- Request ID generation
+- Rate limiting
+- Response compression (built-in)
+
+
+Hooks vs. Middleware
+--------------------
+
+Responder gives you two levels of request processing:
+
+**Hooks** (``before_request`` / ``after_request``) run inside Responder's
+routing layer. They receive Responder's ``req`` and ``resp`` objects and
+are the simplest way to add behavior::
+
+    @api.route(before_request=True)
+    def add_header(req, resp):
+        resp.headers["X-Powered-By"] = "Responder"
+
+    @api.after_request()
+    def log_request(req, resp):
+        print(f"{req.method} {req.url.path} -> {resp.status_code}")
+
+**Middleware** runs at the ASGI level, wrapping the entire application.
+It's more powerful but more complex — you work with raw ASGI scopes
+instead of Responder objects. Use middleware when you need to process
+requests *before* they reach Responder's routing, or when you need to
+integrate with Starlette middleware.
+
+
+Using Starlette Middleware
+--------------------------
+
+Responder is built on Starlette, so any Starlette middleware works
+out of the box::
+
+    from starlette.middleware.base import BaseHTTPMiddleware
+
+    class TimingMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request, call_next):
+            import time
+            start = time.time()
+            response = await call_next(request)
+            duration = time.time() - start
+            response.headers["X-Response-Time"] = f"{duration:.3f}s"
+            return response
+
+    api.add_middleware(TimingMiddleware)
+
+The ``dispatch`` method receives a Starlette ``Request`` and a
+``call_next`` function. Call ``call_next(request)`` to pass the request
+to the next middleware (or to your route handler). The return value is
+a Starlette ``Response`` that you can modify before it's sent.
+
+
+Built-in Middleware
+-------------------
+
+Responder configures several middleware components automatically:
+
+- **GZipMiddleware** — compresses responses larger than 500 bytes
+- **TrustedHostMiddleware** — validates the ``Host`` header
+- **ServerErrorMiddleware** — catches unhandled exceptions
+- **ExceptionMiddleware** — routes exceptions to your handlers
+- **SessionMiddleware** — manages signed cookie sessions
+
+Optional middleware you can enable:
+
+- **CORSMiddleware** — ``api = responder.API(cors=True)``
+- **HTTPSRedirectMiddleware** — ``api = responder.API(enable_hsts=True)``
+
+
+Adding Third-Party Middleware
+-----------------------------
+
+Any ASGI middleware can be added with ``api.add_middleware()``::
+
+    from some_package import SomeMiddleware
+
+    api.add_middleware(SomeMiddleware, option1="value", option2=True)
+
+Keyword arguments are passed to the middleware's constructor.
+
+
+Middleware Order
+----------------
+
+Middleware wraps your application like layers of an onion. The *last*
+middleware added is the *outermost* layer — it sees the request first
+and the response last.
+
+Responder's built-in middleware stack (from outermost to innermost):
+
+1. SessionMiddleware
+2. ServerErrorMiddleware
+3. CORSMiddleware (if enabled)
+4. TrustedHostMiddleware
+5. HTTPSRedirectMiddleware (if enabled)
+6. GZipMiddleware
+7. ExceptionMiddleware
+8. Your routes
+
+When you call ``api.add_middleware()``, your middleware is added *outside*
+the existing stack. Keep this in mind for ordering dependencies — if
+middleware A depends on middleware B having run first, add B before A.
+
+
+When to Use What
+-----------------
+
+- **Simple header additions, logging, auth checks** → use hooks
+- **Response transformation, timing, third-party integrations** → use middleware
+- **Rate limiting** → use the built-in ``RateLimiter`` (it uses hooks internally)
+- **Request ID** → use ``api = responder.API(request_id=True)``
+
+Start with hooks. They're simpler and cover most cases. Graduate to
+middleware when hooks aren't enough.

docs/source/tutorial-rest.rst

@@ -0,0 +1,219 @@
+Building a REST API
+===================
+
+This tutorial walks you through building a complete REST API from scratch.
+By the end, you'll have a working API with CRUD operations, request
+validation, error handling, and interactive documentation.
+
+We'll build a simple book catalog — a service that lets you create, read,
+update, and delete books.
+
+
+Project Setup
+-------------
+
+Create a new file called ``app.py``::
+
+    import responder
+
+    api = responder.API(
+        title="Book Catalog",
+        version="1.0",
+        openapi="3.0.2",
+        docs_route="/docs",
+    )
+
+We're enabling OpenAPI documentation from the start. Visit ``/docs`` at
+any point to see interactive Swagger UI for your API.
+
+
+Define Your Models
+------------------
+
+We'll use `Pydantic <https://docs.pydantic.dev/>`_ to define our data
+models. Pydantic models serve double duty — they validate incoming data
+*and* generate OpenAPI schemas automatically::
+
+    from pydantic import BaseModel
+
+    class BookIn(BaseModel):
+        """What the client sends when creating a book."""
+        title: str
+        author: str
+        year: int
+        isbn: str | None = None
+
+    class Book(BaseModel):
+        """What the API returns."""
+        id: int
+        title: str
+        author: str
+        year: int
+        isbn: str | None = None
+
+``BookIn`` is the *input* model — it doesn't have an ``id`` because the
+server assigns that. ``Book`` is the *output* model — it includes
+everything. This input/output separation is a common REST API pattern.
+
+
+In-Memory Storage
+-----------------
+
+For this tutorial, we'll store books in a simple dict. In a real
+application, you'd use a database (see :doc:`tutorial-sqlalchemy`)::
+
+    books_db: dict[int, dict] = {}
+    next_id = 1
+
+
+List All Books
+--------------
+
+The first endpoint — list all books. This is a ``GET`` request to
+``/books``::
+
+    @api.route("/books", methods=["GET"], response_model=list)
+    def list_books(req, resp):
+        resp.media = list(books_db.values())
+
+In REST API design, ``GET`` requests should never modify data. They're
+*safe* and *idempotent* — calling them multiple times has the same effect
+as calling them once.
+
+
+Create a Book
+-------------
+
+To create a book, the client sends a ``POST`` request with a JSON body.
+We use ``request_model=BookIn`` to validate the input automatically — if
+the client sends bad data, they get a ``422`` response with error details::
+
+    @api.route("/books", methods=["POST"], check_existing=False,
+               request_model=BookIn, response_model=Book)
+    async def create_book(req, resp):
+        global next_id
+        data = await req.media()
+
+        book = {"id": next_id, **data}
+        books_db[next_id] = book
+        next_id += 1
+
+        resp.media = book
+        resp.status_code = 201
+
+Note ``resp.status_code = 201`` — the HTTP ``201 Created`` status code
+tells the client that a new resource was successfully created. This is
+more informative than a generic ``200 OK``.
+
+
+Get a Single Book
+-----------------
+
+Retrieve a specific book by its ID. The ``{book_id:int}`` route parameter
+ensures only integer IDs match — requests like ``/books/abc`` will 404::
+
+    @api.route("/books/{book_id:int}", methods=["GET"], response_model=Book)
+    def get_book(req, resp, *, book_id):
+        if book_id not in books_db:
+            resp.status_code = 404
+            resp.media = {"error": f"Book {book_id} not found"}
+            return
+
+        resp.media = books_db[book_id]
+
+
+Update a Book
+-------------
+
+``PUT`` replaces a resource entirely. The client must send all fields::
+
+    @api.route("/books/{book_id:int}", methods=["PUT"], check_existing=False,
+               request_model=BookIn, response_model=Book)
+    async def update_book(req, resp, *, book_id):
+        if book_id not in books_db:
+            resp.status_code = 404
+            resp.media = {"error": f"Book {book_id} not found"}
+            return
+
+        data = await req.media()
+        book = {"id": book_id, **data}
+        books_db[book_id] = book
+        resp.media = book
+
+
+Delete a Book
+-------------
+
+``DELETE`` removes a resource. The convention is to return ``204 No Content``
+with an empty body on success::
+
+    @api.route("/books/{book_id:int}", methods=["DELETE"], check_existing=False)
+    def delete_book(req, resp, *, book_id):
+        if book_id not in books_db:
+            resp.status_code = 404
+            resp.media = {"error": f"Book {book_id} not found"}
+            return
+
+        del books_db[book_id]
+        resp.status_code = 204
+
+
+Error Handling
+--------------
+
+Let's add a custom error handler so any ``ValueError`` in our code returns
+a clean JSON response instead of a 500 error::
+
+    @api.exception_handler(ValueError)
+    async def handle_value_error(req, resp, exc):
+        resp.status_code = 400
+        resp.media = {"error": str(exc)}
+
+
+Run It
+------
+
+Add the standard entry point at the bottom of your file::
+
+    if __name__ == "__main__":
+        api.run()
+
+Start the server::
+
+    $ python app.py
+
+Visit ``http://localhost:5042/docs`` to see your interactive API
+documentation. You can test every endpoint directly from the browser.
+
+
+Try It Out
+----------
+
+Using ``curl``::
+
+    # Create a book
+    $ curl -X POST http://localhost:5042/books \
+        -H "Content-Type: application/json" \
+        -d '{"title": "Dune", "author": "Frank Herbert", "year": 1965}'
+
+    # List all books
+    $ curl http://localhost:5042/books
+
+    # Get a specific book
+    $ curl http://localhost:5042/books/1
+
+    # Update a book
+    $ curl -X PUT http://localhost:5042/books/1 \
+        -H "Content-Type: application/json" \
+        -d '{"title": "Dune", "author": "Frank Herbert", "year": 1965, "isbn": "978-0441172719"}'
+
+    # Delete a book
+    $ curl -X DELETE http://localhost:5042/books/1
+
+
+What's Next
+-----------
+
+This tutorial used in-memory storage. For a real application, you'll want
+a database. See :doc:`tutorial-sqlalchemy` for how to integrate SQLAlchemy
+with Responder using the lifespan pattern.

docs/source/tutorial-sqlalchemy.rst

@@ -0,0 +1,254 @@
+Using SQLAlchemy
+================
+
+Most real web applications need a database. This guide shows how to
+integrate `SQLAlchemy <https://www.sqlalchemy.org/>`_ with Responder,
+using async support and the lifespan pattern for connection management.
+
+SQLAlchemy is the most popular Python database toolkit. It gives you an
+ORM (Object-Relational Mapper) for working with databases using Python
+classes instead of raw SQL, plus a powerful query builder for when you
+need fine-grained control.
+
+
+Installation
+------------
+
+Install SQLAlchemy with async support and an async database driver.
+We'll use SQLite for simplicity, but the pattern works with PostgreSQL,
+MySQL, and any other database SQLAlchemy supports::
+
+    $ uv pip install 'sqlalchemy[asyncio]' aiosqlite
+
+
+Define Your Models
+------------------
+
+SQLAlchemy models map Python classes to database tables. Each attribute
+becomes a column::
+
+    # models.py
+    from sqlalchemy import Column, Integer, String
+    from sqlalchemy.orm import DeclarativeBase
+
+    class Base(DeclarativeBase):
+        pass
+
+    class Book(Base):
+        __tablename__ = "books"
+
+        id = Column(Integer, primary_key=True, autoincrement=True)
+        title = Column(String, nullable=False)
+        author = Column(String, nullable=False)
+        year = Column(Integer, nullable=False)
+        isbn = Column(String, nullable=True)
+
+``DeclarativeBase`` is SQLAlchemy's modern base class (SQLAlchemy 2.0+).
+Each model class corresponds to a table, and each ``Column`` corresponds
+to a column in that table.
+
+
+Database Setup
+--------------
+
+Create the async engine and session factory. The *engine* manages
+the connection pool. The *session* is your unit of work — you use it to
+query and modify data within a transaction::
+
+    # database.py
+    from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+
+    DATABASE_URL = "sqlite+aiosqlite:///./books.db"
+
+    engine = create_async_engine(DATABASE_URL, echo=True)
+    async_session = async_sessionmaker(engine, expire_on_commit=False)
+
+The ``echo=True`` flag prints all SQL queries to the console — very
+helpful during development, but you'll want to disable it in production.
+
+The ``expire_on_commit=False`` flag keeps model attributes accessible
+after a commit, which is convenient for returning created objects in
+API responses.
+
+
+Lifespan for Startup and Shutdown
+----------------------------------
+
+Use Responder's lifespan context manager to create the database tables
+on startup and dispose of connections on shutdown::
+
+    # app.py
+    from contextlib import asynccontextmanager
+    import responder
+    from database import engine
+    from models import Base
+
+    @asynccontextmanager
+    async def lifespan(app):
+        # Startup: create tables
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+        yield
+        # Shutdown: close all connections
+        await engine.dispose()
+
+    api = responder.API(lifespan=lifespan)
+
+This is the proper way to manage database connections in an async
+application. The lifespan context manager ensures that:
+
+1. Tables are created before the first request
+2. The connection pool is properly closed when the server shuts down
+3. If table creation fails, the server won't start
+
+
+CRUD Endpoints
+--------------
+
+Now let's build the API endpoints. Each one opens a database session,
+does its work, and commits or rolls back::
+
+    from pydantic import BaseModel
+    from sqlalchemy import select
+    from database import async_session
+    from models import Book
+
+    # Pydantic models for request/response validation
+    class BookIn(BaseModel):
+        title: str
+        author: str
+        year: int
+        isbn: str | None = None
+
+    class BookOut(BaseModel):
+        id: int
+        title: str
+        author: str
+        year: int
+        isbn: str | None = None
+
+        class Config:
+            from_attributes = True
+
+The ``from_attributes = True`` config tells Pydantic to read data from
+SQLAlchemy model attributes (not just dicts). This lets you pass a
+SQLAlchemy ``Book`` object directly to ``BookOut``.
+
+**List all books**::
+
+    @api.route("/books", methods=["GET"])
+    async def list_books(req, resp):
+        async with async_session() as session:
+            result = await session.execute(select(Book))
+            books = result.scalars().all()
+            resp.media = [BookOut.model_validate(b).model_dump() for b in books]
+
+**Create a book**::
+
+    @api.route("/books", methods=["POST"], check_existing=False,
+               request_model=BookIn, response_model=BookOut)
+    async def create_book(req, resp):
+        data = await req.media()
+
+        async with async_session() as session:
+            book = Book(**data)
+            session.add(book)
+            await session.commit()
+            await session.refresh(book)
+            resp.media = BookOut.model_validate(book).model_dump()
+            resp.status_code = 201
+
+**Get a single book**::
+
+    @api.route("/books/{book_id:int}", methods=["GET"])
+    async def get_book(req, resp, *, book_id):
+        async with async_session() as session:
+            book = await session.get(Book, book_id)
+            if book is None:
+                resp.status_code = 404
+                resp.media = {"error": "Book not found"}
+                return
+            resp.media = BookOut.model_validate(book).model_dump()
+
+**Update a book**::
+
+    @api.route("/books/{book_id:int}", methods=["PUT"], check_existing=False,
+               request_model=BookIn)
+    async def update_book(req, resp, *, book_id):
+        data = await req.media()
+
+        async with async_session() as session:
+            book = await session.get(Book, book_id)
+            if book is None:
+                resp.status_code = 404
+                resp.media = {"error": "Book not found"}
+                return
+
+            for key, value in data.items():
+                setattr(book, key, value)
+
+            await session.commit()
+            await session.refresh(book)
+            resp.media = BookOut.model_validate(book).model_dump()
+
+**Delete a book**::
+
+    @api.route("/books/{book_id:int}", methods=["DELETE"], check_existing=False)
+    async def delete_book(req, resp, *, book_id):
+        async with async_session() as session:
+            book = await session.get(Book, book_id)
+            if book is None:
+                resp.status_code = 404
+                resp.media = {"error": "Book not found"}
+                return
+
+            await session.delete(book)
+            await session.commit()
+            resp.status_code = 204
+
+
+Run It
+------
+
+::
+
+    if __name__ == "__main__":
+        api.run()
+
+Start the server and you'll see SQLAlchemy's SQL echo in the console.
+The SQLite database file ``books.db`` is created automatically on first
+startup.
+
+
+Using PostgreSQL
+----------------
+
+To switch to PostgreSQL, just change the connection URL and driver::
+
+    $ uv pip install asyncpg
+
+::
+
+    DATABASE_URL = "postgresql+asyncpg://user:pass@localhost/mydb"
+
+Everything else stays the same. SQLAlchemy abstracts the database
+differences so your application code doesn't need to change.
+
+
+Tips
+----
+
+- Use ``async with async_session() as session`` for every request.
+  Don't share sessions across requests — each request should get its
+  own session and transaction.
+
+- For complex queries, use SQLAlchemy's ``select()`` with ``.where()``,
+  ``.order_by()``, ``.limit()``, and ``.offset()`` — it composes
+  naturally.
+
+- In production, use connection pooling (SQLAlchemy does this by
+  default) and set pool size limits appropriate for your database.
+
+- Consider `Alembic <https://alembic.sqlalchemy.org/>`_ for database
+  migrations — it tracks schema changes over time so you can evolve
+  your database without losing data.

docs/source/tutorial-websockets.rst

@@ -0,0 +1,171 @@
+WebSocket Tutorial
+==================
+
+HTTP is request-response — the client asks, the server answers, and the
+connection closes. WebSockets upgrade that into a persistent, bidirectional
+channel where both sides can send messages at any time. This is what powers
+chat apps, live dashboards, multiplayer games, and collaborative editors.
+
+This tutorial builds a simple chat room to show how WebSockets work in
+Responder.
+
+
+How WebSockets Work
+-------------------
+
+1. The client sends a normal HTTP request with an ``Upgrade: websocket``
+   header.
+2. The server accepts the upgrade and the connection switches protocols.
+3. Both sides can now send messages freely — no more request/response.
+4. Either side can close the connection at any time.
+
+In Responder, WebSocket routes receive a ``ws`` object instead of
+``req`` and ``resp``. The ``ws`` object has methods for accepting the
+connection, sending and receiving data, and closing.
+
+
+Echo Server
+-----------
+
+The simplest WebSocket — echoes everything back::
+
+    @api.route("/ws", websocket=True)
+    async def echo(ws):
+        await ws.accept()
+        while True:
+            data = await ws.receive_text()
+            await ws.send_text(f"Echo: {data}")
+
+The ``await ws.accept()`` call completes the WebSocket handshake. After
+that, you're in a loop — receive a message, send a response.
+
+Test it with a WebSocket client::
+
+    $ pip install websocket-client
+    $ python -c "
+    import websocket
+    ws = websocket.create_connection('ws://localhost:5042/ws')
+    ws.send('hello')
+    print(ws.recv())  # Echo: hello
+    ws.close()
+    "
+
+
+Chat Room
+---------
+
+A chat room needs to broadcast messages to all connected clients. We keep
+a set of active connections and iterate through them when someone sends
+a message::
+
+    connected = set()
+
+    @api.route("/chat", websocket=True)
+    async def chat(ws):
+        await ws.accept()
+        connected.add(ws)
+        try:
+            while True:
+                message = await ws.receive_text()
+                # Broadcast to all connected clients
+                for client in connected:
+                    await client.send_text(message)
+        except Exception:
+            pass
+        finally:
+            connected.discard(ws)
+
+The ``try/finally`` block ensures we remove disconnected clients from
+the set, even if the connection drops unexpectedly.
+
+
+Data Formats
+------------
+
+WebSockets support three data formats:
+
+**Text** — plain strings::
+
+    await ws.send_text("hello")
+    message = await ws.receive_text()
+
+**JSON** — auto-serialized Python objects::
+
+    await ws.send_json({"type": "update", "data": [1, 2, 3]})
+    message = await ws.receive_json()
+
+**Binary** — raw bytes, useful for images, audio, or custom protocols::
+
+    await ws.send_bytes(b"\x00\x01\x02")
+    data = await ws.receive_bytes()
+
+
+HTML Client
+-----------
+
+Here's a minimal HTML page that connects to the chat room. The browser's
+built-in ``WebSocket`` API handles everything — no libraries needed:
+
+.. code-block:: html
+
+    <!DOCTYPE html>
+    <html>
+    <body>
+      <div id="messages"></div>
+      <input id="input" placeholder="Type a message..." />
+      <script>
+        const ws = new WebSocket("ws://localhost:5042/chat");
+        const messages = document.getElementById("messages");
+        const input = document.getElementById("input");
+
+        ws.onmessage = (event) => {
+          const p = document.createElement("p");
+          p.textContent = event.data;
+          messages.appendChild(p);
+        };
+
+        input.addEventListener("keypress", (e) => {
+          if (e.key === "Enter") {
+            ws.send(input.value);
+            input.value = "";
+          }
+        });
+      </script>
+    </body>
+    </html>
+
+Save this as ``static/index.html`` and serve it with Responder's
+built-in static file support.
+
+
+Before-Request Hooks for WebSockets
+------------------------------------
+
+You can run code before a WebSocket connection is established, just like
+HTTP before-request hooks. This is useful for authentication::
+
+    @api.before_request(websocket=True)
+    async def ws_auth(ws):
+        # Check for a token in the query string
+        # (WebSocket headers are limited in browsers)
+        await ws.accept()
+
+WebSocket before-request hooks receive the ``ws`` object and must call
+``await ws.accept()`` if they want the connection to proceed.
+
+
+Testing WebSockets
+------------------
+
+Use Starlette's ``TestClient`` for WebSocket tests::
+
+    from starlette.testclient import TestClient
+
+    def test_echo():
+        client = TestClient(api)
+        with client.websocket_connect("/ws") as ws:
+            ws.send_text("hello")
+            assert ws.receive_text() == "Echo: hello"
+
+The ``websocket_connect`` context manager handles the connection
+lifecycle — it connects on enter and disconnects on exit.

examples/helloworld.py

@@ -0,0 +1,19 @@
+# Example HTTP service definition, using Responder.
+# https://pypi.org/project/responder/
+import responder
+
+api = responder.API()
+
+
+@api.route("/")
+async def index(req, resp):
+    resp.text = "hello, world!"
+
+
+@api.route("/{greeting}")
+async def greet_world(req, resp, *, greeting):
+    resp.text = f"{greeting}, world!"
+
+
+if __name__ == "__main__":
+    api.run()

examples/lifespan.py

@@ -0,0 +1,26 @@
+# Example showing the lifespan context manager pattern.
+# https://pypi.org/project/responder/
+from contextlib import asynccontextmanager
+
+import responder
+
+
+@asynccontextmanager
+async def lifespan(app):
+    # Startup: initialize resources
+    print("Starting up...")
+    yield
+    # Shutdown: clean up resources
+    print("Shutting down...")
+
+
+api = responder.API(lifespan=lifespan)
+
+
+@api.route("/{greeting}")
+async def greet_world(req, resp, *, greeting):
+    resp.text = f"{greeting}, world!"
+
+
+if __name__ == "__main__":
+    api.run()

examples/rest_api.py

@@ -0,0 +1,70 @@
+# Complete REST API example with Pydantic validation.
+# https://responder.kennethreitz.org/tutorial-rest.html
+import responder
+from pydantic import BaseModel
+
+
+class BookIn(BaseModel):
+    title: str
+    author: str
+    year: int
+    isbn: str | None = None
+
+
+class BookOut(BaseModel):
+    id: int
+    title: str
+    author: str
+    year: int
+    isbn: str | None = None
+
+
+api = responder.API(
+    title="Book Catalog",
+    version="1.0",
+    openapi="3.0.2",
+    docs_route="/docs",
+)
+
+books_db: dict[int, dict] = {}
+next_id = 1
+
+
+@api.route("/books", methods=["GET"])
+def list_books(req, resp):
+    resp.media = list(books_db.values())
+
+
+@api.route("/books", methods=["POST"], check_existing=False,
+           request_model=BookIn, response_model=BookOut)
+async def create_book(req, resp):
+    global next_id
+    data = await req.media()
+    book = {"id": next_id, **data}
+    books_db[next_id] = book
+    next_id += 1
+    resp.media = book
+    resp.status_code = 201
+
+
+@api.route("/books/{book_id:int}", methods=["GET"])
+def get_book(req, resp, *, book_id):
+    if book_id not in books_db:
+        resp.status_code = 404
+        resp.media = {"error": f"Book {book_id} not found"}
+        return
+    resp.media = books_db[book_id]
+
+
+@api.route("/books/{book_id:int}", methods=["DELETE"], check_existing=False)
+def delete_book(req, resp, *, book_id):
+    if book_id not in books_db:
+        resp.status_code = 404
+        resp.media = {"error": f"Book {book_id} not found"}
+        return
+    del books_db[book_id]
+    resp.status_code = 204
+
+
+if __name__ == "__main__":
+    api.run()