Release 2.5.1

Bumps [urllib3](https://github.com/urllib3/urllib3) from 2.5.0 to 2.6.0.
- [Release notes](https://github.com/urllib3/urllib3/releases)
- [Changelog](https://github.com/urllib3/urllib3/blob/main/CHANGES.rst)
- [Commits](https://github.com/urllib3/urllib3/compare/2.5.0...2.6.0)

---
updated-dependencies:
- dependency-name: urllib3
  dependency-version: 2.6.0
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.coveragerc

@@ -1,5 +0,0 @@
-[run]
-omit=
-    src/microdot_websocket_alt.py
-    src/microdot_asgi_websocket.py
-    src/microdot_ssl.py

.flake8

@@ -1,3 +0,0 @@
-[flake8]
-select = C,E,F,W,B,B950
-per-file-ignores = ./*/__init__.py:F401

.github/FUNDING.yml

@@ -1,3 +0,0 @@
-github: miguelgrinberg
-patreon: miguelgrinberg
-custom: https://paypal.me/miguelgrinberg

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**IMPORTANT**: If you have a question, or you are not sure if you have found a bug in this package, then you are in the wrong place. Hit back in your web browser, and then open a GitHub Discussion instead. Likewise, if you are unable to provide the information requested below, open a discussion to troubleshoot your issue.
+
+**Describe the bug**
+A clear and concise description of what the bug is. If you are getting errors, please include the complete error message, including the stack trace.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: GitHub Discussions
+    url: https://github.com/miguelgrinberg/microdot/discussions
+    about: Ask questions here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/tests.yml

@@ -11,22 +11,23 @@ jobs:
     name: lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
       - run: python -m pip install --upgrade pip wheel
       - run: pip install tox tox-gh-actions
       - run: tox -eflake8
+      - run: tox -edocs
   tests:
     name: tests
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python: ['3.6', '3.7', '3.8', '3.9', '3.10']
+        python: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
         with:
           python-version: ${{ matrix.python }}
       - run: python -m pip install --upgrade pip wheel
@@ -36,27 +37,40 @@ jobs:
     name: tests-micropython
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
       - run: python -m pip install --upgrade pip wheel
       - run: pip install tox tox-gh-actions
       - run: tox -eupy
+  tests-circuitpython:
+    name: tests-circuitpython
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - run: python -m pip install --upgrade pip wheel
+      - run: pip install tox tox-gh-actions
+      - run: tox -ecpy
   coverage:
     name: coverage
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
       - run: python -m pip install --upgrade pip wheel
-      - run: pip install tox tox-gh-actions codecov
+      - run: pip install tox tox-gh-actions
       - run: tox
-      - run: codecov
+      - uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}
   benchmark:
     name: benchmark
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
       - run: python -m pip install --upgrade pip wheel
       - run: pip install tox tox-gh-actions
       - run: tox -ebenchmark

.gitignore

@@ -25,6 +25,8 @@ wheels/
 .installed.cfg
 *.egg
 MANIFEST
+requirements.txt
+requirements-dev.txt
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -90,6 +92,8 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+.direnv
+.envrc
 
 # Spyder project settings
 .spyderproject
@@ -103,3 +107,8 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+# other
+*.der
+*.pem
+*_txt.py

.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CHANGES.md

@@ -1,5 +1,202 @@
 # Microdot change log
 
+**Release 2.5.1** - 2025-12-21
+
+- CSRF: accept cross-site request if origin is in the CORS allowed origin list ([commit](https://github.com/miguelgrinberg/microdot/commit/ba6893ca0fb3c3dd18cf934f8eee893cc2a10daa))
+
+**Release 2.5.0** - 2025-12-21
+
+- CSRF protection [#335](https://github.com/miguelgrinberg/microdot/issues/335) ([commit](https://github.com/miguelgrinberg/microdot/commit/0bae4c9477e9fdb231d1979cc6ed26c31e12b1aa))
+- Added support for ASGI lifespan events [#322](https://github.com/miguelgrinberg/microdot/issues/322) ([commit](https://github.com/miguelgrinberg/microdot/commit/f128b3ded45ccd418a00d199769240342a613b5e))
+- Added `scheme` and `route` attributes to the request object ([commit](https://github.com/miguelgrinberg/microdot/commit/1c7020ca1a3e5a6a1549dc52de38a0b7fd0a439a))
+- Added `Login.get_current_user()` helper method ([commit](https://github.com/miguelgrinberg/microdot/commit/053b8a81380fcdf285592a32e6b590ee50b7d048))
+
+**Release 2.4.0** - 2025-11-08
+
+- SSE: Add support for the retry command and keepalive comments ([commit](https://github.com/miguelgrinberg/microdot/commit/d0808efa6b32e00992596f1bb3d4c3a372df2168))
+- Ignore `expires` and `max_age` arguments if passed to `Response.delete_cookie` [#323](https://github.com/miguelgrinberg/microdot/issues/323) ([commit](https://github.com/miguelgrinberg/microdot/commit/d61785b2e8d18438e5031de9c49e61642e5cfb3f))
+- Ignore "muted" errors during request creation ([commit](https://github.com/miguelgrinberg/microdot/commit/ce9de6e37a6323664eb7666b817932f371f1e099))
+- Add package version to `microdot/__init__.py` file [#312](https://github.com/miguelgrinberg/microdot/issues/312) ([commit](https://github.com/miguelgrinberg/microdot/commit/38f5a27b33c7968fc7414b67742e034e2b9a09ca))
+
+**Release 2.3.5** - 2025-10-18
+
+- Always encode ASGI response bodies to bytes ([commit](https://github.com/miguelgrinberg/microdot/commit/f70c524fb0bdc8c5fef2223c82f5e339445bc5fa))
+- Remove unused instance variable in `Microdot` class ([commit](https://github.com/miguelgrinberg/microdot/commit/27fc03f10047e4483f8d19559025d728b14a27c8))
+
+**Release 2.3.4** - 2025-10-16
+
+- Prevent reading past EOF in multipart parser [#309](https://github.com/miguelgrinberg/microdot/issues/309) ([commit](https://github.com/miguelgrinberg/microdot/commit/6045390cef8735cbbc9f5f7eee7a3912f00e284d))
+- Generate a valid CORS response when the request is badly formatted [#305](https://github.com/miguelgrinberg/microdot/issues/305) ([commit](https://github.com/miguelgrinberg/microdot/commit/cca0b0f693c909134bc19eb41dfb5a86226e032b))
+- Faster HTTP streaming when using ASGI [#318](https://github.com/miguelgrinberg/microdot/issues/318) ([commit](https://github.com/miguelgrinberg/microdot/commit/7addcf4bb51f1caf57663c5bb4d8cc16ee6391e1))
+- Parse empty cookies [#308](https://github.com/miguelgrinberg/microdot/issues/308) ([commit](https://github.com/miguelgrinberg/microdot/commit/c12d4658091ff7eec1ac67c83bcd51eb38af9db7))
+- Add weather dashboard example [#303](https://github.com/miguelgrinberg/microdot/issues/303) ([commit](https://github.com/miguelgrinberg/microdot/commit/7071358b1f95892b1342226b43411e036be67d3a))
+- Add Python 3.13 and 3.14 to the CI builds ([commit](https://github.com/miguelgrinberg/microdot/commit/e9c9937b41e652876241307307f3e855f4f07379))
+
+**Release 2.3.3** - 2025-07-01
+
+- Handle partial reads in WebSocket class [#294](https://github.com/miguelgrinberg/microdot/issues/294) ([commit](https://github.com/miguelgrinberg/microdot/commit/9bc3dced6c1f582dde0496961d25170b448ad8d7))
+- Add SVG to supported mimetypes [#302](https://github.com/miguelgrinberg/microdot/issues/302) ([commit](https://github.com/miguelgrinberg/microdot/commit/1d419ce59bf7006617109c05dc2d6fc6d1dc8235)) (thanks **Ozuba**!)
+- Do not silence exceptions that occur in the SSE task ([commit](https://github.com/miguelgrinberg/microdot/commit/654a85f46b7dd7a1e94f81193c4a78a8a1e99936))
+- Add Support for SSE responses in the test client ([commit](https://github.com/miguelgrinberg/microdot/commit/f5d3d931edfbacedebf5fdf938ef77c5ee910380))
+- Documentation improvements for the `Request` class ([commit](https://github.com/miguelgrinberg/microdot/commit/3dffa05ffb229813156b71e10a85283bdaa26d5e))
+- Additional documentation for the `URLPattern` class ([commit](https://github.com/miguelgrinberg/microdot/commit/786e5e533748e1343612c97123773aec9a1a99fc))
+- More detailed documentation for route responses ([commit](https://github.com/miguelgrinberg/microdot/commit/dc61470fa959549bb43313906ba6ed9f686babc2))
+- Additional documentation on WebSocket and SSE disconnections ([commit](https://github.com/miguelgrinberg/microdot/commit/7c98c4589de4774a88381b393444c75094532550))
+- More detailed documentation for `current_user` ([commit](https://github.com/miguelgrinberg/microdot/commit/e146e2d08deddf9b924c7657f04db28d71f34221))
+- Add a sub-application example ([commit](https://github.com/miguelgrinberg/microdot/commit/d7a9c535639268e415714b12ac898ae38e516308))
+
+**Release 2.3.2** - 2025-05-08
+
+- Use async error handlers in auth module [#298](https://github.com/miguelgrinberg/microdot/issues/298) ([commit](https://github.com/miguelgrinberg/microdot/commit/d9d7ff0825e4c5fbed6564d3684374bf3937df11))
+
+**Release 2.3.1** - 2025-04-13
+
+- Additional support needed when using `orjson` ([commit](https://github.com/miguelgrinberg/microdot/commit/cd0b3234ddb0c8ff4861d369836ec2aed77494db))
+
+**Release 2.3.0** - 2025-04-12
+
+- Support optional authentication methods ([commit](https://github.com/miguelgrinberg/microdot/commit/f317b15bdbf924007e5e3414e0c626baccc3ede6))
+- Catch SSL exceptions while writing the response [#206](https://github.com/miguelgrinberg/microdot/issues/206) ([commit](https://github.com/miguelgrinberg/microdot/commit/e7ee74d6bba74cfd89b9ddc38f28e02514eb1791))
+- Use `orjson` instead of `json` if available ([commit](https://github.com/miguelgrinberg/microdot/commit/086f2af3deab86d4340f3f1feb9e019de59f351d))
+- Addressed typing warnings from pyright ([commit](https://github.com/miguelgrinberg/microdot/commit/b6f232db1125045d79c444c736a2ae59c5501fdd))
+
+**Release 2.2.0** - 2025-03-22
+
+- Support for `multipart/form-data` requests [#287](https://github.com/miguelgrinberg/microdot/issues/287) ([commit](https://github.com/miguelgrinberg/microdot/commit/11a91a60350518e426b557fae8dffe75912f8823))
+- Support custom path components in URLs ([commit #1](https://github.com/miguelgrinberg/microdot/commit/c92b5ae28222af5a1094f5d2f70a45d4d17653d5) [commit #2](https://github.com/miguelgrinberg/microdot/commit/aa76e6378b37faab52008a8aab8db75f81b29323))
+- Expose the Jinja environment as `Template.jinja_env` ([commit](https://github.com/miguelgrinberg/microdot/commit/953dd9432122defe943f0637bbe7e01f2fc7743f))
+- Simplified urldecode logic ([commit #1](https://github.com/miguelgrinberg/microdot/commit/3bc31f10b2b2d4460c62366013278d87665f0f97) [commit #2](https://github.com/miguelgrinberg/microdot/commit/d203df75fef32c7cc0fe7cc6525e77522b37a289))
+- Additional urldecode tests ([commit](https://github.com/miguelgrinberg/microdot/commit/99f65c0198590c0dfb402c24685b6f8dfba1935d))
+- Documentation improvements ([commit](https://github.com/miguelgrinberg/microdot/commit/c6b99b6d8117d4e40e16d5b953dbf4deb023d24d))
+- Update micropython version used in tests to 1.24.1 ([commit](https://github.com/miguelgrinberg/microdot/commit/4cc2e95338a7de3b03742389004147ee21285621))
+
+**Release 2.1.0** - 2025-02-04
+
+- User login support ([commit](https://github.com/miguelgrinberg/microdot/commit/d807011ad006e53e70c4594d7eac04d03bb08681))
+- Basic and token authentication support ([commit](https://github.com/miguelgrinberg/microdot/commit/675c9787974da926af446974cd96ef224e0ee27f))
+- Added `local` argument to the `app.mount()` method, to define sub-application specific before and after request handlers ([commit](https://github.com/miguelgrinberg/microdot/commit/fd7931e1aec173c60f81dad18c1a102ed8f0e081))
+- Added `Request.url_prefix`, `Request.subapp` and local mounts ([commit](https://github.com/miguelgrinberg/microdot/commit/fd7931e1aec173c60f81dad18c1a102ed8f0e081))
+- Added a front end to the SSE example [#281](https://github.com/miguelgrinberg/microdot/issues/281) ([commit](https://github.com/miguelgrinberg/microdot/commit/d487a73c1ea5b3467e23907618b348ca52e0235c)) (thanks **Maxi**!)
+- Additional ``app.mount()`` unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/cd87abba30206ec6d3928e0aabacb2fccf7baf70))
+
+**Release 2.0.7** - 2024-11-10
+
+- Accept responses with just a status code [#263](https://github.com/miguelgrinberg/microdot/issues/263) ([commit #1](https://github.com/miguelgrinberg/microdot/commit/4eac013087f807cafa244b8a6b7b0ed4c82ff150) [commit #2](https://github.com/miguelgrinberg/microdot/commit/c46e4291061046f1be13f300dd08645b71c16635))
+- Fixed compressed file content-type assignment [#251](https://github.com/miguelgrinberg/microdot/issues/251) ([commit](https://github.com/miguelgrinberg/microdot/commit/482ab6d5ca068d71ea6301f45918946161e9fcc1)) (thanks **Lukas Kremla**!)
+- Better documentation for start_server[#252](https://github.com/miguelgrinberg/microdot/issues/252) ([commit](https://github.com/miguelgrinberg/microdot/commit/0a021462e0c42c249d587a2d600f5a21a408adfc))
+- Fix URLs in documentation [#253](https://github.com/miguelgrinberg/microdot/issues/253) ([commit](https://github.com/miguelgrinberg/microdot/commit/5e5fc5e93e11cbf6e3dc8036494e8732d1815d3e)) (thanks **Stanislav Garanzha**!)
+
+**Release 2.0.6** - 2024-06-18
+
+- Add event ID to the SSE implementation [#213](https://github.com/miguelgrinberg/microdot/issues/213) ([commit](https://github.com/miguelgrinberg/microdot/commit/904d5fcaa2d19d939a719b8e68c4dee3eb470739)) (thanks **Hamsanger**!)
+- Configurable session cookie options [#242](https://github.com/miguelgrinberg/microdot/issues/242) ([commit](https://github.com/miguelgrinberg/microdot/commit/0151611fc84fec450820d673f4c4d70c32c990a7))
+- Improved cookie support in the test client ([commit](https://github.com/miguelgrinberg/microdot/commit/4cb155ee411dc2d9c9f15714cb32b25ba79b156a))
+- Cookie path support in session extension and test client ([commit](https://github.com/miguelgrinberg/microdot/commit/6ffb8a8fe920111c4d8c16e98715a0d5ee2d1da3))
+- Refactor `Session` class to make it more reusable ([commit](https://github.com/miguelgrinberg/microdot/commit/dea79c5ce224dec7858ffef45a42bed442fd3a5a))
+- Use `@functools.wraps` on decorated functions ([commit](https://github.com/miguelgrinberg/microdot/commit/f6876c0d154adcae96098405fb6a1fdf1ea4ec28))
+- Removed outdated import from documentation [#216](https://github.com/miguelgrinberg/microdot/issues/216) ([commit](https://github.com/miguelgrinberg/microdot/commit/6b1fd6191702e7a9ad934fddfcdd0a3cebea7c94)) (thanks **Carlo Colombo**!)
+- Add roadmap details to readme ([commit](https://github.com/miguelgrinberg/microdot/commit/a0ea439def238084c4d68309c0992b66ffd28ad6))
+
+**Release 2.0.5** - 2024-03-09
+
+- Correct handling of 0 as an integer argument (regression from #207) [#212](https://github.com/miguelgrinberg/microdot/issues/212) ([commit](https://github.com/miguelgrinberg/microdot/commit/d0a4cf8fa7dfb1da7466157b18d3329a8cf9a5df))
+
+**Release 2.0.4** - 2024-02-20
+
+- Do not use regexes for parsing simple URLs [#207](https://github.com/miguelgrinberg/microdot/issues/207) ([commit #1](https://github.com/miguelgrinberg/microdot/commit/38262c56d34784401659639b482a4a1224e1e59a) [commit #2](https://github.com/miguelgrinberg/microdot/commit/f6cba2c0f7e18e2f32b5adb779fb037b6c473eab))
+- Added documentation on using alternative uTemplate loaders ([commit](https://github.com/miguelgrinberg/microdot/commit/bf519478cbc6e296785241cd7d01edb23c317cd3))
+- Added CircuitPython builds ([commit](https://github.com/miguelgrinberg/microdot/commit/e44c271bae88f4327d3eda16d8780ac264d1ebab))
+
+**Release 2.0.3** - 2024-01-07
+
+- Add a limit to WebSocket message size [#193](https://github.com/miguelgrinberg/microdot/issues/193) ([commit](https://github.com/miguelgrinberg/microdot/commit/5d188e8c0ddef6ce633ca702dbdd4a90f2799597))
+- Pass keyword arguments to thread executor in the correct way [#195](https://github.com/miguelgrinberg/microdot/issues/195) ([commit](https://github.com/miguelgrinberg/microdot/commit/6712c47400d7c426c88032f65ab74466524eccab))
+- Update uasyncio library used in tests to include new TLS support ([commit](https://github.com/miguelgrinberg/microdot/commit/c8c91e83457d24320f22c9a74e80b15e06b072ca))
+- Documentation improvements ([commit](https://github.com/miguelgrinberg/microdot/commit/b80b6b64d02d21400ca8a5077f5ed1127cc202ae))
+
+**Release 2.0.2** - 2023-12-28
+
+- Support binary data in the SSE extension ([commit](https://github.com/miguelgrinberg/microdot/commit/1fc11193da0d298f5539e2ad218836910a13efb2))
+- Upgrade micropython tests to use v1.22 + initial CircuitPython testing work ([commit](https://github.com/miguelgrinberg/microdot/commit/79452a46992351ccad2c0317c20bf50be0d76641))
+- Improvements to migration guide ([commit](https://github.com/miguelgrinberg/microdot/commit/84842e39c360a8b3ddf36feac8af201fb19bbb0b))
+- Remove spurious async in documentation example [#187](https://github.com/miguelgrinberg/microdot/issues/187) ([commit](https://github.com/miguelgrinberg/microdot/commit/ad368be993e2e3007579f1d3880e36d60c71da92)) (thanks **Tak Tran**!)
+
+**Release 2.0.1** - 2023-12-23
+
+- Addressed some inadvertent mistakes in the template extensions ([commit](https://github.com/miguelgrinberg/microdot/commit/bd18ceb4424e9dfb52b1e6d498edd260aa24fc53))
+
+**Release 2.0.0** - 2023-12-22
+
+- Major redesign [#186](https://github.com/miguelgrinberg/microdot/issues/186) ([commit](https://github.com/miguelgrinberg/microdot/commit/20ea305fe793eb206b52af9eb5c5f3c1e9f57dbb))
+    - Code reorganization as a `microdot` package
+    - Asyncio is now the core implementation
+    - New support for Server-Sent Events (SSE)
+    - Several extensions redesigned
+    - Support for "partitioned" cookies
+    - [Cross-compiling and freezing](https://microdot.readthedocs.io/en/stable/freezing.html) guidance
+    - A [Migration Guide](https://microdot.readthedocs.io/en/stable/migrating.html) to help transition to version 2 from older releases
+
+**Release 1.3.4** - 2023-11-08
+
+- Handle change in `wait_closed()` behavior in Python 3.12 [#177](https://github.com/miguelgrinberg/microdot/issues/177) ([commit](https://github.com/miguelgrinberg/microdot/commit/5550b20cdd347d59e2aa68f6ebf9e9abffaff9fc))
+- Added missing request argument in some documentation examples [#163](https://github.com/miguelgrinberg/microdot/issues/163) ([commit](https://github.com/miguelgrinberg/microdot/commit/744548f8dc33a72512b34c4001ee9c6c1edd22ee))
+- Fix minor documentation typos [#161](https://github.com/miguelgrinberg/microdot/issues/161) ([commit](https://github.com/miguelgrinberg/microdot/commit/2e4911d10826cbb3914de4a45e495c3be36543fa)) (thanks **Andy Piper**!)
+
+**Release 1.3.3** - 2023-07-16
+
+- Handle query string arguments without value [#149](https://github.com/miguelgrinberg/microdot/issues/149) ([commit](https://github.com/miguelgrinberg/microdot/commit/3554bc91cb1523efa5b66fe3ef173f8e86e8c2a0))
+- Support empty responses with ASGI adapter ([commit](https://github.com/miguelgrinberg/microdot/commit/e09e9830f43af41d38775547637558494151a385))
+- Added CORS extension to Python package ([commit](https://github.com/miguelgrinberg/microdot/commit/304ca2ef6881fe718126b3e308211e760109d519))
+- Document access to WSGI and ASGI attributes [#153](https://github.com/miguelgrinberg/microdot/issues/153) ([commit](https://github.com/miguelgrinberg/microdot/commit/d99df2c4010ab70c60b86ab334d656903e04eb26))
+- Upgrade micropython tests to use v1.20 ([commit](https://github.com/miguelgrinberg/microdot/commit/e0f0565551966ee0238a5a1819c78a13639ad704))
+
+**Release 1.3.2** - 2023-06-13
+
+- In ASGI, return headers as strings and not binary [#144](https://github.com/miguelgrinberg/microdot/issues/144) ([commit](https://github.com/miguelgrinberg/microdot/commit/e92310fa55bbffcdcbb33f560e27c3579d7ac451))
+- Incorrect import in `static_async.py` example ([commit](https://github.com/miguelgrinberg/microdot/commit/c07a53943508e64baea160748e67efc92e75b036))
+
+**Release 1.3.1** - 2023-05-21
+
+- Support negative numbers for int path components [#137](https://github.com/miguelgrinberg/microdot/issues/137) ([commit](https://github.com/miguelgrinberg/microdot/commit/a0dd7c8ab6d681932324e56ed101aba861a105a0))
+- Use a more conservative default for socket timeout [#130](https://github.com/miguelgrinberg/microdot/issues/130) ([commit](https://github.com/miguelgrinberg/microdot/commit/239cf4ff37268a7e2467b93be44fe9f91cee8aee))
+- More robust check for socket timeout error code [#106](https://github.com/miguelgrinberg/microdot/issues/106) ([commit](https://github.com/miguelgrinberg/microdot/commit/efec9f14be7b6f3451e4d1d0fe7e528ce6ca74dc))
+- WebSocket error when handling PING packet [#129](https://github.com/miguelgrinberg/microdot/issues/129) ([commit](https://github.com/miguelgrinberg/microdot/commit/87cd098f66e24bed6bbad29b1490a129e355bbb3))
+- Explicitly set UTF-8 encoding for HTML files in examples [#132](https://github.com/miguelgrinberg/microdot/issues/132) ([commit](https://github.com/miguelgrinberg/microdot/commit/f81de6d9582f4905b9c2735d3c639b92d7e77994))
+
+**Release 1.3.0** - 2023-04-08
+
+- Cross-Origin Resource Sharing (CORS) extension [#45](https://github.com/miguelgrinberg/microdot/issues/45) ([commit](https://github.com/miguelgrinberg/microdot/commit/67798f7dbffb30018ab4b62a9aaa297f63bc9e64))
+- Respond to `HEAD` and `OPTIONS` requests ([commit](https://github.com/miguelgrinberg/microdot/commit/6a31f89673518e79fef5659c04e609b7976a5e34))
+- Tolerate slightly invalid formats in query strings [#126](https://github.com/miguelgrinberg/microdot/issues/126) ([commit](https://github.com/miguelgrinberg/microdot/commit/a1b061656fa19dae583951596b0f1f0603652a56))
+- Support compressed files in `send_file()` [#93](https://github.com/miguelgrinberg/microdot/issues/93) ([commit](https://github.com/miguelgrinberg/microdot/commit/daf1001ec55ab38e6cdfee4931729a3b7506858b))
+- Add `max_age` argument to `send_file()` ([commit](https://github.com/miguelgrinberg/microdot/commit/e684ee32d91d3e2ab9569bb5fd342986c010ffeb))
+- Add `update()` method to `NoCaseDict` class ([commit](https://github.com/miguelgrinberg/microdot/commit/ea6766cea96b756b36ed777f9c1b6a6680db09ba))
+- Set exit code to 1 for failed MicroPython test runs ([commit](https://github.com/miguelgrinberg/microdot/commit/a350e8fd1e55fac12c9e5b909cfa82d880b177ef))
+
+**Release 1.2.4** - 2023-03-03
+
+- One more attempt to correct build issues ([commit](https://github.com/miguelgrinberg/microdot/commit/cb39898829f4edc233ab4e7ba3f7ef3c5c50f196))
+
+**Release 1.2.3** - 2023-03-03
+
+- Corrected a problem with previous build.
+
+**Release 1.2.2** - 2023-03-03
+
+- Add a socket read timeout to abort incomplete requests [#99](https://github.com/miguelgrinberg/microdot/issues/99) ([commit](https://github.com/miguelgrinberg/microdot/commit/d0d358f94a63f8565d6406feff0c6e7418cc7f81))
+- More robust timeout handling [#106](https://github.com/miguelgrinberg/microdot/issues/106) ([commit](https://github.com/miguelgrinberg/microdot/commit/4d432a7d6cd88b874a8b825fb62891ed22881f74))
+- Add @after_error_handler decorator [#97](https://github.com/miguelgrinberg/microdot/issues/97) ([commit](https://github.com/miguelgrinberg/microdot/commit/fcaeee69052b5681706f65b022e667baeee30d4d))
+- Return headers as lowercase byte sequences as required by ASGI ([commit](https://github.com/miguelgrinberg/microdot/commit/ddb3b8f442d3683df04554104edaf8acd9c68148))
+- Async example of static file serving ([commit](https://github.com/miguelgrinberg/microdot/commit/680cd9c023352f0ff03d67f1041ea174b7b7385b))
+- Fixing broken links to examples in documentation [#101](https://github.com/miguelgrinberg/microdot/issues/101) ([commit](https://github.com/miguelgrinberg/microdot/commit/c00b24c9436e1b8f3d4c9bb6f2adfca988902e91)) (thanks **Eric Welch**!)
+- Add scrollbar to documentation's left sidebar ([commit](https://github.com/miguelgrinberg/microdot/commit/2aa90d42451dc64c84efcc4f40a1b6c8d1ef1e8d))
+- Documentation typo [#90](https://github.com/miguelgrinberg/microdot/issues/90) ([commit](https://github.com/miguelgrinberg/microdot/commit/81394980234f24aac834faf8e2e8225231e9014b)) (thanks **William Wheeler**!)
+- Add CPU timing to benchmark ([commit](https://github.com/miguelgrinberg/microdot/commit/9398c960752f87bc32d7c4349cbf594e5d678e99))
+- Upgrade uasyncio release used in tests ([commit](https://github.com/miguelgrinberg/microdot/commit/3d6815119ca1ec989f704f626530f938c857a8e5))
+- Update unittest library for MicroPython ([commit](https://github.com/miguelgrinberg/microdot/commit/ecd84ecb7bd3c29d5af96739442b908badeab804))
+- New build of micropython for unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/818f98d9a4e531e01c0f913813425ab2b40c289d))
+- Remove 3.6, add 3.11 to builds ([commit](https://github.com/miguelgrinberg/microdot/commit/dd15d90239b73b5fd413515c9cd4ac23f6d42f67))
+
 **Release 1.2.1** - 2022-12-06
 
 - Error handling invokes parent exceptions [#74](https://github.com/miguelgrinberg/microdot/issues/74) ([commit](https://github.com/miguelgrinberg/microdot/commit/24d74fb8483b04e8abe6e303e06f0a310f32700b)) (thanks **Diego Pomares**!)

MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md LICENSE tox.ini
+recursive-include docs *
+recursive-exclude docs/_build *
+recursive-include tests *
+exclude **/*.pyc

README.md

@@ -3,9 +3,9 @@
 
 *“The impossibly small web framework for Python and MicroPython”*
 
-Microdot is a minimalistic Python web framework inspired by Flask, and designed
-to run on systems with limited resources such as microcontrollers. It runs on
-standard Python and on MicroPython.
+Microdot is a minimalistic Python web framework inspired by Flask. Given its
+small size, it can run on systems with limited resources such as
+microcontrollers. Both standard Python (CPython) and MicroPython are supported.
 
 ```python
 from microdot import Microdot
@@ -13,7 +13,7 @@ from microdot import Microdot
 app = Microdot()
 
 @app.route('/')
-def index(request):
+async def index(request):
     return 'Hello, world!'
 
 app.run()
@@ -21,5 +21,23 @@ app.run()
 
 ## Resources
 
-- [Documentation](https://microdot.readthedocs.io/en/latest/)
 - [Change Log](https://github.com/miguelgrinberg/microdot/blob/main/CHANGES.md)
+- Documentation
+    - [Latest](https://microdot.readthedocs.io/en/latest/)
+    - [Stable (v2)](https://microdot.readthedocs.io/en/stable/)
+- Legacy (v1)
+    - [Code](https://github.com/miguelgrinberg/microdot/tree/v1)
+    - [Documentation](https://microdot.readthedocs.io/en/v1/)
+
+## Roadmap
+
+The following features are planned for future releases of Microdot, both for
+MicroPython and CPython:
+
+- Authentication support, similar to [Flask-Login](https://github.com/maxcountryman/flask-login) for Flask (**Added in version 2.1**)
+- Support for forms encoded in `multipart/form-data` format (**Added in version 2.2**)
+- CSRF protection extension (**Added in version 2.5**)
+- Pub/sub mini-framework for WebSocket and SSE
+- OpenAPI integration, similar to [APIFairy](https://github.com/miguelgrinberg/apifairy) for Flask
+
+Do you have other ideas to propose? Let's [discuss them](https://github.com/:miguelgrinberg/microdot/discussions/new?category=ideas)!

docs/_static/css/custom.css

@@ -1,3 +1,8 @@
 .py.class, .py.function, .py.method, .py.property {
   margin-top: 20px;
 }
+
+div.sphinxsidebar {
+    max-height: 100%;
+    overflow-y: auto;
+}

docs/api.rst

@@ -1,109 +0,0 @@
-API Reference
-=============
-
-``microdot`` module
--------------------
-
-.. autoclass:: microdot.Microdot
-   :members:
-
-.. autoclass:: microdot.Request
-   :members:
-
-.. autoclass:: microdot.Response
-   :members:
-
-.. autoclass:: microdot.NoCaseDict
-   :members:
-
-.. autoclass:: microdot.MultiDict
-   :members:
-
-``microdot_asyncio`` module
----------------------------
-
-.. autoclass:: microdot_asyncio.Microdot
-   :inherited-members:
-   :members:
-
-.. autoclass:: microdot_asyncio.Request
-   :inherited-members:
-   :members:
-
-.. autoclass:: microdot_asyncio.Response
-   :inherited-members:
-   :members:
-
-``microdot_utemplate`` module
------------------------------
-
-.. automodule:: microdot_utemplate
-   :members:
-
-``microdot_jinja`` module
--------------------------
-
-.. automodule:: microdot_jinja
-   :members:
-
-``microdot_session`` module
----------------------------
-
-.. automodule:: microdot_session
-   :members:
-
-``microdot_websocket`` module
-------------------------------
-
-.. automodule:: microdot_websocket
-   :members:
-
-``microdot_asyncio_websocket`` module
--------------------------------------
-
-.. automodule:: microdot_asyncio_websocket
-   :members:
-
-``microdot_asgi_websocket`` module
--------------------------------------
-
-.. automodule:: microdot_asgi_websocket
-   :members:
-
-``microdot_ssl`` module
------------------------
-
-.. automodule:: microdot_ssl
-   :members:
-
-``microdot_test_client`` module
--------------------------------
-
-.. autoclass:: microdot_test_client.TestClient
-   :members:
-
-.. autoclass:: microdot_test_client.TestResponse
-   :members:
-
-``microdot_asyncio_test_client`` module
----------------------------------------
-
-.. autoclass:: microdot_asyncio_test_client.TestClient
-   :members:
-
-.. autoclass:: microdot_asyncio_test_client.TestResponse
-   :members:
-
-``microdot_wsgi`` module
-------------------------
-
-.. autoclass:: microdot_wsgi.Microdot
-   :members:
-   :exclude-members: shutdown, run
-
-``microdot_asgi`` module
-------------------------
-
-.. autoclass:: microdot_asgi.Microdot
-   :members:
-   :exclude-members: shutdown, run

docs/api/asgi.rst

@@ -0,0 +1,6 @@
+ASGI
+----
+
+.. autoclass:: microdot.asgi.Microdot
+   :members:
+   :exclude-members: shutdown, run

docs/api/auth.rst

@@ -0,0 +1,7 @@
+Authentication
+--------------
+
+.. automodule:: microdot.auth
+   :inherited-members:
+   :special-members: __call__
+   :members:

docs/api/cors.rst

@@ -0,0 +1,5 @@
+Cross-Origin Resource Sharing (CORS)
+------------------------------------
+
+.. automodule:: microdot.cors
+   :members:

docs/api/csrf.rst

@@ -0,0 +1,5 @@
+Cross-Site Request Forgery (CSRF) Protection
+--------------------------------------------
+
+.. automodule:: microdot.csrf
+   :members:

docs/api/index.rst

@@ -0,0 +1,21 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   microdot
+   multipart
+   websocket
+   sse
+   utemplate
+   jinja
+   sessions
+   auth
+   login
+   cors
+   csrf
+   test_client
+   asgi
+   wsgi
+

docs/api/jinja.rst

@@ -0,0 +1,5 @@
+Templates (Jinja)
+-----------------
+
+.. automodule:: microdot.jinja
+   :members:

docs/api/login.rst

@@ -0,0 +1,7 @@
+User Logins
+-----------
+
+.. automodule:: microdot.login
+   :inherited-members:
+   :special-members: __call__
+   :members:

docs/api/microdot.rst

@@ -0,0 +1,14 @@
+Core API
+--------
+
+.. autoclass:: microdot.Microdot
+   :members:
+
+.. autoclass:: microdot.Request
+   :members:
+
+.. autoclass:: microdot.Response
+   :members:
+
+.. autoclass:: microdot.URLPattern
+   :members:

docs/api/multipart.rst

@@ -0,0 +1,5 @@
+Multipart Forms
+---------------
+
+.. automodule:: microdot.multipart
+   :members:

docs/api/sessions.rst

@@ -0,0 +1,5 @@
+User Sessions
+-------------
+
+.. automodule:: microdot.session
+   :members:

docs/api/sse.rst

@@ -0,0 +1,5 @@
+Server-Sent Events (SSE)
+------------------------
+
+.. automodule:: microdot.sse
+   :members:

docs/api/test_client.rst

@@ -0,0 +1,5 @@
+Test Client
+-----------
+
+.. automodule:: microdot.test_client
+   :members:

docs/api/utemplate.rst

@@ -0,0 +1,5 @@
+Templates (uTemplate)
+---------------------
+
+.. automodule:: microdot.utemplate
+   :members:

docs/api/websocket.rst

@@ -0,0 +1,5 @@
+WebSocket
+---------
+
+.. automodule:: microdot.websocket
+   :members:

docs/api/wsgi.rst

@@ -0,0 +1,6 @@
+WSGI
+----
+
+.. autoclass:: microdot.wsgi.Microdot
+   :members:
+   :exclude-members: shutdown, run

docs/conf.py

@@ -46,7 +46,8 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'furo'
+html_title = 'Microdot'
 
 # 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,
@@ -58,12 +59,6 @@ html_css_files = [
 ]
 
 html_theme_options = {
-    'github_user': 'miguelgrinberg',
-    'github_repo': 'microdot',
-    'github_banner': True,
-    'github_button': True,
-    'github_type': 'star',
-    'fixed_sidebar': True,
 }
 
 autodoc_default_options = {

docs/contributing.rst

@@ -0,0 +1,7 @@
+Contributing
+------------
+
+Thank you for your interest in Microdot!
+
+Please visit the `GitHub repository <https://github.com/miguelgrinberg/microdot>`_
+to learn about the project and find open issues and pull requests.

docs/extensions.rst

@@ -1,495 +0,0 @@
-Core Extensions
----------------
-
-Microdot is a highly extensible web application framework. The extensions
-described in this section are maintained as part of the Microdot project and
-can be obtained from the same source code repository.
-
-Asynchronous Support with Asyncio
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
-
-   * - Required external dependencies
-     - | CPython: None
-       | MicroPython: `uasyncio <https://github.com/micropython/micropython/tree/master/extmod/uasyncio>`_
-
-   * - Examples
-     - | `hello_async.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_async.py>`_
-
-Microdot can be extended to use an asynchronous programming model based on the
-``asyncio`` package. When the :class:`Microdot <microdot_asyncio.Microdot>`
-class is imported from the ``microdot_asyncio`` package, an asynchronous server
-is used, and handlers can be defined as coroutines.
-
-The example that follows uses ``asyncio`` coroutines for concurrency::
-
-    from microdot_asyncio import Microdot
-
-    app = Microdot()
-
-    @app.route('/')
-    async def hello(request):
-        return 'Hello, world!'
-
-    app.run()
-
-Rendering HTML Templates
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Many web applications use HTML templates for rendering content to clients.
-Microdot includes extensions to render templates with the
-`utemplate <https://github.com/pfalcon/utemplate>`_ package on CPython and
-MicroPython, and with `Jinja <https://jinja.palletsprojects.com/>`_ only on
-CPython.
-
-Using the uTemplate Engine
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_utemplate.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_utemplate.py>`_
-
-   * - Required external dependencies
-     - | `utemplate <https://github.com/pfalcon/utemplate/tree/master/utemplate>`_
-
-   * - Examples
-     - | `hello_utemplate.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_utemplate.py>`_
-       | `hello_utemplate_async.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_utemplate_async.py>`_
-
-The :func:`render_template <microdot_utemplate.render_template>` function is
-used to render HTML templates with the uTemplate engine. The first argument is
-the template filename, relative to the templates directory, which is
-*templates* by default. Any additional arguments are passed to the template
-engine to be used as arguments.
-
-Example::
-
-    from microdot_utemplate import render_template
-
-    @app.get('/')
-    def index(req):
-        return render_template('index.html')
-
-The default location from where templates are loaded is the *templates*
-subdirectory. This location can be changed with the
-:func:`init_templates <microdot_utemplate.init_templates>` function::
-
-    from microdot_utemplate import init_templates
-
-    init_templates('my_templates')
-
-Using the Jinja Engine
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython only
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_jinja.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_jinja.py>`_
-
-   * - Required external dependencies
-     - | `Jinja2 <https://jinja.palletsprojects.com/>`_
-
-   * - Examples
-     - | `hello_jinja.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_jinja.py>`_
-
-The :func:`render_template <microdot_jinja.render_template>` function is used
-to render HTML templates with the Jinja engine. The first argument is the
-template filename, relative to the templates directory, which is *templates* by
-default. Any additional arguments are passed to the template engine to be used
-as arguments.
-
-Example::
-
-    from microdot_jinja import render_template
-
-    @app.get('/')
-    def index(req):
-        return render_template('index.html')
-
-The default location from where templates are loaded is the *templates*
-subdirectory. This location can be changed with the
-:func:`init_templates <microdot_jinja.init_templates>` function::
-
-    from microdot_jinja import init_templates
-
-    init_templates('my_templates')
-
-.. note::
-    The Jinja extension is not compatible with MicroPython.
-
-Maintaing Secure User Sessions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_session.py>`_
-
-   * - Required external dependencies
-     - | CPython: `PyJWT <https://pyjwt.readthedocs.io/>`_
-       | MicroPython: `jwt.py <https://github.com/micropython/micropython-lib/blob/master/python-ecosys/pyjwt/jwt.py>`_,
-                      `hmac <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/hmac/hmac.py>`_
-
-   * - Examples
-     - | `login.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/login.py>`_
-
-The session extension provides a secure way for the application to maintain
-user sessions. The session is stored as a signed cookie in the client's
-browser, in `JSON Web Token (JWT) <https://en.wikipedia.org/wiki/JSON_Web_Token>`_
-format.
-
-To work with user sessions, the application first must configure the secret key
-that will be used to sign the session cookies. It is very important that this
-key is kept secret. An attacker who is in possession of this key can generate
-valid user session cookies with any contents.
-
-To set the secret key, use the :func:`set_session_secret_key <microdot_session.set_session_secret_key>` function::
-
-    from microdot_session import set_session_secret_key
-
-    set_session_secret_key('top-secret!')
-
-To :func:`get_session <microdot_session.get_session>`,
-:func:`update_session <microdot_session.update_session>` and
-:func:`delete_session <microdot_session.delete_session>` functions are used
-inside route handlers to retrieve, store and delete session data respectively.
-The :func:`with_session <microdot_session.with_session>` decorator is provided
-as a convenient way to retrieve the session at the start of a route handler.
-
-Example::
-
-    from microdot import Microdot
-    from microdot_session import set_session_secret_key, with_session, \
-        update_session, delete_session
-
-    app = Microdot()
-    set_session_secret_key('top-secret')
-
-    @app.route('/', methods=['GET', 'POST'])
-    @with_session
-    def index(req, session):
-        username = session.get('username')
-        if req.method == 'POST':
-            username = req.form.get('username')
-            update_session(req, {'username': username})
-            return redirect('/')
-        if username is None:
-            return 'Not logged in'
-        else:
-            return 'Logged in as ' + username
-
-    @app.post('/logout')
-    def logout(req):
-        delete_session(req)
-        return redirect('/')
-
-WebSocket Support
-~~~~~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_websocket.py>`_
-
-   * - Required external dependencies
-     - | None
-
-   * - Examples
-     - | `echo.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo.py>`_
-       | `echo_wsgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_wsgi.py>`_
-
-The WebSocket extension provides a way for the application to handle WebSocket
-requests. The :func:`websocket <microdot_websocket.with_websocket>` decorator
-is used to mark a route handler as a WebSocket handler. The handler receives
-a WebSocket object as a second argument. The WebSocket object provides
-``send()`` and ``receive()`` methods to send and receive messages respectively.
-
-Example::
-
-        @app.route('/echo')
-        @with_websocket
-        def echo(request, ws):
-            while True:
-                message = ws.receive()
-                ws.send(message)
-
-.. note::
-   An unsupported *microdot_websocket_alt.py* module, with the same
-   interface, is also provided. This module uses the native WebSocket support
-   in MicroPython that powers the WebREPL, and may provide slightly better
-   performance for MicroPython low-end boards. This module is not compatible
-   with CPython.
-
-Asynchronous WebSocket
-~~~~~~~~~~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
-       | `microdot_websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_websocket.py>`_
-       | `microdot_asyncio_websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio_websocket.py>`_
-
-   * - Required external dependencies
-     - | CPython: None
-       | MicroPython: `uasyncio <https://github.com/micropython/micropython/tree/master/extmod/uasyncio>`_
-
-   * - Examples
-     - | `echo_async.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_async.py>`_
-
-This extension has the same interface as the synchronous WebSocket extension,
-but the ``receive()`` and ``send()`` methods are asynchronous.
-
-.. note::
-   An unsupported *microdot_asgi_websocket.py* module, with the same
-   interface, is also provided. This module must be used instead of
-   *microdot_asyncio_websocket.py* when the ASGI support is used. The
-   `echo_asgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_asgi.py>`_
-   example shows how to use this module.
-
-HTTPS Support
-~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_ssl.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_ssl.py>`_
-
-   * - Examples
-     - | `hello_tls.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/tls/hello_tls.py>`_
-       | `hello_asyncio_tls.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/tls/hello_asyncio_tls.py>`_
-
-The ``run()`` function accepts an optional ``ssl`` argument, through which an
-initialized ``SSLContext`` object can be passed. MicroPython does not currently
-have a ``SSLContext`` implementation, so the ``microdot_ssl`` module provides
-a basic implementation that can be used to create a context.
-
-Example::
-
-    from microdot import Microdot
-    from microdot_ssl import create_ssl_context
-
-    app = Microdot()
-
-    @app.route('/')
-    def index(req):
-        return 'Hello, World!'
-
-    sslctx = create_ssl_context('cert.der', 'key.der')
-    app.run(port=4443, debug=True, ssl=sslctx)
-
-.. note::
-   The ``microdot_ssl`` module is only needed for MicroPython. When used under
-   CPython, this module creates a standard ``SSLContext`` instance.
-
-.. note::
-   The ``uasyncio`` library for MicroPython does not currently support TLS, so
-   this feature is not available for asynchronous applications on that
-   platform. The ``asyncio`` library for CPython is fully supported.
-
-Test Client
-~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_test_client.py>`_
-
-   * - Required external dependencies
-     - | None
-
-The Microdot Test Client is a utility class that can be used during testing to
-send requests into the application.
-
-Example::
-
-    from microdot import Microdot
-    from microdot_test_client import TestClient
-
-    app = Microdot()
-
-    @app.route('/')
-    def index(req):
-        return 'Hello, World!'
-
-    def test_app():
-        client = TestClient(app)
-        response = client.get('/')
-        assert response.text == 'Hello, World!'
-
-See the documentation for the :class:`TestClient <microdot_test_client.TestClient>`
-class for more details.
-
-Asynchronous Test Client
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
-       | `microdot_test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_test_client.py>`_
-       | `microdot_asyncio_test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio_test_client.py>`_
-
-   * - Required external dependencies
-     - | None
-
-Similar to the :class:`TestClient <microdot_test_client.TestClient>` class
-above, but for asynchronous applications.
-
-Example usage::
-
-    from microdot_asyncio_test_client import TestClient
-
-    async def test_app():
-        client = TestClient(app)
-        response = await client.get('/')
-        assert response.text == 'Hello, World!'
-
-See the :class:`reference documentation <microdot_asyncio_test_client.TestClient>`
-for details.
-
-Deploying on a Production Web Server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``Microdot`` class creates its own simple web server. This is enough for an
-application deployed with MicroPython, but when using CPython it may be useful
-to use a separate, battle-tested web server. To address this need, Microdot
-provides extensions that implement the WSGI and ASGI protocols.
-
-Using a WSGI Web Server
-^^^^^^^^^^^^^^^^^^^^^^^
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython only
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_wsgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_wsgi.py>`_
-
-   * - Required external dependencies
-     - | A WSGI web server, such as `Gunicorn <https://gunicorn.org/>`_.
-
-   * - Examples
-     - | `hello_wsgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_wsgi.py>`_
-
-
-The ``microdot_wsgi`` module provides an extended ``Microdot`` class that
-implements the WSGI protocol and can be used with a compliant WSGI web server
-such as `Gunicorn <https://gunicorn.org/>`_ or
-`uWSGI <https://uwsgi-docs.readthedocs.io/en/latest/>`_.
-
-To use a WSGI web server, the application must import the
-:class:`Microdot <microdot_wsgi.Microdot>` class from the ``microdot_wsgi``
-module::
-
-    from microdot_wsgi import Microdot
-
-    app = Microdot()
-
-    @app.route('/')
-    def index(req):
-        return 'Hello, World!'
-
-The ``app`` application instance created from this class is a WSGI application
-that can be used with any complaint WSGI web server. If the above application
-is stored in a file called *test.py*, then the following command runs the
-web application using the Gunicorn web server::
-
-    gunicorn test:app
-
-Using an ASGI Web Server
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython only
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
-       | `microdot_asgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asgi.py>`_
-
-   * - Required external dependencies
-     - | An ASGI web server, such as `Uvicorn <https://uvicorn.org/>`_.
-
-   * - Examples
-     - | `hello_asgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello_asgi.py>`_
-
-The ``microdot_asgi`` module provides an extended ``Microdot`` class that
-implements the ASGI protocol and can be used with a compliant ASGI server such
-as `Uvicorn <https://www.uvicorn.org/>`_.
-
-To use an ASGI web server, the application must import the
-:class:`Microdot <microdot_asgi.Microdot>` class from the ``microdot_asgi``
-module::
-
-    from microdot_asgi import Microdot
-
-    app = Microdot()
-
-    @app.route('/')
-    async def index(req):
-        return 'Hello, World!'
-
-The ``app`` application instance created from this class is an ASGI application
-that can be used with any complaint ASGI web server. If the above application
-is stored in a file called *test.py*, then the following command runs the
-web application using the Uvicorn web server::
-
-    uvicorn test:app
-

docs/extensions/auth.rst

@@ -0,0 +1,112 @@
+Authentication
+~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `auth.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/auth.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `basic_auth.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/auth/basic_auth.py>`_
+       | `token_auth.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/auth/token_auth.py>`_
+
+The authentication extension provides helper classes for two commonly used
+authentication patterns, described below.
+
+Basic Authentication
+^^^^^^^^^^^^^^^^^^^^
+
+`Basic Authentication <https://en.wikipedia.org/wiki/Basic_access_authentication>`_
+is a method of authentication that is part of the HTTP specification. It allows
+clients to authenticate to a server using a username and a password. Web
+browsers have native support for Basic Authentication and will automatically
+prompt the user for a username and a password when a protected resource is
+accessed.
+
+To use Basic Authentication, create an instance of the :class:`BasicAuth <microdot.auth.BasicAuth>`
+class::
+
+    from microdot.auth import BasicAuth
+
+    auth = BasicAuth(app)
+
+Next, create an authentication function. The function must accept a request
+object and a username and password pair provided by the user. If the
+credentials are valid, the function must return an object that represents the
+user. If the authentication function cannot validate the user provided
+credentials it must return ``None``. Decorate the function with
+``@auth.authenticate``::
+
+    @auth.authenticate
+    async def verify_user(request, username, password):
+        user = await load_user_from_database(username)
+        if user and user.verify_password(password):
+            return user
+
+To protect a route with authentication, add the ``auth`` instance as a
+decorator::
+
+    @app.route('/')
+    @auth
+    async def index(request):
+        return f'Hello, {request.g.current_user}!'
+
+While running an authenticated request, the user object returned by the
+authenticaction function is accessible as ``request.g.current_user``.
+
+If an endpoint is intended to work with or without authentication, then it can
+be protected with the ``auth.optional`` decorator::
+
+    @app.route('/')
+    @auth.optional
+    async def index(request):
+        if request.g.current_user:
+            return f'Hello, {request.g.current_user}!'
+        else:
+            return 'Hello, anonymous user!'
+
+As shown in the example, a route can check ``request.g.current_user`` to
+determine if the user is authenticated or not.
+
+Token Authentication
+^^^^^^^^^^^^^^^^^^^^
+
+To set up token authentication, create an instance of
+:class:`TokenAuth <microdot.auth.TokenAuth>`::
+
+    from microdot.auth import TokenAuth
+
+    auth = TokenAuth()
+
+Then add a function that verifies the token and returns the user it belongs to,
+or ``None`` if the token is invalid or expired::
+
+    @auth.authenticate
+    async def verify_token(request, token):
+        return load_user_from_token(token)
+
+As with Basic authentication, the ``auth`` instance is used as a decorator to
+protect your routes, and the authenticated user is accessible from the request
+object as ``request.g.current_user``::
+
+    @app.route('/')
+    @auth
+    async def index(request):
+        return f'Hello, {request.g.current_user}!'
+
+Optional authentication can also be used with tokens::
+
+    @app.route('/')
+    @auth.optional
+    async def index(request):
+        if request.g.current_user:
+            return f'Hello, {request.g.current_user}!'
+        else:
+            return 'Hello, anonymous user!'

docs/extensions/cors.rst

@@ -0,0 +1,34 @@
+Cross-Origin Resource Sharing (CORS)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `cors.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/cors.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `app.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/cors/app.py>`_
+
+The CORS extension provides support for `Cross-Origin Resource Sharing
+(CORS) <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_. CORS is a
+mechanism that allows web applications running on different origins to access
+resources from each other. For example, a web application running on
+``https://example.com`` can access resources from ``https://api.example.com``.
+
+To enable CORS support, create an instance of the
+:class:`CORS <microdot.cors.CORS>` class and configure the desired options.
+Example::
+
+    from microdot import Microdot
+    from microdot.cors import CORS
+
+    app = Microdot()
+    cors = CORS(app, allowed_origins=['https://example.com'],
+                allow_credentials=True)

docs/extensions/csrf.rst

@@ -0,0 +1,94 @@
+Cross-Site Request Forgery (CSRF) Protection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `csrf.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/csrf.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `app.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/csrf/app.py>`_
+
+The CSRF extension provides protection against `Cross-Site Request Forgery
+(CSRF) <https://owasp.org/www-community/attacks/csrf>`_ attacks. This
+protection defends against attackers attempting to submit forms or other
+state-changing requests from their own site on behalf of unsuspecting victims,
+while taking advantage of the victims previously established sessions or
+cookies to impersonate them.
+
+This extension checks the ``Sec-Fetch-Site`` header sent by all modern web
+browsers to achieve this protection. As a fallback mechanism for older browsers
+that do not support this header, this extension can be linked to the CORS
+extension to validate the ``Origin`` header. If you are interested in the
+details of this protection mechanism, it is described in the
+`OWASP CSRF Prevention Cheat Sheet <https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#fetch-metadata-headers>`_
+page.
+
+.. note::
+   As of December 2025, OWASP considers the use of Fetch Metadata Headers for
+   CSRF protection a
+   `defense in depth <https://en.wikipedia.org/wiki/Defence_in_depth>`_
+   technique that is insufficient on its own.
+
+   There is an interesting
+   `discussion <https://github.com/OWASP/CheatSheetSeries/issues/1803>`_ on
+   this topic in the OWASP GitHub repository where it appears to be agreement
+   that this technique provides complete protection for the vast majority of
+   use cases. If you are unsure if this method works for your use case, please
+   read this discussion to have more context and make the right decision. 
+
+To enable CSRF protection, create an instance of the
+:class:`CSRF <microdot.csrf.CSRF>` class and configure the desired options.
+Example::
+
+    from microdot import Microdot
+    from microdot.cors import CORS
+    from microdot.csrf import CSRF
+
+    app = Microdot()
+    cors = CORS(app, allowed_origins=['https://example.com'])
+    csrf = CSRF(app, cors)
+
+This will protect all routes that use a state-changing method (``POST``,
+``PUT``, ``PATCH`` or ``DELETE``) and will return a 403 status code response to
+any requests that fail the CSRF check.
+
+If there are routes that need to be exempted from the CSRF check, they can be
+decorated with the :meth:`csrf.exempt <microdot.csrf.CSRF.exempt>` decorator::
+
+    @app.post('/webhook')
+    @csrf.exempt
+    async def webhook(request):
+        # ...
+
+For some applications it may be more convenient to have CSRF checks turned off
+by default, and only apply them to explicitly selected routes. In this case,
+pass ``protect_all=False`` when you construct the ``CSRF`` instance and use the
+:meth:`csrf.protect <microdot.csrf.CSRF.protect>` decorator::
+
+    csrf = CSRF(app, cors, protect_all=False)
+
+    @app.post('/submit-form')
+    @csrf.protect
+    async def submit_form(request):
+        # ...
+
+By default, requests coming from different subdomains are considered to be
+cross-site, and as such they will not pass the CSRF check. If you'd like
+subdomain requests to be considered safe, then set the
+``allow_subdomains=True`` option when you create the ``CSRF`` class.
+
+.. note::
+   This extension is designed to block requests issued by web browsers when
+   they are found to be unsafe or unauthorized by the application owner. The
+   method used to determine if a request should be allowed or not is based on
+   the value of headers that are only sent by web browsers. Clients other than
+   web browsers are not affected by this extension and can send requests
+   freely.

docs/extensions/index.rst

@@ -0,0 +1,21 @@
+Core Extensions
+---------------
+
+Microdot is a highly extensible web application framework. The extensions
+described in this section are maintained as part of the Microdot project in
+the same source code repository.
+
+.. toctree::
+   :maxdepth: 1
+
+   multipart
+   websocket
+   sse
+   templates
+   sessions
+   auth
+   login
+   cors
+   csrf
+   test_client
+   production

docs/extensions/login.rst

@@ -0,0 +1,85 @@
+User Logins
+~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `login.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/auth.py>`_
+       | `session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/session.py>`_
+       | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
+   * - Required external dependencies
+     - | CPython: `PyJWT <https://pyjwt.readthedocs.io/>`_
+       | MicroPython: `jwt.py <https://github.com/micropython/micropython-lib/blob/master/python-ecosys/pyjwt/jwt.py>`_,
+                      `hmac.py <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/hmac/hmac.py>`_
+   * - Examples
+     - | `login.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/login/login.py>`_
+
+The login extension provides user login functionality. The logged in state of
+the user is stored in the user session cookie, and an optional "remember me"
+cookie can also be added to keep the user logged in across browser sessions.
+
+To use this extension, create instances of the
+:class:`Session <microdot.session.Session>` and :class:`Login <microdot.login.Login>`
+class::
+
+    Session(app, secret_key='top-secret!')
+    login = Login()
+
+The ``Login`` class accept an optional argument with the URL of the login page.
+The default for this URL is */login*.
+
+The application must represent users as objects with an ``id`` attribute. A
+function decorated with ``@login.user_loader`` is used to load a user object::
+
+    @login.user_loader
+    async def get_user(user_id):
+        return database.get_user(user_id)
+
+The application must implement the login form. At the point in which the user
+credentials have been received and verified, a call to the
+:func:`login_user() <microdot.login.Login.login_user>` function must be made to
+record the user in the user session::
+
+    @app.route('/login', methods=['GET', 'POST'])
+    async def login(request):
+        # ...
+        if user.check_password(password):
+            return await login.login_user(request, user, remember=remember_me)
+        return redirect('/login')
+
+The optional ``remember`` argument is used to add a remember me cookie that
+will log the user in automatically in future sessions. A value of ``True`` will
+keep the log in active for 30 days. Alternatively, an integer number of days
+can be passed in this argument.
+
+Any routes that require the user to be logged in must be decorated with
+:func:`@login <microdot.login.Login.__call__>`::
+
+    @app.route('/')
+    @login
+    async def index(request):
+        # ...
+
+Routes that are of a sensitive nature can be decorated with
+:func:`@login.fresh <microdot.login.Login.fresh>`
+instead. This decorator requires that the user has logged in during the current
+session, and will ask the user to logged in again if the session was
+authenticated through a remember me cookie::
+
+    @app.get('/fresh')
+    @login.fresh
+    async def fresh(request):
+        # ...
+
+To log out a user, the :func:`logout_user() <microdot.auth.Login.logout_user>`
+is used::
+
+    @app.post('/logout')
+    @login
+    async def logout(request):
+        await login.logout_user(request)
+        return redirect('/')

docs/extensions/multipart.rst

@@ -0,0 +1,73 @@
+Multipart Forms
+~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     -  | `multipart.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/multipart.py>`_
+        | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `formdata.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/uploads/formdata.py>`_
+
+The multipart extension handles multipart forms, including those that have file
+uploads.
+
+The :func:`with_form_data <microdot.multipart.with_form_data>` decorator
+provides the simplest way to work with these forms. With this decorator added
+to the route, whenever the client sends a multipart request the
+:attr:`request.form <microdot.Request.form>` and
+:attr:`request.files <microdot.Request.files>` properties are populated with
+the submitted data. For form fields the field values are always strings. For
+files, they are instances of the
+:class:`FileUpload <microdot.multipart.FileUpload>` class.
+
+Example::
+
+    from microdot.multipart import with_form_data
+
+    @app.post('/upload')
+    @with_form_data
+    async def upload(request):
+        print('form fields:', request.form)
+        print('files:', request.files)
+
+One disadvantage of the ``@with_form_data`` decorator is that it has to copy
+any uploaded files to memory or temporary disk files, depending on their size.
+The :attr:`FileUpload.max_memory_size <microdot.multipart.FileUpload.max_memory_size>`
+attribute can be used to control the cutoff size above which a file upload
+is transferred to a temporary file.
+
+A more performant alternative to the ``@with_form_data`` decorator is the
+:class:`FormDataIter <microdot.multipart.FormDataIter>` class, which iterates
+over the form fields sequentially, giving the application the option to parse
+the form fields on the fly and decide what to copy and what to discard. When
+using ``FormDataIter`` the ``request.form`` and ``request.files`` attributes
+are not used.
+
+Example::
+
+
+    from microdot.multipart import FormDataIter
+
+    @app.post('/upload')
+    async def upload(request):
+        async for name, value in FormDataIter(request):
+            print(name, value)
+
+For fields that contain an uploaded file, the ``value`` returned by the
+iterator is the same ``FileUpload`` instance. The application can choose to
+save the file with the :meth:`save() <microdot.multipart.FileUpload.save>`
+method, or read it with the :meth:`read() <microdot.multipart.FileUpload.read>`
+method, optionally passing a size to read it in chunks. The
+:meth:`copy() <microdot.multipart.FileUpload.copy>` method is also available to
+apply the copying logic used by the ``@with_form_data`` decorator, which is
+inefficient but allows the file to be set aside to be processed later, after
+the remaining form fields.

docs/extensions/production.rst

@@ -0,0 +1,120 @@
+Production Deployments
+~~~~~~~~~~~~~~~~~~~~~~
+
+The ``Microdot`` class creates its own simple web server. This is enough for an
+application deployed with MicroPython, but when using CPython it may be useful
+to use a separate, battle-tested web server. To address this need, Microdot
+provides extensions that implement the ASGI and WSGI protocols.
+
+Using an ASGI Web Server
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython only
+
+   * - Required Microdot source files
+     - | `asgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/asgi.py>`_
+
+   * - Required external dependencies
+     - | An ASGI web server, such as `Uvicorn <https://www.uvicorn.org/>`_.
+
+   * - Examples
+     - | `hello_asgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_asgi.py>`_
+       | `hello_asgi.py (uTemplate) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/utemplate/hello_asgi.py>`_
+       | `hello_asgi.py (Jinja) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/jinja/hello_asgi.py>`_
+       | `echo_asgi.py (WebSocket) <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_asgi.py>`_
+
+The ``asgi`` module provides an extended ``Microdot`` class that
+implements the ASGI protocol and can be used with a compliant ASGI server such
+as `Uvicorn <https://www.uvicorn.org/>`_.
+
+To use an ASGI web server, the application must import the
+:class:`Microdot <microdot.asgi.Microdot>` class from the ``asgi`` module::
+
+    from microdot.asgi import Microdot
+
+    app = Microdot()
+
+    @app.route('/')
+    async def index(req):
+        return 'Hello, World!'
+
+The ``app`` application instance created from this class can be used as the
+ASGI callable with any complaint ASGI web server. If the above example
+application was stored in a file called *test.py*, then the following command
+runs the web application using the Uvicorn web server::
+
+    uvicorn test:app
+
+When using the ASGI support, the ``scope`` dictionary provided by the web
+server is available to request handlers as ``request.asgi_scope``.
+
+The application instance can be initialized with ``lifespan_startup`` and
+``lifespan_shutdown`` arguments, which are invoked when the web server sends
+the ASGI lifespan signals with the ASGI scope as only argument::
+
+    async def startup(scope):
+        pass
+
+    async def shutdown(scope):
+        pass
+
+    app = Microdot(lifespan_startup=startup, lifespan_shutdown=shutdown)
+
+Using a WSGI Web Server
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython only
+
+   * - Required Microdot source files
+     - | `wsgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/wsgi.py>`_
+
+   * - Required external dependencies
+     - | A WSGI web server, such as `Gunicorn <https://gunicorn.org/>`_.
+
+   * - Examples
+     - | `hello_wsgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_wsgi.py>`_
+       | `hello_wsgi.py (uTemplate) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/utemplate/hello_wsgi.py>`_
+       | `hello_wsgi.py (Jinja) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/jinja/hello_wsgi.py>`_
+       | `echo_wsgi.py (WebSocket) <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_wsgi.py>`_
+
+
+The ``wsgi`` module provides an extended ``Microdot`` class that implements the
+WSGI protocol and can be used with a compliant WSGI web server such as 
+`Gunicorn <https://gunicorn.org/>`_ or
+`uWSGI <https://uwsgi-docs.readthedocs.io/en/latest/>`_.
+
+To use a WSGI web server, the application must import the
+:class:`Microdot <microdot.wsgi.Microdot>` class from the ``wsgi`` module::
+
+    from microdot.wsgi import Microdot
+
+    app = Microdot()
+
+    @app.route('/')
+    def index(req):
+        return 'Hello, World!'
+
+The ``app`` application instance created from this class can be used as a WSGI
+callbable with any complaint WSGI web server. If the above application
+was stored in a file called *test.py*, then the following command runs the
+web application using the Gunicorn web server::
+
+    gunicorn test:app
+
+When using the WSGI support, the ``environ`` dictionary provided by the web
+server is available to request handlers as ``request.environ``.
+
+.. note::
+    In spite of WSGI being a synchronous protocol, the Microdot application
+    internally runs under an asyncio event loop. For that reason, the
+    recommendation to prefer ``async def`` handlers over ``def`` still applies
+    under WSGI. Consult the :ref:`Concurrency` section for a discussion of how
+    the two types of functions are handled by Microdot.

docs/extensions/sessions.rst

@@ -0,0 +1,68 @@
+Secure User Sessions
+~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/session.py>`_
+       | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
+
+   * - Required external dependencies
+     - | CPython: `PyJWT <https://pyjwt.readthedocs.io/>`_
+       | MicroPython: `jwt.py <https://github.com/micropython/micropython-lib/blob/master/python-ecosys/pyjwt/jwt.py>`_,
+                      `hmac.py <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/hmac/hmac.py>`_
+
+   * - Examples
+     - | `login.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/sessions/login.py>`_
+
+The session extension provides a secure way for the application to maintain
+user sessions. The session data is stored as a signed cookie in the client's
+browser, in `JSON Web Token (JWT) <https://en.wikipedia.org/wiki/JSON_Web_Token>`_
+format.
+
+To work with user sessions, the application first must configure a secret key
+that will be used to sign the session cookies. It is very important that this
+key is kept secret, as its name implies. An attacker who is in possession of
+this key can generate valid user session cookies with any contents.
+
+To initialize the session extension and configure the secret key, create a
+:class:`Session <microdot.session.Session>` object::
+
+    Session(app, secret_key='top-secret')
+
+The :func:`with_session <microdot.session.with_session>` decorator is the
+most convenient way to retrieve the session at the start of a request::
+
+    from microdot import Microdot, redirect
+    from microdot.session import Session, with_session
+
+    app = Microdot()
+    Session(app, secret_key='top-secret')
+
+    @app.route('/', methods=['GET', 'POST'])
+    @with_session
+    async def index(req, session):
+        username = session.get('username')
+        if req.method == 'POST':
+            username = req.form.get('username')
+            session['username'] = username
+            session.save()
+            return redirect('/')
+        if username is None:
+            return 'Not logged in'
+        else:
+            return 'Logged in as ' + username
+
+    @app.post('/logout')
+    @with_session
+    async def logout(req, session):
+        session.delete()
+        return redirect('/')
+
+The :func:`save() <microdot.session.SessionDict.save>` and
+:func:`delete() <microdot.session.SessionDict.delete>` methods are used to update
+and destroy the user session respectively.

docs/extensions/sse.rst

@@ -0,0 +1,60 @@
+Server-Sent Events
+~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     -  | `sse.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/sse.py>`_
+        | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `counter.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/sse/counter.py>`_
+
+The Server-Sent Events (SSE) extension simplifies the creation of a streaming
+endpoint that follows the SSE web standard. The :func:`with_sse <microdot.sse.with_sse>`
+decorator is used to mark a route as an SSE handler. Decorated routes receive
+an SSE object as second argument. The SSE object provides a ``send()``
+asynchronous method to send an event to the client.
+
+Example::
+
+    from microdot.sse import with_sse
+
+    @app.route('/events')
+    @with_sse
+    async def events(request, sse):
+        for i in range(10):
+            await asyncio.sleep(1)
+            await sse.send({'counter': i})  # unnamed event
+        await sse.send('end', event='comment')  # named event
+
+To end the SSE connection, the route handler can exit, without returning
+anything, as shown in the above examples.
+
+If the client ends the SSE connection from their side, the route function is
+cancelled. The route function can catch the ``CancelledError`` exception from
+asyncio to perform cleanup tasks::
+
+    @app.route('/events')
+    @with_sse
+    async def events(request, sse):
+        try:
+            i = 0
+            while True:
+                await asyncio.sleep(1)
+                await sse.send({'counter': i})
+                i += 1
+        except asyncio.CancelledError:
+            print('Client disconnected!')
+
+.. note::
+   The SSE protocol is unidirectional, so there is no ``receive()`` method in
+   the SSE object. For bidirectional communication with the client, use the
+   WebSocket extension.

docs/extensions/templates.rst

@@ -0,0 +1,123 @@
+Templates
+~~~~~~~~~
+
+Many web applications use HTML templates for rendering content to clients.
+Microdot includes extensions to render templates with the
+`utemplate <https://github.com/pfalcon/utemplate>`_ package on CPython and
+MicroPython, and with `Jinja <https://jinja.palletsprojects.com/>`_ only on
+CPython.
+
+Using the uTemplate Engine
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `utemplate.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/utemplate.py>`_
+
+   * - Required external dependencies
+     - | `utemplate <https://github.com/pfalcon/utemplate/tree/master/utemplate>`_
+
+   * - Examples
+     - | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/utemplate/hello.py>`_
+
+The :class:`Template <microdot.utemplate.Template>` class is used to load a
+template. The argument is the template filename, relative to the templates
+directory, which is *templates* by default.
+
+The ``Template`` object has a :func:`render() <microdot.utemplate.Template.render>`
+method that renders the template to a string. This method receives any
+arguments that are used by the template.
+
+Example::
+
+    from microdot.utemplate import Template
+
+    @app.get('/')
+    async def index(req):
+        return Template('index.html').render()
+
+The ``Template`` object also has a :func:`generate() <microdot.utemplate.Template.generate>`
+method, which returns a generator instead of a string. The
+:func:`render_async() <microdot.utemplate.Template.render_async>` and
+:func:`generate_async() <microdot.utemplate.Template.generate_async>` methods
+are the asynchronous versions of these two methods.
+
+The default location from where templates are loaded is the *templates*
+subdirectory. This location can be changed with the
+:func:`Template.initialize <microdot.utemplate.Template.initialize>` class
+method::
+
+    Template.initialize('my_templates')
+
+By default templates are automatically compiled the first time they are
+rendered, or when their last modified timestamp is more recent than the
+compiledo file's timestamp. This loading behavior can be changed by switching
+to a different template loader. For example, if the templates are pre-compiled,
+the timestamp check and compile steps can be removed by switching to the
+"compiled" template loader::
+
+    from utemplate import compiled
+    from microdot.utemplate import Template
+
+    Template.initialize(loader_class=compiled.Loader)
+
+Consult the `uTemplate documentation <https://github.com/pfalcon/utemplate>`_
+for additional information regarding template loaders.
+
+Using the Jinja Engine
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython only
+
+   * - Required Microdot source files
+     - | `jinja.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/jinja.py>`_
+
+   * - Required external dependencies
+     - | `Jinja2 <https://jinja.palletsprojects.com/>`_
+
+   * - Examples
+     - | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/jinja/hello.py>`_
+
+The :class:`Template <microdot.jinja.Template>` class is used to load a
+template. The argument is the template filename, relative to the templates
+directory, which is *templates* by default.
+
+The ``Template`` object has a :func:`render() <microdot.jinja.Template.render>`
+method that renders the template to a string. This method receives any
+arguments that are used by the template.
+
+Example::
+
+    from microdot.jinja import Template
+
+    @app.get('/')
+    async def index(req):
+        return Template('index.html').render()
+
+The ``Template`` object also has a :func:`generate() <microdot.jinja.Template.generate>`
+method, which returns a generator instead of a string.
+
+The default location from where templates are loaded is the *templates*
+subdirectory. This location can be changed with the
+:func:`Template.initialize <microdot.jinja.Template.initialize>` class method::
+
+    Template.initialize('my_templates')
+
+The ``initialize()`` method also accepts ``enable_async`` argument, which
+can be set to ``True`` if asynchronous rendering of templates is desired. If
+this option is enabled, then the
+:func:`render_async() <microdot.jinja.Template.render_async>` and
+:func:`generate_async() <microdot.jinja.Template.generate_async>` methods
+must be used.
+
+.. note::
+    The Jinja extension is not compatible with MicroPython.

docs/extensions/test_client.rst

@@ -0,0 +1,36 @@
+Test Client
+~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/test_client.py>`_
+
+   * - Required external dependencies
+     - | None
+
+The Microdot Test Client is a utility class that can be used in tests to send
+requests into the application without having to start a web server.
+
+Example::
+
+    from microdot import Microdot
+    from microdot.test_client import TestClient
+
+    app = Microdot()
+
+    @app.route('/')
+    def index(req):
+        return 'Hello, World!'
+
+    async def test_app():
+        client = TestClient(app)
+        response = await client.get('/')
+        assert response.text == 'Hello, World!'
+
+See the documentation for the :class:`TestClient <microdot.test_client.TestClient>`
+class for more details.

docs/extensions/websocket.rst

@@ -0,0 +1,63 @@
+WebSocket
+~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     -  | `websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/websocket.py>`_
+        | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `echo.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo.py>`_
+
+The WebSocket extension gives the application the ability to handle WebSocket
+requests. The :func:`with_websocket <microdot.websocket.with_websocket>`
+decorator is used to mark a route handler as a WebSocket handler. Decorated
+routes receive a WebSocket object as a second argument. The WebSocket object
+provides ``send()`` and ``receive()`` asynchronous methods to send and receive
+messages respectively.
+
+Example::
+
+    from microdot.websocket import with_websocket
+
+    @app.route('/echo')
+    @with_websocket
+    async def echo(request, ws):
+        while True:
+            message = await ws.receive()
+            await ws.send(message)
+
+To end the WebSocket connection, the route handler can exit, without returning
+anything::
+
+    @app.route('/echo')
+    @with_websocket
+    async def echo(request, ws):
+        while True:
+            message = await ws.receive()
+            if message == 'exit':
+                break
+            await ws.send(message)
+        await ws.send('goodbye')
+
+If the client ends the WebSocket connection from their side, the route function
+is cancelled. The route function can catch the ``CancelledError`` exception
+from asyncio to perform cleanup tasks::
+
+    @app.route('/echo')
+    @with_websocket
+    async def echo(request, ws):
+        try:
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
+        except asyncio.CancelledError:
+            print('Client disconnected!')

docs/implementation/freezing.rst

@@ -0,0 +1,113 @@
+Cross-Compiling and Freezing Microdot
+-------------------------------------
+
+.. note::
+   This section only applies when using Microdot on MicroPython.
+
+Microdot is a fairly small framework, so its size is not something you need to
+be concerned about unless you are working with MicroPython on hardware with a
+very small amount of disk space and/or RAM. In such cases every byte counts, so
+this section provides some recommendations on how to keep Microdot's footprint
+as small as possible.
+
+Choosing What Modules to Install
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Microdot has a modular design that allows you to only install the modules that
+your application needs.
+
+For minimal web application support based on the core Microdot web server
+without extensions, you can just copy `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/microdot.py>`_
+to the source directory on your device. The core Microdot web server does not
+have any dependencies, so you don't need to install anything else.
+
+If your application uses some of the provided extensions to the core web
+server, then instead of installing *microdot.py* you'll need to create a
+*microdot* subdirectory and install the following files in it:
+
+- `__init__.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/__init__.py>`_
+- `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/microdot.py>`_
+- Any extension modules that you need from the `microdot <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot>`_ source directory.
+
+Some of the extensions also have dependencies of their own, so you may need to
+install those in your device as well (outside of the ``microdot``
+subdirectory). Consult the documentation of each extension to learn if any
+third-party dependencies are required.
+
+Cross-Compiling
+~~~~~~~~~~~~~~~
+
+An issue that is common with low-end microcontroller boards is that they do not
+have enough RAM for the MicroPython compiler to compile the source files, but
+once the code is compiled they are able to run it just fine.
+
+To address this, MicroPython allows you to cross-compile source files on your
+desktop or laptop computer and then upload their compiled versions to the
+device. A good strategy is to cross-compile all the dependencies that are used
+by your application, since these are not going to be updated very often. If the
+goal is to minimize the use of RAM, you can also opt to cross-compile your
+application source files.
+
+The MicroPython cross-compiler is available as a package that you can install
+on standard Python. You must determine the version of MicroPython that you will
+be running on your device, and install the compiler that matches that version.
+For example, if you plan to use MicroPython 1.21.0 on your device, you can
+install the cross-compiler for this version with the following command::
+
+    pip install mpy-cross==1.21.0
+
+Then run the cross-compiler for each source file that you want to compile.
+Since the cross-compilation happens on your computer, you will need to have
+copies of all the source files you need to compile locally on your disk. Here
+is how you can compile the *microdot.py* file, assuming you have a copy in the
+current directory in your computer::
+
+    mpy-cross microdot.py
+
+The cross-compiler will create a file with the same name as the source file,
+but with the extension changed to *.mpy*.
+
+Once you have all your dependencies compiled, you can replace the *.py* files
+in your device with their corresponding *.mpy* versions. MicroPython
+automatically recognizes *.mpy* files, so there is no need to make any changes
+to any source code to start using compiled files.
+
+Freezing
+~~~~~~~~
+
+The ultimate option to reduce the size of a MicroPython application is to
+"freeze" it. Freezing is a process that takes MicroPython source code (either
+dependencies, application code or both), pre-compiles it and incorporates it
+into a custom-built MicroPython firmware that is flashed to the device.
+
+Freezing MicroPython modules to firmware has the advantage that the code is
+imported directly from the device's ROM, leaving more RAM available for
+application use.
+
+The process to create a custom firmware is unfortunately non-trivial and
+different for each microcontroller platform, so you will need to consult the
+MicroPython documentation that applies to your device to learn how to do this.
+
+The part of the process that is common to all devices is the creation of a
+`manifest file <https://docs.micropython.org/en/latest/reference/manifest.html>`_
+to tell the MicroPython firmware builder which packages and modules to freeze.
+
+For a minimal installation of Microdot consisting only in its *microdot.py*
+source file, the manifest file that you need use to build the firmware must
+include the following declaration::
+
+    module('microdot')
+
+If instead you are working with a version of Microdot that includes some or all
+of its extensions, then the manifest file must reference the ``microdot``
+package plus any third-party dependencies that are needed. Below is a manifest
+file for a complete Microdot installation that includes all the extensions::
+
+    package('microdot')
+    package('utemplate')  # required only if templates are used
+    module('pyjwt')       # required only if user sessions are used
+
+In this example, the *microdot* and *utemplate* packages must be available in
+the directory where the manifest file is located so that the MicroPython build
+can find them. The `pyjwt` module is part of the MicroPython standard library
+and will be downloaded as part of the build.

docs/implementation/index.rst

@@ -0,0 +1,11 @@
+Implementation notes
+--------------------
+
+This section covers some implementation aspects of Microdot.
+
+.. toctree::
+   :maxdepth: 1
+
+   migrating
+   freezing
+

docs/implementation/migrating.rst

@@ -0,0 +1,145 @@
+Migrating to Microdot 2.x from Older Releases
+---------------------------------------------
+
+Version 2 of Microdot incorporates feedback received from users of earlier
+releases, and attempts to improve and correct some design decisions that have
+proven to be problematic.
+
+For this reason most applications built for earlier versions will need to be
+updated to work correctly with Microdot 2. This section describes the backwards
+incompatible changes that were made.
+
+Code reorganization
+~~~~~~~~~~~~~~~~~~~
+
+The Microdot source code has been moved into a ``microdot`` package,
+eliminating the need for each extension to be named with a *microdot_* prefix.
+
+As a result of this change, all extensions have been renamed to shorter names.
+For example, the *microdot_cors.py* module is now called *cors.py*.
+
+This change affects the way extensions are imported. Instead of this::
+
+    from microdot_cors import CORS
+
+the import statement should be::
+
+    from microdot.cors import CORS
+
+No more synchronous web server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In earlier releases of Microdot the core web server was built on synchronous
+Python, and asynchronous support was enabled with the asyncio extension.
+
+Microdot 2 eliminates the synchronous web server, and implements the core
+server logic directly with asyncio, eliminating the need for an asyncio
+extension.
+
+Any applications built using the asyncio extension will need to update their
+imports from this::
+
+    from microdot_asyncio import Microdot
+
+to this::
+
+    from microdot import Microdot
+
+Applications that were built using the synchronous web server do not need to
+change their imports, but will now work asynchronously. Review the
+:ref:`Concurrency` section to learn about the potential issues when using
+``def`` function handlers, and the benefits of transitioning to ``async def``
+handlers.
+
+Removed extensions
+~~~~~~~~~~~~~~~~~~
+
+Some extensions became unnecessary and have been removed or merged with other
+extensions:
+
+- *microdot_asyncio.py*: this is now the core web server.
+- *microdot_asyncio_websocket.py*: this is now the main WebSocket extension.
+- *microdot_asyncio_test_client.py*: this is now the main test client
+  extension.
+- *microdot_asgi_websocket.py*: the functionality in this extension is now
+  available in the ASGI extension.
+- *microdot_ssl.py*: this extension was only used with the synchronous web
+  server, so it is not needed anymore.
+- *microdot_websocket_alt.py*: this extension was only used with the
+  synchronous web server, so it is not needed anymore.
+
+No more ``render_template()`` function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Jinja and uTemplate extensions have been redesigned to work better under
+the asynchronous engine, and as a result, the ``render_template()`` function
+has been eliminated.
+
+Instead of this::
+
+    return render_template('index.html', title='Home')
+
+use this::
+
+    return Template('index.html').render(title='Home')
+
+As a result of this change, it is now possible to use asynchronous rendering::
+
+    return await Template('index.html').render_async(title='Home')
+
+Also thanks to this redesign, the template can be streamed instead of returned
+as a single string::
+
+    return Template('index.html').generate(title='Home')
+
+Streamed templates also have an asynchronous version::
+
+    return Template('index.html').generate_async(title='Home')
+
+Class-based user sessions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The session extension has been completely redesigned. To initialize session
+support for the application, create a ``Session`` object::
+
+    app = Microdot()
+    Session(app, secret_key='top-secret!')
+
+The ``@with_session`` decorator is used to include the session in a request::
+
+    @app.get('/')
+    @with_session
+    async def index(request, session):
+        # ...
+
+The ``session`` can be used as a dictionary to retrieve or change the session.
+To save the session when it has been modified, call its ``save()`` method::
+
+    @app.get('/')
+    @with_session
+    async def index(request, session):
+        # ...
+        session.save()
+        return 'OK'
+
+To delete the session, call its ``delete()`` method before returning from the
+request.
+
+WSGI extension redesign
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Given that the synchronous web server has been removed, the WSGI extension has
+been redesigned to work as a synchronous wrapper for the asynchronous web
+server.
+
+Applications using the WSGI extension continue to run under an asynchronous
+loop and should try to use the recommended ``async def`` handlers, but can be
+deployed with standard WSGI servers such as Gunicorn.
+
+WebSocket support when using the WSGI extension is enabled when using a
+compatible web server. At this time only Gunicorn is supported for WebSocket.
+Given that WebSocket support is asynchronous, it would be better to switch to
+the ASGI extension, which has full support for WebSocket as defined in the ASGI
+specification.
+
+As before, the WSGI extension is not available under MicroPython.

docs/index.rst

@@ -9,16 +9,19 @@ Microdot
 *"The impossibly small web framework for Python and MicroPython"*
 
 Microdot is a minimalistic Python web framework inspired by
-`Flask <https://flask.palletsprojects.com/>`_, and designed to run on
-systems with limited resources such as microcontrollers. It runs on standard
-Python and on `MicroPython <https://micropython.org>`_.
+`Flask <https://flask.palletsprojects.com/>`_. Given its size, it can run on
+systems with limited resources such as microcontrollers. Both standard Python
+(CPython) and `MicroPython <https://micropython.org>`_ are supported.
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2 
 
    intro
-   extensions
-   api
+   users-guide/index
+   extensions/index
+   implementation/index
+   api/index
+   contributing
 
 * :ref:`genindex`
 * :ref:`search`

docs/intro.rst

@@ -1,758 +1,44 @@
 Installation
 ------------
 
-For standard Python (CPython) projects, Microdot and all of its core extensions
-can be installed with ``pip``::
+The installation method is different depending on which flavor of Python you 
+are using.
+
+CPython Installation
+~~~~~~~~~~~~~~~~~~~~
+
+For use with standard Python (CPython) projects, Microdot and all of its core
+extensions are installed with ``pip`` or any of its alternatives::
 
     pip install microdot
 
-For MicroPython, you can install it with ``upip`` if that option is available,
-but the recommended approach is to manually copy *microdot.py* and any
-desired optional extension source files from the
-`GitHub repository <https://github.com/miguelgrinberg/microdot/tree/main/src>`_
-into your device, possibly after
-`compiling <https://docs.micropython.org/en/latest/reference/mpyfiles.html>`_
-them to *.mpy* files. These source files can also be
-`frozen <https://docs.micropython.org/en/latest/develop/optimizations.html?highlight=frozen#frozen-bytecode>`_
-and incorporated into a custom MicroPython firmware.
-
-Getting Started
----------------
-
-This section describes the main features of Microdot in an informal manner. For
-detailed reference information, consult the :ref:`API Reference`.
-
-A Simple Microdot Web Server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following is an example of a simple web server::
-
-    from microdot import Microdot
-
-    app = Microdot()
-
-    @app.route('/')
-    def index(request):
-        return 'Hello, world!'
-
-    app.run()
-
-The script imports the :class:`Microdot <microdot.Microdot>` class and creates
-an application instance from it.
-
-The application instance provides a :func:`route() <microdot.Microdot.route>`
-decorator, which is used to define one or more routes, as needed by the
-application.
-
-The ``route()`` decorator takes the path portion of the URL as an
-argument, and maps it to the decorated function, so that the function is called
-when the client requests the URL. The function is passed a
-:class:`Request <microdot.Request>` object as an argument, which provides
-access to the information passed by the client. The value returned by the
-function is sent back to the client as the response.
-
-The :func:`run() <microdot.Microdot.run>` method starts the application's web
-server on port 5000 (or the port number passed in the ``port`` argument). This
-method blocks while it waits for connections from clients.
-
-Running with CPython
-~~~~~~~~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-
-   * - Required external dependencies
-     - | None
-
-   * - Examples
-     - | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello.py>`_
-
-When using CPython, you can start the web server by running the script that
-defines and runs the application instance::
-
-    python main.py
-
-While the script is running, you can open a web browser and navigate to
-*http://localhost:5000/*, which is the default address for the Microdot web
-server. From other computers in the same network, use the IP address or
-hostname of the computer running the script instead of ``localhost``.
-
-Running with MicroPython
+MicroPython Installation
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. list-table::
-   :align: left
+For MicroPython, the recommended approach is to manually copy the necessary
+source files from the
+`GitHub repository <https://github.com/miguelgrinberg/microdot/tree/main/src>`_
+into your device.
 
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+Use the following guidelines to know what files to copy:
 
-   * - Required external dependencies
-     - | None
+* For a minimal setup with only the base web server functionality, copy
+  `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
+  to your device.
+* For a configuration that includes one or more of the optional extensions,
+  create a *microdot* directory in your device and copy the following files:
 
-   * - Examples
-     - | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello.py>`_
-       | `gpio.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/gpio/gpio.py>`_
+  * `__init__.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/__init__.py>`_
+  * `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
+  * any needed `extensions <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot>`_.
 
-When using MicroPython, you can upload a *main.py* file containing the web
-server code to your device along with *microdot.py*. MicroPython will
-automatically run *main.py* when the device is powered on, so the web server
-will automatically start. The application can be accessed on port 5000 at the
-device's IP address. As indicated above, the port can be changed by passing the
-``port`` argument to the ``run()`` method.
+Some of the low end devices are perfectly capable of running Microdot once
+compiled, but do not have enough RAM for the compiler. For these cases you can
+`pre-compile <https://docs.micropython.org/en/latest/reference/mpyfiles.html>`_
+the files to *.mpy* files for the version of MicroPython that you use in your
+device.
 
-.. note::
-   Microdot does not configure the network interface of the device in which it
-   is running. If your device requires a network connection to be made in
-   advance, for example to a Wi-Fi access point, this must be configured before
-   the ``run()`` method is invoked.
+If space in your device is extremely tight, you may also consider
+`freezing <https://docs.micropython.org/en/latest/develop/optimizations.html?highlight=frozen#frozen-bytecode>`_
+the Microdot files and incorporating them into a custom MicroPython firmware.
 
-Defining Routes
-~~~~~~~~~~~~~~~
-
-The :func:`route() <microdot.Microdot.route>` decorator is used to associate an
-application URL with the function that handles it. The only required argument
-to the decorator is the path portion of the URL.
-
-The following example creates a route for the root URL of the application::
-
-    @app.route('/')
-    def index(request):
-        return 'Hello, world!'
-
-When a client requests the root URL (for example, *http://localhost:5000/*),
-Microdot will call the ``index()`` function, passing it a
-:class:`Request <microdot.Request>` object. The return value of the function
-is the response that is sent to the client.
-
-Below is a another example, this one with a route for a URL with two components
-in its path::
-
-    @app.route('/users/active')
-    def active_users(request):
-        return 'Active users: Susan, Joe, and Bob'
-
-The complete URL that maps to this route is
-*http://localhost:5000/users/active*.
-
-An application can include multiple routes. Microdot uses the path portion of
-the URL to determine the correct route function to call for each incoming
-request.
-
-Choosing the HTTP Method
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-All the example routes shown above are associated with ``GET`` requests. But
-applications often need to define routes for other HTTP methods, such as
-``POST``, ``PUT``, ``PATCH`` and ``DELETE``. The ``route()`` decorator takes a
-``methods`` optional argument, in which the application can provide a list of
-HTTP methods that the route should be associated with on the given path.
-
-The following example defines a route that handles ``GET`` and ``POST``
-requests within the same function::
-
-    @app.route('/invoices', methods=['GET', 'POST'])
-    def invoices(request):
-        if request.method == 'GET':
-            return 'get invoices'
-        elif request.method == 'POST':
-            return 'create an invoice'
-
-In cases like the above, where a single URL is used to handle multiple HTTP
-methods, it may be desirable to write a separate function for each HTTP method.
-The above example can be implemented with two routes as follows::
-
-    @app.route('/invoices', methods=['GET'])
-    def get_invoices(request):
-        return 'get invoices'
-
-    @app.route('/invoices', methods=['POST'])
-    def create_invoice(request):
-        return 'create an invoice'
-
-Microdot provides the :func:`get() <microdot.Microdot.get>`,
-:func:`post() <microdot.Microdot.post>`, :func:`put() <microdot.Microdot.put>`,
-:func:`patch() <microdot.Microdot.patch>`, and
-:func:`delete() <microdot.Microdot.delete>` decorator shortcuts as well. The
-two example routes above can be written more concisely with them::
-
-    @app.get('/invoices')
-    def get_invoices(request):
-        return 'get invoices'
-
-    @app.post('/invoices')
-    def create_invoice(request):
-        return 'create an invoice'
-
-Including Dynamic Components in the URL Path
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The examples shown above all use hardcoded URL paths. Microdot also supports
-the definition of routes that have dynamic components in the path. For example,
-the following route associates all URLs that have a path following the pattern
-*http://localhost:5000/users/<username>* with the ``get_user()`` function::
-
-    @app.get('/users/<username>')
-    def get_user(request, username):
-        return 'User: ' + username
-
-As shown in the example, a path components that is enclosed in angle brackets
-is considered dynamic. Microdot accepts any values for that section of the URL
-path, and passes the value received to the function as an argument after
-the request object.
-
-Routes are not limited to a single dynamic component. The following route shows
-how multiple dynamic components can be included in the path::
-
-    @app.get('/users/<firstname>/<lastname>')
-    def get_user(request, firstname, lastname):
-        return 'User: ' + firstname + ' ' + lastname
-
-Dynamic path components are considered to be strings by default. An explicit
-type can be specified as a prefix, separated from the dynamic component name by
-a colon. The following route has two dynamic components declared as an integer
-and a string respectively::
-
-    @app.get('/users/<int:id>/<string:username>')
-    def get_user(request, id, username):
-        return 'User: ' + username + ' (' + str(id) + ')'
-
-If a dynamic path component is defined as an integer, the value passed to the
-route function is also an integer. If the client sends a value that is not an
-integer in the corresponding section of the URL path, then the URL will not
-match and the route will not be called.
-
-A special type ``path`` can be used to capture the remainder of the path as a
-single argument::
-
-    @app.get('/tests/<path:path>')
-    def get_test(request, path):
-        return 'Test: ' + path
-
-For the most control, the ``re`` type allows the application to provide a
-custom regular expression for the dynamic component. The next example defines
-a route that only matches usernames that begin with an upper or lower case
-letter, followed by a sequence of letters or numbers::
-
-    @app.get('/users/<re:[a-zA-Z][a-zA-Z0-9]*:username>')
-    def get_user(request, username):
-        return 'User: ' + username
-
-.. note::
-   Dynamic path components are passed to route functions as keyword arguments,
-   so the names of the function arguments must match the names declared in the
-   path specification.
-
-Before and After Request Handlers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-It is common for applications to need to perform one or more actions before a
-request is handled. Examples include authenticating and/or authorizing the
-client, opening a connection to a database, or checking if the requested
-resource can be obtained from a cache. The
-:func:`before_request() <microdot.Microdot.before_request>` decorator registers
-a function to be called before the request is dispatched to the route function.
-
-The following example registers a before request handler that ensures that the
-client is authenticated before the request is handled::
-
-    @app.before_request
-    def authenticate(request):
-        user = authorize(request)
-        if not user:
-            return 'Unauthorized', 401
-        request.g.user = user
-
-Before request handlers receive the request object as an argument. If the
-function returns a value, Microdot sends it to the client as the response, and
-does not invoke the route function. This gives before request handlers the
-power to intercept a request if necessary. The example above uses this
-technique to prevent an unauthorized user from accessing the requested
-resource.
-
-After request handlers registered with the
-:func:`after_request() <microdot.Microdot.after_request>` decorator are called
-after the route function returns a response. Their purpose is to perform any
-common closing or cleanup tasks. The next example shows a combination of before
-and after request handlers that print the time it takes for a request to be
-handled::
-
-    @app.before_request
-    def start_timer(request):
-        request.g.start_time = time.time()
-
-    @ap.after_request
-    def end_timer(request, response):
-        duration = time.time() - request.g.start_time
-        print(f'Request took {duration:0.2f} seconds')
-
-After request handlers receive the request and response objects as arguments.
-The function can return a modified response object to replace the original. If
-the function does not return a value, then the original response object is
-used.
-
-.. note::
-   The :ref:`request.g <The "g" Object>` object is a special object that allows
-   the before and after request handlers, as well sa the route function to
-   share data during the life of the request.
-
-Error Handlers
-^^^^^^^^^^^^^^
-
-When an error occurs during the handling of a request, Microdot ensures that
-the client receives an appropriate error response. Some of the common errors
-automatically handled by Microdot are:
-
-- 400 for malformed requests.
-- 404 for URLs that are not defined.
-- 405 for URLs that are defined, but not for the requested HTTP method.
-- 413 for requests that are larger than the allowed size.
-- 500 when the application raises an exception.
-
-While the above errors are fully complaint with the HTTP specification, the
-application might want to provide custom responses for them. The
-:func:`errorhandler() <microdot.Microdot.errorhandler>` decorator registers
-functions to respond to specific error codes. The following example shows a
-custom error handler for 404 errors::
-
-    @app.errorhandler(404)
-    def not_found(request):
-        return {'error': 'resource not found'}, 404
-
-The ``errorhandler()`` decorator has a second form, in which it takes an
-exception class as an argument. Microdot will then invoke the handler when the
-exception is an instance of the given class is raised. The next example
-provides a custom response for division by zero errors::
-
-    @app.errorhandler(ZeroDivisionError)
-    def division_by_zero(request, exception):
-        return {'error': 'division by zero'}, 500
-
-When the raised exception class does not have an error handler defined, but
-one or more of its base classes do, Microdot makes an attempt to invoke the
-most specific handler.
-
-Mounting a Sub-Application
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Small Microdot applications can be written an a single source file, but this
-is not the best option for applications that past certain size. To make it
-simpler to write large applications, Microdot supports the concept of
-sub-applications that can be "mounted" on a larger application, possibly with
-a common URL prefix applied to all of its routes.
-
-Consider, for example, a *customers.py* sub-application that implements
-operations on customers::
-
-    from microdot import Microdot
-
-    customers_app = Microdot()
-
-    @customers_app.get('/')
-    def get_customers(request):
-        # return all customers
-
-    @customers_app.post('/')
-    def new_customer(request):
-        # create a new customer
-
-In the same way, the *orders.py* sub-application implements operations on
-customer orders::
-
-    from microdot import Microdot
-
-    orders_app = Microdot()
-
-    @orders_app.get('/')
-    def get_orders(request):
-        # return all orders
-
-    @orders_app.post('/')
-    def new_order(request):
-        # create a new order
-
-Now the main application, which is stored in *main.py*, can import and mount
-the sub-applications to build the combined application::
-
-    from microdot import Microdot
-    from customers import customers_app
-    from orders import orders_app
-
-    def create_app():
-        app = Microdot()
-        app.mount(customers_app, url_prefix='/customers')
-        app.mount(orders_app, url_prefix='/orders')
-        return app
-
-    app = create_app()
-    app.run()
-
-The resulting application will have the customer endpoints available at
-*/customers/* and the order endpoints available at */orders/*.
-
-.. note::
-   Before request, after request and error handlers defined in the
-   sub-application are also copied over to the main application at mount time.
-   Once installed in the main application, these handlers will apply to the
-   whole application and not just the sub-application in which they were
-   created.
-
-Shutting Down the Server
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Web servers are designed to run forever, and are often stopped by sending them
-an interrupt signal. But having a way to gracefully stop the server is
-sometimes useful, especially in testing environments. Microdot provides a
-:func:`shutdown() <microdot.Microdot.shutdown>` method that can be invoked
-during the handling of a route to gracefully shut down the server when that
-request completes. The next example shows how to use this feature::
-
-    @app.get('/shutdown')
-    def shutdown(request):
-        request.app.shutdown()
-        return 'The server is shutting down...'
-
-The Request Object
-~~~~~~~~~~~~~~~~~~
-
-The :class:`Request <microdot.Request>` object encapsulates all the information
-passed by the client. It is passed as an argument to route handlers, as well as
-to before request, after request and error handlers.
-
-Request Attributes
-^^^^^^^^^^^^^^^^^^
-
-The request object provides access to the request attributes, including:
-
-- :attr:`method <microdot.Request.method>`: The HTTP method of the request.
-- :attr:`path <microdot.Request.path>`: The path of the request.
-- :attr:`args <microdot.Request.args>`: The query string parameters of the
-  request, as a :class:`MultiDict <microdot.MultiDict>` object.
-- :attr:`headers <microdot.Request.headers>`: The headers of the request, as a
-  dictionary.
-- :attr:`cookies <microdot.Request.cookies>`: The cookies that the client sent
-  with the request, as a dictionary.
-- :attr:`content_type <microdot.Request.content_type>`: The content type
-  specified by the client, or ``None`` if no content type was specified.
-- :attr:`content_length <microdot.Request.content_length>`: The content
-  length of the request, or 0 if no content length was specified.
-- :attr:`client_addr <microdot.Request.client_addr>`: The network address of
-  the client, as a tuple (host, port).
-- :attr:`app <microdot.Request.app>`: The application instance that created the
-  request.
-
-JSON Payloads
-^^^^^^^^^^^^^
-
-When the client sends a request that contains JSON data in the body, the
-application can access the parsed JSON data using the
-:attr:`json <microdot.Request.json>` attribute. The following example shows how
-to use this attribute::
-
-    @app.post('/customers')
-    def create_customer(request):
-        customer = request.json
-        # do something with customer
-        return {'success': True}
-
-.. note::
-   The client must set the ``Content-Type`` header to ``application/json`` for
-   the ``json`` attribute of the request object to be populated.
-
-URLEncoded Form Data
-^^^^^^^^^^^^^^^^^^^^
-
-The request object also supports standard HTML form submissions through the
-:attr:`form <microdot.Request.form>` attribute, which presents the form data
-as a :class:`MultiDict <microdot.MultiDict>` object. Example::
-
-    @app.route('/', methods=['GET', 'POST'])
-    def index(req):
-        name = 'Unknown'
-        if req.method == 'POST':
-            name = req.form.get('name')
-        return f'Hello {name}'
-
-.. note::
-   Form submissions are only parsed when the ``Content-Type`` header is set by
-   the client to ``application/x-www-form-urlencoded``. Form submissions using
-   the ``multipart/form-data`` content type are currently not supported.
-
-Accessing the Raw Request Body
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-For cases in which neither JSON nor form data is expected, the
-:attr:`body <microdot.Request.body>` request attribute returns the entire body
-of the request as a byte sequence.
-
-If the expected body is too large to fit in memory, the application can use the
-:attr:`stream <microdot.Request.stream>` request attribute to read the body
-contents as a file-like object.
-
-Cookies
-^^^^^^^
-
-Cookies that are sent by the client are made available throught the
-:attr:`cookies <microdot.Request.cookies>` attribute of the request object in
-dictionary form.
-
-The "g" Object
-^^^^^^^^^^^^^^
-
-Sometimes applications need to store data during the lifetime of a request, so
-that it can be shared between the before or after request handlers and the
-route function. The request object provides the :attr:`g <microdot.Request.g>`
-attribute for that purpose.
-
-In the following example, a before request handler
-authorizes the client and stores the username so that the route function can
-use it::
-
-    @app.before_request
-    def authorize(request):
-        username = authenticate_user(request)
-        if not username:
-            return 'Unauthorized', 401
-        request.g.username = username
-
-    @app.get('/')
-    def index(request):
-        return f'Hello, {request.g.username}!'
-
-Request-Specific After Request Handlers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Sometimes applications need to perform operations on the response object,
-before it is sent to the client, for example to set or remove a cookie. A good
-option to use for this is to define a request-specific after request handler
-using the :func:`after_request <microdot.Microdot.after_request>` decorator.
-Request-specific after request handlers are called by Microdot after the route
-function returns and all the application's after request handlers have been
-called.
-
-The next example shows how a cookie can be updated using a request-specific
-after request handler defined inside a route function::
-
-    @app.post('/logout')
-    def logout(request):
-        @request.after_request
-        def reset_session(request, response):
-            response.set_cookie('session', '', http_only=True)
-            return response
-
-        return 'Logged out'
-
-Request Limits
-^^^^^^^^^^^^^^
-
-To help prevent malicious attacks, Microdot provides some configuration options
-to limit the amount of information that is accepted:
-
-- :attr:`max_content_length <microdot.Microdot.max_content_length>`: The
-  maximum size accepted for the request body, in bytes. When a client sends a
-  request that is larger than this, the server will respond with a 413 error.
-  The default is 16KB.
-- :attr:`max_body_length <microdot.Microdot.max_body_length>`: The maximum
-  size that is loaded in the :attr:`body <microdot.Request.body>` attribute, in
-  bytes. Requests that have a body that is larger than this size but smaller
-  than the size set for ``max_content_length`` can only be accessed through the
-  :attr:`stream <microdot.Request.stream>` attribute. The default is also 16KB.
-- :attr:`max_readline <microdot.Microdot.max_readline>`: The maximum allowed
-  size for a request line, in bytes. The default is 2KB.
-
-The following example configures the application to accept requests with
-payloads up to 1MB big, but prevents requests that are larger than 8KB from
-being loaded into memory::
-
-    Request.max_content_length = 1024 * 1024
-    Request.max_body_length = 8 * 1024
-
-Responses
-~~~~~~~~~
-
-The value or values that are returned from the route function are used by
-Microdot to build the response that is sent to the client. The following
-sections describe the different types of responses that are supported.
-
-The Three Parts of a Response
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Route functions can return one, two or three values. The first or only value is
-always returned to the client in the response body::
-
-    @app.get('/')
-    def index(request):
-        return 'Hello, World!'
-
-In the above example, Microdot issues a standard 200 status code response, and
-inserts the necessary headers.
-
-The applicaton can provide its own status code as a second value returned from
-the route. The example below returns a 202 status code::
-
-    @app.get('/')
-    def index(request):
-        return 'Hello, World!', 202
-
-The application can also return a third value, a dictionary with additional
-headers that are added to, or replace the default ones provided by Microdot.
-The next example returns an HTML response, instead of a default text response::
-
-    @app.get('/')
-    def index(request):
-        return '<h1>Hello, World!</h1>', 202, {'Content-Type': 'text/html'}
-
-If the application needs to return custom headers, but does not need to change
-the default status code, then it can return two values, omitting the stauts
-code::
-
-    @app.get('/')
-    def index(request):
-        return '<h1>Hello, World!</h1>', {'Content-Type': 'text/html'}
-
-The application can also return a :class:`Response <microdot.Response>` object
-containing all the details of the response as a single value.
-
-JSON Responses
-^^^^^^^^^^^^^^
-
-If the application needs to return a response with JSON formatted data, it can
-return a dictionary or a list as the first value, and Microdot will
-automatically format the response as JSON.
-
-Example::
-
-    @app.get('/')
-    def index(request):
-        return {'hello': 'world'}
-
-.. note::
-   A ``Content-Type`` header set to ``application/json`` is automatically added
-   to the response.
-
-Redirects
-^^^^^^^^^
-
-The :func:`redirect <microdot.Response.redirect>` function is a helper that
-creates redirect responses::
-
-    from microdot import redirect
-
-    @app.get('/')
-    def index(request):
-        return redirect('/about')
-
-File Responses
-^^^^^^^^^^^^^^
-
-The :func:`send_file <microdot.Response.send_file>` function builds a response
-object for a file::
-
-        from microdot import send_file
-
-        @app.get('/')
-        def index(request):
-            return send_file('/static/index.html')
-
-.. note::
-   Unlike other web frameworks, Microdot does not automatically configure a
-   route to serve static files. The following is an example route that can be
-   added to the application to serve static files from a *static* directory in
-   the project::
-
-        @app.route('/static/<path:path>')
-        def static(request, path):
-            if '..' in path:
-                # directory traversal is not allowed
-                return 'Not found', 404
-            return send_file('static/' + path)
-
-Streaming Responses
-^^^^^^^^^^^^^^^^^^^
-
-Instead of providing a response as a single value, an application can opt to
-return a response that is generated in chunks by returning a generator. The
-example below returns all the numbers in the fibonacci sequence below 100::
-
-    @app.get('/fibonacci')
-    def fibonacci(request):
-        def generate_fibonacci():
-            a, b = 0, 1
-            while a < 100:
-                yield str(a) + '\n'
-                a, b = b, a + b
-
-        return generate_fibonacci()
-
-Changing the Default Response Content Type
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Microdot uses a ``text/plain`` content type by default for responses that do
-not explicitly include the ``Content-Type`` header. The application can change
-this default by setting the desired content type in the
-:attr:`default_content_type <microdot.Response.default_content_type>` attribute
-of the :class:`Response <microdot.Response>` class.
-
-The example that follows configures the application to use ``text/html`` as
-default content type::
-
-    from microdot import Response
-
-    Response.default_content_type = 'text/html'
-
-Setting Cookies
-^^^^^^^^^^^^^^^
-
-Many web applications rely on cookies to maintain client state between
-requests. Cookies can be set with the ``Set-Cookie`` header in the response,
-but since this is such a common practice, Microdot provides the
-:func:`set_cookie() <microdot.Response.set_cookie>` method in the response
-object to add a properly formatted cookie header to the response.
-
-Given that route functions do not normally work directly with the response
-object, the recommended way to set a cookie is to do it in a
-:ref:`Request-Specific After Request Handler <Request-Specific After Request Handlers>`.
-
-Example::
-
-    @app.get('/')
-    def index(request):
-        @request.after_request
-        def set_cookie(request, response):
-            response.set_cookie('name', 'value')
-            return response
-
-        return 'Hello, World!'
-
-Another option is to create a response object directly in the route function::
-
-    @app.get('/')
-    def index(request):
-        response = Response('Hello, World!')
-        response.set_cookie('name', 'value')
-        return response
-
-.. note::
-   Standard cookies do not offer sufficient privacy and security controls, so
-   never store sensitive information in them unless you are adding additional
-   protection mechanisms such as encryption or cryptographic signing. The
-   :ref:`session <Maintaing Secure User Sessions>` extension implements signed
-   cookies that prevent tampering by malicious actors.
-
-Concurrency
-~~~~~~~~~~~
-
-By default, Microdot runs in synchronous (single-threaded) mode. However, if
-the ``threading`` module is available, each request will be started on a
-separate thread and requests will be handled concurrently.
-
-Be aware that most microcontroller boards support a very limited form of
-multi-threading that is not appropriate for concurrent request handling. For
-that reason, use of the `threading <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/threading/threading.py>`_
-module on microcontroller platforms is not recommended.
-
-The :ref:`micropython_asyncio <Asynchronous Support with Asyncio>` extension
-provides a more robust concurrency option that is supported even on low-end
-MicroPython boards.

docs/users-guide/concurrency.rst

@@ -0,0 +1,36 @@
+Concurrency
+~~~~~~~~~~~
+
+Microdot implements concurrency through the ``asyncio`` package, which means
+that applications must be careful to prevent blocking in their handlers.
+
+"async def" handlers
+^^^^^^^^^^^^^^^^^^^^
+
+The recommendation for route handlers in Microdot is to use asynchronous
+functions, declared as ``async def``. Microdot executes these handler
+functions as native asynchronous tasks. The standard considerations for writing
+asynchronous code apply, and in particular blocking calls should be avoided to
+ensure the application runs smoothly and is always responsive.
+
+"def" handlers
+^^^^^^^^^^^^^^
+
+Microdot also supports the use of synchronous route handlers, declared as
+standard ``def`` functions. These handlers are handled differently under
+CPython and MicroPython.
+
+When running on CPython, Microdot executes synchronous handlers in a
+`thread executor <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor>`_,
+which uses a thread pool. The use of blocking or CPU intensive code in these
+handlers does not have such a negative effect on the application, because
+handlers do not run on the same thread as the asynchronous loop. On the other
+hand, the application will be affected by threading issues such as those caused
+by the Global Interpreter Lock.
+
+Under MicroPython the situation is different. Most microcontroller boards
+do not have or have very limited threading support, so Microdot executes
+synchronous handlers in the main and often only thread available. This means
+that these functions will block the asynchronous loop when they take too long
+to complete. The use of properly written asynchronous handlers should be
+preferred.

docs/users-guide/defining-routes.rst

@@ -0,0 +1,378 @@
+Defining Routes
+~~~~~~~~~~~~~~~
+
+In Microdot, routes define the logic of the web application.
+
+The route decorator
+^^^^^^^^^^^^^^^^^^^
+The :func:`route() <microdot.Microdot.route>` decorator is used to associate an
+application URL with the function that handles it. The only required argument
+to the decorator is the path portion of the URL.
+
+The following example creates a route for the root URL of the application::
+
+    @app.route('/')
+    async def index(request):
+        return 'Hello, world!'
+
+When a client requests the root URL (for example, *http://localhost:5000/*),
+Microdot will call the ``index()`` function, passing it a
+:class:`Request <microdot.Request>` object. The return value of the function
+is the response that is sent to the client.
+
+Below is another example, this one with a route for a URL with two components
+in its path::
+
+    @app.route('/users/active')
+    async def active_users(request):
+        return 'Active users: Susan, Joe, and Bob'
+
+The complete URL that maps to this route is
+*http://localhost:5000/users/active*.
+
+An application can define multiple routes. Microdot uses the path portion of
+the URL to determine the correct route function to call for each incoming
+request.
+
+Choosing the HTTP Method
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+All the example routes shown above are associated with ``GET`` requests, which
+are the default. Applications often need to define routes for other HTTP
+methods, such as ``POST``, ``PUT``, ``PATCH`` and ``DELETE``. The ``route()``
+decorator takes a ``methods`` optional argument, in which the application can
+provide a list of HTTP methods that the route should be associated with on the
+given path.
+
+The following example defines a route that handles ``GET`` and ``POST``
+requests within the same function::
+
+    @app.route('/invoices', methods=['GET', 'POST'])
+    async def invoices(request):
+        if request.method == 'GET':
+            return 'get invoices'
+        elif request.method == 'POST':
+            return 'create an invoice'
+
+As an alternative to the example above, in which a single function is used to
+handle multiple HTTP methods, sometimes it may be desirable to write a separate
+function for each HTTP method. The above example can be implemented with two
+routes as follows::
+
+    @app.route('/invoices', methods=['GET'])
+    async def get_invoices(request):
+        return 'get invoices'
+
+    @app.route('/invoices', methods=['POST'])
+    async def create_invoice(request):
+        return 'create an invoice'
+
+Microdot provides the :func:`get() <microdot.Microdot.get>`,
+:func:`post() <microdot.Microdot.post>`, :func:`put() <microdot.Microdot.put>`,
+:func:`patch() <microdot.Microdot.patch>`, and
+:func:`delete() <microdot.Microdot.delete>` decorators as shortcuts for the
+corresponding HTTP methods. The two example routes above can be written more
+concisely with them::
+
+    @app.get('/invoices')
+    async def get_invoices(request):
+        return 'get invoices'
+
+    @app.post('/invoices')
+    async def create_invoice(request):
+        return 'create an invoice'
+
+Including Dynamic Components in the URL Path
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The examples shown above all use hardcoded URL paths. Microdot also supports
+the definition of routes that have dynamic components in the path. For example,
+the following route associates all URLs that have a path following the pattern
+*http://localhost:5000/users/<username>* with the ``get_user()`` function::
+
+    @app.get('/users/<username>')
+    async def get_user(request, username):
+        return 'User: ' + username
+
+As shown in the example, a path component that is enclosed in angle brackets
+is considered a placeholder. Microdot accepts any values for that portion of
+the URL path, and passes the value received to the function as an argument
+after the request object.
+
+Routes are not limited to a single dynamic component. The following route shows
+how multiple dynamic components can be included in the path::
+
+    @app.get('/users/<firstname>/<lastname>')
+    async def get_user(request, firstname, lastname):
+        return 'User: ' + firstname + ' ' + lastname
+
+Dynamic path components are considered to be strings by default. An explicit
+type can be specified as a prefix, separated from the dynamic component name by
+a colon. The following route has two dynamic components declared as an integer
+and a string respectively::
+
+    @app.get('/users/<int:id>/<string:username>')
+    async def get_user(request, id, username):
+        return 'User: ' + username + ' (' + str(id) + ')'
+
+If a dynamic path component is defined as an integer, the value passed to the
+route function is also an integer. If the client sends a value that is not an
+integer in the corresponding section of the URL path, then the URL will not
+match and the route will not be called.
+
+A special type ``path`` can be used to capture the remainder of the path as a
+single argument. The difference between an argument of type ``path`` and one of
+type ``string`` is that the latter stops capturing when a ``/`` appears in the
+URL::
+
+    @app.get('/tests/<path:path>')
+    async def get_test(request, path):
+        return 'Test: ' + path
+
+The ``re`` type allows the application to provide a custom regular expression
+for the dynamic component. The next example defines a route that only matches
+usernames that begin with an upper or lower case letter, followed by a sequence
+of letters or numbers::
+
+    @app.get('/users/<re:[a-zA-Z][a-zA-Z0-9]*:username>')
+    async def get_user(request, username):
+        return 'User: ' + username
+
+The ``re`` type returns the URL component as a string, which sometimes may not
+be the most convenient. To convert a path component to something more
+meaningful than a string, the application can register a custom URL component
+type and provide a parser function that performs the conversion. In the
+following example, a ``hex`` custom type is registered to automatically
+convert hex numbers given in the path to numbers::
+
+    from microdot import URLPattern
+
+    URLPattern.register_type('hex', parser=lambda value: int(value, 16))
+
+    @app.get('/users/<hex:user_id>')
+    async def get_user(request, user_id):
+        user = get_user_by_id(user_id)
+        # ...
+
+In addition to the parser, the custom URL component can include a pattern,
+given as a regular expression. When a pattern is provided, the URL component
+will only match if the regular expression matches the value passed in the URL.
+The ``hex`` example above can be expanded with a pattern as follows::
+
+    URLPattern.register_type('hex', pattern='[0-9a-fA-F]+',
+                             parser=lambda value: int(value, 16))
+
+In cases where a pattern isn't provided, or when the pattern is unable to
+filter out all invalid values, the parser function can return ``None`` to
+indicate a failed match. The next example shows how the parser for the ``hex``
+type can be expanded to do that::
+
+    def hex_parser(value):
+        try:
+            return int(value, 16)
+        except ValueError:
+            return None
+
+    URLPattern.register_type('hex', parser=hex_parser)
+
+.. note::
+   Dynamic path components are passed to route functions as keyword arguments,
+   so the names of the function arguments must match the names declared in the
+   path specification.
+
+Before and After Request Handlers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is common for applications to need to perform one or more actions before a
+request is handled. Examples include authenticating and/or authorizing the
+client, opening a connection to a database, or checking if the requested
+resource can be obtained from a cache. The
+:func:`before_request() <microdot.Microdot.before_request>` decorator registers
+a function to be called before the request is dispatched to the route function.
+
+The following example registers a before-request handler that ensures that the
+client is authenticated before the request is handled::
+
+    @app.before_request
+    async def authenticate(request):
+        user = authorize(request)
+        if not user:
+            return 'Unauthorized', 401
+        request.g.user = user
+
+Before-request handlers receive the request object as an argument. If the
+function returns a value, Microdot sends it to the client as the response, and
+does not invoke the route function. This gives before-request handlers the
+power to intercept a request if necessary. The example above uses this
+technique to prevent an unauthorized user from accessing the requested
+route.
+
+After-request handlers registered with the
+:func:`after_request() <microdot.Microdot.after_request>` decorator are called
+after the route function returns a response. Their purpose is to perform any
+common closing or cleanup tasks. The next example shows a combination of
+before- and after-request handlers that print the time it takes for a request
+to be handled::
+
+    @app.before_request
+    async def start_timer(request):
+        request.g.start_time = time.time()
+
+    @app.after_request
+    async def end_timer(request, response):
+        duration = time.time() - request.g.start_time
+        print(f'Request took {duration:0.2f} seconds')
+
+After-request handlers receive the request and response objects as arguments,
+and they can return a modified response object to replace the original. If
+no value is returned from an after-request handler, then the original response
+object is used.
+
+The after-request handlers are only invoked for successful requests. The
+:func:`after_error_request() <microdot.Microdot.after_error_request>`
+decorator can be used to register a function that is called after an error
+occurs. The function receives the request and the error response and is
+expected to return an updated response object after performing any necessary
+cleanup.
+
+.. note::
+   The :ref:`request.g <The "g" Object>` object used in many of the above
+   examples is a special object that allows the before- and after-request
+   handlers, as well as the route function to share data during the life of the
+   request.
+
+Error Handlers
+^^^^^^^^^^^^^^
+
+When an error occurs during the handling of a request, Microdot ensures that
+the client receives an appropriate error response. Some of the common errors
+automatically handled by Microdot are:
+
+- 400 for malformed requests.
+- 404 for URLs that are unknown.
+- 405 for URLs that are known, but not implemented for the requested HTTP
+  method.
+- 413 for requests that are larger than the allowed size.
+- 500 when the application raises an unhandled exception.
+
+While the above errors are fully complaint with the HTTP specification, the
+application might want to provide custom responses for them. The
+:func:`errorhandler() <microdot.Microdot.errorhandler>` decorator registers
+functions to respond to specific error codes. The following example shows a
+custom error handler for 404 errors::
+
+    @app.errorhandler(404)
+    async def not_found(request):
+        return {'error': 'resource not found'}, 404
+
+The ``errorhandler()`` decorator has a second form, in which it takes an
+exception class as an argument. Microdot will invoke the handler when an
+unhandled exception that is an instance of the given class is raised. The next
+example provides a custom response for division by zero errors::
+
+    @app.errorhandler(ZeroDivisionError)
+    async def division_by_zero(request, exception):
+        return {'error': 'division by zero'}, 500
+
+When the raised exception class does not have an error handler defined, but
+one or more of its parent classes do, Microdot makes an attempt to invoke the
+most specific handler.
+
+Mounting a Sub-Application
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Small Microdot applications can be written as a single source file, but this
+is not the best option for applications that pass a certain size. To make it
+simpler to write large applications, Microdot supports the concept of
+sub-applications that can be "mounted" on a larger application, possibly with
+a common URL prefix applied to all of its routes. For developers familiar with
+the Flask framework, this is a similar concept to Flask's blueprints.
+
+Consider, for example, a *customers.py* sub-application that implements
+operations on customers::
+
+    from microdot import Microdot
+
+    customers_app = Microdot()
+
+    @customers_app.get('/')
+    async def get_customers(request):
+        # return all customers
+
+    @customers_app.post('/')
+    async def new_customer(request):
+        # create a new customer
+
+Similar to the above, the *orders.py* sub-application implements operations on
+customer orders::
+
+    from microdot import Microdot
+
+    orders_app = Microdot()
+
+    @orders_app.get('/')
+    async def get_orders(request):
+        # return all orders
+
+    @orders_app.post('/')
+    async def new_order(request):
+        # create a new order
+
+Now the main application, which is stored in *main.py*, can import and mount
+the sub-applications to build the larger combined application::
+
+    from microdot import Microdot
+    from customers import customers_app
+    from orders import orders_app
+
+    def create_app():
+        app = Microdot()
+        app.mount(customers_app, url_prefix='/customers')
+        app.mount(orders_app, url_prefix='/orders')
+        return app
+
+    app = create_app()
+    app.run()
+
+The resulting application will have the customer endpoints available at
+*/customers/* and the order endpoints available at */orders/*.
+
+.. note::
+   During the handling of a request, the
+   :attr:`Request.url_prefix <microdot.Microdot.url_prefix>` attribute is
+   set to the URL prefix under which the sub-application was mounted, or an
+   empty string if the endpoint did not come from a sub-application or the
+   sub-application was mounted without a URL prefix. It is possible to issue a
+   redirect that is relative to the sub-application as follows::
+
+      return redirect(request.url_prefix + '/relative-url')
+
+When mounting an application as shown above, before-request, after-request and
+error handlers defined in the sub-application are copied over to the main
+application at mount time. Once installed in the main application, these
+handlers will apply to the whole application and not just the sub-application
+in which they were created.
+
+The :func:`mount() <microdot.Microdot.mount>` method has a ``local`` argument
+that defaults to ``False``. When this argument is set to ``True``, the
+before-request, after-request and error handlers defined in the sub-application
+will only apply to the sub-application.
+
+Shutting Down the Server
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Web servers are designed to run forever, and are often stopped by sending them
+an interrupt signal. But having a way to gracefully stop the server is
+sometimes useful, especially in testing environments. Microdot provides a
+:func:`shutdown() <microdot.Microdot.shutdown>` method that can be invoked
+during the handling of a route to gracefully shut down the server when that
+request completes. The next example shows how to use this feature::
+
+    @app.get('/shutdown')
+    async def shutdown(request):
+        request.app.shutdown()
+        return 'The server is shutting down...'
+
+The request that invokes the ``shutdown()`` method will complete, and then the
+server will not accept any new requests and stop once any remaining requests
+complete. At this point the ``app.run()`` call will return.

docs/users-guide/index.rst

@@ -0,0 +1,18 @@
+User's Guide
+------------
+
+This section describes the main features of Microdot.
+
+.. toctree::
+   :maxdepth: 1
+
+   intro
+   defining-routes
+   request-object
+   responses
+   concurrency
+
+For detailed reference information, consult the :ref:`API Reference`.
+
+If you are familiar with releases of Microdot before 2.x, review the
+:ref:`Migration Guide <Migrating to Microdot 2.x from Older Releases>`.

docs/users-guide/intro.rst

@@ -0,0 +1,160 @@
+Introduction
+~~~~~~~~~~~~
+
+This section covers how to create and run a basic Microdot web application.
+
+A simple web server
+^^^^^^^^^^^^^^^^^^^
+
+The following is an example of a simple web server::
+
+    from microdot import Microdot
+
+    app = Microdot()
+
+    @app.route('/')
+    async def index(request):
+        return 'Hello, world!'
+
+    app.run()
+
+The script imports the :class:`Microdot <microdot.Microdot>` class and creates
+an application instance from it.
+
+The application instance provides a :func:`route() <microdot.Microdot.route>`
+decorator, which is used to define one or more routes, as needed by the
+application.
+
+The ``route()`` decorator takes the path portion of the URL as an
+argument, and maps it to the decorated function, so that the function is called
+when the client requests the URL.
+
+When the function is called, it is passed a :class:`Request <microdot.Request>`
+object as an argument, which provides access to the information passed by the
+client. The value returned by the function is sent back to the client as the
+response.
+
+Microdot is an asynchronous framework that uses the ``asyncio`` package. Route
+handler functions can be defined as ``async def`` or ``def`` functions, but
+``async def`` functions are recommended for performance.
+
+The :func:`run() <microdot.Microdot.run>` method starts the application's web
+server on port 5000 by default, and creates its own asynchronous loop. This
+method blocks while it waits for connections from clients.
+
+For some applications it may be necessary to run the web server alongside other
+asynchronous tasks, on an already running loop. In that case, instead of
+``app.run()`` the web server can be started by invoking the
+:func:`start_server() <microdot.Microdot.start_server>` coroutine as shown in
+the following example::
+
+    import asyncio
+    from microdot import Microdot
+
+    app = Microdot()
+
+    @app.route('/')
+    async def index(request):
+        return 'Hello, world!'
+
+    async def main():
+        # start the server in a background task
+        server = asyncio.create_task(app.start_server())
+
+        # ... do other asynchronous work here ...
+
+        # cleanup before ending the application
+        await server
+
+    asyncio.run(main())
+
+Running with CPython
+^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :align: left
+
+   * - Required Microdot source files
+     - | `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello.py>`_
+
+When using CPython, you can start the web server by running the script that
+has the ``app.run()`` call at the bottom::
+
+    python main.py
+
+After starting the script, open a web browser and navigate to
+*http://localhost:5000/* to access the application at the default address for
+the Microdot web server. From other computers in the same network, use the IP
+address or hostname of the computer running the script instead of
+``localhost``.
+
+Running with MicroPython
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :align: left
+
+   * - Required Microdot source files
+     - | `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello.py>`_
+       | `gpio.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/gpio/gpio.py>`_
+
+When using MicroPython, you can upload a *main.py* file containing the web
+server code to your device, along with the required Microdot files, as defined
+in the :ref:`MicroPython Installation` section.
+
+MicroPython will automatically run *main.py* when the device is powered on, so
+the web server will automatically start. The application can be accessed on
+port 5000 at the device's IP address. As indicated above, the port can be
+changed by passing the ``port`` argument to the ``run()`` method.
+
+.. note::
+   Microdot does not configure the network interface of the device in which it
+   is running. If your device requires a network connection to be made in
+   advance, for example to a Wi-Fi access point, this must be configured before
+   the ``run()`` method is invoked.
+
+Web Server Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :func:`run() <microdot.Microdot.run>` and
+:func:`start_server() <microdot.Microdot.start_server>` methods support a few
+arguments to configure the web server.
+
+- ``port``: The port number to listen on. Pass the desired port number in this
+  argument to use a port different than the default of 5000. For example::
+
+    app.run(port=6000)
+
+- ``host``: The IP address of the network interface to listen on. By default
+  the server listens on all available interfaces. To listen only on the local
+  loopback interface, pass ``'127.0.0.1'`` as value for this argument.
+- ``debug``: when set to ``True``, the server ouputs logging information to the
+  console. The default is ``False``.
+- ``ssl``: an ``SSLContext`` instance that configures the server to use TLS
+  encryption, or ``None`` to disable TLS use. The default is ``None``. The
+  following example demonstrates how to configure the server with an SSL
+  certificate stored in *cert.pem* and *key.pem* files::
+
+    import ssl
+
+    # ...
+
+    sslctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    sslctx.load_cert_chain('cert.pem', 'key.pem')
+    app.run(port=4443, debug=True, ssl=sslctx)
+
+.. note::
+   When using CPython, the certificate and key files must be given in PEM
+   format. When using MicroPython, these files must be given in DER format.

docs/users-guide/request-object.rst

@@ -0,0 +1,169 @@
+The Request Object
+~~~~~~~~~~~~~~~~~~
+
+The :class:`Request <microdot.Request>` object encapsulates all the information
+passed by the client. It is passed as an argument to route handlers, as well as
+to before-request, after-request and error handlers.
+
+Request Attributes
+^^^^^^^^^^^^^^^^^^
+
+The request object provides access to the request attributes, including:
+
+- :attr:`method <microdot.Request.method>`: The HTTP method of the request.
+- :attr:`path <microdot.Request.path>`: The path of the request.
+- :attr:`args <microdot.Request.args>`: The query string parameters of the
+  request, as a :class:`MultiDict <microdot.MultiDict>` object.
+- :attr:`headers <microdot.Request.headers>`: The headers of the request, as a
+  dictionary.
+- :attr:`cookies <microdot.Request.cookies>`: The cookies that the client sent
+  with the request, as a dictionary.
+- :attr:`content_type <microdot.Request.content_type>`: The content type
+  specified by the client, or ``None`` if no content type was specified.
+- :attr:`content_length <microdot.Request.content_length>`: The content
+  length of the request, or 0 if no content length was specified.
+- :attr:`json <microdot.Request.json>`: The parsed JSON data in the request
+  body. See :ref:`below <JSON Payloads>` for additional details.
+- :attr:`form <microdot.Request.form>`: The parsed form data in the request
+  body, as a dictionary. See :ref:`below <Form Data>` for additional details.
+- :attr:`files <microdot.Request.files>`: A dictionary with the file uploads
+  included in the request body. Note that file uploads are only supported when
+  the :ref:`Multipart Forms` extension is used.
+- :attr:`client_addr <microdot.Request.client_addr>`: The network address of
+  the client, as a tuple (host, port).
+- :attr:`app <microdot.Request.app>`: The application instance that created the
+  request.
+- :attr:`g <microdot.Request.g>`: The ``g`` object, where handlers can store
+  request-specific data to be shared among handlers. See :ref:`The "g" Object`
+  for details.
+
+JSON Payloads
+^^^^^^^^^^^^^
+
+When the client sends a request that contains JSON data in the body, the
+application can access the parsed JSON data using the
+:attr:`json <microdot.Request.json>` attribute. The following example shows how
+to use this attribute::
+
+    @app.post('/customers')
+    async def create_customer(request):
+        customer = request.json
+        # do something with customer
+        return {'success': True}
+
+.. note::
+   The client must set the ``Content-Type`` header to ``application/json`` for
+   the ``json`` attribute of the request object to be populated.
+
+Form Data
+^^^^^^^^^
+
+The request object also supports standard HTML form submissions through the
+:attr:`form <microdot.Request.form>` attribute, which presents the form data
+as a :class:`MultiDict <microdot.MultiDict>` object. Example::
+
+    @app.route('/', methods=['GET', 'POST'])
+    async def index(req):
+        name = 'Unknown'
+        if req.method == 'POST':
+            name = req.form.get('name')
+        return f'Hello {name}'
+
+.. note::
+   Form submissions automatically parsed when the ``Content-Type`` header is
+   set by the client to ``application/x-www-form-urlencoded``. For form
+   submissions that use the ``multipart/form-data`` content type the
+   :ref:`Multipart Forms` extension must be used.
+
+Accessing the Raw Request Body
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For cases in which neither JSON nor form data is expected, the
+:attr:`body <microdot.Request.body>` request attribute returns the entire body
+of the request as a byte sequence.
+
+If the expected body is too large to fit safely in memory, the application can
+use the :attr:`stream <microdot.Request.stream>` request attribute to read the
+body contents as a file-like object. The
+:attr:`max_body_length <microdot.Request.max_body_length>` attribute of the
+request object defines the size at which bodies are streamed instead of loaded
+into memory.
+
+Cookies
+^^^^^^^
+
+Cookies that are sent by the client are made available through the
+:attr:`cookies <microdot.Request.cookies>` attribute of the request object in
+dictionary form.
+
+The "g" Object
+^^^^^^^^^^^^^^
+
+Sometimes applications need to store data during the lifetime of a request, so
+that it can be shared between the before- and after-request handlers, the
+route function and any error handlers. The request object provides the
+:attr:`g <microdot.Request.g>` attribute for that purpose.
+
+In the following example, a before request handler authorizes the client and
+stores the username so that the route function can use it::
+
+    @app.before_request
+    async def authorize(request):
+        username = authenticate_user(request)
+        if not username:
+            return 'Unauthorized', 401
+        request.g.username = username
+
+    @app.get('/')
+    async def index(request):
+        return f'Hello, {request.g.username}!'
+
+Request-Specific After-Request Handlers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes applications need to perform operations on the response object
+before it is sent to the client, for example to set or remove a cookie. A good
+option to use for this is to define a request-specific after-request handler
+using the :func:`after_request <microdot.Microdot.after_request>` decorator.
+Request-specific after-request handlers are called by Microdot after the route
+function returns and all the application-wide after-request handlers have been
+called.
+
+The next example shows how a cookie can be updated using a request-specific
+after-request handler defined inside a route function::
+
+    @app.post('/logout')
+    async def logout(request):
+        @request.after_request
+        def reset_session(request, response):
+            response.set_cookie('session', '', http_only=True)
+            return response
+
+        return 'Logged out'
+
+Request Limits
+^^^^^^^^^^^^^^
+
+To help prevent malicious attacks, Microdot provides some configuration options
+to limit the amount of information that is accepted:
+
+- :attr:`max_content_length <microdot.Request.max_content_length>`: The
+  maximum size accepted for the request body, in bytes. When a client sends a
+  request that is larger than this, the server will respond with a 413 error.
+  The default is 16KB.
+- :attr:`max_body_length <microdot.Request.max_body_length>`: The maximum
+  size that is loaded in the :attr:`body <microdot.Request.body>` attribute, in
+  bytes. Requests that have a body that is larger than this size but smaller
+  than the size set for ``max_content_length`` can only be accessed through the
+  :attr:`stream <microdot.Request.stream>` attribute. The default is also 16KB.
+- :attr:`max_readline <microdot.Request.max_readline>`: The maximum allowed
+  size for a request line, in bytes. The default is 2KB.
+
+The following example configures the application to accept requests with
+payloads up to 1MB in size, but prevents requests that are larger than 8KB from
+being loaded into memory::
+
+    from microdot import Request
+
+    Request.max_content_length = 1024 * 1024
+    Request.max_body_length = 8 * 1024

docs/users-guide/responses.rst

@@ -0,0 +1,200 @@
+Responses
+~~~~~~~~~
+
+The value or values that are returned from the route function are used by
+Microdot to build the response that is sent to the client. The following
+sections describe the different types of responses that are supported.
+
+The Three Parts of a Response
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Route functions can return one, two or three values. The first and most
+important value is the response body::
+
+    @app.get('/')
+    async def index(request):
+        return 'Hello, World!'
+
+In the above example, Microdot issues a standard 200 status code response
+indicating a successful request. The body of the response is the
+``'Hello, World!'`` string returned by the function. Microdot includes default
+headers with this response, including the ``Content-Type`` header set to
+``text/plain`` to indicate a response in plain text.
+
+The application can provide its own status code as a second value returned from
+the route to override the 200 default. The example below returns a 202 status
+code::
+
+    @app.get('/')
+    async def index(request):
+        return 'Hello, World!', 202
+
+The application can also return a third value, a dictionary with additional
+headers that are added to, or replace the default ones included by Microdot.
+The next example returns an HTML response, instead of the default plain text
+response::
+
+    @app.get('/')
+    async def index(request):
+        return '<h1>Hello, World!</h1>', 202, {'Content-Type': 'text/html'}
+
+If the application does not need to return a body, then it can omit it and
+have the status code as the first or only returned value::
+
+    @app.get('/')
+    async def index(request):
+        return 204
+
+Likewise, if the application needs to return a body and custom headers, but
+does not need to change the default status code, then it can return two values,
+omitting the status code::
+
+    @app.get('/')
+    async def index(request):
+        return '<h1>Hello, World!</h1>', {'Content-Type': 'text/html'}
+
+Lastly, the application can also return a :class:`Response <microdot.Response>`
+object containing all the details of the response as a single value.
+
+JSON Responses
+^^^^^^^^^^^^^^
+
+If the application needs to return a response with JSON formatted data, it can
+return a dictionary or a list as the first value, and Microdot will
+automatically format the response as JSON.
+
+Example::
+
+    @app.get('/')
+    async def index(request):
+        return {'hello': 'world'}
+
+.. note::
+   A ``Content-Type`` header set to ``application/json`` is automatically added
+   to the response.
+
+Redirects
+^^^^^^^^^
+
+The :func:`redirect <microdot.Response.redirect>` function is a helper that
+creates redirect responses::
+
+    from microdot import redirect
+
+    @app.get('/')
+    async def index(request):
+        return redirect('/about')
+
+File Responses
+^^^^^^^^^^^^^^
+
+The :func:`send_file <microdot.Response.send_file>` function builds a response
+object for a file::
+
+        from microdot import send_file
+
+        @app.get('/')
+        async def index(request):
+            return send_file('/static/index.html')
+
+A suggested caching duration can be returned to the client in the ``max_age``
+argument::
+
+        from microdot import send_file
+
+        @app.get('/')
+        async def image(request):
+            return send_file('/static/image.jpg', max_age=3600)  # in seconds
+
+.. note::
+   Unlike other web frameworks, Microdot does not automatically configure a
+   route to serve static files. The following is an example route that can be
+   added to the application to serve static files from a *static* directory in
+   the project::
+
+        @app.route('/static/<path:path>')
+        async def static(request, path):
+            if '..' in path:
+                # directory traversal is not allowed
+                return 'Not found', 404
+            return send_file('static/' + path, max_age=86400)
+
+Streaming Responses
+^^^^^^^^^^^^^^^^^^^
+
+Instead of providing a response as a single value, an application can opt to
+return a response that is generated in chunks, by returning a Python generator.
+The example below returns all the numbers in the fibonacci sequence below 100::
+
+    @app.get('/fibonacci')
+    async def fibonacci(request):
+        async def generate_fibonacci():
+            a, b = 0, 1
+            while a < 100:
+                yield str(a) + '\n'
+                a, b = b, a + b
+
+        return generate_fibonacci()
+
+.. note::
+   Under CPython, the generator function can be a ``def`` or ``async def``
+   function, as well as a class-based generator.
+
+   Under MicroPython, asynchronous generator functions are not supported, so
+   only ``def`` generator functions can be used. Asynchronous class-based
+   generators are supported.
+
+Changing the Default Response Content Type
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Microdot uses a ``text/plain`` content type by default for responses that do
+not explicitly include the ``Content-Type`` header. The application can change
+this default by setting the desired content type in the
+:attr:`default_content_type <microdot.Response.default_content_type>` attribute
+of the :class:`Response <microdot.Response>` class.
+
+The example that follows configures the application to use ``text/html`` as
+default content type::
+
+    from microdot import Response
+
+    Response.default_content_type = 'text/html'
+
+Setting Cookies
+^^^^^^^^^^^^^^^
+
+Many web applications rely on cookies to maintain client state between
+requests. Cookies can be set with the ``Set-Cookie`` header in the response,
+but since this is such a common practice, Microdot provides the
+:func:`set_cookie() <microdot.Response.set_cookie>` method in the response
+object to add a properly formatted cookie header to the response.
+
+Given that route functions do not normally work directly with the response
+object, the recommended way to set a cookie is to do it in a
+:ref:`request-specific after-request handler <Request-Specific After-Request Handlers>`.
+
+Example::
+
+    @app.get('/')
+    async def index(request):
+        @request.after_request
+        async def set_cookie(request, response):
+            response.set_cookie('name', 'value')
+            return response
+
+        return 'Hello, World!'
+
+Another option is to create a response object directly in the route function::
+
+    @app.get('/')
+    async def index(request):
+        response = Response('Hello, World!')
+        response.set_cookie('name', 'value')
+        return response
+
+.. note::
+   Standard cookies do not offer sufficient privacy and security controls, so
+   never store sensitive information in them unless you are adding additional
+   protection mechanisms such as encryption or cryptographic signing. The
+   :ref:`session <Maintaining Secure User Sessions>` extension implements signed
+   cookies that prevent tampering by malicious actors.

examples/auth/README.md

@@ -0,0 +1 @@
+This directory contains examples that demonstrate basic and token authentication.

examples/auth/basic_auth.py

@@ -0,0 +1,31 @@
+from microdot import Microdot
+from microdot.auth import BasicAuth
+from pbkdf2 import generate_password_hash, check_password_hash
+
+
+# this example provides an implementation of the generate_password_hash and
+# check_password_hash functions that can be used in MicroPython. On CPython
+# there are many other options for password hashisng so there is no need to use
+# this custom solution.
+USERS = {
+    'susan': generate_password_hash('hello'),
+    'david': generate_password_hash('bye'),
+}
+app = Microdot()
+auth = BasicAuth()
+
+
+@auth.authenticate
+async def check_credentials(request, username, password):
+    if username in USERS and check_password_hash(USERS[username], password):
+        return username
+
+
+@app.route('/')
+@auth
+async def index(request):
+    return f'Hello, {request.g.current_user}!'
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

examples/auth/pbkdf2.py

@@ -0,0 +1,47 @@
+import os
+import hashlib
+
+# PBKDF2 secure password hashing algorithm obtained from:
+# https://codeandlife.com/2023/01/06/how-to-calculate-pbkdf2-hmac-sha256-with-
+# python,-example-code/
+
+
+def sha256(b):
+    return hashlib.sha256(b).digest()
+
+
+def ljust(b, n, f):
+    return b + f * (n - len(b))
+
+
+def gethmac(key, content):
+    okeypad = bytes(v ^ 0x5c for v in ljust(key, 64, b'\0'))
+    ikeypad = bytes(v ^ 0x36 for v in ljust(key, 64, b'\0'))
+    return sha256(okeypad + sha256(ikeypad + content))
+
+
+def pbkdf2(pwd, salt, iterations=1000):
+    U = salt + b'\x00\x00\x00\x01'
+    T = bytes(64)
+    for _ in range(iterations):
+        U = gethmac(pwd, U)
+        T = bytes(a ^ b for a, b in zip(U, T))
+    return T
+
+
+# The number of iterations may need to be adjusted depending on the hardware.
+# Lower numbers make the password hashing algorithm faster but less secure, so
+# the largest number that can be tolerated should be used.
+def generate_password_hash(password, salt=None, iterations=100000):
+    salt = salt or os.urandom(16)
+    dk = pbkdf2(password.encode(), salt, iterations)
+    return f'pbkdf2-hmac-sha256:{salt.hex()}:{iterations}:{dk.hex()}'
+
+
+def check_password_hash(password_hash, password):
+    algorithm, salt, iterations, dk = password_hash.split(':')
+    iterations = int(iterations)
+    if algorithm != 'pbkdf2-hmac-sha256':
+        return False
+    return pbkdf2(password.encode(), salt=bytes.fromhex(salt),
+                  iterations=iterations) == bytes.fromhex(dk)

examples/auth/token_auth.py

@@ -0,0 +1,26 @@
+from microdot import Microdot
+from microdot.auth import TokenAuth
+
+app = Microdot()
+auth = TokenAuth()
+
+TOKENS = {
+    'susan-token': 'susan',
+    'david-token': 'david',
+}
+
+
+@auth.authenticate
+async def check_token(request, token):
+    if token in TOKENS:
+        return TOKENS[token]
+
+
+@app.route('/')
+@auth
+async def index(request):
+    return f'Hello, {request.g.current_user}!'
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

examples/benchmark/mem.py

@@ -4,7 +4,7 @@ app = Microdot()
 
 
 @app.get('/')
-def index(req):
+async def index(req):
     return {'hello': 'world'}
 
 

examples/benchmark/mem_asgi.py

@@ -1,4 +1,4 @@
-from microdot_asgi import Microdot
+from microdot.asgi import Microdot
 
 app = Microdot()
 

examples/benchmark/mem_async.py

@@ -1,11 +0,0 @@
-from microdot_asyncio import Microdot
-
-app = Microdot()
-
-
-@app.get('/')
-async def index(req):
-    return {'hello': 'world'}
-
-
-app.run()

examples/benchmark/mem_fastapi.py

@@ -4,5 +4,5 @@ app = FastAPI()
 
 
 @app.get('/')
-def index():
+async def index():
     return {'hello': 'world'}

examples/benchmark/mem_quart.py

@@ -4,5 +4,5 @@ app = Quart(__name__)
 
 
 @app.get('/')
-def index():
+async def index():
     return {'hello': 'world'}

examples/benchmark/mem_wsgi.py

@@ -1,4 +1,4 @@
-from microdot_wsgi import Microdot
+from microdot.wsgi import Microdot
 
 app = Microdot()
 

examples/benchmark/requirements.in

@@ -0,0 +1,9 @@
+pip-tools
+flask
+quart
+fastapi
+gunicorn
+uvicorn
+requests
+psutil
+humanize

examples/benchmark/requirements.txt

@@ -1,33 +1,113 @@
-aiofiles==0.8.0
-anyio==3.6.1
-blinker==1.5
-certifi==2022.6.15
-charset-normalizer==2.1.0
-click==8.1.3
-fastapi==0.79.0
-Flask==2.2.1
-gunicorn==20.1.0
-h11==0.13.0
-h2==4.1.0
-hpack==4.0.0
-humanize==4.3.0
-hypercorn==0.13.2
-hyperframe==6.0.1
-idna==3.3
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+aiofiles==23.2.1
+    # via quart
+annotated-types==0.6.0
+    # via pydantic
+anyio==3.7.1
+    # via starlette
+blinker==1.7.0
+    # via
+    #   flask
+    #   quart
+build==1.0.3
+    # via pip-tools
+certifi==2024.7.4
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via
+    #   flask
+    #   pip-tools
+    #   quart
+    #   uvicorn
+fastapi==0.109.1
+    # via -r requirements.in
+flask==3.0.0
+    # via
+    #   -r requirements.in
+    #   quart
+gunicorn==23.0.0
+    # via -r requirements.in
+h11==0.16.0
+    # via
+    #   hypercorn
+    #   uvicorn
+    #   wsproto
+h2==4.3.0
+    # via hypercorn
+hpack==4.1.0
+    # via h2
+humanize==4.9.0
+    # via -r requirements.in
+hypercorn==0.15.0
+    # via quart
+hyperframe==6.1.0
+    # via h2
+idna==3.7
+    # via
+    #   anyio
+    #   requests
 itsdangerous==2.1.2
-Jinja2==3.1.2
-MarkupSafe==2.1.1
-microdot
+    # via
+    #   flask
+    #   quart
+jinja2==3.1.6
+    # via
+    #   flask
+    #   quart
+markupsafe==2.1.3
+    # via
+    #   jinja2
+    #   quart
+    #   werkzeug
+packaging==23.2
+    # via
+    #   build
+    #   gunicorn
+pip-tools==7.3.0
+    # via -r requirements.in
 priority==2.0.0
-psutil==5.9.1
-pydantic==1.9.1
-quart==0.18.0
-requests==2.28.1
-sniffio==1.2.0
-starlette==0.19.1
-toml==0.10.2
-typing_extensions==4.3.0
-urllib3==1.26.11
-uvicorn==0.18.2
-Werkzeug==2.2.1
-wsproto==1.1.0
+    # via hypercorn
+psutil==5.9.6
+    # via -r requirements.in
+pydantic==2.5.2
+    # via fastapi
+pydantic-core==2.14.5
+    # via pydantic
+pyproject-hooks==1.0.0
+    # via build
+quart==0.20.0
+    # via -r requirements.in
+requests==2.32.4
+    # via -r requirements.in
+sniffio==1.3.0
+    # via anyio
+starlette==0.35.1
+    # via fastapi
+typing-extensions==4.9.0
+    # via
+    #   fastapi
+    #   pydantic
+    #   pydantic-core
+urllib3==2.6.0
+    # via requests
+uvicorn==0.24.0.post1
+    # via -r requirements.in
+werkzeug==3.0.6
+    # via
+    #   flask
+    #   quart
+wheel==0.42.0
+    # via pip-tools
+wsproto==1.2.0
+    # via hypercorn
+
+# The following packages are considered to be unsafe in a requirements file:
+# pip
+# setuptools

examples/benchmark/run.py

@@ -1,6 +1,7 @@
 import os
 import subprocess
 import time
+from timeit import timeit
 import requests
 import psutil
 import humanize
@@ -13,13 +14,8 @@ apps = [
     ),
     (
         'micropython mem.py',
-        {'MICROPYPATH': '../../src'},
-        'microdot-micropython-sync'
-    ),
-    (
-        'micropython mem_async.py',
         {'MICROPYPATH': '../../src:../../libs/micropython'},
-        'microdot-micropython-async'
+        'microdot-micropython'
     ),
     (
         ['python', '-c', 'import time; time.sleep(10)'],
@@ -29,66 +25,65 @@ apps = [
     (
         'python mem.py',
         {'PYTHONPATH': '../../src'},
-        'microdot-cpython-sync'
-    ),
-    (
-        'python mem_async.py',
-        {'PYTHONPATH': '../../src'},
-        'microdot-cpython-async'
-    ),
-    (
-        'gunicorn --workers 1 --bind :5000 mem_wsgi:app',
-        {'PYTHONPATH': '../../src'},
-        'microdot-gunicorn-sync'
+        'microdot-cpython'
     ),
     (
         'uvicorn --workers 1 --port 5000 mem_asgi:app',
         {'PYTHONPATH': '../../src'},
-        'microdot-uvicorn-async'
+        'microdot-uvicorn'
+    ),
+    (
+        'gunicorn --workers 1 --bind :5000 mem_wsgi:app',
+        {'PYTHONPATH': '../../src'},
+        'microdot-gunicorn'
     ),
     (
         'flask run',
         {'FLASK_APP': 'mem_flask.py'},
-        'flask-run-sync'
+        'flask-run'
     ),
     (
         'quart run',
         {'QUART_APP': 'mem_quart.py'},
-        'quart-run-async'
+        'quart-run'
     ),
     (
         'gunicorn --workers 1 --bind :5000 mem_flask:app',
         {},
-        'flask-gunicorn-sync'
+        'flask-gunicorn'
     ),
     (
         'uvicorn --workers 1 --port 5000 mem_quart:app',
         {},
-        'quart-uvicorn-async'
+        'quart-uvicorn'
     ),
     (
         'uvicorn --workers 1 --port 5000 mem_fastapi:app',
         {},
-        'fastapi-uvicorn-async'
+        'fastapi-uvicorn'
     ),
 ]
 
 for app, env, name in apps:
     p = subprocess.Popen(
         app.split() if isinstance(app, str) else app,
-        env={'PATH': os.environ['PATH'], **env},
+        env={'PATH': os.environ['PATH'] + ':../../bin', **env},
         stdout=subprocess.DEVNULL,
         stderr=subprocess.DEVNULL
     )
     time.sleep(1)
+    tm = 0
     if not name.startswith('baseline'):
-        r = requests.get('http://localhost:5000')
-        r.raise_for_status()
+        def req():
+            r = requests.get('http://localhost:5000')
+            r.raise_for_status()
+
+        tm = timeit(req, number=1000)
     proc = psutil.Process(p.pid)
     mem = proc.memory_info().rss
     for child in proc.children(recursive=True):
         mem += child.memory_info().rss
     bar = '*' * (mem // (1024 * 1024))
-    print(f'{name:<28}{humanize.naturalsize(mem):>10} {bar}')
+    print(f'{name:<28}{tm:10.2f}s {humanize.naturalsize(mem):>10} {bar}')
     p.terminate()
     time.sleep(1)

examples/cors/README.md

@@ -0,0 +1 @@
+This directory contains Cross-Origin Resource Sharing (CORS) examples.

examples/cors/app.py

@@ -0,0 +1,14 @@
+from microdot import Microdot
+from microdot.cors import CORS
+
+app = Microdot()
+CORS(app, allowed_origins=['https://example.org'], allow_credentials=True)
+
+
+@app.route('/')
+def index(request):
+    return 'Hello World!'
+
+
+if __name__ == '__main__':
+    app.run()

examples/csrf/README.md

@@ -0,0 +1,41 @@
+# CSRF Example
+
+This is a small example that demonstrates how the CSRF protection in Microdot
+works.
+
+## Running the example
+
+Start by cloning the repostory or copying the two example files *app.py* and
+*evil.py* to your computer. The only dependency these examples need to run is `microdot`, so create a virtual environment and run:
+
+    pip install microdot
+
+You need two terminals. On the first one, run:
+
+    python app.py
+
+To see the application open *http://localhost:5000* on your web browser. The
+application allows you to make payments through a web form. Each payment that
+you make reduces the balance in your account. Type an amount in the form field and press the "Issue Payment" button to see how the balance decreases.
+
+Leave the application running. On the second terminal run:
+
+    python evil.py
+
+Open a second browser tab and navigate to *http://localhost:5001*. This 
+application simulates a malicious web site that tries to steal money from your
+account. It does this by sending a cross-site form submission to the above
+application.
+
+The application presents a form that fools you into thinking you can win some
+money. Clicking the button triggers the cross-site request to the form in the
+first application, with the payment amount set to $100.
+
+Because the application has CSRF protection enabled, the cross-site request
+fails.
+
+If you want to see how the attack can succeed, open *app.py* in your editor and
+comment out the line that creates the ``csrf`` object. Restart *app.py* in your
+first terminal, then go back to the second browser tab and click the
+"Win $100!" button again. You will now see that the form is submitted
+successfully and your balance in the first application is decremented by $100.

examples/csrf/app.py

@@ -0,0 +1,40 @@
+from microdot import Microdot, redirect
+from microdot.cors import CORS
+from microdot.csrf import CSRF
+
+app = Microdot()
+cors = CORS(app, allowed_origins=['http://localhost:5000'])
+csrf = CSRF(app, cors)
+
+balance = 1000
+
+
+@app.route('/', methods=['GET', 'POST'])
+def index(request):
+    global balance
+    if request.method == 'POST':
+        try:
+            balance -= float(request.form['amount'])
+        except ValueError:
+            pass
+        return redirect('/')
+
+    page = f'''<!doctype html>
+<html>
+  <head>
+    <title>CSRF Example</title>
+  </head>
+  <body>
+    <h1>CSRF Example</h1>
+    <p>You have ${balance:.02f}</p>
+    <form method="POST" action="">
+      Pay $<input type="text" name="amount" size="10" />
+      <input type="submit" value="Issue Payment" />
+    </form>
+  </body>
+</html>'''
+    return page, {'Content-Type': 'text/html'}
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

examples/csrf/evil.py

@@ -0,0 +1,25 @@
+from microdot import Microdot
+
+app = Microdot()
+
+
+@app.route('/', methods=['GET', 'POST'])
+def index(request):
+    page = '''<!doctype html>
+<html>
+  <head>
+    <title>CSRF Example</title>
+  </head>
+  <body>
+    <h1>Evil Site</h1>
+    <form method="POST" action="http://localhost:5000">
+      <input type="hidden" name="amount" value="100" />
+      <input type="submit" value="Win $100!" />
+    </form>
+  </body>
+</html>'''
+    return page, {'Content-Type': 'text/html'}
+
+
+if __name__ == '__main__':
+    app.run(port=5001, debug=True)

examples/gpio/gpio.html

@@ -2,6 +2,7 @@
 <html>
     <head>
         <title>Microdot GPIO Example</title>
+        <meta charset="UTF-8">
         <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
         <script>
             function getCookie(name) {

examples/gpio/weather/README.md

@@ -0,0 +1,104 @@
+# Microdot Weather Dashboard
+
+This example reports the temperature and humidity, both as a web application
+and as a JSON API.
+
+![Weather Dashboard Screenshot](screenshot.png)
+
+## Requirements
+
+- A microcontroller that supports MicroPython (e.g. ESP8266, ESP32, Raspberry
+  Pi Pico W, etc.)
+- A DHT22 temperature and humidity sensor
+- A breadboard and some jumper wires to create the circuit
+
+## Circuit
+
+Install the microconller and the DHT22 sensor on different parts of the
+breadboard. Make the following connections with jumper wires:
+
+- from a microcontroller power pin (3.3V or 5V) to the left pin of the DHT22
+  sensor. 
+- from a microcontroller `GND` pin to the right pin of the DHT22 sensor.
+- from any available microcontroller GPIO pin to the middle pin of the DHT22
+  sensor. If the DHT22 sensor has 4 pins instead of 3, use the one on the left,
+  next to the pin receiving power.
+
+The following diagram shows a possible wiring for this circuit using an ESP8266
+microcontroller and the 4-pin variant of the DHT22. In this diagram the data
+pin of the DHT22 sensor is connected to pin `D2` of the ESP8266, which is
+assigned to GPIO #4. Note that the location of the pins in the microcontroller
+board will vary depending on which microcontroller you use.
+
+![Circuit diagram](circuit.png)
+
+## Installation
+
+Edit *config.py* as follows:
+
+- Set the `DHT22_PIN` variable to the GPIO pin number connected to the sensor's
+  data pin. Make sure you consult the documentation for your microcontroller to
+  learn what number you should use for your chosen GPIO pin. In the example
+  diagram above, the value should be 4.
+- Enter your Wi-Fi SSID name and password in this file.
+
+Install MicroPython on your microcontroller board following instructions on the
+MicroPython website. Then use a tool such as
+[rshell](https://github.com/dhylands/rshell) to upload the following files to
+the board:
+
+- *main.py*
+- *config.py*
+- *index.html*
+- *microdot.py*
+
+You can find *microdot.py* in the *src/microdot* directory of this repository.
+
+If you are using a low end microcontroller such as the ESP8266, it is quite
+possible that the *microdot.py* file will fail to compile due to the
+MicroPython compiler needing more RAM than available in the device. In that
+case, you can install the `mpy-cross` Python package in your computer (same
+version as your MicroPython firmware) and precompile this file. The precompiled
+file will have the name *microdot.mpy*. Upload this file and remove
+*microdot.py* from the device.
+
+When the device is restarted after the files were uploaded, it will connect to
+Wi-Fi and then start a web server on port 8000. One way to find out which IP
+address was assigned to your device is to check your Wi-Fi's router
+administration panel. Another option is to connect to the MicroPython REPL with
+`rshell` or any other tool that you like, and then press Ctrl-D at the
+MicroPython prompt to soft boot the device. The IP address is printed to the
+terminal on startup.
+
+You should not upload other *.py* files that exist in this directory to your
+device. These files are used when running with emulated hardware.
+
+## Trying out the application
+
+Once the device is running the server, you can connect to it using a web
+browser. For example, if your device's Wi-Fi connection was assigned the IP
+address 192.168.0.145, type *http://192.168.0.45:8000/* in your browser's
+address bar. Note it is *http://* and not *https://*. This example does not use
+the TLS/SSL protocol.
+
+To test the JSON API, you can use `curl` or your favorite HTTP client. The API
+endpoint uses the */api* path, with the same URL as the main website. Here is
+an example using `curl`:
+
+```bash
+$ curl http://192.168.0.145:8000/api
+{"temperature": 21.6, "humidity": 58.9, "time": 1752444652}
+```
+
+The `temperature` value is given in degrees Celsius. The `humidity` value is
+given as a percentage. The `time` value is a UNIX timestamp.
+
+## Running in Emulation mode
+
+You can run this application on your computer, directly from this directory.
+When used in this way, the DHT22 hardware is emulated, and the temperature and
+humidity values are randomly generated.
+
+The only dependency that is needed for this application to run in emulation
+mode is `microdot`, so make sure that is installed, or else add a copy of the
+*microdot.py* from the *src/microdot* directory in this folder.

examples/gpio/weather/config.py

@@ -0,0 +1,3 @@
+DHT22_PIN = 4  # GPIO pin for DHT22 sensor
+WIFI_ESSID = 'your_wifi_ssid'
+WIFI_PASSWORD = 'your_wifi_password'

examples/gpio/weather/dht.py

@@ -0,0 +1,26 @@
+"""
+DO NOT UPLOAD THIS FILE TO YOUR MICROPYTHON DEVICE
+
+This module emulates MicroPython's DHT22 driver. It can be used when running
+on a system without the DHT22 hardware.
+
+The temperature and humidity values that are returned are random values.
+"""
+
+from random import random
+
+
+class DHT22:
+    def __init__(self, pin):
+        self.pin = pin
+
+    def measure(self):
+        pass
+
+    def temperature(self):
+        """Return a random temperature between 10 and 30 degrees Celsius."""
+        return random() * 20 + 10
+
+    def humidity(self):
+        """Return a random humidity between 30 and 70 percent."""
+        return random() * 40 + 30

examples/gpio/weather/index.html

@@ -0,0 +1,169 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot Weather Dashboard</title>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/gauge.js/1.3.9/gauge.min.js" integrity="sha512-/gkYCBz4KVyJb3Shz6Z1kKu9Za5EdInNezzsm2O/DPvAYhCeIOounTzi7yuIF526z3rNZfIDxcx+rJAD07p8aA==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+    <style>
+      html, body {
+        height: 95%;
+        font-family: Arial, sans-serif;
+      }
+      #container {
+        position: relative;
+        top: 50%;
+        left: 50%;
+        transform: translate(-50%, -50%);
+      }
+      h1 {
+        font-size: 1.5em;
+      }
+      h1, p {
+        text-align: center;
+      }
+      table {
+        margin-left: auto;
+        margin-right: auto;
+      }
+      table h1 {
+        margin-top: 0;
+      }
+      table p {
+        margin: 0;
+      }
+      #temperature, #humidity {
+        width: 100%;
+        max-width: 400px;
+        aspect-ratio: 2;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="container">
+      <h1>Microdot Weather Dashboard</h1>
+      <table cellspacing="0" cellpadding="0">
+        <tr>
+          <td>
+            <canvas id="temperature" width="400" height="200"></canvas>
+          </td>
+          <td>
+            <canvas id="humidity" width="400" height="200"></canvas>
+          </td>
+        </tr>
+        <tr>
+          <td>
+            <p>Temperature</p>
+            <h1><span id="temperature-text">??</span>°C</h1>
+          </td>
+          <td>
+            <p>Humidity</p>
+            <h1><span id="humidity-text">??</span>%</h1>
+          </td>
+        </tr>
+        <tr>
+          <td colspan="2">
+            <p><i>Last updated: <span id="time-text">...</span></i></p>
+          </td>
+        </tr>
+      </table>
+    </div>
+    <script>
+      // create the temperature gauge
+      let temperatureGauge = new Gauge(document.getElementById('temperature')).setOptions({
+        angle: 0,
+        lineWidth: 0.3,
+        radiusScale: 1,
+        pointer: {
+          length: 0.6,
+          strokeWidth: 0.035,
+          color: '#000000',
+        },
+        limitMax: false,
+        limitMin: false,
+        highDpiSupport: true,
+        staticLabels: {
+          font: "14px sans-serif",
+          labels: [-30, -20, -10, 0, 10, 20, 30, 40, 50],
+          color: "#000000",
+          fractionDigits: 0,
+        },
+        staticZones: [
+          {strokeStyle: "#85a6e8", min: -30, max: 0},
+          {strokeStyle: "#a5dde8", min: 0, max: 10},
+          {strokeStyle: "#a5e8a6", min: 10, max: 20},
+          {strokeStyle: "#e8d8a5", min: 20, max: 30},
+          {strokeStyle: "#e8a8a5", min: 30, max: 50},
+        ],  
+        renderTicks: {
+          divisions: 8,
+          divWidth: 1.1,
+          divLength: 0.7,
+          divColor: '#333333',
+          subDivisions: 4,
+          subLength: 0.3,
+          subWidth: 0.6,
+          subColor: '#666666'
+        }
+      });
+      temperatureGauge.maxValue = 50;
+      temperatureGauge.setMinValue(-30);
+      temperatureGauge.animationSpeed = 36;
+      temperatureGauge.set(0);
+
+      let humidityGauge = new Gauge(document.getElementById('humidity')).setOptions({
+        angle: 0,
+        lineWidth: 0.3,
+        radiusScale: 1,
+        pointer: {
+          length: 0.6,
+          strokeWidth: 0.035,
+          color: '#000000',
+        },
+        limitMax: false,
+        limitMin: false,
+        highDpiSupport: true,
+        staticLabels: {
+          font: "14px sans-serif",
+          labels: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
+          color: "#000000",
+          fractionDigits: 0,
+        },
+        staticZones: [
+          {strokeStyle: "#85a6e8", min: 0, max: 40},
+          {strokeStyle: "#a5e8a6", min: 40, max: 70},
+          {strokeStyle: "#e8a8a5", min: 70, max: 100},
+        ],  
+        renderTicks: {
+          divisions: 10,
+          divWidth: 1.1,
+          divLength: 0.7,
+          divColor: '#333333',
+          subDivisions: 4,
+          subLength: 0.3,
+          subWidth: 0.6,
+          subColor: '#666666'
+        }
+      });
+      humidityGauge.maxValue = 100;
+      humidityGauge.setMinValue(0);
+      humidityGauge.animationSpeed = 36;
+      humidityGauge.set(0);
+
+      async function update() {
+        const response = await fetch('/api');
+        if (response.ok) {
+          const data = await response.json();
+          temperatureGauge.set(data.temperature);
+          humidityGauge.set(data.humidity);
+          document.getElementById('temperature-text').textContent = data.temperature;
+          document.getElementById('humidity-text').textContent = data.humidity;
+          document.getElementById('time-text').textContent = new Date(data.time * 1000).toLocaleString();
+        }
+        setTimeout(update, 60000); // refresh every minute
+      }
+      update();
+    </script>
+
+  </body>
+</html>

examples/gpio/weather/machine.py

@@ -0,0 +1,12 @@
+"""
+DO NOT UPLOAD THIS FILE TO YOUR MICROPYTHON DEVICE
+
+This module emulates parts of MicroPython's `machine` module, to enable to run
+MicroPython applications on UNIX, Mac or Windows systems without dedicated
+hardware.
+"""
+
+
+class Pin:
+    def __init__(self, pin):
+        self.pin = pin

examples/gpio/weather/main.py

@@ -0,0 +1,112 @@
+import asyncio
+import dht
+import gc
+import machine
+import network
+import socket
+import time
+
+import config
+from microdot import Microdot, send_file
+
+app = Microdot()
+current_temperature = None
+current_humidity = None
+current_time = None
+
+
+def wifi_connect():
+    """Connect to the configured Wi-Fi network.
+    Returns the IP address of the connected interface.
+    """
+    ap_if = network.WLAN(network.AP_IF)
+    ap_if.active(False)
+
+    sta_if = network.WLAN(network.STA_IF)
+    if not sta_if.isconnected():
+        print('connecting to network...')
+        sta_if.active(True)
+        sta_if.connect(config.WIFI_ESSID, config.WIFI_PASSWORD)
+        for i in range(20):
+            if sta_if.isconnected():
+                break
+            time.sleep(1)
+        if not sta_if.isconnected():
+            raise RuntimeError('Could not connect to network')
+    return sta_if.ifconfig()[0]
+
+
+def get_current_time():
+    """Return the current Unix time.
+    Note that because many microcontrollers do not have a clock, this function
+    makes a call to an NTP server to obtain the current time. A Wi-Fi
+    connection needs to be in place before calling this function.
+    """
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    s.settimeout(5)
+    s.sendto(b'\x1b' + 47 * b'\0',
+             socket.getaddrinfo('pool.ntp.org', 123)[0][4])
+    msg, _ = s.recvfrom(1024)
+    return ((msg[40] << 24) | (msg[41] << 16) | (msg[42] << 8) | msg[43]) - \
+        2208988800
+
+
+def get_current_weather():
+    """Read the temperature and humidity from the DHT22 sensor.
+    Returns them as a tuple. The returned temperature is in degrees Celcius.
+    The humidity is a 0-100 percentage.
+    """
+    d = dht.DHT22(machine.Pin(config.DHT22_PIN))
+    d.measure()
+    return d.temperature(), d.humidity()
+
+
+async def refresh_weather():
+    """Background task that updates the temperature and humidity.
+    This task is designed to run in the background. It connects to the DHT22
+    temperature and humidity sensor once per minute and stores the updated
+    readings in global variables.
+    """
+    global current_temperature
+    global current_humidity
+    global current_time
+
+    while True:
+        try:
+            t = get_current_time()
+            temp, hum = get_current_weather()
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:
+            print(f'Could not obtain weather, error: {error}')
+        else:
+            current_time = t
+            current_temperature = int(temp * 10) / 10
+            current_humidity = int(hum * 10) / 10
+        gc.collect()
+        await asyncio.sleep(60)
+
+
+@app.route('/')
+async def index(request):
+    return send_file('index.html')
+
+
+@app.route('/api')
+async def api(request):
+    return {
+        'temperature': current_temperature,
+        'humidity': current_humidity,
+        'time': current_time,
+    }
+
+
+async def start():
+    ip = wifi_connect()
+    print(f'Starting server at http://{ip}:8000...')
+    bgtask = asyncio.create_task(refresh_weather())
+    server = asyncio.create_task(app.start_server(port=8000))
+    await asyncio.gather(server, bgtask)
+
+
+asyncio.run(start())

examples/gpio/weather/network.py

@@ -0,0 +1,31 @@
+"""
+DO NOT UPLOAD THIS FILE TO YOUR MICROPYTHON DEVICE
+
+This module emulates parts of MicroPython's `network` module, in particular
+those related to establishing a Wi-Fi connection. This enables to run
+MicroPython applications on UNIX, Mac or Windows systems without dedicated
+hardware.
+
+Note that no connections are attempted. The assumption is that the system is
+already connected. The "127.0.0.1" address is always returned.
+"""
+
+AP_IF = 1
+STA_IF = 2
+
+
+class WLAN:
+    def __init__(self, network):
+        self.network = network
+
+    def isconnected(self):
+        return True
+
+    def ifconfig(self):
+        return ('127.0.0.1', 'n/a', 'n/a', 'n/a')
+
+    def connect(self):
+        pass
+
+    def active(self, active=None):
+        pass

examples/hello/hello.py

@@ -2,10 +2,11 @@ from microdot import Microdot
 
 app = Microdot()
 
-htmldoc = '''<!DOCTYPE html>
+html = '''<!DOCTYPE html>
 <html>
     <head>
         <title>Microdot Example Page</title>
+        <meta charset="UTF-8">
     </head>
     <body>
         <div>
@@ -19,12 +20,12 @@ htmldoc = '''<!DOCTYPE html>
 
 
 @app.route('/')
-def hello(request):
-    return htmldoc, 200, {'Content-Type': 'text/html'}
+async def hello(request):
+    return html, 200, {'Content-Type': 'text/html'}
 
 
 @app.route('/shutdown')
-def shutdown(request):
+async def shutdown(request):
     request.app.shutdown()
     return 'The server is shutting down...'
 

examples/hello/hello_asgi.py

@@ -1,11 +1,12 @@
-from microdot_asgi import Microdot
+from microdot.asgi import Microdot
 
 app = Microdot()
 
-htmldoc = '''<!DOCTYPE html>
+html = '''<!DOCTYPE html>
 <html>
     <head>
         <title>Microdot Example Page</title>
+        <meta charset="UTF-8">
     </head>
     <body>
         <div>
@@ -20,7 +21,7 @@ htmldoc = '''<!DOCTYPE html>
 
 @app.route('/')
 async def hello(request):
-    return htmldoc, 200, {'Content-Type': 'text/html'}
+    return html, 200, {'Content-Type': 'text/html'}
 
 
 @app.route('/shutdown')

examples/hello/hello_async.py

@@ -1,32 +0,0 @@
-from microdot_asyncio import Microdot
-
-app = Microdot()
-
-htmldoc = '''<!DOCTYPE html>
-<html>
-    <head>
-        <title>Microdot Example Page</title>
-    </head>
-    <body>
-        <div>
-            <h1>Microdot Example Page</h1>
-            <p>Hello from Microdot!</p>
-            <p><a href="/shutdown">Click to shutdown the server</a></p>
-        </div>
-    </body>
-</html>
-'''
-
-
-@app.route('/')
-async def hello(request):
-    return htmldoc, 200, {'Content-Type': 'text/html'}
-
-
-@app.route('/shutdown')
-async def shutdown(request):
-    request.app.shutdown()
-    return 'The server is shutting down...'
-
-
-app.run(debug=True)

examples/hello/hello_wsgi.py

@@ -1,11 +1,12 @@
-from microdot_wsgi import Microdot
+from microdot.wsgi import Microdot
 
 app = Microdot()
 
-htmldoc = '''<!DOCTYPE html>
+html = '''<!DOCTYPE html>
 <html>
     <head>
         <title>Microdot Example Page</title>
+        <meta charset="UTF-8">
     </head>
     <body>
         <div>
@@ -20,7 +21,7 @@ htmldoc = '''<!DOCTYPE html>
 
 @app.route('/')
 def hello(request):
-    return htmldoc, 200, {'Content-Type': 'text/html'}
+    return html, 200, {'Content-Type': 'text/html'}
 
 
 @app.route('/shutdown')

examples/login/README.md

@@ -0,0 +1 @@
+This directory contains examples that demonstrate user logins.

examples/login/login.py

@@ -0,0 +1,123 @@
+from microdot import Microdot, redirect
+from microdot.session import Session
+from microdot.login import Login
+from pbkdf2 import generate_password_hash, check_password_hash
+
+# this example provides an implementation of the generate_password_hash and
+# check_password_hash functions that can be used in MicroPython. On CPython
+# there are many other options for password hashisng so there is no need to use
+# this custom solution.
+
+
+class User:
+    def __init__(self, id, username, password):
+        self.id = id
+        self.username = username
+        self.password_hash = self.create_hash(password)
+
+    def create_hash(self, password):
+        return generate_password_hash(password)
+
+    def check_password(self, password):
+        return check_password_hash(self.password_hash, password)
+
+
+USERS = {
+    'user001': User('user001', 'susan', 'hello'),
+    'user002': User('user002', 'david', 'bye'),
+}
+
+app = Microdot()
+Session(app, secret_key='top-secret!')
+login = Login()
+
+
+@login.user_loader
+async def get_user(user_id):
+    return USERS.get(user_id)
+
+
+@app.route('/login', methods=['GET', 'POST'])
+async def login_page(request):
+    if request.method == 'GET':
+        return '''
+            <!doctype html>
+            <html>
+              <body>
+                <h1>Please Login</h1>
+                <form method="POST">
+                  <p>
+                    Username<br>
+                    <input name="username" autofocus>
+                  </p>
+                  <p>
+                    Password:<br>
+                    <input name="password" type="password">
+                    <br>
+                  </p>
+                  <p>
+                    <input name="remember_me" type="checkbox"> Remember me
+                    <br>
+                  </p>
+                  <p>
+                    <button type="submit">Login</button>
+                  </p>
+                </form>
+              </body>
+            </html>
+        ''', {'Content-Type': 'text/html'}
+    username = request.form['username']
+    password = request.form['password']
+    remember_me = bool(request.form.get('remember_me'))
+
+    for user in USERS.values():
+        if user.username == username:
+            if user.check_password(password):
+                return await login.login_user(request, user,
+                                              remember=remember_me)
+    return redirect('/login')
+
+
+@app.route('/')
+@login
+async def index(request):
+    return f'''
+        <!doctype html>
+        <html>
+          <body>
+            <h1>Hello, {request.g.current_user.username}!</h1>
+            <p>
+              <a href="/fresh">Click here</a> to access the fresh login page.
+            </p>
+            <form method="POST" action="/logout">
+              <button type="submit">Logout</button>
+            </form>
+          </body>
+        </html>
+    ''', {'Content-Type': 'text/html'}
+
+
+@app.get('/fresh')
+@login.fresh
+async def fresh(request):
+    return f'''
+        <!doctype html>
+        <html>
+          <body>
+            <h1>Hello, {request.g.current_user.username}!</h1>
+            <p>This page requires a fresh login session.</p>
+            <p><a href="/">Go back</a> to the main page.</p>
+          </body>
+        </html>
+    ''', {'Content-Type': 'text/html'}
+
+
+@app.post('/logout')
+@login
+async def logout(request):
+    await login.logout_user(request)
+    return redirect('/')
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

examples/login/pbkdf2.py

@@ -0,0 +1,47 @@
+import os
+import hashlib
+
+# PBKDF2 secure password hashing algorithm obtained from:
+# https://codeandlife.com/2023/01/06/how-to-calculate-pbkdf2-hmac-sha256-with-
+# python,-example-code/
+
+
+def sha256(b):
+    return hashlib.sha256(b).digest()
+
+
+def ljust(b, n, f):
+    return b + f * (n - len(b))
+
+
+def gethmac(key, content):
+    okeypad = bytes(v ^ 0x5c for v in ljust(key, 64, b'\0'))
+    ikeypad = bytes(v ^ 0x36 for v in ljust(key, 64, b'\0'))
+    return sha256(okeypad + sha256(ikeypad + content))
+
+
+def pbkdf2(pwd, salt, iterations=1000):
+    U = salt + b'\x00\x00\x00\x01'
+    T = bytes(64)
+    for _ in range(iterations):
+        U = gethmac(pwd, U)
+        T = bytes(a ^ b for a, b in zip(U, T))
+    return T
+
+
+# The number of iterations may need to be adjusted depending on the hardware.
+# Lower numbers make the password hashing algorithm faster but less secure, so
+# the largest number that can be tolerated should be used.
+def generate_password_hash(password, salt=None, iterations=100000):
+    salt = salt or os.urandom(16)
+    dk = pbkdf2(password.encode(), salt, iterations)
+    return f'pbkdf2-hmac-sha256:{salt.hex()}:{iterations}:{dk.hex()}'
+
+
+def check_password_hash(password_hash, password):
+    algorithm, salt, iterations, dk = password_hash.split(':')
+    iterations = int(iterations)
+    if algorithm != 'pbkdf2-hmac-sha256':
+        return False
+    return pbkdf2(password.encode(), salt=bytes.fromhex(salt),
+                  iterations=iterations) == bytes.fromhex(dk)

examples/sessions/login.py

@@ -1,11 +1,14 @@
+# This is a simple example that demonstrates how to use the user session, but
+# is not intended as a complete login solution. See the login subdirectory for
+# a more complete example.
 from microdot import Microdot, Response, redirect
-from microdot_session import set_session_secret_key, with_session, \
-    update_session, delete_session
+from microdot.session import Session, with_session
 
 BASE_TEMPLATE = '''<!doctype html>
 <html>
   <head>
     <title>Microdot login example</title>
+    <meta charset="UTF-8">
   </head>
   <body>
     <h1>Microdot login example</h1>
@@ -17,7 +20,7 @@ LOGGED_OUT = '''<p>You are not logged in.</p>
 <form method="POST">
   <p>
     Username:
-    <input type="text" name="username" autofocus />
+    <input name="username" autofocus />
   </p>
   <input type="submit" value="Submit" />
 </form>'''
@@ -28,18 +31,19 @@ LOGGED_IN = '''<p>Hello <b>{username}</b>!</p>
 </form>'''
 
 app = Microdot()
-set_session_secret_key('top-secret')
+Session(app, secret_key='top-secret')
 Response.default_content_type = 'text/html'
 
 
 @app.get('/')
 @app.post('/')
 @with_session
-def index(req, session):
+async def index(req, session):
     username = session.get('username')
     if req.method == 'POST':
         username = req.form.get('username')
-        update_session(req, {'username': username})
+        session['username'] = username
+        session.save()
         return redirect('/')
     if username is None:
         return BASE_TEMPLATE.format(content=LOGGED_OUT)
@@ -49,8 +53,9 @@ def index(req, session):
 
 
 @app.post('/logout')
-def logout(req):
-    delete_session(req)
+@with_session
+async def logout(req, session):
+    session.delete()
     return redirect('/')
 
 

examples/sse/counter.py

@@ -0,0 +1,28 @@
+import asyncio
+from microdot import Microdot, send_file
+from microdot.sse import with_sse
+
+app = Microdot()
+
+
+@app.route("/")
+async def main(request):
+    return send_file('index.html')
+
+
+@app.route('/events')
+@with_sse
+async def events(request, sse):
+    print('Client connected')
+    try:
+        i = 0
+        while True:
+            await asyncio.sleep(1)
+            i += 1
+            await sse.send({'counter': i})
+    except asyncio.CancelledError:
+        pass
+    print('Client disconnected')
+
+
+app.run()

examples/sse/index.html

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Microdot SSE Example</title>
+    <meta charset="UTF-8">
+  </head>
+  <body>
+    <h1>Microdot SSE Example</h1>
+    <div id="log"></div>
+    <script>
+      const log = (text, color) => {
+        document.getElementById('log').innerHTML += `<span style="color: ${color}">${text}</span><br>`;
+      };
+
+      const eventSource = new EventSource('/events');
+
+      eventSource.onopen = () => {
+        log('Connection to server opened.', 'black');
+      };
+
+      eventSource.onmessage = (event) => {
+        log(`Received message: ${event.data}`, 'blue');
+      };
+
+      eventSource.onerror = (event) => {
+        log(`EventSource failed: ${event.type}`, 'red');
+      };
+    </script>
+  </body>
+</html>

examples/static/gzstatic.py

@@ -0,0 +1,20 @@
+from microdot import Microdot, send_file
+
+app = Microdot()
+
+
+@app.route('/')
+def index(request):
+    return send_file('gzstatic/index.html', compressed=True,
+                     file_extension='.gz')
+
+
+@app.route('/static/<path:path>')
+def static(request, path):
+    if '..' in path:
+        # directory traversal is not allowed
+        return 'Not found', 404
+    return send_file('gzstatic/' + path, compressed=True, file_extension='.gz')
+
+
+app.run(debug=True)

examples/static/static.py

@@ -1,15 +1,14 @@
 from microdot import Microdot, send_file
-
 app = Microdot()
 
 
 @app.route('/')
-def index(request):
+async def index(request):
     return send_file('static/index.html')
 
 
 @app.route('/static/<path:path>')
-def static(request, path):
+async def static(request, path):
     if '..' in path:
         # directory traversal is not allowed
         return 'Not found', 404

examples/static/static/index.css

@@ -0,0 +1,10 @@
+p {
+  font-family: Arial, Helvetica, sans-serif;
+  color: #333333;
+}
+
+h1 {
+  font-family: Arial, Helvetica, sans-serif;
+  color: #3070b3;
+  text-align: center;
+}