Release 2.0.0

Bumps [urllib3](https://github.com/urllib3/urllib3) from 1.26.17 to 1.26.18.
- [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/1.26.17...1.26.18)

---
updated-dependencies:
- dependency-name: urllib3
  dependency-type: direct:production
...

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

.flake8

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

.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

@@ -2,17 +2,17 @@ name: build
 on:
   push:
     branches:
-      - master
+      - main
   pull_request:
     branches:
-      - master
+      - main
 jobs:
   lint:
     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
@@ -21,12 +21,12 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python: ['3.6', '3.7', '3.8', '3.9']
+        python: ['3.8', '3.9', '3.10', '3.11', '3.12']
       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,8 +36,8 @@ 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
@@ -45,9 +45,21 @@ jobs:
     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
+  benchmark:
+    name: benchmark
+    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 -ebenchmark

.gitignore

@@ -2,6 +2,7 @@
 __pycache__/
 *.py[cod]
 *$py.class
+*_html.py
 
 # C extensions
 *.so
@@ -102,3 +103,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,183 @@
 # Microdot change log
 
+**Release 2.0.0** - 2023-12-22
+
+- Major redesign switching to asyncio as the base implementation (See the [Migration Guide](https://microdot.readthedocs.io/en/stable/migrating.html) in the docs for details) [#186](https://github.com/miguelgrinberg/microdot/issues/186) ([commit](https://github.com/miguelgrinberg/microdot/commit/20ea305fe793eb206b52af9eb5c5f3c1e9f57dbb))
+
+**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**!)
+- Addressed error when deleting a user session in async app [#86](https://github.com/miguelgrinberg/microdot/issues/86) ([commit](https://github.com/miguelgrinberg/microdot/commit/5a589afd5e519e94e84fc1ee69033f2dad51c3ea))
+- Add asyncio file upload example ([commit](https://github.com/miguelgrinberg/microdot/commit/c841cbedda40f59a9d87f6895fdf9fd954f854a2))
+- New Jinja and uTemplate examples with Bootstrap ([commit](https://github.com/miguelgrinberg/microdot/commit/211ad953aeedb4c7f73fe210424aa173b4dc7fee))
+- Fix typos in documentation [#77](https://github.com/miguelgrinberg/microdot/issues/77) ([commit](https://github.com/miguelgrinberg/microdot/commit/4a9b92b800d3fd87110f7bc9f546c10185ee13bc)) (thanks **Diego Pomares**!)
+- Add missing exception argument to error handler example in documentation [#73](https://github.com/miguelgrinberg/microdot/issues/73) ([commit](https://github.com/miguelgrinberg/microdot/commit/c443599089f2127d1cb052dfba8a05c1969d65e3)) (thanks **Diego Pomares**!)
+
+**Release 1.2.0** - 2022-09-25
+
+- Use a case insensitive dict for headers ([commit #1](https://github.com/miguelgrinberg/microdot/commit/b0fd6c432371ca5cb10d07ff84c4deed7aa0ce2e) [commit #2](https://github.com/miguelgrinberg/microdot/commit/a8515c97b030f942fa6ca85cbe1772291468fb0d))
+- urlencode() helper function ([commit #1](https://github.com/miguelgrinberg/microdot/commit/672512e086384e808489305502e6ebebcc5a888f) [commit #2](https://github.com/miguelgrinberg/microdot/commit/b133dcc34368853ee685396a1bcb50360e807813))
+- Added `request.url` attribute with the complete URL of the request ([commit](https://github.com/miguelgrinberg/microdot/commit/1547e861ee28d43d10fe4c4ed1871345d4b81086))
+- Do not log HTTPException occurrences ([commit](https://github.com/miguelgrinberg/microdot/commit/cbefb6bf3a3fdcff8b7a8bacad3449be18e46e3b))
+- Cache user session for performance ([commit](https://github.com/miguelgrinberg/microdot/commit/01947b101ebe198312c88d73872e3248024918f0))
+- File upload example ([commit](https://github.com/miguelgrinberg/microdot/commit/8ebe81c09b604ddc1123e78ad6bc87ceda5f8597))
+- Minor documentation styling fixes ([commit](https://github.com/miguelgrinberg/microdot/commit/4f263c63ab7bb1ce0dd48d8e00f3c6891e1bf07e))
+
+**Release 1.1.1** - 2022-09-18
+
+- Make WebSocket internals consistent between TLS and non-TLS [#61](https://github.com/miguelgrinberg/microdot/issues/61) ([commit](https://github.com/miguelgrinberg/microdot/commit/5693b812ceb2c0d51ec3c991adf6894a87e6fcc7))
+
+**Release 1.1.0** - 2022-09-17
+
+- Websocket support [#55](https://github.com/miguelgrinberg/microdot/issues/55) ([commit](https://github.com/miguelgrinberg/microdot/commit/2399c29c8a45289f009f47fd66438452da93cdab))
+- SSL/TLS support ([commit #1](https://github.com/miguelgrinberg/microdot/commit/b61f51f2434465b7a0ee197aabf46e8f99f6e8ad) [commit #2](https://github.com/miguelgrinberg/microdot/commit/fe750feb0373b41cb022521a6a3edf1973847a74))
+- Add `abort()` function ([commit](https://github.com/miguelgrinberg/microdot/commit/3c125c43d2e037ce64138e22c1ff4186ea107471))
+- Charset handling in Content-Type headers [#60](https://github.com/miguelgrinberg/microdot/issues/60) ([commit](https://github.com/miguelgrinberg/microdot/commit/75725795b45d275deaee133204e400e8fbb3de70))
+- Recover from errors writing the response ([commit](https://github.com/miguelgrinberg/microdot/commit/dc7a041ebd30f38b9f6b22c4bbcd61993c43944e))
+- Reorganized examples into subdirectories ([commit](https://github.com/miguelgrinberg/microdot/commit/a01fc9c3f070e21e705b8f12ceb8288b0f304569))
+- Update tests to use MicroPython 1.19 ([commit](https://github.com/miguelgrinberg/microdot/commit/42b6d6979381d9cd8ccc6ab6e079f12ec5987b80))
+- Update MicroPython libraries used by tests ([commit](https://github.com/miguelgrinberg/microdot/commit/e767426228eeacd58886bccb5046049e994c0479))
+- Fix links to hello and gpio examples in documentation [#53](https://github.com/miguelgrinberg/microdot/issues/53) ([commit](https://github.com/miguelgrinberg/microdot/commit/ec0f9ba855cca7dd35cddad40c4cb7eb17d8842a)) (thanks **Sterling G. Baird**!)
+
+**Release 1.0.0** - 2022-08-07
+
+- User sessions with signed JWTs ([commit](https://github.com/miguelgrinberg/microdot/commit/355ffefcb2697b30d03359d35283835901f375d6))
+- Mount sub-applications ([commit](https://github.com/miguelgrinberg/microdot/commit/cd5b35d86f2bdd2924234d19943b06dbad6db7c0))
+- Request-specific `after_request` handlers ([commit](https://github.com/miguelgrinberg/microdot/commit/120abe45ecee3ef215c2201337fcb399d5602d59))
+- Render templates with uTemplate ([commit](https://github.com/miguelgrinberg/microdot/commit/54c13295827548a9258a9af914d199f06d8ae5cd))
+- Render templates with Jinja ([commit](https://github.com/miguelgrinberg/microdot/commit/7686b2ae38fb980de0de33c1585f430af11e1cdf))
+- Test client ([commit](https://github.com/miguelgrinberg/microdot/commit/199d23f2c72356072a32fa7bdc85b094c8a63766))
+- Async test client ([commit](https://github.com/miguelgrinberg/microdot/commit/3bcdf4d496630672ed702677b1e22e5364b2b95a))
+- Example that serves static files from a directory ([commit](https://github.com/miguelgrinberg/microdot/commit/a3d7772b8a8e49526f895d10af52a4c0568922b2))
+- Allow routes to only return a body and headers ([commit](https://github.com/miguelgrinberg/microdot/commit/16f3775fa26ea08600898f6a244d5baabea32813))
+- Improved handling of 400 and 405 errors ([commit](https://github.com/miguelgrinberg/microdot/commit/8177b9c7f1c1dfedcd10dcd1562caf6e442d941f))
+- Support responses with more than one cookie in WSGI and ASGI extensions ([commit](https://github.com/miguelgrinberg/microdot/commit/e8d16cf3f90270c5cd3fb13168c5cc983708989c))
+- Cookie expiration can also be given as a string ([commit](https://github.com/miguelgrinberg/microdot/commit/3a54984b674148b6e590eb989de18c1ff0aa9217))
+- Accept POST request with empty body ([commit](https://github.com/miguelgrinberg/microdot/commit/bf3aff6c35982c7dc4a42ae5415933b252cebc0d))
+- Add missing asgi module to package ([commit](https://github.com/miguelgrinberg/microdot/commit/7f1e546067d2222fa1499af69a6a697e5b7188be))
+- Memory usage comparison and benchmark ([commit](https://github.com/miguelgrinberg/microdot/commit/d090bbf8e2b7ce07c802b06de7ebb29de68d788d))
+- Do not use `_thread` for multithreading ([commit](https://github.com/miguelgrinberg/microdot/commit/998c1970586bf5298b6f749460ab88496e429612))
+- Getting Started documentation chapter ([commit](https://github.com/miguelgrinberg/microdot/commit/037024320f08e294601d7b4e206b309dc77b1d90))
+- Concurrency section added to the documentation ([commit](https://github.com/miguelgrinberg/microdot/commit/2f496db50b3d3629c68178b5915454cf1d87bc89))
+- Documentation for all official extensions ([commit](https://github.com/miguelgrinberg/microdot/commit/09dc3ef7aa8e37c64f6ee919e4603c53b05bc156))
+- Remove legacy `microdot-asyncio` package files ([commit](https://github.com/miguelgrinberg/microdot/commit/f1a93ec35e2e758015360b753cb9b07dbf4e96d1))
+- Added MicroPython libraries required by user sessions ([commit](https://github.com/miguelgrinberg/microdot/commit/c9e148bd04aa70df2d8cc8db766eb52fa87cda31))
+- Reorganized vendored MicroPython libraries ([commit](https://github.com/miguelgrinberg/microdot/commit/7df74b05374cfc398fcdeb280e93ec3f46047c2a))
+
+**Release 0.9.0** - 2022-06-04
+
+- Streaming responses [#44](https://github.com/miguelgrinberg/microdot/issues/44) ([commit](https://github.com/miguelgrinberg/microdot/commit/d71665fd388c92a50198faf0d761235f0138797a))
+- Return 204 when view function returns None ([commit](https://github.com/miguelgrinberg/microdot/commit/71009b49781ce356155df661a66dc98170f35d63))
+- ASGI support (CPython only) ([commit](https://github.com/miguelgrinberg/microdot/commit/7e8ecb199717dd90c6cb374cb0d24b54dd6ea33e))
+- WSGI support (CPython only) ([commit](https://github.com/miguelgrinberg/microdot/commit/1ae51ccdf75991a2958b06f7a3439d64f92f1b69))
+- Documentation updates ([commit](https://github.com/miguelgrinberg/microdot/commit/bcbad516751f1ea9928f4a6d0e8843a4334b885a))
+- Add Python 3.10 to build ([commit](https://github.com/miguelgrinberg/microdot/commit/5b5eb907d83d94dde544b266e6659071e4d47ee1))
+- Run linter on examples ([commit](https://github.com/miguelgrinberg/microdot/commit/c18ccccb8e0744d8670433aeeba068c5654f32df))
+
+**Release 0.8.2** - 2022-04-20
+
+- Remove debugging print statement [#38](https://github.com/miguelgrinberg/microdot/issues/38) ([commit](https://github.com/miguelgrinberg/microdot/commit/0f278321c8bd65c5cb67425eb837e6581cbb0054)) (thanks **Mark Blakeney**!)
+
+**Release 0.8.1** - 2022-03-18
+
+- Optimizations for request streams and bodies ([commit](https://github.com/miguelgrinberg/microdot/commit/29a9f6f46c737aa0fd452766c23bd83008594ac4))
+
+**Release 0.8.0** - 2022-02-18
+
+- Support streamed request payloads [#26](https://github.com/miguelgrinberg/microdot/issues/26) ([commit](https://github.com/miguelgrinberg/microdot/commit/992fa722c1312c0ac0ee9fbd5e23ad7b52d3caca))
+- Use case insensitive comparisons for HTTP headers [#33](https://github.com/miguelgrinberg/microdot/issues/33) ([commit](https://github.com/miguelgrinberg/microdot/commit/e16fb94b2d1e88ef681d70f7f456c37ee9859df6)) (thanks **Steve Li**!)
+- More robust logic to read request body [#31](https://github.com/miguelgrinberg/microdot/issues/31) ([commit](https://github.com/miguelgrinberg/microdot/commit/bd82c4deabf40d37e6b7397b08e8eb40ba2b6a42))
+- Simplified `hello_async.py` example ([commit](https://github.com/miguelgrinberg/microdot/commit/c130d8f2d45dcce9606dda25d31d653ce91faf92))
+
+**Release 0.7.2** - 2021-09-28
+
+- Document a security risk in the send_file function ([commit](https://github.com/miguelgrinberg/microdot/commit/d29ed6aaa1f2080fcf471bf6ae0f480f95ff1716)) (thanks **Ky Tran**!)
+- Validate redirect URLs ([commit](https://github.com/miguelgrinberg/microdot/commit/8e5fb92ff1ccd50972b0c1cb5a6c3bd5eb54d86b)) (thanks **Ky Tran**!)
+- Return a 400 error when request object could not be created ([commit](https://github.com/miguelgrinberg/microdot/commit/06015934b834622d39f52b3e13d16bfee9dc8e5a))
+
+**Release 0.7.1** - 2021-09-27
+
+- Breaking change: Limit the size of each request line to 2KB. A different maximum can be set in `Request.max_readline`. ([commit](https://github.com/miguelgrinberg/microdot/commit/de9c991a9ab836d57d5c08bf4282f99f073b502a)) (thanks **Ky Tran**!)
+
+**Release 0.7.0** - 2021-09-27
+
+- Breaking change: Limit the size of the request body to 16KB. A different maximum can be set in `Request.max_content_length`. ([commit](https://github.com/miguelgrinberg/microdot/commit/5003a5b3d948a7cf365857b419bebf6e388593a1))
+- Add documentation for `request.client_addr` [#27](https://github.com/miguelgrinberg/microdot/issues/27) ([commit](https://github.com/miguelgrinberg/microdot/commit/833fecb105ce456b95f1d2a6ea96dceca1075814)) (thanks **Mark Blakeney**!)
+- Added documentation for reason argument in the Response object ([commit](https://github.com/miguelgrinberg/microdot/commit/d527bdb7c32ab918a1ecf6956cf3a9f544504354))
+
+**Release 0.6.0** - 2021-08-11
+
+- Better handling of content types in form and json methods [#24](https://github.com/miguelgrinberg/microdot/issues/24) ([commit](https://github.com/miguelgrinberg/microdot/commit/da32f23e35f871470a40638e7000e84b0ff6d17f))
+- Accept a custom reason phrase for the HTTP response [#25](https://github.com/miguelgrinberg/microdot/issues/25) ([commit](https://github.com/miguelgrinberg/microdot/commit/bd74bcab74f283c89aadffc8f9c20d6ff0f771ce))
+- Make mime type check for form submissions more robust ([commit](https://github.com/miguelgrinberg/microdot/commit/dd3fc20507715a23d0fa6fa3aae3715c8fbc0351))
+- Copy client headers to avoid write back [#23](https://github.com/miguelgrinberg/microdot/issues/23) ([commit](https://github.com/miguelgrinberg/microdot/commit/0641466faa9dda0c54f78939ac05993c0812e84a)) (thanks **Mark Blakeney**!)
+- Work around a bug in uasyncio's create_server() function ([commit](https://github.com/miguelgrinberg/microdot/commit/46963ba4644d7abc8dc653c99bc76222af526964))
+- More unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/5cd3ace5166ec549579b0b1149ae3d7be195974a))
+- Installation instructions ([commit](https://github.com/miguelgrinberg/microdot/commit/1a8db51cb3754308da6dcc227512dcdeb4ce4557))
+- Run tests with pytest ([commit](https://github.com/miguelgrinberg/microdot/commit/8b4ebbd9535b3c083fb2a955284609acba07f05e))
+- Deprecated the microdot-asyncio package ([commit](https://github.com/miguelgrinberg/microdot/commit/a82ed55f56e14fbcea93e8171af86ab42657fa96))
+
 **Release 0.5.0** - 2021-06-06
 
 - [Documentation](https://microdot.readthedocs.io/en/latest/) site ([commit](https://github.com/miguelgrinberg/microdot/commit/12cd60305b7b48ab151da52661fc5988684dbcd8))

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

@@ -1,9 +1,36 @@
 # microdot
-[![Build status](https://github.com/miguelgrinberg/microdot/workflows/build/badge.svg)](https://github.com/miguelgrinberg/microdot/actions) [![codecov](https://codecov.io/gh/miguelgrinberg/microdot/branch/master/graph/badge.svg)](https://codecov.io/gh/miguelgrinberg/microdot)
+[![Build status](https://github.com/miguelgrinberg/microdot/workflows/build/badge.svg)](https://github.com/miguelgrinberg/microdot/actions) [![codecov](https://codecov.io/gh/miguelgrinberg/microdot/branch/main/graph/badge.svg)](https://codecov.io/gh/miguelgrinberg/microdot)
 
-A minimalistic Python web framework for microcontrollers inspired by Flask
+*“The impossibly small web framework for Python and 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
+
+app = Microdot()
+
+@app.route('/')
+async def index(request):
+    return 'Hello, world!'
+
+app.run()
+```
+
+## Migrating to Microdot 2
+
+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. The
+[Migration Guide](https://microdot.readthedocs.io/en/stable/migrating.html)
+describes the backwards incompatible changes that were made.
 
 ## Resources
 
-- [Documentation](https://microdot.readthedocs.io/en/latest/)
+- Documentation: [Latest](https://microdot.readthedocs.io/en/latest/) [Stable](https://microdot.readthedocs.io/en/stable/) [Legacy v1.x](https://microdot.readthedocs.io/en/v1/)
 - [Change Log](https://github.com/miguelgrinberg/microdot/blob/main/CHANGES.md)

SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you think you've found a vulnerability on this project, please send me (Miguel Grinberg) an email at miguel.grinberg@gmail.com with a description of the problem. I will personally review the issue and respond to you with next steps.
+
+If the issue is highly sensitive, you are welcome to encrypt your message. Here is my [PGP key](https://keyserver.ubuntu.com/pks/lookup?search=miguel.grinberg%40gmail.com&fingerprint=on&op=index).
+
+Please do not disclose vulnerabilities publicly before discussing how to proceed with me.

bin/mkrelease

@@ -1,33 +0,0 @@
-#!/bin/bash
-VERSION=$1
-if [[ "$VERSION" == "" ]]; then
-    echo Usage: $0 "<version>"
-    exit 1
-fi
-
-git diff --cached --exit-code >/dev/null
-if [[ "$?" != "0" ]]; then
-    echo Commit your changes before using this script.
-    exit 1
-fi
-
-set -e
-for PKG in microdot*; do
-    echo Building $PKG...
-    cd $PKG
-    sed -i "" "s/version.*$/version=\"$VERSION\",/" setup.py
-    git add setup.py
-    rm -rf dist
-    python setup.py sdist bdist_wheel --universal
-    cd ..
-done
-git commit -m "Release v$VERSION"
-git tag v$VERSION
-git push --tags origin master
-
-for PKG in microdot*; do
-    echo Releasing $PKG...
-    cd $PKG
-    twine upload dist/*
-    cd ..
-done

docs/_static/css/custom.css

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

docs/api.rst

@@ -4,59 +4,62 @@ API Reference
 ``microdot`` module
 -------------------
 
-The ``microdot`` module defines a few classes that help implement HTTP-based
-servers for MicroPython and standard Python, with multithreading support for
-Python interpreters that support it.
-
-``Microdot`` class
-~~~~~~~~~~~~~~~~~~
-
 .. autoclass:: microdot.Microdot
    :members:
 
-``Request`` class
-~~~~~~~~~~~~~~~~~
-
 .. autoclass:: microdot.Request
    :members:
 
-``Response`` class
-~~~~~~~~~~~~~~~~~~
-
 .. autoclass:: microdot.Response
    :members:
 
-``MultiDict`` class
-~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: microdot.MultiDict
+``websocket`` extension
+-----------------------
+
+.. automodule:: microdot.websocket
    :members:
 
-``microdot_asyncio`` module
----------------------------
+``utemplate`` templating extension
+----------------------------------
 
-The ``microdot_asyncio`` module defines a few classes that help implement
-HTTP-based servers for MicroPython and standard Python that use ``asyncio``
-and coroutines.
-
-``Microdot`` class
-~~~~~~~~~~~~~~~~~~
-
-.. autoclass:: microdot_asyncio.Microdot
-   :inherited-members:
+.. automodule:: microdot.utemplate
    :members:
 
-``Request`` class
-~~~~~~~~~~~~~~~~~
+``jinja`` templating extension
+------------------------------
 
-.. autoclass:: microdot_asyncio.Request
-   :inherited-members:
+.. automodule:: microdot.jinja
    :members:
 
-``Response`` class
-~~~~~~~~~~~~~~~~~~
+``session`` extension
+---------------------
 
-.. autoclass:: microdot_asyncio.Response
-   :inherited-members:
+.. automodule:: microdot.session
    :members:
 
+``cors`` extension
+------------------
+
+.. automodule:: microdot.cors
+   :members:
+
+``test_client`` extension
+-------------------------
+
+.. automodule:: microdot.test_client
+   :members:
+
+``asgi`` extension
+------------------
+
+.. autoclass:: microdot.asgi.Microdot
+   :members:
+   :exclude-members: shutdown, run
+
+``wsgi`` extension
+-------------------
+
+.. autoclass:: microdot.wsgi.Microdot
+   :members:
+   :exclude-members: shutdown, run

docs/conf.py

@@ -12,9 +12,8 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../microdot'))
-sys.path.insert(1, os.path.abspath('../microdot-asyncio'))
-
+sys.path.insert(0, os.path.abspath('../src'))
+sys.path.insert(1, os.path.abspath('../libs/common'))
 
 # -- Project information -----------------------------------------------------
 
@@ -29,6 +28,7 @@ author = 'Miguel Grinberg'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autosectionlabel',
     'sphinx.ext.autodoc',
 ]
 

docs/extensions.rst

@@ -0,0 +1,440 @@
+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.
+
+WebSocket Support
+~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     -  | `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>`_
+
+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::
+
+        @app.route('/echo')
+        @with_websocket
+        async def echo(request, ws):
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
+
+Server-Sent Events Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     -  | `sse.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/sse.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::
+
+    @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
+
+.. 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.
+
+Rendering 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:`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
+     - | `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:`init_templates <microdot.utemplate.init_templates>` function::
+
+    from microdot.jinja import init_templates
+
+    init_templates('my_templates')
+
+The ``init_templates()`` function 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.utemplate.Template.render_async>` and
+:func:`generate_async() <microdot.utemplate.Template.generate_async>` methods
+must be used.
+
+.. note::
+    The Jinja extension is not compatible with MicroPython.
+
+Maintaining 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>`_
+
+   * - 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.
+
+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
+     - | `cors.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/cors/cors.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)
+
+Testing with the 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.
+
+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 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://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``.
+
+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/freezing.rst

@@ -0,0 +1,110 @@
+Cross-Compiling and Freezing Microdot (MicroPython Only)
+--------------------------------------------------------
+
+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 without problems.
+
+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 depending on the device, 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/index.rst

@@ -6,15 +6,20 @@
 Microdot
 ========
 
-Microdot is a minimalistic Python web framework for microcontrollers 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>`_.
+*"The impossibly small web framework for Python and MicroPython"*
+
+Microdot is a minimalistic Python web framework inspired by
+`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
 
    intro
+   extensions
+   migrating
+   freezing
    api
 
 * :ref:`genindex`

docs/intro.rst

@@ -1,29 +1,872 @@
-Examples
---------
+Installation
+------------
 
-The following is an example of a standard single or multi-threaded web
-server::
+The installation method is different depending on the version of Python.
+
+CPython Installation
+~~~~~~~~~~~~~~~~~~~~
+
+For use with standard Python (CPython) projects, Microdot and all of its core
+extensions are installed with ``pip``::
+
+    pip install microdot
+
+MicroPython Installation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+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, ideally 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.
+
+Use the following guidelines to know what files to copy:
+
+- 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>`_
+  into your project.
+- For a configuration that includes one or more optional extensions, create a
+  *microdot* directory in your device and copy the following files:
+   - `__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>`_.
+
+
+Getting Started
+---------------
+
+This section describes the main features of Microdot in an informal manner.
+
+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>`.
+
+A Simple Microdot Web Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following is an example of a simple web server::
 
     from microdot import Microdot
 
     app = Microdot()
 
     @app.route('/')
-    def hello(request):
+    async def index(request):
         return 'Hello, world!'
 
     app.run()
 
-Microdot also supports the asynchronous model and can be used under
-``asyncio``. The example that follows is equivalent to the one above, but uses
-coroutines for concurrency::
+The script imports the :class:`Microdot <microdot.Microdot>` class and creates
+an application instance from it.
 
-    from microdot_asyncio import Microdot
+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.
 
-    app = Microdot()
+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. 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
+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/tree/main/src/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>` method supports 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::
+   The ``ssl`` argument can only be used with CPython at this time, because
+   MicroPython's asyncio module does not currently support SSL certificates or
+   TLS encryption. Work on this is
+   `in progress <https://github.com/micropython/micropython/pull/11897>`_.
+
+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('/')
-    async def hello(request):
+    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 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, 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
+
+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>')
+    async 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
+    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 past 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
+
+    async 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')
+    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.
+
+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.
+- :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.
+
+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'])
+    async 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 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
+
+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('/')
+    async def index(request):
+        return 'Hello, World!'
+
+In the above example, Microdot issues a standard 200 status code response, and
+inserts default headers.
+
+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 a default text response::
+
+    @app.get('/')
+    async 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 status
+code::
+
+    @app.get('/')
+    async 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('/')
+    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.
+
+Concurrency
+~~~~~~~~~~~
+
+Microdot implements concurrency through the ``asyncio`` package. Applications
+must ensure their handlers do not block, as this will prevent other concurrent
+requests from being handled.
+
+When running under CPython, ``async def`` handler functions run as native 
+asyncio tasks, while ``def`` handler functions are executed in a
+`thread executor <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor>`_
+to prevent them from blocking the asynchronous loop.
+
+Under MicroPython the situation is different. Most microcontroller boards
+implementing MicroPython do not have threading support or executors, so ``def``
+handler functions in this platform can only run in the main and only thread.
+These functions will block the asynchronous loop when they take too long to
+complete so ``async def`` handlers properly written to allow other handlers to
+run in parallel should be preferred.

docs/migrating.rst

@@ -0,0 +1,142 @@
+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 await 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.
+
+As before, the WSGI extension is not available under MicroPython.

examples/benchmark/README.md

@@ -0,0 +1,5 @@
+This directory contains a few example applications for different
+configurations of Microdot, plus similar implementations for other web
+frameworks.
+
+The *run.py* script runs these applications and reports memory usage for each.

examples/benchmark/mem.py

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

examples/benchmark/mem_asgi.py

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

examples/benchmark/mem_fastapi.py

@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get('/')
+async def index():
+    return {'hello': 'world'}

examples/benchmark/mem_flask.py

@@ -0,0 +1,8 @@
+from flask import Flask
+
+app = Flask(__name__)
+
+
+@app.get('/')
+def index():
+    return {'hello': 'world'}

examples/benchmark/mem_quart.py

@@ -0,0 +1,8 @@
+from quart import Quart
+
+app = Quart(__name__)
+
+
+@app.get('/')
+async def index():
+    return {'hello': 'world'}

examples/benchmark/mem_wsgi.py

@@ -0,0 +1,8 @@
+from microdot.wsgi import Microdot
+
+app = Microdot()
+
+
+@app.get('/')
+def index(req):
+    return {'hello': 'world'}

examples/benchmark/requirements.in

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

examples/benchmark/requirements.txt

@@ -0,0 +1,115 @@
+#
+# 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
+    #   fastapi
+    #   starlette
+blinker==1.7.0
+    # via
+    #   flask
+    #   quart
+build==1.0.3
+    # via pip-tools
+certifi==2023.11.17
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via
+    #   flask
+    #   pip-tools
+    #   quart
+    #   uvicorn
+fastapi==0.104.1
+    # via -r requirements.in
+flask==3.0.0
+    # via
+    #   -r requirements.in
+    #   quart
+gunicorn==21.2.0
+    # via -r requirements.in
+h11==0.14.0
+    # via
+    #   hypercorn
+    #   uvicorn
+    #   wsproto
+h2==4.1.0
+    # via hypercorn
+hpack==4.0.0
+    # via h2
+humanize==4.9.0
+    # via -r requirements.in
+hypercorn==0.15.0
+    # via quart
+hyperframe==6.0.1
+    # via h2
+idna==3.6
+    # via
+    #   anyio
+    #   requests
+itsdangerous==2.1.2
+    # via
+    #   flask
+    #   quart
+jinja2==3.1.2
+    # 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
+    # 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.19.4
+    # via -r requirements.in
+requests==2.31.0
+    # via -r requirements.in
+sniffio==1.3.0
+    # via anyio
+starlette==0.27.0
+    # via fastapi
+typing-extensions==4.9.0
+    # via
+    #   fastapi
+    #   pydantic
+    #   pydantic-core
+urllib3==2.1.0
+    # via requests
+uvicorn==0.24.0.post1
+    # via -r requirements.in
+werkzeug==3.0.1
+    # 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

@@ -0,0 +1,89 @@
+import os
+import subprocess
+import time
+from timeit import timeit
+import requests
+import psutil
+import humanize
+
+apps = [
+    (
+        ['micropython', '-c', 'import time; time.sleep(10)'],
+        {},
+        'baseline-micropython'
+    ),
+    (
+        'micropython mem.py',
+        {'MICROPYPATH': '../../src:../../libs/micropython'},
+        'microdot-micropython'
+    ),
+    (
+        ['python', '-c', 'import time; time.sleep(10)'],
+        {},
+        'baseline-python'
+    ),
+    (
+        'python mem.py',
+        {'PYTHONPATH': '../../src'},
+        'microdot-cpython'
+    ),
+    (
+        'uvicorn --workers 1 --port 5000 mem_asgi:app',
+        {'PYTHONPATH': '../../src'},
+        'microdot-uvicorn'
+    ),
+    (
+        'gunicorn --workers 1 --bind :5000 mem_wsgi:app',
+        {'PYTHONPATH': '../../src'},
+        'microdot-gunicorn'
+    ),
+    (
+        'flask run',
+        {'FLASK_APP': 'mem_flask.py'},
+        'flask-run'
+    ),
+    (
+        'quart run',
+        {'QUART_APP': 'mem_quart.py'},
+        'quart-run'
+    ),
+    (
+        'gunicorn --workers 1 --bind :5000 mem_flask:app',
+        {},
+        'flask-gunicorn'
+    ),
+    (
+        'uvicorn --workers 1 --port 5000 mem_quart:app',
+        {},
+        'quart-uvicorn'
+    ),
+    (
+        'uvicorn --workers 1 --port 5000 mem_fastapi:app',
+        {},
+        'fastapi-uvicorn'
+    ),
+]
+
+for app, env, name in apps:
+    p = subprocess.Popen(
+        app.split() if isinstance(app, str) else app,
+        env={'PATH': os.environ['PATH'] + ':../../bin', **env},
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL
+    )
+    time.sleep(1)
+    tm = 0
+    if not name.startswith('baseline'):
+        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}{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/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/hello/README.md

@@ -0,0 +1,2 @@
+This directory contains several "Hello, World!" type examples for different
+platforms and configurations supported by Microdot.

examples/hello/hello.py

@@ -1,11 +1,12 @@
-from microdot import Microdot, Response
+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 Response(body=htmldoc, headers={'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,15 +1,12 @@
-try:
-    import uasyncio as asyncio
-except ImportError:
-    import asyncio
-from microdot_asyncio import Microdot, Response
+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>
@@ -24,7 +21,7 @@ htmldoc = '''<!DOCTYPE html>
 
 @app.route('/')
 async def hello(request):
-    return Response(body=htmldoc, headers={'Content-Type': 'text/html'})
+    return html, 200, {'Content-Type': 'text/html'}
 
 
 @app.route('/shutdown')
@@ -33,8 +30,8 @@ async def shutdown(request):
     return 'The server is shutting down...'
 
 
-async def main():
-    await app.start_server(debug=True)
-
-
-asyncio.run(main())
+if __name__ == '__main__':
+    print('''Use an ASGI web server to run this applicaton.
+Example:
+    uvicorn hello_asgi:app
+''')

examples/hello/hello_wsgi.py

@@ -0,0 +1,37 @@
+from microdot.wsgi import Microdot
+
+app = Microdot()
+
+html = '''<!DOCTYPE html>
+<html>
+    <head>
+        <title>Microdot Example Page</title>
+        <meta charset="UTF-8">
+    </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('/')
+def hello(request):
+    return html, 200, {'Content-Type': 'text/html'}
+
+
+@app.route('/shutdown')
+def shutdown(request):
+    request.app.shutdown()
+    return 'The server is shutting down...'
+
+
+if __name__ == '__main__':
+    print('''Use a WSGI web server to run this applicaton.
+Example:
+    gunicorn hello_wsgi:app
+''')

examples/sessions/README.md

@@ -0,0 +1 @@
+This directory contains examples that take advantage of user sessions.

examples/sessions/login.py

@@ -0,0 +1,60 @@
+from microdot import Microdot, Response, redirect
+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>
+    {content}
+  </body>
+</html>'''
+
+LOGGED_OUT = '''<p>You are not logged in.</p>
+<form method="POST">
+  <p>
+    Username:
+    <input name="username" autofocus />
+  </p>
+  <input type="submit" value="Submit" />
+</form>'''
+
+LOGGED_IN = '''<p>Hello <b>{username}</b>!</p>
+<form method="POST" action="/logout">
+  <input type="submit" value="Logout" />
+</form>'''
+
+app = Microdot()
+Session(app, secret_key='top-secret')
+Response.default_content_type = 'text/html'
+
+
+@app.get('/')
+@app.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 BASE_TEMPLATE.format(content=LOGGED_OUT)
+    else:
+        return BASE_TEMPLATE.format(content=LOGGED_IN.format(
+            username=username))
+
+
+@app.post('/logout')
+@with_session
+async def logout(req, session):
+    session.delete()
+    return redirect('/')
+
+
+if __name__ == '__main__':
+    app.run()

examples/sse/counter.py

@@ -0,0 +1,16 @@
+import asyncio
+from microdot import Microdot
+from microdot.sse import with_sse
+
+app = Microdot()
+
+
+@app.route('/events')
+@with_sse
+async def events(request, sse):
+    for i in range(10):
+        await asyncio.sleep(1)
+        await sse.send({'counter': i})
+
+
+app.run(debug=True)

examples/static/README.md

@@ -0,0 +1,2 @@
+The example in this directory demonstrates how to serve static files out of a
+directory.

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

@@ -0,0 +1,18 @@
+from microdot import Microdot, send_file
+app = Microdot()
+
+
+@app.route('/')
+async def index(request):
+    return send_file('static/index.html')
+
+
+@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)
+
+
+app.run(debug=True)

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;
+}

examples/static/static/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Static File Serving Demo</title>
+    <meta charset="UTF-8">
+  </head>
+  <body>
+    <h1>Static File Serving Demo</h1>
+    <img src="static/logo.png" alt="logo">
+  </body>
+</html>

examples/streaming/README.md

@@ -0,0 +1 @@
+This directory contain examples that demonstrate how to use streaming responses.

examples/streaming/video_stream.py

@@ -0,0 +1,67 @@
+import sys
+import asyncio
+from microdot import Microdot
+
+app = Microdot()
+
+frames = []
+for file in ['1.jpg', '2.jpg', '3.jpg']:
+    with open(file, 'rb') as f:
+        frames.append(f.read())
+
+
+@app.route('/')
+async def index(request):
+    return '''<!doctype html>
+<html>
+  <head>
+    <title>Microdot Video Streaming</title>
+    <meta charset="UTF-8">
+  </head>
+  <body>
+    <h1>Microdot Video Streaming</h1>
+    <img src="/video_feed">
+  </body>
+</html>''', 200, {'Content-Type': 'text/html'}
+
+
+@app.route('/video_feed')
+async def video_feed(request):
+    print('Starting video stream.')
+
+    if sys.implementation.name != 'micropython':
+        # CPython supports async generator function
+        async def stream():
+            try:
+                yield b'--frame\r\n'
+                while True:
+                    for frame in frames:
+                        yield b'Content-Type: image/jpeg\r\n\r\n' + frame + \
+                            b'\r\n--frame\r\n'
+                        await asyncio.sleep(1)
+            except GeneratorExit:
+                print('Stopping video stream.')
+    else:
+        # MicroPython can only use class-based async generators
+        class stream():
+            def __init__(self):
+                self.i = 0
+
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                await asyncio.sleep(1)
+                self.i = (self.i + 1) % len(frames)
+                return b'Content-Type: image/jpeg\r\n\r\n' + \
+                    frames[self.i] + b'\r\n--frame\r\n'
+
+            async def aclose(self):
+                print('Stopping video stream.')
+
+    return stream(), 200, {'Content-Type':
+                           'multipart/x-mixed-replace; boundary=frame'}
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

examples/templates/jinja/async_template.py

@@ -0,0 +1,18 @@
+from microdot import Microdot, Response
+from microdot.jinja import template, init_templates
+
+init_templates('templates', enable_async=True)
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return await template('index.html').render_async(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/jinja/bootstrap.py

@@ -0,0 +1,19 @@
+from microdot import Microdot, Response
+from microdot.jinja import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/')
+async def index(req):
+    return template('page1.html').render(page='Page 1')
+
+
+@app.route('/page2')
+async def page2(req):
+    return template('page2.html').render(page='Page 2')
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/jinja/hello.py

@@ -0,0 +1,17 @@
+from microdot import Microdot, Response
+from microdot.jinja import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return template('index.html').render(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/jinja/hello_asgi.py

@@ -0,0 +1,17 @@
+from microdot.asgi import Microdot, Response
+from microdot.jinja import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return template('index.html').render(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/jinja/hello_wsgi.py

@@ -0,0 +1,17 @@
+from microdot.wsgi import Microdot, Response
+from microdot.jinja import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return template('index.html').render(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/jinja/streaming.py

@@ -0,0 +1,17 @@
+from microdot import Microdot, Response
+from microdot.jinja import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return template('index.html').generate(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/jinja/templates/base.html

@@ -0,0 +1,48 @@
+<!--
+  This is based on the Bootstrap 5 starter template from the documentation:
+  https://getbootstrap.com/docs/5.0/getting-started/introduction/#starter-template
+-->
+<!doctype html>
+<html lang="en">
+  <head>
+    <!-- Required meta tags -->
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
+
+    <title>Microdot + Jinja + Bootstrap</title>
+  </head>
+  <body>
+    <nav class="navbar navbar-expand-lg navbar-light bg-light">
+      <div class="container">
+        <a class="navbar-brand" href="/">Microdot + Jinja + Bootstrap</a>
+      </div>
+    </nav>
+    <br>
+    <div class="container">
+      <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+        <symbol id="info-fill" fill="currentColor" viewBox="0 0 16 16">
+          <path d="M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zm.93-9.412-1 4.705c-.07.34.029.533.304.533.194 0 .487-.07.686-.246l-.088.416c-.287.346-.92.598-1.465.598-.703 0-1.002-.422-.808-1.319l.738-3.468c.064-.293.006-.399-.287-.47l-.451-.081.082-.381 2.29-.287zM8 5.5a1 1 0 1 1 0-2 1 1 0 0 1 0 2z"/>
+        </symbol>
+      </svg>
+      <div class="alert alert-primary d-flex align-items-center" role="alert">
+        <svg class="bi flex-shrink-0 me-2" width="24" height="24" role="img" aria-label="Info:"><use xlink:href="#info-fill"/></svg>
+        <div>This example demonstrates how to create an application that uses <a href="https://getbootstrap.com" class="alert-link">Bootstrap</a> styling. The page layout is defined in a base template that is inherited by several pages.</div>
+      </div>
+      {% block content %}{% endblock %}
+    </div>
+
+    <!-- Optional JavaScript; choose one of the two! -->
+
+    <!-- Option 1: Bootstrap Bundle with Popper -->
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
+
+    <!-- Option 2: Separate Popper and Bootstrap JS -->
+    <!--
+    <script src="https://cdn.jsdelivr.net/npm/@popperjs/core@2.9.2/dist/umd/popper.min.js" integrity="sha384-IQsoLXl5PILFhosVNubq5LC7Qb9DXgDA9i+tQ8Zj3iwWAwPtgFTxbJ8NT4GN1R8p" crossorigin="anonymous"></script>
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.min.js" integrity="sha384-cVKIPhGWiC2Al4u+LWgxfKTRIcfu0JTxR+EQDz/bgldoEyl4H0zUF0QKbrJ0EcQF" crossorigin="anonymous"></script>
+    -->
+  </body>
+</html>

examples/templates/jinja/templates/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot + Jinja example</title>
+    <meta charset="UTF-8">
+  </head>
+  <body>
+    <h1>Microdot + Jinja example</h1>
+    {% if name %}
+    <p>Hello, <b>{{ name }}</b>!</p>
+    {% endif %}
+    <form method="POST">
+      <p>
+        What is your name?
+        <input type="text" name="name" autofocus />
+      </p>
+      <input type="submit" value="Submit" />
+    </form>
+  </body>
+</html>

examples/templates/jinja/templates/page1.html

@@ -0,0 +1,6 @@
+{% extends 'base.html' %}
+
+{% block content %}
+<h2>This is {{ page }}</h2>
+<p>Go to <a href="/page2">Page 2</a>.</p>
+{% endblock %}

examples/templates/jinja/templates/page2.html

@@ -0,0 +1,6 @@
+{% extends 'base.html' %}
+
+{% block content %}
+<h2>This is {{ page }}</h2>
+<p>Go back <a href="/">Page 1</a>.</p>
+{% endblock %}

examples/templates/utemplate/async_template.py

@@ -0,0 +1,17 @@
+from microdot import Microdot, Response
+from microdot.utemplate import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return await template('index.html').render_async(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/utemplate/bootstrap.py

@@ -0,0 +1,19 @@
+from microdot import Microdot, Response
+from microdot.utemplate import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/')
+async def index(req):
+    return template('page1.html').render(page='Page 1')
+
+
+@app.route('/page2')
+async def page2(req):
+    return template('page2.html').render(page='Page 2')
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

examples/templates/utemplate/hello.py

@@ -0,0 +1,17 @@
+from microdot import Microdot, Response
+from microdot.utemplate import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return template('index.html').render(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/utemplate/hello_asgi.py

@@ -0,0 +1,17 @@
+from microdot.asgi import Microdot, Response
+from microdot.utemplate import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return template('index.html').render(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/utemplate/hello_wsgi.py

@@ -0,0 +1,17 @@
+from microdot.wsgi import Microdot, Response
+from microdot.utemplate import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return template('index.html').render(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/utemplate/streaming.py

@@ -0,0 +1,17 @@
+from microdot import Microdot, Response
+from microdot.utemplate import template
+
+app = Microdot()
+Response.default_content_type = 'text/html'
+
+
+@app.route('/', methods=['GET', 'POST'])
+async def index(req):
+    name = None
+    if req.method == 'POST':
+        name = req.form.get('name')
+    return template('index.html').generate(name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/templates/utemplate/templates/base_footer.html

@@ -0,0 +1,14 @@
+    </div>
+
+    <!-- Optional JavaScript; choose one of the two! -->
+
+    <!-- Option 1: Bootstrap Bundle with Popper -->
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
+
+    <!-- Option 2: Separate Popper and Bootstrap JS -->
+    <!--
+    <script src="https://cdn.jsdelivr.net/npm/@popperjs/core@2.9.2/dist/umd/popper.min.js" integrity="sha384-IQsoLXl5PILFhosVNubq5LC7Qb9DXgDA9i+tQ8Zj3iwWAwPtgFTxbJ8NT4GN1R8p" crossorigin="anonymous"></script>
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.min.js" integrity="sha384-cVKIPhGWiC2Al4u+LWgxfKTRIcfu0JTxR+EQDz/bgldoEyl4H0zUF0QKbrJ0EcQF" crossorigin="anonymous"></script>
+    -->
+  </body>
+</html>

examples/templates/utemplate/templates/base_header.html

@@ -0,0 +1,33 @@
+<!--
+  This is based on the Bootstrap 5 starter template from the documentation:
+  https://getbootstrap.com/docs/5.0/getting-started/introduction/#starter-template
+-->
+<!doctype html>
+<html lang="en">
+  <head>
+    <!-- Required meta tags -->
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
+
+    <title>Microdot + uTemplate + Bootstrap</title>
+  </head>
+  <body>
+    <nav class="navbar navbar-expand-lg navbar-light bg-light">
+      <div class="container">
+        <a class="navbar-brand" href="/">Microdot + uTemplate + Bootstrap</a>
+      </div>
+    </nav>
+    <br>
+    <div class="container">
+      <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+        <symbol id="info-fill" fill="currentColor" viewBox="0 0 16 16">
+          <path d="M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zm.93-9.412-1 4.705c-.07.34.029.533.304.533.194 0 .487-.07.686-.246l-.088.416c-.287.346-.92.598-1.465.598-.703 0-1.002-.422-.808-1.319l.738-3.468c.064-.293.006-.399-.287-.47l-.451-.081.082-.381 2.29-.287zM8 5.5a1 1 0 1 1 0-2 1 1 0 0 1 0 2z"/>
+        </symbol>
+      </svg>
+      <div class="alert alert-primary d-flex align-items-center" role="alert">
+        <svg class="bi flex-shrink-0 me-2" width="24" height="24" role="img" aria-label="Info:"><use xlink:href="#info-fill"/></svg>
+        <div>This example demonstrates how to create an application that uses <a href="https://getbootstrap.com" class="alert-link">Bootstrap</a> styling. The page layout is defined in a base template that is inherited by several pages.</div>
+      </div>

examples/templates/utemplate/templates/index.html

@@ -0,0 +1,21 @@
+{% args name %}
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot + uTemplate example</title>
+    <meta charset="UTF-8">
+  </head>
+  <body>
+    <h1>Microdot + uTemplate example</h1>
+    {% if name %}
+    <p>Hello, <b>{{ name }}</b>!</p>
+    {% endif %}
+    <form method="POST">
+      <p>
+        What is your name?
+        <input type="text" name="name" autofocus />
+      </p>
+      <input type="submit" value="Submit" />
+    </form>
+  </body>
+</html>

examples/templates/utemplate/templates/page1.html

@@ -0,0 +1,7 @@
+{% args page %}
+{% include 'base_header.html' %}
+
+<h2>This is {{ page }}</h2>
+<p>Go to <a href="/page2">Page 2</a>.</p>
+
+{% include 'base_footer.html' %}

examples/templates/utemplate/templates/page2.html

@@ -0,0 +1,7 @@
+{% args page %}
+{% include 'base_header.html' %}
+
+<h2>This is {{ page }}</h2>
+<p>Go back <a href="/">Page 1</a>.</p>
+
+{% include 'base_footer.html' %}

examples/tls/README.md

@@ -0,0 +1,20 @@
+This directory contains examples that demonstrate how to start TLS servers.
+
+To run these examples, SSL certificate and private key files need to be
+created. When running under CPython, the files should be in PEM format, named
+`cert.pem` and `key.pem`. When running under MicroPython, they should be in DER
+format, and named `cert.der` and `key.der`.
+
+To quickly create a self-signed SSL certificate, use the following command:
+
+```bash
+openssl req -x509 -newkey rsa:4096 -nodes -out cert.pem -keyout key.pem -days 365
+```
+
+To convert the resulting PEM files to DER format for MicroPython, use these
+commands:
+
+```bash
+openssl x509 -in cert.pem -out cert.der -outform DER
+openssl rsa -in key.pem -out key.der -outform DER
+```

examples/tls/hello.py

@@ -0,0 +1,36 @@
+import ssl
+from microdot import Microdot
+
+app = Microdot()
+
+html = '''<!DOCTYPE html>
+<html>
+    <head>
+        <title>Microdot Example Page</title>
+        <meta charset="UTF-8">
+    </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 html, 200, {'Content-Type': 'text/html'}
+
+
+@app.route('/shutdown')
+async def shutdown(request):
+    request.app.shutdown()
+    return 'The server is shutting down...'
+
+
+sslctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+sslctx.load_cert_chain('cert.pem', 'key.pem')
+app.run(port=4443, debug=True, ssl=sslctx)

examples/uploads/README.md

@@ -0,0 +1 @@
+This directory contains file upload examples.

examples/uploads/files/README.md

@@ -0,0 +1 @@
+Uploaded files are saved to this directory.

examples/uploads/index.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot Upload Example</title>
+    <meta charset="UTF-8">
+  </head>
+  <body>
+    <h1>Microdot Upload Example</h1>
+    <form id="form">
+      <input type="file" id="file" name="file" />
+      <input type="submit" value="Upload" />
+    </form>
+    <script>
+      async function upload(ev) {
+        ev.preventDefault();
+        const file = document.getElementById('file').files[0];
+        if (!file) {
+          return;
+        }
+        await fetch('/upload', {
+          method: 'POST',
+          body: file,
+          headers: {
+            'Content-Type': 'application/octet-stream',
+            'Content-Disposition': `attachment; filename="${file.name}"`,
+          },
+        }).then(res => {
+          console.log('Upload accepted');
+          window.location.href = '/';
+        });
+      }
+      document.getElementById('form').addEventListener('submit', upload);
+    </script>
+  </body>
+</html>

examples/uploads/uploads.py

@@ -0,0 +1,34 @@
+from microdot import Microdot, send_file, Request
+
+app = Microdot()
+Request.max_content_length = 1024 * 1024  # 1MB (change as needed)
+
+
+@app.get('/')
+async def index(request):
+    return send_file('index.html')
+
+
+@app.post('/upload')
+async def upload(request):
+    # obtain the filename and size from request headers
+    filename = request.headers['Content-Disposition'].split(
+        'filename=')[1].strip('"')
+    size = int(request.headers['Content-Length'])
+
+    # sanitize the filename
+    filename = filename.replace('/', '_')
+
+    # write the file to the files directory in 1K chunks
+    with open('files/' + filename, 'wb') as f:
+        while size > 0:
+            chunk = await request.stream.read(min(size, 1024))
+            f.write(chunk)
+            size -= len(chunk)
+
+    print('Successfully saved file: ' + filename)
+    return ''
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

examples/websocket/README.md

@@ -0,0 +1 @@
+This directory contains WebSocket examples.

examples/websocket/echo.py

@@ -0,0 +1,20 @@
+from microdot import Microdot, send_file
+from microdot.websocket import with_websocket
+
+app = Microdot()
+
+
+@app.route('/')
+async def index(request):
+    return send_file('index.html')
+
+
+@app.route('/echo')
+@with_websocket
+async def echo(request, ws):
+    while True:
+        data = await ws.receive()
+        await ws.send(data)
+
+
+app.run()

examples/websocket/echo_asgi.py

@@ -0,0 +1,20 @@
+from microdot.asgi import Microdot, send_file, with_websocket
+
+app = Microdot()
+
+
+@app.route('/')
+async def index(request):
+    return send_file('index.html')
+
+
+@app.route('/echo')
+@with_websocket
+async def echo(request, ws):
+    while True:
+        data = await ws.receive()
+        await ws.send(data)
+
+
+if __name__ == '__main__':
+    app.run()

examples/websocket/echo_wsgi.py

@@ -0,0 +1,20 @@
+from microdot.wsgi import Microdot, send_file, with_websocket
+
+app = Microdot()
+
+
+@app.route('/')
+async def index(request):
+    return send_file('index.html')
+
+
+@app.route('/echo')
+@with_websocket
+async def echo(request, ws):
+    while True:
+        data = await ws.receive()
+        await ws.send(data)
+
+
+if __name__ == '__main__':
+    app.run()

examples/websocket/index.html

@@ -0,0 +1,36 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot WebSocket Demo</title>
+    <meta charset="UTF-8">
+  </head>
+  <body>
+    <h1>Microdot WebSocket Demo</h1>
+    <div id="log"></div>
+    <br>
+    <form id="form">
+      <label for="text">Input: </label>
+      <input type="text" id="text" autofocus>
+    </form>
+    <script>
+      const log = (text, color) => {
+        document.getElementById('log').innerHTML += `<span style="color: ${color}">${text}</span><br>`;
+      };
+
+      const socket = new WebSocket('ws://' + location.host + '/echo');
+      socket.addEventListener('message', ev => {
+        log('<<< ' + ev.data, 'blue');
+      });
+      socket.addEventListener('close', ev => {
+        log('<<< closed');
+      });
+      document.getElementById('form').onsubmit = ev => {
+        ev.preventDefault();
+        const textField = document.getElementById('text');
+        log('>>> ' + textField.value, 'red');
+        socket.send(textField.value);
+        textField.value = '';
+      };
+    </script>
+  </body>
+</html>

legacy/README.md

@@ -1,5 +0,0 @@
-microdot-asyncio
-================
-
-This package has been merged with the ``microdot`` package. It currently
-installs as an empty package that depends on it.

legacy/pyproject.toml

@@ -1,6 +0,0 @@
-[build-system]
-requires = [
-    "setuptools>=42",
-    "wheel"
-]
-build-backend = "setuptools.build_meta"

legacy/setup.cfg

@@ -1,24 +0,0 @@
-[metadata]
-name = microdot-asyncio
-version = 0.4.0
-author = Miguel Grinberg
-author_email = miguel.grinberg@gmail.com
-description = AsyncIO support for the Microdot web framework'
-long_description = file: README.md
-long_description_content_type = text/markdown
-url = https://github.com/miguelgrinberg/microdot
-project_urls =
-    Bug Tracker = https://github.com/miguelgrinberg/microdot/issues
-classifiers =
-    Environment :: Web Environment
-    Intended Audience :: Developers
-    Programming Language :: Python :: 3
-    Programming Language :: Python :: Implementation :: MicroPython
-    License :: OSI Approved :: MIT License
-    Operating System :: OS Independent
-[options]
-zip_safe = False
-include_package_data = True
-py_modules =
-install_requires =
-    microdot

legacy/setup.py

@@ -1,3 +0,0 @@
-import setuptools
-
-setuptools.setup()

libs/README.md

@@ -0,0 +1,9 @@
+# Vendored MicroPyton libraries
+
+This directory contains some libraries that are required by examples and unit
+tests.
+
+All libraries except `utemplate` were copied from the
+[micropython-lib](https://github.com/micropython/micropython-lib) project. See
+the README file in the `common/utemplate` subdirectory for details about this
+library.

libs/common/utemplate/README.md

@@ -0,0 +1,114 @@
+utemplate
+=========
+
+`utemplate` is a lightweight and memory-efficient template engine for
+Python, primarily designed for use with Pycopy, a lightweight Python
+implementation (https://github.com/pfalcon/pycopy). It is also fully
+compatible with CPython and other compliant Python implementations.
+
+`utemplate` syntax is roughly based on Django/Jinja2 syntax (e.g.
+`{% if %}`, `{{var}}`), but only the most needed features are offered
+(for example, "filters" (`{{var|filter}}`) are syntactic sugar for
+function calls, and so far are not planned to be implemented, function
+calls can be used directly instead: `{{filter(var)}}`).
+
+`utemplate` compiles templates to Python source code, specifically to
+a generator function which, being iterated over, produces consecutive
+parts (substrings) of the rendered template. This allows for minimal
+memory usage during template substitution (with Pycopy, it starts
+from mere hundreds of bytes). Generated Python code can be imported as
+a module directly, or a simple loader class (`utemplate.compiled.Loader`)
+is provided for convenience.
+
+There is also a loader class which will compile templates on the fly,
+if not already compiled - `utemplate.source.Loader`.
+
+Finally, there's a loader which will automatically recompile a template
+module if source template is changed - `utemplate.recompile.Loader`.
+This loader class is the most convenient to use during development, but
+on the other hand, it performs extra processing not required for a
+finished/deployed application.
+
+To test/manage templates, `utemplate_util.py` tool is provided. For
+example, to quickly try a template (assuming you are already in
+`examples/` dir):
+
+    pycopy ../utemplate_util.py run squares.tpl
+
+or
+
+    python3 ../utemplate_util.py run squares.tpl
+
+Templates can take parameters (that's how dynamic content is generated).
+Template parameters are passed as arguments to a generator function
+produced from a template. They also can be passed on the `utemplate_util.py`
+command line (arguments will be treated as strings in this case, but
+can be of any types if called from your code):
+
+    pycopy ../utemplate_util.py run test1.tpl foo bar
+
+Quick Syntax Reference
+----------------------
+
+Evaluating Python expression, converting it to a string and outputting to
+rendered content:
+
+* `{{<expr>}}`
+
+Where `expr` is an arbitrary Python expression - from a bare variable name,
+to function calls, `yield from`/`await` expressions, etc.
+
+Supported statements:
+
+* `{% args <var1>, <var2>, ... %}` - specify arguments to a template
+  (optional, should be at the beginning of a template if you want to
+  pass any arguments). All argument types as supported by Python can
+  be used: positional and keyword, with default values, `*args` and
+  `**kwargs` forms, etc.
+* `{% if <expr> %}`, `{% elif <expr> %}`, `{% else %}`, `{% endif %}` -
+  similar to Python's `if` statement
+* `{% for <var> in <expr> %}`, `{% endfor %}` - similar to Python's
+  `for` statement
+* `{% while <expr> %}`, `{% endwhile %}` - similar to Python's `while`
+  statement
+* `{% set <var> = <expr> %}` - assignment statement
+* `{% include "name.tpl" %}` - statically include another template
+* `{% include {{name}} %}` - dynamically include template whose name is
+  stored in variable `name`.
+
+File Naming Conventions
+-----------------------
+
+* The recommended extension for templates is `.tpl`, e.g. `example.tpl`.
+* When template is compiled, dot (`.`) in its name is replaced
+  with underscore (`_`) and `.py` appended, e.g. `example_tpl.py`. It
+  thus can be imported with `import example_tpl`.
+* The name passed to `{% include %}` statement should be full name of
+  a template with extension, e.g. `{% include "example.tpl" %}`.
+* For dynamic form of the `include`, a variable should similarly contain
+  a full name of the template, e.g. `{% set name = "example.tpl" %}` /
+  `{% include {{name}} %}`.
+
+Examples
+--------
+
+`examples/squares.tpl` as mentioned in the usage examples above has the
+following content:
+
+```
+{% args n=5 %}
+{% for i in range(n) %}
+| {{i}} | {{"%2d" % i ** 2}} |
+{% endfor %}
+```
+
+More examples are available in the [examples/](examples/) directory.
+
+If you want to see a complete example web application which uses `utemplate`,
+refer to https://github.com/pfalcon/notes-pico .
+
+License
+-------
+
+`utemplate` is written and maintained by Paul Sokolovsky. It's available
+under the MIT license.

libs/common/utemplate/compiled.py

@@ -0,0 +1,14 @@
+class Loader:
+
+    def __init__(self, pkg, dir):
+        if dir == ".":
+            dir = ""
+        else:
+            dir = dir.replace("/", ".") + "."
+        if pkg and pkg != "__main__":
+            dir = pkg + "." + dir
+        self.p = dir
+
+    def load(self, name):
+        name = name.replace(".", "_")
+        return __import__(self.p + name, None, None, (name,)).render

libs/common/utemplate/recompile.py

@@ -0,0 +1,21 @@
+# (c) 2014-2020 Paul Sokolovsky. MIT license.
+try:
+    from uos import stat, remove
+except:
+    from os import stat, remove
+from . import source
+
+
+class Loader(source.Loader):
+
+    def load(self, name):
+        o_path = self.pkg_path + self.compiled_path(name)
+        i_path = self.pkg_path + self.dir + "/" + name
+        try:
+            o_stat = stat(o_path)
+            i_stat = stat(i_path)
+            if i_stat[8] > o_stat[8]:
+                # input file is newer, remove output to force recompile
+                remove(o_path)
+        finally:
+            return super().load(name)

libs/common/utemplate/source.py

@@ -0,0 +1,188 @@
+# (c) 2014-2019 Paul Sokolovsky. MIT license.
+from . import compiled
+
+
+class Compiler:
+
+    START_CHAR = "{"
+    STMNT = "%"
+    STMNT_END = "%}"
+    EXPR = "{"
+    EXPR_END = "}}"
+
+    def __init__(self, file_in, file_out, indent=0, seq=0, loader=None):
+        self.file_in = file_in
+        self.file_out = file_out
+        self.loader = loader
+        self.seq = seq
+        self._indent = indent
+        self.stack = []
+        self.in_literal = False
+        self.flushed_header = False
+        self.args = "*a, **d"
+
+    def indent(self, adjust=0):
+        if not self.flushed_header:
+            self.flushed_header = True
+            self.indent()
+            self.file_out.write("def render%s(%s):\n" % (str(self.seq) if self.seq else "", self.args))
+            self.stack.append("def")
+        self.file_out.write("    " * (len(self.stack) + self._indent + adjust))
+
+    def literal(self, s):
+        if not s:
+            return
+        if not self.in_literal:
+            self.indent()
+            self.file_out.write('yield """')
+            self.in_literal = True
+        self.file_out.write(s.replace('"', '\\"'))
+
+    def close_literal(self):
+        if self.in_literal:
+            self.file_out.write('"""\n')
+        self.in_literal = False
+
+    def render_expr(self, e):
+        self.indent()
+        self.file_out.write('yield str(' + e + ')\n')
+
+    def parse_statement(self, stmt):
+        tokens = stmt.split(None, 1)
+        if tokens[0] == "args":
+            if len(tokens) > 1:
+                self.args = tokens[1]
+            else:
+                self.args = ""
+        elif tokens[0] == "set":
+            self.indent()
+            self.file_out.write(stmt[3:].strip() + "\n")
+        elif tokens[0] == "include":
+            if not self.flushed_header:
+                # If there was no other output, we still need a header now
+                self.indent()
+            tokens = tokens[1].split(None, 1)
+            args = ""
+            if len(tokens) > 1:
+                args = tokens[1]
+            if tokens[0][0] == "{":
+                self.indent()
+                # "1" as fromlist param is uPy hack
+                self.file_out.write('_ = __import__(%s.replace(".", "_"), None, None, 1)\n' % tokens[0][2:-2])
+                self.indent()
+                self.file_out.write("yield from _.render(%s)\n" % args)
+                return
+
+            with self.loader.input_open(tokens[0][1:-1]) as inc:
+                self.seq += 1
+                c = Compiler(inc, self.file_out, len(self.stack) + self._indent, self.seq)
+                inc_id = self.seq
+                self.seq = c.compile()
+            self.indent()
+            self.file_out.write("yield from render%d(%s)\n" % (inc_id, args))
+        elif len(tokens) > 1:
+            if tokens[0] == "elif":
+                assert self.stack[-1] == "if"
+                self.indent(-1)
+                self.file_out.write(stmt + ":\n")
+            else:
+                self.indent()
+                self.file_out.write(stmt + ":\n")
+                self.stack.append(tokens[0])
+        else:
+            if stmt.startswith("end"):
+                assert self.stack[-1] == stmt[3:]
+                self.stack.pop(-1)
+            elif stmt == "else":
+                assert self.stack[-1] == "if"
+                self.indent(-1)
+                self.file_out.write("else:\n")
+            else:
+                assert False
+
+    def parse_line(self, l):
+        while l:
+            start = l.find(self.START_CHAR)
+            if start == -1:
+                self.literal(l)
+                return
+            self.literal(l[:start])
+            self.close_literal()
+            sel = l[start + 1]
+            #print("*%s=%s=" % (sel, EXPR))
+            if sel == self.STMNT:
+                end = l.find(self.STMNT_END)
+                assert end > 0
+                stmt = l[start + len(self.START_CHAR + self.STMNT):end].strip()
+                self.parse_statement(stmt)
+                end += len(self.STMNT_END)
+                l = l[end:]
+                if not self.in_literal and l == "\n":
+                    break
+            elif sel == self.EXPR:
+    #            print("EXPR")
+                end = l.find(self.EXPR_END)
+                assert end > 0
+                expr = l[start + len(self.START_CHAR + self.EXPR):end].strip()
+                self.render_expr(expr)
+                end += len(self.EXPR_END)
+                l = l[end:]
+            else:
+                self.literal(l[start])
+                l = l[start + 1:]
+
+    def header(self):
+        self.file_out.write("# Autogenerated file\n")
+
+    def compile(self):
+        self.header()
+        for l in self.file_in:
+            self.parse_line(l)
+        self.close_literal()
+        return self.seq
+
+
+class Loader(compiled.Loader):
+
+    def __init__(self, pkg, dir):
+        super().__init__(pkg, dir)
+        self.dir = dir
+        if pkg == "__main__":
+            # if pkg isn't really a package, don't bother to use it
+            # it means we're running from "filesystem directory", not
+            # from a package.
+            pkg = None
+
+        self.pkg_path = ""
+        if pkg:
+            p = __import__(pkg)
+            if isinstance(p.__path__, str):
+                # uPy
+                self.pkg_path = p.__path__
+            else:
+                # CPy
+                self.pkg_path = p.__path__[0]
+            self.pkg_path += "/"
+
+    def input_open(self, template):
+        path = self.pkg_path + self.dir + "/" + template
+        return open(path)
+
+    def compiled_path(self, template):
+        return self.dir + "/" + template.replace(".", "_") + ".py"
+
+    def load(self, name):
+        try:
+            return super().load(name)
+        except (OSError, ImportError):
+            pass
+
+        compiled_path = self.pkg_path + self.compiled_path(name)
+
+        f_in = self.input_open(name)
+        f_out = open(compiled_path, "w")
+        c = Compiler(f_in, f_out, loader=self)
+        c.compile()
+        f_in.close()
+        f_out.close()
+        return super().load(name)

libs/micropython/asyncio/__init__.py

@@ -1,4 +1,4 @@
-# MicroPython uasyncio module
+# MicroPython asyncio module
 # MIT license; Copyright (c) 2019 Damien P. George
 
 from .core import *
@@ -18,6 +18,7 @@ _attrs = {
     "StreamWriter": "stream",
 }
 
+
 # Lazy loader, effectively does:
 #   global attr
 #   from .mod import attr

libs/micropython/asyncio/core.py

@@ -1,4 +1,4 @@
-# MicroPython uasyncio module
+# MicroPython asyncio module
 # MIT license; Copyright (c) 2019 Damien P. George
 
 from time import ticks_ms as ticks, ticks_diff, ticks_add
@@ -6,7 +6,7 @@ import sys, select
 
 # Import TaskQueue and Task, preferring built-in C code over Python code
 try:
-    from _uasyncio import TaskQueue, Task
+    from _asyncio import TaskQueue, Task
 except:
     from .task import TaskQueue, Task
 
@@ -30,6 +30,7 @@ _exc_context = {"message": "Task exception wasn't retrieved", "exception": None,
 ################################################################################
 # Sleep functions
 
+
 # "Yield" once, then raise StopIteration
 class SingletonGenerator:
     def __init__(self):
@@ -41,7 +42,7 @@ class SingletonGenerator:
 
     def __next__(self):
         if self.state is not None:
-            _task_queue.push_sorted(cur_task, self.state)
+            _task_queue.push(cur_task, self.state)
             self.state = None
             return None
         else:
@@ -115,11 +116,11 @@ class IOQueue:
             # print('poll', s, sm, ev)
             if ev & ~select.POLLOUT and sm[0] is not None:
                 # POLLIN or error
-                _task_queue.push_head(sm[0])
+                _task_queue.push(sm[0])
                 sm[0] = None
             if ev & ~select.POLLIN and sm[1] is not None:
                 # POLLOUT or error
-                _task_queue.push_head(sm[1])
+                _task_queue.push(sm[1])
                 sm[1] = None
             if sm[0] is None and sm[1] is None:
                 self._dequeue(s)
@@ -132,6 +133,7 @@ class IOQueue:
 ################################################################################
 # Main run loop
 
+
 # Ensure the awaitable is a task
 def _promote_to_task(aw):
     return aw if isinstance(aw, Task) else create_task(aw)
@@ -142,7 +144,7 @@ def create_task(coro):
     if not hasattr(coro, "send"):
         raise TypeError("coroutine expected")
     t = Task(coro, globals())
-    _task_queue.push_head(t)
+    _task_queue.push(t)
     return t
 
 
@@ -167,7 +169,7 @@ def run_until_complete(main_task=None):
             _io_queue.wait_io_event(dt)
 
         # Get next task to run and continue it
-        t = _task_queue.pop_head()
+        t = _task_queue.pop()
         cur_task = t
         try:
             # Continue running the coroutine, it's responsible for rescheduling itself
@@ -175,6 +177,10 @@ def run_until_complete(main_task=None):
             if not exc:
                 t.coro.send(None)
             else:
+                # If the task is finished and on the run queue and gets here, then it
+                # had an exception and was not await'ed on.  Throwing into it now will
+                # raise StopIteration and the code below will catch this and run the
+                # call_exception_handler function.
                 t.data = None
                 t.coro.throw(exc)
         except excs_all as er:
@@ -185,22 +191,37 @@ def run_until_complete(main_task=None):
                 if isinstance(er, StopIteration):
                     return er.value
                 raise er
-            # Schedule any other tasks waiting on the completion of this task
-            waiting = False
-            if hasattr(t, "waiting"):
-                while t.waiting.peek():
-                    _task_queue.push_head(t.waiting.pop_head())
+            if t.state:
+                # Task was running but is now finished.
+                waiting = False
+                if t.state is True:
+                    # "None" indicates that the task is complete and not await'ed on (yet).
+                    t.state = None
+                elif callable(t.state):
+                    # The task has a callback registered to be called on completion.
+                    t.state(t, er)
+                    t.state = False
                     waiting = True
-                t.waiting = None  # Free waiting queue head
-            if not waiting and not isinstance(er, excs_stop):
-                # An exception ended this detached task, so queue it for later
-                # execution to handle the uncaught exception if no other task retrieves
-                # the exception in the meantime (this is handled by Task.throw).
-                _task_queue.push_head(t)
-            # Indicate task is done by setting coro to the task object itself
-            t.coro = t
-            # Save return value of coro to pass up to caller
-            t.data = er
+                else:
+                    # Schedule any other tasks waiting on the completion of this task.
+                    while t.state.peek():
+                        _task_queue.push(t.state.pop())
+                        waiting = True
+                    # "False" indicates that the task is complete and has been await'ed on.
+                    t.state = False
+                if not waiting and not isinstance(er, excs_stop):
+                    # An exception ended this detached task, so queue it for later
+                    # execution to handle the uncaught exception if no other task retrieves
+                    # the exception in the meantime (this is handled by Task.throw).
+                    _task_queue.push(t)
+                # Save return value of coro to pass up to caller.
+                t.data = er
+            elif t.state is None:
+                # Task is already finished and nothing await'ed on the task,
+                # so call the exception handler.
+                _exc_context["exception"] = exc
+                _exc_context["future"] = t
+                Loop.call_exception_handler(_exc_context)
 
 
 # Create a new task from a coroutine and run it until it finishes
@@ -237,7 +258,7 @@ class Loop:
     def stop():
         global _stop_task
         if _stop_task is not None:
-            _task_queue.push_head(_stop_task)
+            _task_queue.push(_stop_task)
             # If stop() is called again, do nothing
             _stop_task = None
 
@@ -251,9 +272,9 @@ class Loop:
         return Loop._exc_handler
 
     def default_exception_handler(loop, context):
-        print(context["message"])
-        print("future:", context["future"], "coro=", context["future"].coro)
-        sys.print_exception(context["exception"])
+        print(context["message"], file=sys.stderr)
+        print("future:", context["future"], "coro=", context["future"].coro, file=sys.stderr)
+        sys.print_exception(context["exception"], sys.stderr)
 
     def call_exception_handler(context):
         (Loop._exc_handler or Loop.default_exception_handler)(Loop, context)

libs/micropython/asyncio/event.py

@@ -1,8 +1,9 @@
-# MicroPython uasyncio module
+# MicroPython asyncio module
 # MIT license; Copyright (c) 2019-2020 Damien P. George
 
 from . import core
 
+
 # Event class for primitive events that can be waited on, set, and cleared
 class Event:
     def __init__(self):
@@ -17,16 +18,17 @@ class Event:
         # Note: This must not be called from anything except the thread running
         # the asyncio loop (i.e. neither hard or soft IRQ, or a different thread).
         while self.waiting.peek():
-            core._task_queue.push_head(self.waiting.pop_head())
+            core._task_queue.push(self.waiting.pop())
         self.state = True
 
     def clear(self):
         self.state = False
 
-    async def wait(self):
+    # async
+    def wait(self):
         if not self.state:
             # Event not set, put the calling task on the event's waiting queue
-            self.waiting.push_head(core.cur_task)
+            self.waiting.push(core.cur_task)
             # Set calling task's data to the event's queue so it can be removed if needed
             core.cur_task.data = self.waiting
             yield
@@ -36,27 +38,29 @@ class Event:
 # MicroPython-extension: This can be set from outside the asyncio event loop,
 # such as other threads, IRQs or scheduler context. Implementation is a stream
 # that asyncio will poll until a flag is set.
-# Note: Unlike Event, this is self-clearing.
+# Note: Unlike Event, this is self-clearing after a wait().
 try:
-    import uio
+    import io
 
-    class ThreadSafeFlag(uio.IOBase):
+    class ThreadSafeFlag(io.IOBase):
         def __init__(self):
-            self._flag = 0
+            self.state = 0
 
         def ioctl(self, req, flags):
             if req == 3:  # MP_STREAM_POLL
-                return self._flag * flags
-            return None
+                return self.state * flags
+            return -1  # Other requests are unsupported
 
         def set(self):
-            self._flag = 1
+            self.state = 1
+
+        def clear(self):
+            self.state = 0
 
         async def wait(self):
-            if not self._flag:
+            if not self.state:
                 yield core._io_queue.queue_read(self)
-            self._flag = 0
-
+            self.state = 0
 
 except ImportError:
     pass

libs/micropython/asyncio/funcs.py

@@ -0,0 +1,130 @@
+# MicroPython asyncio module
+# MIT license; Copyright (c) 2019-2022 Damien P. George
+
+from . import core
+
+
+async def _run(waiter, aw):
+    try:
+        result = await aw
+        status = True
+    except BaseException as er:
+        result = None
+        status = er
+    if waiter.data is None:
+        # The waiter is still waiting, cancel it.
+        if waiter.cancel():
+            # Waiter was cancelled by us, change its CancelledError to an instance of
+            # CancelledError that contains the status and result of waiting on aw.
+            # If the wait_for task subsequently gets cancelled externally then this
+            # instance will be reset to a CancelledError instance without arguments.
+            waiter.data = core.CancelledError(status, result)
+
+
+async def wait_for(aw, timeout, sleep=core.sleep):
+    aw = core._promote_to_task(aw)
+    if timeout is None:
+        return await aw
+
+    # Run aw in a separate runner task that manages its exceptions.
+    runner_task = core.create_task(_run(core.cur_task, aw))
+
+    try:
+        # Wait for the timeout to elapse.
+        await sleep(timeout)
+    except core.CancelledError as er:
+        status = er.value
+        if status is None:
+            # This wait_for was cancelled externally, so cancel aw and re-raise.
+            runner_task.cancel()
+            raise er
+        elif status is True:
+            # aw completed successfully and cancelled the sleep, so return aw's result.
+            return er.args[1]
+        else:
+            # aw raised an exception, propagate it out to the caller.
+            raise status
+
+    # The sleep finished before aw, so cancel aw and raise TimeoutError.
+    runner_task.cancel()
+    await runner_task
+    raise core.TimeoutError
+
+
+def wait_for_ms(aw, timeout):
+    return wait_for(aw, timeout, core.sleep_ms)
+
+
+class _Remove:
+    @staticmethod
+    def remove(t):
+        pass
+
+
+# async
+def gather(*aws, return_exceptions=False):
+    if not aws:
+        return []
+
+    def done(t, er):
+        # Sub-task "t" has finished, with exception "er".
+        nonlocal state
+        if gather_task.data is not _Remove:
+            # The main gather task has already been scheduled, so do nothing.
+            # This happens if another sub-task already raised an exception and
+            # woke the main gather task (via this done function), or if the main
+            # gather task was cancelled externally.
+            return
+        elif not return_exceptions and not isinstance(er, StopIteration):
+            # A sub-task raised an exception, indicate that to the gather task.
+            state = er
+        else:
+            state -= 1
+            if state:
+                # Still some sub-tasks running.
+                return
+        # Gather waiting is done, schedule the main gather task.
+        core._task_queue.push(gather_task)
+
+    ts = [core._promote_to_task(aw) for aw in aws]
+    for i in range(len(ts)):
+        if ts[i].state is not True:
+            # Task is not running, gather not currently supported for this case.
+            raise RuntimeError("can't gather")
+        # Register the callback to call when the task is done.
+        ts[i].state = done
+
+    # Set the state for execution of the gather.
+    gather_task = core.cur_task
+    state = len(ts)
+    cancel_all = False
+
+    # Wait for the a sub-task to need attention.
+    gather_task.data = _Remove
+    try:
+        yield
+    except core.CancelledError as er:
+        cancel_all = True
+        state = er
+
+    # Clean up tasks.
+    for i in range(len(ts)):
+        if ts[i].state is done:
+            # Sub-task is still running, deregister the callback and cancel if needed.
+            ts[i].state = True
+            if cancel_all:
+                ts[i].cancel()
+        elif isinstance(ts[i].data, StopIteration):
+            # Sub-task ran to completion, get its return value.
+            ts[i] = ts[i].data.value
+        else:
+            # Sub-task had an exception with return_exceptions==True, so get its exception.
+            ts[i] = ts[i].data
+
+    # Either this gather was cancelled, or one of the sub-tasks raised an exception with
+    # return_exceptions==False, so reraise the exception here.
+    if state:
+        raise state
+
+    # Return the list of return values of each sub-task.
+    return ts