Release 1.2.0

Fixes #21

.coveragerc

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

.github/workflows/tests.yml

@@ -2,10 +2,10 @@ name: build
 on:
   push:
     branches:
-      - master
+      - main
   pull_request:
     branches:
-      - master
+      - main
 jobs:
   lint:
     name: lint
@@ -21,7 +21,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python: ['3.6', '3.7', '3.8', '3.9']
+        python: ['3.6', '3.7', '3.8', '3.9', '3.10']
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
@@ -51,3 +51,12 @@ jobs:
       - run: pip install tox tox-gh-actions codecov
       - run: tox
       - run: codecov
+  benchmark:
+    name: benchmark
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+      - 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

CHANGES.md

@@ -0,0 +1,158 @@
+# Microdot change log
+
+**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))
+- Support duplicate arguments in query string and form submissions [#21](https://github.com/miguelgrinberg/microdot/issues/21) ([commit](https://github.com/miguelgrinberg/microdot/commit/b0c25a1a7298189373be5df1668e0afb5532cdaf))
+- Merge `microdot-asyncio` package with `microdot` ([commit](https://github.com/miguelgrinberg/microdot/commit/b7b881e3c7f1c6ede6546e498737e93928425c30))
+- Added a change log ([commit](https://github.com/miguelgrinberg/microdot/commit/9955ac99a6ac20308644f02d6e6e32847d28b70c))
+- Improve project structure ([commit](https://github.com/miguelgrinberg/microdot/commit/4b101d15971fa2883d187f0bab0be999ae30b583))
+
+**Release v0.4.0** - 2021-06-04
+
+- Add HTTP method-specific route decorators ([commit](https://github.com/miguelgrinberg/microdot/commit/a3288a63ed45f700f79b67d0b57fc4dd20e844c1))
+- Server shutdown [#19](https://github.com/miguelgrinberg/microdot/issues/19) ([commit](https://github.com/miguelgrinberg/microdot/commit/0ad538df91f8b6b8a3885aa602c014ee7fe4526b))
+- Update microypthon binary for tests to 1.15 ([commit](https://github.com/miguelgrinberg/microdot/commit/3bd7fe8cea4598a7dbd0efcb9c6ce57ec2b79f9c))
+
+**Release v0.3.1** - 2021-02-06
+
+- Support large downloads in send_file [#3](https://github.com/miguelgrinberg/microdot/issues/3) ([commit](https://github.com/miguelgrinberg/microdot/commit/3e29af57753dbb7961ff98719a4fc4f71c0b4e3e))
+- Move socket import and add simple hello example [#12](https://github.com/miguelgrinberg/microdot/issues/12) ([commit](https://github.com/miguelgrinberg/microdot/commit/c5e1873523b609680ff67d7abfada72568272250)) (thanks **Damien George**!)
+- Update python versions to build ([commit](https://github.com/miguelgrinberg/microdot/commit/dfbe2edd797153fc9be40bc1928d93bdee7e7be5))
+- Handle Chrome preconnect [#8](https://github.com/miguelgrinberg/microdot/issues/8) ([commit](https://github.com/miguelgrinberg/microdot/commit/125af4b4a92b1d78acfa9d57ad2f507e759b6938)) (thanks **Ricardo Mendonça Ferreira**!)
+- Readme update ([commit](https://github.com/miguelgrinberg/microdot/commit/1aacb3cf46bd0b634ec3bc852ff9439f3c5dd773))
+- Switch to GitHub actions for builds ([commit](https://github.com/miguelgrinberg/microdot/commit/4c0afa2beca0c3b0f167fd25c6849d6937c412ba))
+
+**Release v0.3.0** - 2019-05-05
+
+- g, before_request and after_request ([commit](https://github.com/miguelgrinberg/microdot/commit/8aa50f171d2d04bc15c472ab1d9b3288518f7a21))
+- Threaded mode ([commit](https://github.com/miguelgrinberg/microdot/commit/494800ff9ff474c38644979086057e3584573969))
+- Optional asyncio support ([commit](https://github.com/miguelgrinberg/microdot/commit/3d9b5d7084d52e749553ca79206ed7060f963f9d))
+- Debug mode ([commit](https://github.com/miguelgrinberg/microdot/commit/4c83cb75636572066958ef2cc0802909deafe542))
+- Print exceptions ([commit](https://github.com/miguelgrinberg/microdot/commit/491202de1fce232b9629b7f1db63594fd13f84a3))
+- Flake8 ([commit](https://github.com/miguelgrinberg/microdot/commit/92edc17522d7490544c7186d62a2964caf35c861))
+- Unit testing framework ([commit](https://github.com/miguelgrinberg/microdot/commit/f741ed7cf83320d25ce16a1a29796af6fdfb91e9))
+- More robust header checking in tests ([commit](https://github.com/miguelgrinberg/microdot/commit/03efe46a26e7074f960dd4c9a062c53d6f72bfa0))
+- Response unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/cd71986a5042dcc308617a3db89476f28dd13ecf))
+- Request unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/0b95feafc96dc91d7d34528ff2d8931a8aa3d612))
+- More unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/76ab1fa6d72dd9deaa24aeaf4895a0c6fc883bcb))
+- Async request and response unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/89f7f09b9a2d0dfccefabebbe9b83307133bd97c))
+- More asyncio unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/ba986a89ff72ebbd9a65307b81ee769879961594))
+- Improve code structure ([commit](https://github.com/miguelgrinberg/microdot/commit/b16466f1a9432a608eb23769907e8952fe304a9a))
+- URL pattern matching unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/0a373775d54df571ceddaac090094bb62dbe6c72))
+- Rename microdot_async to microdot_asyncio ([commit](https://github.com/miguelgrinberg/microdot/commit/e5525c5c485ae8901c9602da7e4582b58fb2da40))
+
+**Release 0.2.0** - 2019-04-19
+
+- Error handlers ([commit](https://github.com/miguelgrinberg/microdot/commit/0f2c749f6d1b9edbf124523160e10449c932ea45))
+- Fleshed out example GPIO application ([commit](https://github.com/miguelgrinberg/microdot/commit/52f2d0c4918d00d1a7e46cc7fd9a909ef6d259c1))
+- More robust parsing of cookie header ([commit](https://github.com/miguelgrinberg/microdot/commit/2f58c41cc89946d51646df83d4f9ae0e24e447b9))
+
+**Release 0.1.1** - 2019-04-17
+
+- Minor fixes for micropython ([commit](https://github.com/miguelgrinberg/microdot/commit/e4ff70cf8fe839f5b5297157bf028569188b9031))
+- Initial commit ([commit](https://github.com/miguelgrinberg/microdot/commit/311a82a44430d427948866b09cb6136e60a5b1c9))

README.md

@@ -1,8 +1,25 @@
 # 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”*
 
-## Documentation
+Microdot is a minimalistic Python web framework inspired by Flask, and designed
+to run on systems with limited resources such as microcontrollers. It runs on
+standard Python and on MicroPython.
 
-Coming soon!
+```python
+from microdot import Microdot
+
+app = Microdot()
+
+@app.route('/')
+def index(request):
+    return 'Hello, world!'
+
+app.run()
+```
+
+## Resources
+
+- [Documentation](https://microdot.readthedocs.io/en/latest/)
+- [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/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/custom.css

@@ -0,0 +1,3 @@
+.py.class, .py.function, .py.method, .py.property {
+  margin-top: 20px;
+}

docs/api.rst

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

docs/conf.py

@@ -0,0 +1,71 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../src'))
+sys.path.insert(1, os.path.abspath('../libs/common'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'Microdot'
+copyright = '2021, Miguel Grinberg'
+author = 'Miguel Grinberg'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.autodoc',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+html_css_files = [
+    'css/custom.css',
+]
+
+html_theme_options = {
+    'github_user': 'miguelgrinberg',
+    'github_repo': 'microdot',
+    'github_banner': True,
+    'github_button': True,
+    'github_type': 'star',
+    'fixed_sidebar': True,
+}
+
+autodoc_default_options = {
+    'member-order': 'bysource',
+}

docs/extensions.rst

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

docs/index.rst

@@ -0,0 +1,24 @@
+.. Microdot documentation master file, created by
+   sphinx-quickstart on Fri Jun  4 17:40:19 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Microdot
+========
+
+*"The impossibly small web framework for Python and MicroPython"*
+
+Microdot is a minimalistic Python web framework inspired by
+`Flask <https://flask.palletsprojects.com/>`_, and designed to run on
+systems with limited resources such as microcontrollers. It runs on standard
+Python and on `MicroPython <https://micropython.org>`_.
+
+.. toctree::
+   :maxdepth: 3
+
+   intro
+   extensions
+   api
+
+* :ref:`genindex`
+* :ref:`search`

docs/intro.rst

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

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

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('/')
+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_async.py

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

examples/benchmark/mem_fastapi.py

@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get('/')
+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('/')
+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.txt

@@ -0,0 +1,33 @@
+aiofiles==0.8.0
+anyio==3.6.1
+blinker==1.5
+certifi==2022.6.15
+charset-normalizer==2.1.0
+click==8.1.3
+fastapi==0.79.0
+Flask==2.2.1
+gunicorn==20.1.0
+h11==0.13.0
+h2==4.1.0
+hpack==4.0.0
+humanize==4.3.0
+hypercorn==0.13.2
+hyperframe==6.0.1
+idna==3.3
+itsdangerous==2.1.2
+Jinja2==3.1.2
+MarkupSafe==2.1.1
+microdot
+priority==2.0.0
+psutil==5.9.1
+pydantic==1.9.1
+quart==0.18.0
+requests==2.28.1
+sniffio==1.2.0
+starlette==0.19.1
+toml==0.10.2
+typing_extensions==4.3.0
+urllib3==1.26.11
+uvicorn==0.18.2
+Werkzeug==2.2.1
+wsproto==1.1.0

examples/benchmark/results.txt

@@ -0,0 +1,14 @@
+❯ curl -X GET http://localhost:5000/        <-- microdot
+{"ram": 8429568}%
+❯ curl -X GET http://localhost:5000/        <-- microdot_asyncio
+{"ram": 12410880}%
+❯ curl -X GET http://localhost:8000/        <-- microdot_wsgi
+{"ram": 9101312}%
+❯ curl -X GET http://localhost:8000/        <-- microdot_asgi
+{"ram": 18620416}%
+❯ curl -X GET http://localhost:5000/        <-- flask app.run
+{"ram":25460736}
+❯ curl -X GET http://localhost:5000/        <-- flask run
+{"ram":26210304}
+❯ curl -X GET http://localhost:5000/        <-- quart run
+{"ram":31748096}%

examples/benchmark/run.py

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

examples/hello.py

@@ -1,26 +0,0 @@
-from microdot import Microdot, Response
-
-app = Microdot()
-
-htmldoc = """<!DOCTYPE html>
-<html>
-    <head>
-        <title>Microdot Example Page</title>
-    </head>
-    <body>
-        <div>
-            <h1>Microdot Example Page</h1>
-            <p>Hello from Microdot!</p>
-        </div>
-    </body>
-</html>
-"""
-
-
-@app.route("", methods=["GET", "POST"])
-def serial_number(request):
-    print(request.headers)
-    return Response(body=htmldoc, headers={"Content-Type": "text/html"})
-
-
-app.run(debug=True)

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

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

examples/hello/hello_asgi.py

@@ -0,0 +1,36 @@
+from microdot_asgi import Microdot
+
+app = Microdot()
+
+htmldoc = '''<!DOCTYPE html>
+<html>
+    <head>
+        <title>Microdot Example Page</title>
+    </head>
+    <body>
+        <div>
+            <h1>Microdot Example Page</h1>
+            <p>Hello from Microdot!</p>
+            <p><a href="/shutdown">Click to shutdown the server</a></p>
+        </div>
+    </body>
+</html>
+'''
+
+
+@app.route('/')
+async def hello(request):
+    return htmldoc, 200, {'Content-Type': 'text/html'}
+
+
+@app.route('/shutdown')
+async def shutdown(request):
+    request.app.shutdown()
+    return 'The server is shutting down...'
+
+
+if __name__ == '__main__':
+    print('''Use an ASGI web server to run this applicaton.
+Example:
+    uvicorn hello_asgi:app
+''')

examples/hello/hello_async.py

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

examples/hello/hello_jinja.py

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

examples/hello/hello_utemplate.py

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

examples/hello/hello_utemplate_async.py

@@ -0,0 +1,17 @@
+from microdot_asyncio import Microdot, Response
+from microdot_utemplate import render_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 render_template('index.html', name=name)
+
+
+if __name__ == '__main__':
+    app.run()

examples/hello/hello_wsgi.py

@@ -0,0 +1,36 @@
+from microdot_wsgi import Microdot
+
+app = Microdot()
+
+htmldoc = '''<!DOCTYPE html>
+<html>
+    <head>
+        <title>Microdot Example Page</title>
+    </head>
+    <body>
+        <div>
+            <h1>Microdot Example Page</h1>
+            <p>Hello from Microdot!</p>
+            <p><a href="/shutdown">Click to shutdown the server</a></p>
+        </div>
+    </body>
+</html>
+'''
+
+
+@app.route('/')
+def hello(request):
+    return htmldoc, 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/hello/templates/index_jinja.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot + Jinja example</title>
+  </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/hello/templates/index_utemplate.html

@@ -0,0 +1,20 @@
+{% args name %}
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot + uTemplate example</title>
+  </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/sessions/README.md

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

examples/sessions/login.py

@@ -0,0 +1,58 @@
+from microdot import Microdot, Response, redirect
+from microdot_session import set_session_secret_key, with_session, \
+    update_session, delete_session
+
+BASE_TEMPLATE = '''<!doctype html>
+<html>
+  <head>
+    <title>Microdot login example</title>
+  </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 type="text" 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()
+set_session_secret_key('top-secret')
+Response.default_content_type = 'text/html'
+
+
+@app.get('/')
+@app.post('/')
+@with_session
+def index(req, session):
+    username = session.get('username')
+    if req.method == 'POST':
+        username = req.form.get('username')
+        update_session(req, {'username': username})
+        return redirect('/')
+    if username is None:
+        return BASE_TEMPLATE.format(content=LOGGED_OUT)
+    else:
+        return BASE_TEMPLATE.format(content=LOGGED_IN.format(
+            username=username))
+
+
+@app.post('/logout')
+def logout(req):
+    delete_session(req)
+    return redirect('/')
+
+
+if __name__ == '__main__':
+    app.run()

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/static.py

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

examples/static/static/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Static File Serving Demo</title>
+  </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,45 @@
+try:
+    import utime as time
+except ImportError:
+    import time
+
+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('/')
+def index(request):
+    return '''<!doctype html>
+<html>
+  <head>
+    <title>Microdot Video Streaming</title>
+  </head>
+  <body>
+    <h1>Microdot Video Streaming</h1>
+    <img src="/video_feed">
+  </body>
+</html>''', 200, {'Content-Type': 'text/html'}
+
+
+@app.route('/video_feed')
+def video_feed(request):
+    def stream():
+        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'
+                time.sleep(1)
+
+    return stream(), 200, {'Content-Type':
+                           'multipart/x-mixed-replace; boundary=frame'}
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

examples/streaming/video_stream_async.py

@@ -0,0 +1,64 @@
+import sys
+
+try:
+    import uasyncio as asyncio
+except ImportError:
+    import asyncio
+
+from microdot_asyncio 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('/')
+def index(request):
+    return '''<!doctype html>
+<html>
+  <head>
+    <title>Microdot Video Streaming</title>
+  </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):
+    if sys.implementation.name != 'micropython':
+        # CPython supports yielding async generators
+        async def stream():
+            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)
+
+    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'
+
+    return stream(), 200, {'Content-Type':
+                           'multipart/x-mixed-replace; boundary=frame'}
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

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/echo_async_tls.py

@@ -0,0 +1,23 @@
+import ssl
+from microdot_asyncio import Microdot, send_file
+from microdot_asyncio_websocket import with_websocket
+
+app = Microdot()
+
+
+@app.route('/')
+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)
+
+
+sslctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+sslctx.load_cert_chain('cert.pem', 'key.pem')
+app.run(port=4443, debug=True, ssl=sslctx)

examples/tls/echo_tls.py

@@ -0,0 +1,24 @@
+import sys
+from microdot import Microdot, send_file
+from microdot_websocket import with_websocket
+from microdot_ssl import create_ssl_context
+
+app = Microdot()
+
+
+@app.route('/')
+def index(request):
+    return send_file('index.html')
+
+
+@app.route('/echo')
+@with_websocket
+def echo(request, ws):
+    while True:
+        data = ws.receive()
+        ws.send(data)
+
+
+ext = 'der' if sys.implementation.name == 'micropython' else 'pem'
+sslctx = create_ssl_context('cert.' + ext, 'key.' + ext)
+app.run(port=4443, debug=True, ssl=sslctx)

examples/tls/hello_async_tls.py

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

examples/tls/hello_tls.py

@@ -0,0 +1,36 @@
+import sys
+from microdot import Microdot
+from microdot_ssl import create_ssl_context
+
+app = Microdot()
+
+htmldoc = '''<!DOCTYPE html>
+<html>
+    <head>
+        <title>Microdot Example Page</title>
+    </head>
+    <body>
+        <div>
+            <h1>Microdot Example Page</h1>
+            <p>Hello from Microdot!</p>
+            <p><a href="/shutdown">Click to shutdown the server</a></p>
+        </div>
+    </body>
+</html>
+'''
+
+
+@app.route('/')
+def hello(request):
+    return htmldoc, 200, {'Content-Type': 'text/html'}
+
+
+@app.route('/shutdown')
+def shutdown(request):
+    request.app.shutdown()
+    return 'The server is shutting down...'
+
+
+ext = 'der' if sys.implementation.name == 'micropython' else 'pem'
+sslctx = create_ssl_context('cert.' + ext, 'key.' + ext)
+app.run(port=4443, debug=True, ssl=sslctx)

examples/tls/index.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot TLS WebSocket Demo</title>
+  </head>
+  <body>
+    <h1>Microdot TLS 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('wss://' + 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>

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,34 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot Upload Example</title>
+  </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,33 @@
+from microdot import Microdot, send_file
+
+app = Microdot()
+
+
+@app.get('/')
+def index(request):
+    return send_file('index.html')
+
+
+@app.post('/upload')
+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 = request.stream.read(min(size, 1024))
+            f.write(chunk)
+            size -= len(chunk)
+
+    print('Successfully saved file: ' + filename)
+    return ''
+
+
+if __name__ == '__main__':
+    app.run()

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('/')
+def index(request):
+    return send_file('index.html')
+
+
+@app.route('/echo')
+@with_websocket
+def echo(request, ws):
+    while True:
+        data = ws.receive()
+        ws.send(data)
+
+
+app.run()

examples/websocket/echo_asgi.py

@@ -0,0 +1,17 @@
+from microdot_asgi import Microdot, send_file
+from microdot_asgi_websocket import with_websocket
+
+app = Microdot()
+
+
+@app.route('/')
+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)

examples/websocket/echo_async.py

@@ -0,0 +1,20 @@
+from microdot_asyncio import Microdot, send_file
+from microdot_asyncio_websocket import with_websocket
+
+app = Microdot()
+
+
+@app.route('/')
+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_wsgi.py

@@ -0,0 +1,17 @@
+from microdot_wsgi import Microdot, send_file
+from microdot_websocket import with_websocket
+
+app = Microdot()
+
+
+@app.route('/')
+def index(request):
+    return send_file('index.html')
+
+
+@app.route('/echo')
+@with_websocket
+def echo(request, ws):
+    while True:
+        data = ws.receive()
+        ws.send(data)

examples/websocket/index.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot WebSocket Demo</title>
+  </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>

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,116 @@
+utemplate
+=========
+
+*Release: 1.4.1, Source: https://github.com/pfalcon/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/hmac.py

@@ -0,0 +1,87 @@
+# Implements the hmac module from the Python standard library.
+
+
+class HMAC:
+    def __init__(self, key, msg=None, digestmod=None):
+        if not isinstance(key, (bytes, bytearray)):
+            raise TypeError("key: expected bytes/bytearray")
+
+        import hashlib
+
+        if digestmod is None:
+            # TODO: Default hash algorithm is now deprecated.
+            digestmod = hashlib.md5
+
+        if callable(digestmod):
+            # A hashlib constructor returning a new hash object.
+            make_hash = digestmod  # A
+        elif isinstance(digestmod, str):
+            # A hash name suitable for hashlib.new().
+            make_hash = lambda d=b"": hashlib.new(digestmod, d)  # B
+        else:
+            # A module supporting PEP 247.
+            make_hash = digestmod.new  # C
+
+        self._outer = make_hash()
+        self._inner = make_hash()
+
+        self.digest_size = getattr(self._inner, "digest_size", None)
+        # If the provided hash doesn't support block_size (e.g. built-in
+        # hashlib), 64 is the correct default for all built-in hash
+        # functions (md5, sha1, sha256).
+        self.block_size = getattr(self._inner, "block_size", 64)
+
+        # Truncate to digest_size if greater than block_size.
+        if len(key) > self.block_size:
+            key = make_hash(key).digest()
+
+        # Pad to block size.
+        key = key + bytes(self.block_size - len(key))
+
+        self._outer.update(bytes(x ^ 0x5C for x in key))
+        self._inner.update(bytes(x ^ 0x36 for x in key))
+
+        if msg is not None:
+            self.update(msg)
+
+    @property
+    def name(self):
+        return "hmac-" + getattr(self._inner, "name", type(self._inner).__name__)
+
+    def update(self, msg):
+        self._inner.update(msg)
+
+    def copy(self):
+        if not hasattr(self._inner, "copy"):
+            # Not supported for built-in hash functions.
+            raise NotImplementedError()
+        # Call __new__ directly to avoid the expensive __init__.
+        other = self.__class__.__new__(self.__class__)
+        other.block_size = self.block_size
+        other.digest_size = self.digest_size
+        other._inner = self._inner.copy()
+        other._outer = self._outer.copy()
+        return other
+
+    def _current(self):
+        h = self._outer
+        if hasattr(h, "copy"):
+            # built-in hash functions don't support this, and as a result,
+            # digest() will finalise the hmac and further calls to
+            # update/digest will fail.
+            h = h.copy()
+        h.update(self._inner.digest())
+        return h
+
+    def digest(self):
+        h = self._current()
+        return h.digest()
+
+    def hexdigest(self):
+        import binascii
+
+        return str(binascii.hexlify(self.digest()), "utf-8")
+
+
+def new(key, msg=None, digestmod=None):
+    return HMAC(key, msg, digestmod)

libs/micropython/jwt.py

@@ -0,0 +1,78 @@
+import binascii
+import hashlib
+import hmac
+import json
+from time import time
+
+def _to_b64url(data):
+    return (
+        binascii.b2a_base64(data)
+        .rstrip(b"\n")
+        .rstrip(b"=")
+        .replace(b"+", b"-")
+        .replace(b"/", b"_")
+    )
+
+
+def _from_b64url(data):
+    return binascii.a2b_base64(data.replace(b"-", b"+").replace(b"_", b"/") + b"===")
+
+
+class exceptions:
+    class PyJWTError(Exception):
+        pass
+
+    class InvalidTokenError(PyJWTError):
+        pass
+
+    class InvalidAlgorithmError(PyJWTError):
+        pass
+
+    class InvalidSignatureError(PyJWTError):
+        pass
+
+    class ExpiredSignatureError(PyJWTError):
+        pass
+
+
+def encode(payload, key, algorithm="HS256"):
+    if algorithm != "HS256":
+        raise exceptions.InvalidAlgorithmError
+
+    if isinstance(key, str):
+        key = key.encode()
+    header = _to_b64url(json.dumps({"typ": "JWT", "alg": algorithm}).encode())
+    payload = _to_b64url(json.dumps(payload).encode())
+    signature = _to_b64url(hmac.new(key, header + b"." + payload, hashlib.sha256).digest())
+    return (header + b"." + payload + b"." + signature).decode()
+
+
+def decode(token, key, algorithms=["HS256"]):
+    if "HS256" not in algorithms:
+        raise exceptions.InvalidAlgorithmError
+
+    parts = token.encode().split(b".")
+    if len(parts) != 3:
+        raise exceptions.InvalidTokenError
+
+    try:
+        header = json.loads(_from_b64url(parts[0]).decode())
+        payload = json.loads(_from_b64url(parts[1]).decode())
+        signature = _from_b64url(parts[2])
+    except Exception:
+        raise exceptions.InvalidTokenError
+
+    if header["alg"] not in algorithms or header["alg"] != "HS256":
+        raise exceptions.InvalidAlgorithmError
+
+    if isinstance(key, str):
+        key = key.encode()
+    calculated_signature = hmac.new(key, parts[0] + b"." + parts[1], hashlib.sha256).digest()
+    if signature != calculated_signature:
+        raise exceptions.InvalidSignatureError
+
+    if "exp" in payload:
+        if time() > payload["exp"]:
+            raise exceptions.ExpiredSignatureError
+
+    return payload

libs/micropython/uasyncio/__init__.py

@@ -0,0 +1,30 @@
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019 Damien P. George
+
+from .core import *
+
+__version__ = (3, 0, 0)
+
+_attrs = {
+    "wait_for": "funcs",
+    "wait_for_ms": "funcs",
+    "gather": "funcs",
+    "Event": "event",
+    "ThreadSafeFlag": "event",
+    "Lock": "lock",
+    "open_connection": "stream",
+    "start_server": "stream",
+    "StreamReader": "stream",
+    "StreamWriter": "stream",
+}
+
+# Lazy loader, effectively does:
+#   global attr
+#   from .mod import attr
+def __getattr__(attr):
+    mod = _attrs.get(attr, None)
+    if mod is None:
+        raise AttributeError(attr)
+    value = getattr(__import__(mod, None, None, True, 1), attr)
+    globals()[attr] = value
+    return value

libs/micropython/uasyncio/core.py

@@ -0,0 +1,281 @@
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019 Damien P. George
+
+from time import ticks_ms as ticks, ticks_diff, ticks_add
+import sys, select
+
+# Import TaskQueue and Task, preferring built-in C code over Python code
+try:
+    from _uasyncio import TaskQueue, Task
+except:
+    from .task import TaskQueue, Task
+
+
+################################################################################
+# Exceptions
+
+
+class CancelledError(BaseException):
+    pass
+
+
+class TimeoutError(Exception):
+    pass
+
+
+# Used when calling Loop.call_exception_handler
+_exc_context = {"message": "Task exception wasn't retrieved", "exception": None, "future": None}
+
+
+################################################################################
+# Sleep functions
+
+# "Yield" once, then raise StopIteration
+class SingletonGenerator:
+    def __init__(self):
+        self.state = None
+        self.exc = StopIteration()
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        if self.state is not None:
+            _task_queue.push_sorted(cur_task, self.state)
+            self.state = None
+            return None
+        else:
+            self.exc.__traceback__ = None
+            raise self.exc
+
+
+# Pause task execution for the given time (integer in milliseconds, uPy extension)
+# Use a SingletonGenerator to do it without allocating on the heap
+def sleep_ms(t, sgen=SingletonGenerator()):
+    assert sgen.state is None
+    sgen.state = ticks_add(ticks(), max(0, t))
+    return sgen
+
+
+# Pause task execution for the given time (in seconds)
+def sleep(t):
+    return sleep_ms(int(t * 1000))
+
+
+################################################################################
+# Queue and poller for stream IO
+
+
+class IOQueue:
+    def __init__(self):
+        self.poller = select.poll()
+        self.map = {}  # maps id(stream) to [task_waiting_read, task_waiting_write, stream]
+
+    def _enqueue(self, s, idx):
+        if id(s) not in self.map:
+            entry = [None, None, s]
+            entry[idx] = cur_task
+            self.map[id(s)] = entry
+            self.poller.register(s, select.POLLIN if idx == 0 else select.POLLOUT)
+        else:
+            sm = self.map[id(s)]
+            assert sm[idx] is None
+            assert sm[1 - idx] is not None
+            sm[idx] = cur_task
+            self.poller.modify(s, select.POLLIN | select.POLLOUT)
+        # Link task to this IOQueue so it can be removed if needed
+        cur_task.data = self
+
+    def _dequeue(self, s):
+        del self.map[id(s)]
+        self.poller.unregister(s)
+
+    def queue_read(self, s):
+        self._enqueue(s, 0)
+
+    def queue_write(self, s):
+        self._enqueue(s, 1)
+
+    def remove(self, task):
+        while True:
+            del_s = None
+            for k in self.map:  # Iterate without allocating on the heap
+                q0, q1, s = self.map[k]
+                if q0 is task or q1 is task:
+                    del_s = s
+                    break
+            if del_s is not None:
+                self._dequeue(s)
+            else:
+                break
+
+    def wait_io_event(self, dt):
+        for s, ev in self.poller.ipoll(dt):
+            sm = self.map[id(s)]
+            # print('poll', s, sm, ev)
+            if ev & ~select.POLLOUT and sm[0] is not None:
+                # POLLIN or error
+                _task_queue.push_head(sm[0])
+                sm[0] = None
+            if ev & ~select.POLLIN and sm[1] is not None:
+                # POLLOUT or error
+                _task_queue.push_head(sm[1])
+                sm[1] = None
+            if sm[0] is None and sm[1] is None:
+                self._dequeue(s)
+            elif sm[0] is None:
+                self.poller.modify(s, select.POLLOUT)
+            else:
+                self.poller.modify(s, select.POLLIN)
+
+
+################################################################################
+# Main run loop
+
+# Ensure the awaitable is a task
+def _promote_to_task(aw):
+    return aw if isinstance(aw, Task) else create_task(aw)
+
+
+# Create and schedule a new task from a coroutine
+def create_task(coro):
+    if not hasattr(coro, "send"):
+        raise TypeError("coroutine expected")
+    t = Task(coro, globals())
+    _task_queue.push_head(t)
+    return t
+
+
+# Keep scheduling tasks until there are none left to schedule
+def run_until_complete(main_task=None):
+    global cur_task
+    excs_all = (CancelledError, Exception)  # To prevent heap allocation in loop
+    excs_stop = (CancelledError, StopIteration)  # To prevent heap allocation in loop
+    while True:
+        # Wait until the head of _task_queue is ready to run
+        dt = 1
+        while dt > 0:
+            dt = -1
+            t = _task_queue.peek()
+            if t:
+                # A task waiting on _task_queue; "ph_key" is time to schedule task at
+                dt = max(0, ticks_diff(t.ph_key, ticks()))
+            elif not _io_queue.map:
+                # No tasks can be woken so finished running
+                return
+            # print('(poll {})'.format(dt), len(_io_queue.map))
+            _io_queue.wait_io_event(dt)
+
+        # Get next task to run and continue it
+        t = _task_queue.pop_head()
+        cur_task = t
+        try:
+            # Continue running the coroutine, it's responsible for rescheduling itself
+            exc = t.data
+            if not exc:
+                t.coro.send(None)
+            else:
+                t.data = None
+                t.coro.throw(exc)
+        except excs_all as er:
+            # Check the task is not on any event queue
+            assert t.data is None
+            # This task is done, check if it's the main task and then loop should stop
+            if t is main_task:
+                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())
+                    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
+
+
+# Create a new task from a coroutine and run it until it finishes
+def run(coro):
+    return run_until_complete(create_task(coro))
+
+
+################################################################################
+# Event loop wrapper
+
+
+async def _stopper():
+    pass
+
+
+_stop_task = None
+
+
+class Loop:
+    _exc_handler = None
+
+    def create_task(coro):
+        return create_task(coro)
+
+    def run_forever():
+        global _stop_task
+        _stop_task = Task(_stopper(), globals())
+        run_until_complete(_stop_task)
+        # TODO should keep running until .stop() is called, even if there're no tasks left
+
+    def run_until_complete(aw):
+        return run_until_complete(_promote_to_task(aw))
+
+    def stop():
+        global _stop_task
+        if _stop_task is not None:
+            _task_queue.push_head(_stop_task)
+            # If stop() is called again, do nothing
+            _stop_task = None
+
+    def close():
+        pass
+
+    def set_exception_handler(handler):
+        Loop._exc_handler = handler
+
+    def get_exception_handler():
+        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"])
+
+    def call_exception_handler(context):
+        (Loop._exc_handler or Loop.default_exception_handler)(Loop, context)
+
+
+# The runq_len and waitq_len arguments are for legacy uasyncio compatibility
+def get_event_loop(runq_len=0, waitq_len=0):
+    return Loop
+
+
+def current_task():
+    return cur_task
+
+
+def new_event_loop():
+    global _task_queue, _io_queue
+    # TaskQueue of Task instances
+    _task_queue = TaskQueue()
+    # Task queue and poller for stream IO
+    _io_queue = IOQueue()
+    return Loop
+
+
+# Initialise default event loop
+new_event_loop()

libs/micropython/uasyncio/event.py

@@ -0,0 +1,62 @@
+# MicroPython uasyncio 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):
+        self.state = False  # False=unset; True=set
+        self.waiting = core.TaskQueue()  # Queue of Tasks waiting on completion of this event
+
+    def is_set(self):
+        return self.state
+
+    def set(self):
+        # Event becomes set, schedule any tasks waiting on it
+        # 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())
+        self.state = True
+
+    def clear(self):
+        self.state = False
+
+    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)
+            # Set calling task's data to the event's queue so it can be removed if needed
+            core.cur_task.data = self.waiting
+            yield
+        return True
+
+
+# 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.
+try:
+    import uio
+
+    class ThreadSafeFlag(uio.IOBase):
+        def __init__(self):
+            self._flag = 0
+
+        def ioctl(self, req, flags):
+            if req == 3:  # MP_STREAM_POLL
+                return self._flag * flags
+            return None
+
+        def set(self):
+            self._flag = 1
+
+        async def wait(self):
+            if not self._flag:
+                yield core._io_queue.queue_read(self)
+            self._flag = 0
+
+
+except ImportError:
+    pass

libs/micropython/uasyncio/funcs.py

@@ -0,0 +1,74 @@
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2020 Damien P. George
+
+from . import core
+
+
+async def wait_for(aw, timeout, sleep=core.sleep):
+    aw = core._promote_to_task(aw)
+    if timeout is None:
+        return await aw
+
+    def runner(waiter, aw):
+        nonlocal status, result
+        try:
+            result = await aw
+            s = True
+        except BaseException as er:
+            s = er
+        if status is None:
+            # The waiter is still waiting, set status for it and cancel it.
+            status = s
+            waiter.cancel()
+
+    # Run aw in a separate runner task that manages its exceptions.
+    status = None
+    result = None
+    runner_task = core.create_task(runner(core.cur_task, aw))
+
+    try:
+        # Wait for the timeout to elapse.
+        await sleep(timeout)
+    except core.CancelledError as er:
+        if status is True:
+            # aw completed successfully and cancelled the sleep, so return aw's result.
+            return result
+        elif status is None:
+            # This wait_for was cancelled externally, so cancel aw and re-raise.
+            status = True
+            runner_task.cancel()
+            raise er
+        else:
+            # aw raised an exception, propagate it out to the caller.
+            raise status
+
+    # The sleep finished before aw, so cancel aw and raise TimeoutError.
+    status = True
+    runner_task.cancel()
+    await runner_task
+    raise core.TimeoutError
+
+
+def wait_for_ms(aw, timeout):
+    return wait_for(aw, timeout, core.sleep_ms)
+
+
+async def gather(*aws, return_exceptions=False):
+    ts = [core._promote_to_task(aw) for aw in aws]
+    for i in range(len(ts)):
+        try:
+            # TODO handle cancel of gather itself
+            # if ts[i].coro:
+            #    iter(ts[i]).waiting.push_head(cur_task)
+            #    try:
+            #        yield
+            #    except CancelledError as er:
+            #        # cancel all waiting tasks
+            #        raise er
+            ts[i] = await ts[i]
+        except Exception as er:
+            if return_exceptions:
+                ts[i] = er
+            else:
+                raise er
+    return ts

libs/micropython/uasyncio/lock.py

@@ -0,0 +1,53 @@
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2020 Damien P. George
+
+from . import core
+
+# Lock class for primitive mutex capability
+class Lock:
+    def __init__(self):
+        # The state can take the following values:
+        # - 0: unlocked
+        # - 1: locked
+        # - <Task>: unlocked but this task has been scheduled to acquire the lock next
+        self.state = 0
+        # Queue of Tasks waiting to acquire this Lock
+        self.waiting = core.TaskQueue()
+
+    def locked(self):
+        return self.state == 1
+
+    def release(self):
+        if self.state != 1:
+            raise RuntimeError("Lock not acquired")
+        if self.waiting.peek():
+            # Task(s) waiting on lock, schedule next Task
+            self.state = self.waiting.pop_head()
+            core._task_queue.push_head(self.state)
+        else:
+            # No Task waiting so unlock
+            self.state = 0
+
+    async def acquire(self):
+        if self.state != 0:
+            # Lock unavailable, put the calling Task on the waiting queue
+            self.waiting.push_head(core.cur_task)
+            # Set calling task's data to the lock's queue so it can be removed if needed
+            core.cur_task.data = self.waiting
+            try:
+                yield
+            except core.CancelledError as er:
+                if self.state == core.cur_task:
+                    # Cancelled while pending on resume, schedule next waiting Task
+                    self.state = 1
+                    self.release()
+                raise er
+        # Lock available, set it as locked
+        self.state = 1
+        return True
+
+    async def __aenter__(self):
+        return await self.acquire()
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return self.release()

libs/micropython/uasyncio/manifest.py

@@ -0,0 +1,13 @@
+# This list of frozen files doesn't include task.py because that's provided by the C module.
+freeze(
+    "..",
+    (
+        "uasyncio/__init__.py",
+        "uasyncio/core.py",
+        "uasyncio/event.py",
+        "uasyncio/funcs.py",
+        "uasyncio/lock.py",
+        "uasyncio/stream.py",
+    ),
+    opt=3,
+)

libs/micropython/uasyncio/stream.py

@@ -0,0 +1,158 @@
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2020 Damien P. George
+
+from . import core
+
+
+class Stream:
+    def __init__(self, s, e={}):
+        self.s = s
+        self.e = e
+        self.out_buf = b""
+
+    def get_extra_info(self, v):
+        return self.e[v]
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        await self.close()
+
+    def close(self):
+        pass
+
+    async def wait_closed(self):
+        # TODO yield?
+        self.s.close()
+
+    async def read(self, n):
+        yield core._io_queue.queue_read(self.s)
+        return self.s.read(n)
+
+    async def readexactly(self, n):
+        r = b""
+        while n:
+            yield core._io_queue.queue_read(self.s)
+            r2 = self.s.read(n)
+            if r2 is not None:
+                if not len(r2):
+                    raise EOFError
+                r += r2
+                n -= len(r2)
+        return r
+
+    async def readline(self):
+        l = b""
+        while True:
+            yield core._io_queue.queue_read(self.s)
+            l2 = self.s.readline()  # may do multiple reads but won't block
+            l += l2
+            if not l2 or l[-1] == 10:  # \n (check l in case l2 is str)
+                return l
+
+    def write(self, buf):
+        self.out_buf += buf
+
+    async def drain(self):
+        mv = memoryview(self.out_buf)
+        off = 0
+        while off < len(mv):
+            yield core._io_queue.queue_write(self.s)
+            ret = self.s.write(mv[off:])
+            if ret is not None:
+                off += ret
+        self.out_buf = b""
+
+
+# Stream can be used for both reading and writing to save code size
+StreamReader = Stream
+StreamWriter = Stream
+
+
+# Create a TCP stream connection to a remote host
+async def open_connection(host, port):
+    from uerrno import EINPROGRESS
+    import usocket as socket
+
+    ai = socket.getaddrinfo(host, port)[0]  # TODO this is blocking!
+    s = socket.socket()
+    s.setblocking(False)
+    ss = Stream(s)
+    try:
+        s.connect(ai[-1])
+    except OSError as er:
+        if er.errno != EINPROGRESS:
+            raise er
+    yield core._io_queue.queue_write(s)
+    return ss, ss
+
+
+# Class representing a TCP stream server, can be closed and used in "async with"
+class Server:
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        self.close()
+        await self.wait_closed()
+
+    def close(self):
+        self.task.cancel()
+
+    async def wait_closed(self):
+        await self.task
+
+    async def _serve(self, cb, host, port, backlog):
+        import usocket as socket
+
+        ai = socket.getaddrinfo(host, port)[0]  # TODO this is blocking!
+        s = socket.socket()
+        s.setblocking(False)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind(ai[-1])
+        s.listen(backlog)
+        self.task = core.cur_task
+        # Accept incoming connections
+        while True:
+            try:
+                yield core._io_queue.queue_read(s)
+            except core.CancelledError:
+                # Shutdown server
+                s.close()
+                return
+            try:
+                s2, addr = s.accept()
+            except:
+                # Ignore a failed accept
+                continue
+            s2.setblocking(False)
+            s2s = Stream(s2, {"peername": addr})
+            core.create_task(cb(s2s, s2s))
+
+
+# Helper function to start a TCP stream server, running as a new task
+# TODO could use an accept-callback on socket read activity instead of creating a task
+async def start_server(cb, host, port, backlog=5):
+    s = Server()
+    core.create_task(s._serve(cb, host, port, backlog))
+    return s
+
+
+################################################################################
+# Legacy uasyncio compatibility
+
+
+async def stream_awrite(self, buf, off=0, sz=-1):
+    if off != 0 or sz != -1:
+        buf = memoryview(buf)
+        if sz == -1:
+            sz = len(buf)
+        buf = buf[off : off + sz]
+    self.write(buf)
+    await self.drain()
+
+
+Stream.aclose = Stream.wait_closed
+Stream.awrite = stream_awrite
+Stream.awritestr = stream_awrite  # TODO explicitly convert to bytes?

libs/micropython/uasyncio/task.py

@@ -0,0 +1,184 @@
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2020 Damien P. George
+
+# This file contains the core TaskQueue based on a pairing heap, and the core Task class.
+# They can optionally be replaced by C implementations.
+
+from . import core
+
+
+# pairing-heap meld of 2 heaps; O(1)
+def ph_meld(h1, h2):
+    if h1 is None:
+        return h2
+    if h2 is None:
+        return h1
+    lt = core.ticks_diff(h1.ph_key, h2.ph_key) < 0
+    if lt:
+        if h1.ph_child is None:
+            h1.ph_child = h2
+        else:
+            h1.ph_child_last.ph_next = h2
+        h1.ph_child_last = h2
+        h2.ph_next = None
+        h2.ph_rightmost_parent = h1
+        return h1
+    else:
+        h1.ph_next = h2.ph_child
+        h2.ph_child = h1
+        if h1.ph_next is None:
+            h2.ph_child_last = h1
+            h1.ph_rightmost_parent = h2
+        return h2
+
+
+# pairing-heap pairing operation; amortised O(log N)
+def ph_pairing(child):
+    heap = None
+    while child is not None:
+        n1 = child
+        child = child.ph_next
+        n1.ph_next = None
+        if child is not None:
+            n2 = child
+            child = child.ph_next
+            n2.ph_next = None
+            n1 = ph_meld(n1, n2)
+        heap = ph_meld(heap, n1)
+    return heap
+
+
+# pairing-heap delete of a node; stable, amortised O(log N)
+def ph_delete(heap, node):
+    if node is heap:
+        child = heap.ph_child
+        node.ph_child = None
+        return ph_pairing(child)
+    # Find parent of node
+    parent = node
+    while parent.ph_next is not None:
+        parent = parent.ph_next
+    parent = parent.ph_rightmost_parent
+    # Replace node with pairing of its children
+    if node is parent.ph_child and node.ph_child is None:
+        parent.ph_child = node.ph_next
+        node.ph_next = None
+        return heap
+    elif node is parent.ph_child:
+        child = node.ph_child
+        next = node.ph_next
+        node.ph_child = None
+        node.ph_next = None
+        node = ph_pairing(child)
+        parent.ph_child = node
+    else:
+        n = parent.ph_child
+        while node is not n.ph_next:
+            n = n.ph_next
+        child = node.ph_child
+        next = node.ph_next
+        node.ph_child = None
+        node.ph_next = None
+        node = ph_pairing(child)
+        if node is None:
+            node = n
+        else:
+            n.ph_next = node
+    node.ph_next = next
+    if next is None:
+        node.ph_rightmost_parent = parent
+        parent.ph_child_last = node
+    return heap
+
+
+# TaskQueue class based on the above pairing-heap functions.
+class TaskQueue:
+    def __init__(self):
+        self.heap = None
+
+    def peek(self):
+        return self.heap
+
+    def push_sorted(self, v, key):
+        v.data = None
+        v.ph_key = key
+        v.ph_child = None
+        v.ph_next = None
+        self.heap = ph_meld(v, self.heap)
+
+    def push_head(self, v):
+        self.push_sorted(v, core.ticks())
+
+    def pop_head(self):
+        v = self.heap
+        self.heap = ph_pairing(self.heap.ph_child)
+        return v
+
+    def remove(self, v):
+        self.heap = ph_delete(self.heap, v)
+
+
+# Task class representing a coroutine, can be waited on and cancelled.
+class Task:
+    def __init__(self, coro, globals=None):
+        self.coro = coro  # Coroutine of this Task
+        self.data = None  # General data for queue it is waiting on
+        self.ph_key = 0  # Pairing heap
+        self.ph_child = None  # Paring heap
+        self.ph_child_last = None  # Paring heap
+        self.ph_next = None  # Paring heap
+        self.ph_rightmost_parent = None  # Paring heap
+
+    def __iter__(self):
+        if self.coro is self:
+            # Signal that the completed-task has been await'ed on.
+            self.waiting = None
+        elif not hasattr(self, "waiting"):
+            # Lazily allocated head of linked list of Tasks waiting on completion of this task.
+            self.waiting = TaskQueue()
+        return self
+
+    def __next__(self):
+        if self.coro is self:
+            # Task finished, raise return value to caller so it can continue.
+            raise self.data
+        else:
+            # Put calling task on waiting queue.
+            self.waiting.push_head(core.cur_task)
+            # Set calling task's data to this task that it waits on, to double-link it.
+            core.cur_task.data = self
+
+    def done(self):
+        return self.coro is self
+
+    def cancel(self):
+        # Check if task is already finished.
+        if self.coro is self:
+            return False
+        # Can't cancel self (not supported yet).
+        if self is core.cur_task:
+            raise RuntimeError("can't cancel self")
+        # If Task waits on another task then forward the cancel to the one it's waiting on.
+        while isinstance(self.data, Task):
+            self = self.data
+        # Reschedule Task as a cancelled task.
+        if hasattr(self.data, "remove"):
+            # Not on the main running queue, remove the task from the queue it's on.
+            self.data.remove(self)
+            core._task_queue.push_head(self)
+        elif core.ticks_diff(self.ph_key, core.ticks()) > 0:
+            # On the main running queue but scheduled in the future, so bring it forward to now.
+            core._task_queue.remove(self)
+            core._task_queue.push_head(self)
+        self.data = core.CancelledError
+        return True
+
+    def throw(self, value):
+        # This task raised an exception which was uncaught; handle that now.
+        # Set the data because it was cleared by the main scheduling loop.
+        self.data = value
+        if not hasattr(self, "waiting"):
+            # Nothing await'ed on the task so call the exception handler.
+            core._exc_context["exception"] = value
+            core._exc_context["future"] = self
+            core.Loop.call_exception_handler(core._exc_context)

microdot-asyncio/microdot_asyncio.py

@@ -1,166 +0,0 @@
-try:
-    import uasyncio as asyncio
-except ImportError:
-    import asyncio
-from microdot import Microdot as BaseMicrodot
-from microdot import print_exception
-from microdot import Request as BaseRequest
-from microdot import Response as BaseResponse
-
-
-def _iscoroutine(coro):
-    return hasattr(coro, 'send') and hasattr(coro, 'throw')
-
-
-class Request(BaseRequest):
-    @staticmethod
-    async def create(stream, client_addr):
-        # request line
-        line = (await stream.readline()).strip().decode()
-        if not line:  # pragma: no cover
-            return None
-        method, url, http_version = line.split()
-        http_version = http_version.split('/', 1)[1]
-
-        # headers
-        headers = {}
-        content_length = 0
-        while True:
-            line = (await stream.readline()).strip().decode()
-            if line == '':
-                break
-            header, value = line.split(':', 1)
-            value = value.strip()
-            headers[header] = value
-            if header == 'Content-Length':
-                content_length = int(value)
-
-        # body
-        body = await stream.read(content_length) \
-            if content_length else b''
-
-        return Request(client_addr, method, url, http_version, headers, body)
-
-
-class Response(BaseResponse):
-    async def write(self, stream):
-        self.complete()
-
-        # status code
-        await stream.awrite('HTTP/1.0 {status_code} {reason}\r\n'.format(
-            status_code=self.status_code,
-            reason='OK' if self.status_code == 200 else 'N/A').encode())
-
-        # headers
-        for header, value in self.headers.items():
-            values = value if isinstance(value, list) else [value]
-            for value in values:
-                await stream.awrite('{header}: {value}\r\n'.format(
-                    header=header, value=value).encode())
-        await stream.awrite(b'\r\n')
-
-        # body
-        if self.body:
-            if hasattr(self.body, 'read'):
-                while True:
-                    buf = self.body.read(self.send_file_buffer_size)
-                    if len(buf):
-                        await stream.awrite(buf)
-                    if len(buf) < self.send_file_buffer_size:
-                        break
-                if hasattr(self.body, 'close'):
-                    self.body.close()
-            else:
-                await stream.awrite(self.body)
-
-
-class Microdot(BaseMicrodot):
-    def run(self, host='0.0.0.0', port=5000, debug=False):
-        self.debug = debug
-
-        async def serve(reader, writer):
-            if not hasattr(writer, 'awrite'):  # pragma: no cover
-                # CPython provides the awrite and aclose methods in 3.8+
-                async def awrite(self, data):
-                    self.write(data)
-                    await self.drain()
-
-                async def aclose(self):
-                    self.close()
-                    await self.wait_closed()
-
-                from types import MethodType
-                writer.awrite = MethodType(awrite, writer)
-                writer.aclose = MethodType(aclose, writer)
-
-            await self.dispatch_request(reader, writer)
-
-        if self.debug:  # pragma: no cover
-            print('Starting async server on {host}:{port}...'.format(
-                host=host, port=port))
-        loop = asyncio.get_event_loop()
-        loop.run_until_complete(asyncio.start_server(serve, host, port))
-        loop.run_forever()
-        loop.close()  # pragma: no cover
-
-    async def dispatch_request(self, reader, writer):
-        req = await Request.create(reader, writer.get_extra_info('peername'))
-        if req:
-            f = self.find_route(req)
-            try:
-                res = None
-                if f:
-                    for handler in self.before_request_handlers:
-                        res = await self._invoke_handler(handler, req)
-                        if res:
-                            break
-                    if res is None:
-                        res = await self._invoke_handler(
-                            f, req, **req.url_args)
-                    if isinstance(res, tuple):
-                        res = Response(*res)
-                    elif not isinstance(res, Response):
-                        res = Response(res)
-                    for handler in self.after_request_handlers:
-                        res = await self._invoke_handler(
-                            handler, req, res) or res
-                elif 404 in self.error_handlers:
-                    res = await self._invoke_handler(
-                        self.error_handlers[404], req)
-                else:
-                    res = 'Not found', 404
-            except Exception as exc:
-                print_exception(exc)
-                res = None
-                if exc.__class__ in self.error_handlers:
-                    try:
-                        res = await self._invoke_handler(
-                            self.error_handlers[exc.__class__], req, exc)
-                    except Exception as exc2:  # pragma: no cover
-                        print_exception(exc2)
-                if res is None:
-                    if 500 in self.error_handlers:
-                        res = await self._invoke_handler(
-                            self.error_handlers[500], req)
-                    else:
-                        res = 'Internal server error', 500
-            if isinstance(res, tuple):
-                res = Response(*res)
-            elif not isinstance(res, Response):
-                res = Response(res)
-            await res.write(writer)
-        await writer.aclose()
-        if self.debug and req:  # pragma: no cover
-            print('{method} {path} {status_code}'.format(
-                method=req.method, path=req.path,
-                status_code=res.status_code))
-
-    async def _invoke_handler(self, f_or_coro, *args, **kwargs):
-        ret = f_or_coro(*args, **kwargs)
-        if _iscoroutine(ret):
-            ret = await ret
-        return ret
-
-
-redirect = Response.redirect
-send_file = Response.send_file

microdot-asyncio/setup.py

@@ -1,35 +0,0 @@
-"""
-Microdot-AsyncIO
-----------------
-
-AsyncIO support for the Microdot web framework.
-"""
-from setuptools import setup
-
-setup(
-    name='microdot-asyncio',
-    version="0.3.1",
-    url='http://github.com/miguelgrinberg/microdot/',
-    license='MIT',
-    author='Miguel Grinberg',
-    author_email='miguel.grinberg@gmail.com',
-    description='AsyncIO support for the Microdot web framework',
-    long_description=__doc__,
-    py_modules=['microdot_asyncio'],
-    platforms='any',
-    install_requires=[
-        'microdot',
-        'micropython-uasyncio;implementation_name=="micropython"'
-    ],
-    classifiers=[
-        'Environment :: Web Environment',
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: MIT License',
-        'Operating System :: OS Independent',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: Implementation :: MicroPython',
-        'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
-        'Topic :: Software Development :: Libraries :: Python Modules'
-    ]
-)

microdot/microdot.py

@@ -1,416 +0,0 @@
-try:
-    from sys import print_exception
-except ImportError:  # pragma: no cover
-    import traceback
-
-    def print_exception(exc):
-        traceback.print_exc()
-
-concurrency_mode = 'threaded'
-
-try:  # pragma: no cover
-    import threading
-
-    def create_thread(f, *args, **kwargs):
-        """Use the threading module."""
-        threading.Thread(target=f, args=args, kwargs=kwargs).start()
-except ImportError:  # pragma: no cover
-    try:
-        import _thread
-
-        def create_thread(f, *args, **kwargs):
-            """Use MicroPython's _thread module."""
-            def run():
-                f(*args, **kwargs)
-
-            _thread.start_new_thread(run, ())
-    except ImportError:
-        def create_thread(f, *args, **kwargs):
-            """No threads available, call function synchronously."""
-            f(*args, **kwargs)
-
-        concurrency_mode = 'sync'
-try:
-    import ujson as json
-except ImportError:
-    import json
-
-try:
-    import ure as re
-except ImportError:
-    import re
-
-try:
-    import usocket as socket
-except ImportError:
-    try:
-        import socket
-    except ImportError:  # pragma: no cover
-        socket = None
-
-
-def urldecode(string):
-    string = string.replace('+', ' ')
-    parts = string.split('%')
-    if len(parts) == 1:
-        return string
-    result = [parts[0]]
-    for item in parts[1:]:
-        if item == '':
-            result.append('%')
-        else:
-            code = item[:2]
-            result.append(chr(int(code, 16)))
-            result.append(item[2:])
-    return ''.join(result)
-
-
-class Request():
-    class G:
-        pass
-
-    def __init__(self, client_addr, method, url, http_version, headers, body):
-        self.client_addr = client_addr
-        self.method = method
-        self.path = url
-        self.http_version = http_version
-        if '?' in self.path:
-            self.path, self.query_string = self.path.split('?', 1)
-            self.args = self._parse_urlencoded(self.query_string)
-        else:
-            self.query_string = None
-            self.args = {}
-        self.headers = headers
-        self.cookies = {}
-        self.content_length = 0
-        self.content_type = None
-        for header, value in self.headers.items():
-            if header == 'Content-Length':
-                self.content_length = int(value)
-            elif header == 'Content-Type':
-                self.content_type = value
-            elif header == 'Cookie':
-                for cookie in value.split(';'):
-                    name, value = cookie.strip().split('=', 1)
-                    self.cookies[name] = value
-        self.body = body
-        self._json = None
-        self._form = None
-        self.g = Request.G()
-
-    @staticmethod
-    def create(client_stream, client_addr):
-        # request line
-        line = client_stream.readline().strip().decode()
-        if not line:  # pragma: no cover
-            return None
-        method, url, http_version = line.split()
-        http_version = http_version.split('/', 1)[1]
-
-        # headers
-        headers = {}
-        content_length = 0
-        while True:
-            line = client_stream.readline().strip().decode()
-            if line == '':
-                break
-            header, value = line.split(':', 1)
-            value = value.strip()
-            headers[header] = value
-            if header == 'Content-Length':
-                content_length = int(value)
-
-        # body
-        body = client_stream.read(content_length) if content_length else b''
-
-        return Request(client_addr, method, url, http_version, headers, body)
-
-    def _parse_urlencoded(self, urlencoded):
-        return {
-            urldecode(key): urldecode(value) for key, value in [
-                pair.split('=', 1) for pair in
-                urlencoded.split('&')]}
-
-    @property
-    def json(self):
-        if self.content_type != 'application/json':
-            return None
-        if self._json is None:
-            self._json = json.loads(self.body.decode())
-        return self._json
-
-    @property
-    def form(self):
-        if self.content_type != 'application/x-www-form-urlencoded':
-            return None
-        if self._form is None:
-            self._form = self._parse_urlencoded(self.body.decode())
-        return self._form
-
-
-class Response():
-    types_map = {
-        'css': 'text/css',
-        'gif': 'image/gif',
-        'html': 'text/html',
-        'jpg': 'image/jpeg',
-        'js': 'application/javascript',
-        'json': 'application/json',
-        'png': 'image/png',
-        'txt': 'text/plain',
-    }
-    send_file_buffer_size = 1024
-
-    def __init__(self, body='', status_code=200, headers=None):
-        self.status_code = status_code
-        self.headers = headers or {}
-        if isinstance(body, (dict, list)):
-            self.body = json.dumps(body).encode()
-            self.headers['Content-Type'] = 'application/json'
-        elif isinstance(body, str):
-            self.body = body.encode()
-        else:
-            # this applies to bytes or file-like objects
-            self.body = body
-
-    def set_cookie(self, cookie, value, path=None, domain=None, expires=None,
-                   max_age=None, secure=False, http_only=False):
-        http_cookie = '{cookie}={value}'.format(cookie=cookie, value=value)
-        if path:
-            http_cookie += '; Path=' + path
-        if domain:
-            http_cookie += '; Domain=' + domain
-        if expires:
-            http_cookie += '; Expires=' + expires.strftime(
-                "%a, %d %b %Y %H:%M:%S GMT")
-        if max_age:
-            http_cookie += '; Max-Age=' + str(max_age)
-        if secure:
-            http_cookie += '; Secure'
-        if http_only:
-            http_cookie += '; HttpOnly'
-        if 'Set-Cookie' in self.headers:
-            self.headers['Set-Cookie'].append(http_cookie)
-        else:
-            self.headers['Set-Cookie'] = [http_cookie]
-
-    def complete(self):
-        if isinstance(self.body, bytes) and \
-                'Content-Length' not in self.headers:
-            self.headers['Content-Length'] = str(len(self.body))
-        if 'Content-Type' not in self.headers:
-            self.headers['Content-Type'] = 'text/plain'
-
-    def write(self, stream):
-        self.complete()
-
-        # status code
-        stream.write('HTTP/1.0 {status_code} {reason}\r\n'.format(
-            status_code=self.status_code,
-            reason='OK' if self.status_code == 200 else 'N/A').encode())
-
-        # headers
-        for header, value in self.headers.items():
-            values = value if isinstance(value, list) else [value]
-            for value in values:
-                stream.write('{header}: {value}\r\n'.format(
-                    header=header, value=value).encode())
-        stream.write(b'\r\n')
-
-        # body
-        if self.body:
-            if hasattr(self.body, 'read'):
-                while True:
-                    buf = self.body.read(self.send_file_buffer_size)
-                    if len(buf):
-                        stream.write(buf)
-                    if len(buf) < self.send_file_buffer_size:
-                        break
-                if hasattr(self.body, 'close'):
-                    self.body.close()
-            else:
-                stream.write(self.body)
-
-    @classmethod
-    def redirect(cls, location, status_code=302):
-        return cls(status_code=status_code, headers={'Location': location})
-
-    @classmethod
-    def send_file(cls, filename, status_code=200, content_type=None):
-        if content_type is None:
-            ext = filename.split('.')[-1]
-            if ext in Response.types_map:
-                content_type = Response.types_map[ext]
-            else:
-                content_type = 'application/octet-stream'
-        f = open(filename, 'rb')
-        return cls(body=f, status_code=status_code,
-                   headers={'Content-Type': content_type})
-
-
-class URLPattern():
-    def __init__(self, url_pattern):
-        self.pattern = ''
-        self.args = []
-        use_regex = False
-        for segment in url_pattern.lstrip('/').split('/'):
-            if segment and segment[0] == '<':
-                if segment[-1] != '>':
-                    raise ValueError('invalid URL pattern')
-                segment = segment[1:-1]
-                if ':' in segment:
-                    type_, name = segment.rsplit(':', 1)
-                else:
-                    type_ = 'string'
-                    name = segment
-                if type_ == 'string':
-                    pattern = '[^/]+'
-                elif type_ == 'int':
-                    pattern = '\\d+'
-                elif type_ == 'path':
-                    pattern = '.+'
-                elif type_.startswith('re:'):
-                    pattern = type_[3:]
-                else:
-                    raise ValueError('invalid URL segment type')
-                use_regex = True
-                self.pattern += '/({pattern})'.format(pattern=pattern)
-                self.args.append({'type': type_, 'name': name})
-            else:
-                self.pattern += '/{segment}'.format(segment=segment)
-        if use_regex:
-            self.pattern = re.compile('^' + self.pattern + '$')
-
-    def match(self, path):
-        if isinstance(self.pattern, str):
-            if path != self.pattern:
-                return
-            return {}
-        g = self.pattern.match(path)
-        if not g:
-            return
-        args = {}
-        i = 1
-        for arg in self.args:
-            value = g.group(i)
-            if arg['type'] == 'int':
-                value = int(value)
-            args[arg['name']] = value
-            i += 1
-        return args
-
-
-class Microdot():
-    def __init__(self):
-        self.url_map = []
-        self.before_request_handlers = []
-        self.after_request_handlers = []
-        self.error_handlers = {}
-        self.debug = False
-
-    def route(self, url_pattern, methods=None):
-        def decorated(f):
-            self.url_map.append(
-                (methods or ['GET'], URLPattern(url_pattern), f))
-            return f
-        return decorated
-
-    def before_request(self, f):
-        self.before_request_handlers.append(f)
-        return f
-
-    def after_request(self, f):
-        self.after_request_handlers.append(f)
-        return f
-
-    def errorhandler(self, status_code_or_exception_class):
-        def decorated(f):
-            self.error_handlers[status_code_or_exception_class] = f
-            return f
-        return decorated
-
-    def run(self, host='0.0.0.0', port=5000, debug=False):
-        self.debug = debug
-
-        s = socket.socket()
-        ai = socket.getaddrinfo(host, port)
-        addr = ai[0][-1]
-
-        if self.debug:  # pragma: no cover
-            print('Starting {mode} server on {host}:{port}...'.format(
-                mode=concurrency_mode, host=host, port=port))
-        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-        s.bind(addr)
-        s.listen(5)
-
-        while True:
-            sock, addr = s.accept()
-            create_thread(self.dispatch_request, sock, addr)
-
-    def find_route(self, req):
-        f = None
-        for route_methods, route_pattern, route_handler in self.url_map:
-            if req.method in route_methods:
-                req.url_args = route_pattern.match(req.path)
-                if req.url_args is not None:
-                    f = route_handler
-                    break
-        return f
-
-    def dispatch_request(self, sock, addr):
-        if not hasattr(sock, 'readline'):  # pragma: no cover
-            stream = sock.makefile("rwb")
-        else:
-            stream = sock
-
-        req = Request.create(stream, addr)
-        if req:
-            f = self.find_route(req)
-            try:
-                res = None
-                if f:
-                    for handler in self.before_request_handlers:
-                        res = handler(req)
-                        if res:
-                            break
-                    if res is None:
-                        res = f(req, **req.url_args)
-                    if isinstance(res, tuple):
-                        res = Response(*res)
-                    elif not isinstance(res, Response):
-                        res = Response(res)
-                    for handler in self.after_request_handlers:
-                        res = handler(req, res) or res
-                elif 404 in self.error_handlers:
-                    res = self.error_handlers[404](req)
-                else:
-                    res = 'Not found', 404
-            except Exception as exc:
-                print_exception(exc)
-                res = None
-                if exc.__class__ in self.error_handlers:
-                    try:
-                        res = self.error_handlers[exc.__class__](req, exc)
-                    except Exception as exc2:  # pragma: no cover
-                        print_exception(exc2)
-                if res is None:
-                    if 500 in self.error_handlers:
-                        res = self.error_handlers[500](req)
-                    else:
-                        res = 'Internal server error', 500
-            if isinstance(res, tuple):
-                res = Response(*res)
-            elif not isinstance(res, Response):
-                res = Response(res)
-            res.write(stream)
-        stream.close()
-        if stream != sock:  # pragma: no cover
-            sock.close()
-        if self.debug and req:  # pragma: no cover
-            print('{method} {path} {status_code}'.format(
-                method=req.method, path=req.path,
-                status_code=res.status_code))
-
-
-redirect = Response.redirect
-send_file = Response.send_file

microdot/setup.py

@@ -1,31 +0,0 @@
-"""
-Microdot
---------
-
-The impossibly small web framework for MicroPython.
-"""
-from setuptools import setup
-
-setup(
-    name='microdot',
-    version="0.3.1",
-    url='http://github.com/miguelgrinberg/microdot/',
-    license='MIT',
-    author='Miguel Grinberg',
-    author_email='miguel.grinberg@gmail.com',
-    description='The impossibly small web framework for MicroPython',
-    long_description=__doc__,
-    py_modules=['microdot'],
-    platforms='any',
-    classifiers=[
-        'Environment :: Web Environment',
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: MIT License',
-        'Operating System :: OS Independent',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: Implementation :: MicroPython',
-        'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
-        'Topic :: Software Development :: Libraries :: Python Modules'
-    ]
-)

pyproject.toml

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

run_tests.py

@@ -1,8 +1,8 @@
 import sys
 
-sys.path.insert(0, 'microdot')
-sys.path.insert(1, 'microdot-asyncio')
-sys.path.insert(2, 'tests/libs')
+sys.path.insert(0, 'src')
+sys.path.insert(2, 'libs/common')
+sys.path.insert(3, 'libs/micropython')
 
 import unittest
 

setup.cfg

@@ -0,0 +1,38 @@
+[metadata]
+name = microdot
+version = 1.2.0
+author = Miguel Grinberg
+author_email = miguel.grinberg@gmail.com
+description = The impossibly small web framework for MicroPython
+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
+package_dir =
+    = src
+py_modules =
+    microdot
+    microdot_asyncio
+    microdot_utemplate
+    microdot_jinja
+    microdot_session
+    microdot_websocket
+    microdot_websocket_alt
+    microdot_asyncio_websocket
+    microdot_test_client
+    microdot_asyncio_test_client
+    microdot_wsgi
+    microdot_asgi
+    microdot_asgi_websocket

setup.py

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

src/microdot_asgi.py

@@ -0,0 +1,152 @@
+import asyncio
+import os
+import signal
+from microdot_asyncio import *  # noqa: F401, F403
+from microdot_asyncio import Microdot as BaseMicrodot
+from microdot_asyncio import Request
+from microdot import NoCaseDict
+
+
+class _BodyStream:  # pragma: no cover
+    def __init__(self, receive):
+        self.receive = receive
+        self.data = b''
+        self.more = True
+
+    async def read_more(self):
+        if self.more:
+            packet = await self.receive()
+            self.data += packet.get('body', b'')
+            self.more = packet.get('more_body', False)
+
+    async def read(self, n=-1):
+        while self.more and len(self.data) < n:
+            self.read_more()
+        if len(self.data) < n:
+            data = self.data
+            self.data = b''
+            return data
+
+        data = self.data[:n]
+        self.data = self.data[n:]
+        return data
+
+    async def readline(self):
+        return self.readuntil()
+
+    async def readexactly(self, n):
+        return self.read(n)
+
+    async def readuntil(self, separator=b'\n'):
+        if self.more and separator not in self.data:
+            self.read_more()
+        data, self.data = self.data.split(separator, 1)
+        return data
+
+
+class Microdot(BaseMicrodot):
+    def __init__(self):
+        super().__init__()
+        self.embedded_server = False
+
+    async def asgi_app(self, scope, receive, send):
+        """An ASGI application."""
+        if scope['type'] not in ['http', 'websocket']:  # pragma: no cover
+            return
+        path = scope['path']
+        if 'query_string' in scope and scope['query_string']:
+            path += '?' + scope['query_string'].decode()
+        headers = NoCaseDict()
+        content_length = 0
+        for key, value in scope.get('headers', []):
+            headers[key] = value
+            if key.lower() == 'content-length':
+                content_length = int(value)
+
+        if content_length and content_length <= Request.max_body_length:
+            body = b''
+            more = True
+            while more:
+                packet = await receive()
+                body += packet.get('body', b'')
+                more = packet.get('more_body', False)
+            stream = None
+        else:
+            body = b''
+            stream = _BodyStream(receive)
+
+        req = Request(
+            self,
+            (scope['client'][0], scope['client'][1]),
+            scope.get('method', 'GET'),
+            path,
+            'HTTP/' + scope['http_version'],
+            headers,
+            body=body,
+            stream=stream,
+            sock=(receive, send))
+        req.asgi_scope = scope
+
+        res = await self.dispatch_request(req)
+        res.complete()
+
+        header_list = []
+        for name, value in res.headers.items():
+            if not isinstance(value, list):
+                header_list.append((name, value))
+            else:
+                for v in value:
+                    header_list.append((name, v))
+
+        if scope['type'] != 'http':  # pragma: no cover
+            return
+
+        await send({'type': 'http.response.start',
+                    'status': res.status_code,
+                    'headers': header_list})
+
+        cancelled = False
+
+        async def cancel_monitor():
+            nonlocal cancelled
+
+            while True:
+                event = await receive()
+                if event['type'] == 'http.disconnect':  # pragma: no branch
+                    cancelled = True
+                    break
+
+        asyncio.ensure_future(cancel_monitor())
+
+        body_iter = res.body_iter().__aiter__()
+        try:
+            body = await body_iter.__anext__()
+            while not cancelled:  # pragma: no branch
+                next_body = await body_iter.__anext__()
+                await send({'type': 'http.response.body',
+                            'body': body,
+                            'more_body': True})
+                body = next_body
+        except StopAsyncIteration:
+            await send({'type': 'http.response.body',
+                        'body': body,
+                        'more_body': False})
+
+    async def __call__(self, scope, receive, send):
+        return await self.asgi_app(scope, receive, send)
+
+    def shutdown(self):
+        if self.embedded_server:  # pragma: no cover
+            super().shutdown()
+        else:
+            pid = os.getpgrp() if hasattr(os, 'getpgrp') else os.getpid()
+            os.kill(pid, signal.SIGTERM)
+
+    def run(self, host='0.0.0.0', port=5000, debug=False,
+            **options):  # pragma: no cover
+        """Normally you would not start the server by invoking this method.
+        Instead, start your chosen ASGI web server and pass the ``Microdot``
+        instance as the ASGI application.
+        """
+        self.embedded_server = True
+        super().run(host=host, port=port, debug=debug, **options)

src/microdot_asgi_websocket.py

@@ -0,0 +1,86 @@
+from microdot_asyncio import Response, abort
+from microdot_websocket import WebSocket as BaseWebSocket
+
+
+class WebSocket(BaseWebSocket):
+    async def handshake(self):
+        connect = await self.request.sock[0]()
+        if connect['type'] != 'websocket.connect':
+            abort(400)
+        await self.request.sock[1]({'type': 'websocket.accept'})
+
+    async def receive(self):
+        message = await self.request.sock[0]()
+        if message['type'] == 'websocket.disconnect':
+            raise OSError(32, 'Websocket connection closed')
+        elif message['type'] != 'websocket.receive':
+            raise OSError(32, 'Websocket message type not supported')
+        return message.get('bytes', message.get('text'))
+
+    async def send(self, data):
+        if isinstance(data, str):
+            await self.request.sock[1](
+                {'type': 'websocket.send', 'text': data})
+        else:
+            await self.request.sock[1](
+                {'type': 'websocket.send', 'bytes': data})
+
+    async def close(self):
+        if not self.closed:
+            self.closed = True
+            try:
+                await self.request.sock[1]({'type': 'websocket.close'})
+            except:  # noqa E722
+                pass
+
+
+async def websocket_upgrade(request):
+    """Upgrade a request handler to a websocket connection.
+
+    This function can be called directly inside a route function to process a
+    WebSocket upgrade handshake, for example after the user's credentials are
+    verified. The function returns the websocket object::
+
+        @app.route('/echo')
+        async def echo(request):
+            if not (await authenticate_user(request)):
+                abort(401)
+            ws = await websocket_upgrade(request)
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
+    """
+    ws = WebSocket(request)
+    await ws.handshake()
+
+    @request.after_request
+    async def after_request(request, response):
+        return Response.already_handled
+
+    return ws
+
+
+def with_websocket(f):
+    """Decorator to make a route a WebSocket endpoint.
+
+    This decorator is used to define a route that accepts websocket
+    connections. The route then receives a websocket object as a second
+    argument that it can use to send and receive messages::
+
+        @app.route('/echo')
+        @with_websocket
+        async def echo(request, ws):
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
+    """
+    async def wrapper(request, *args, **kwargs):
+        ws = await websocket_upgrade(request)
+        try:
+            await f(request, ws, *args, **kwargs)
+        except OSError as exc:
+            if exc.errno != 32 and exc.errno != 54:
+                raise
+        await ws.close()
+        return ''
+    return wrapper

src/microdot_asyncio.py

@@ -0,0 +1,430 @@
+"""
+microdot_asyncio
+----------------
+
+The ``microdot_asyncio`` module defines a few classes that help implement
+HTTP-based servers for MicroPython and standard Python that use ``asyncio``
+and coroutines.
+"""
+try:
+    import uasyncio as asyncio
+except ImportError:
+    import asyncio
+
+try:
+    import uio as io
+except ImportError:
+    import io
+
+from microdot import Microdot as BaseMicrodot
+from microdot import NoCaseDict
+from microdot import Request as BaseRequest
+from microdot import Response as BaseResponse
+from microdot import print_exception
+from microdot import HTTPException
+from microdot import MUTED_SOCKET_ERRORS
+
+
+def _iscoroutine(coro):
+    return hasattr(coro, 'send') and hasattr(coro, 'throw')
+
+
+class _AsyncBytesIO:
+    def __init__(self, data):
+        self.stream = io.BytesIO(data)
+
+    async def read(self, n=-1):
+        return self.stream.read(n)
+
+    async def readline(self):  # pragma: no cover
+        return self.stream.readline()
+
+    async def readexactly(self, n):  # pragma: no cover
+        return self.stream.read(n)
+
+    async def readuntil(self, separator=b'\n'):  # pragma: no cover
+        return self.stream.readuntil(separator=separator)
+
+    async def awrite(self, data):  # pragma: no cover
+        return self.stream.write(data)
+
+    async def aclose(self):  # pragma: no cover
+        pass
+
+
+class Request(BaseRequest):
+    @staticmethod
+    async def create(app, client_reader, client_writer, client_addr):
+        """Create a request object.
+
+        :param app: The Microdot application instance.
+        :param client_reader: An input stream from where the request data can
+                              be read.
+        :param client_writer: An output stream where the response data can be
+                              written.
+        :param client_addr: The address of the client, as a tuple.
+
+        This method is a coroutine. It returns a newly created ``Request``
+        object.
+        """
+        # request line
+        line = (await Request._safe_readline(client_reader)).strip().decode()
+        if not line:
+            return None
+        method, url, http_version = line.split()
+        http_version = http_version.split('/', 1)[1]
+
+        # headers
+        headers = NoCaseDict()
+        content_length = 0
+        while True:
+            line = (await Request._safe_readline(
+                client_reader)).strip().decode()
+            if line == '':
+                break
+            header, value = line.split(':', 1)
+            value = value.strip()
+            headers[header] = value
+            if header.lower() == 'content-length':
+                content_length = int(value)
+
+        # body
+        body = b''
+        if content_length and content_length <= Request.max_body_length:
+            body = await client_reader.readexactly(content_length)
+            stream = None
+        else:
+            body = b''
+            stream = client_reader
+
+        return Request(app, client_addr, method, url, http_version, headers,
+                       body=body, stream=stream,
+                       sock=(client_reader, client_writer))
+
+    @property
+    def stream(self):
+        if self._stream is None:
+            self._stream = _AsyncBytesIO(self._body)
+        return self._stream
+
+    @staticmethod
+    async def _safe_readline(stream):
+        line = (await stream.readline())
+        if len(line) > Request.max_readline:
+            raise ValueError('line too long')
+        return line
+
+
+class Response(BaseResponse):
+    """An HTTP response class.
+
+    :param body: The body of the response. If a dictionary or list is given,
+                 a JSON formatter is used to generate the body. If a file-like
+                 object or an async generator is given, a streaming response is
+                 used. If a string is given, it is encoded from UTF-8. Else,
+                 the body should be a byte sequence.
+    :param status_code: The numeric HTTP status code of the response. The
+                        default is 200.
+    :param headers: A dictionary of headers to include in the response.
+    :param reason: A custom reason phrase to add after the status code. The
+                   default is "OK" for responses with a 200 status code and
+                   "N/A" for any other status codes.
+    """
+
+    async def write(self, stream):
+        self.complete()
+
+        try:
+            # status code
+            reason = self.reason if self.reason is not None else \
+                ('OK' if self.status_code == 200 else 'N/A')
+            await stream.awrite('HTTP/1.0 {status_code} {reason}\r\n'.format(
+                status_code=self.status_code, reason=reason).encode())
+
+            # headers
+            for header, value in self.headers.items():
+                values = value if isinstance(value, list) else [value]
+                for value in values:
+                    await stream.awrite('{header}: {value}\r\n'.format(
+                        header=header, value=value).encode())
+            await stream.awrite(b'\r\n')
+
+            # body
+            async for body in self.body_iter():
+                if isinstance(body, str):  # pragma: no cover
+                    body = body.encode()
+                await stream.awrite(body)
+        except OSError as exc:  # pragma: no cover
+            if exc.errno in MUTED_SOCKET_ERRORS or \
+                    exc.args[0] == 'Connection lost':
+                pass
+            else:
+                raise
+
+    def body_iter(self):
+        if hasattr(self.body, '__anext__'):
+            # response body is an async generator
+            return self.body
+
+        response = self
+
+        class iter:
+            def __aiter__(self):
+                if response.body:
+                    self.i = 0  # need to determine type of response.body
+                else:
+                    self.i = -1  # no response body
+                return self
+
+            async def __anext__(self):
+                if self.i == -1:
+                    raise StopAsyncIteration
+                if self.i == 0:
+                    if hasattr(response.body, 'read'):
+                        self.i = 2  # response body is a file-like object
+                    elif hasattr(response.body, '__next__'):
+                        self.i = 1  # response body is a sync generator
+                        return next(response.body)
+                    else:
+                        self.i = -1  # response body is a plain string
+                        return response.body
+                elif self.i == 1:
+                    try:
+                        return next(response.body)
+                    except StopIteration:
+                        raise StopAsyncIteration
+                buf = response.body.read(response.send_file_buffer_size)
+                if _iscoroutine(buf):  # pragma: no cover
+                    buf = await buf
+                if len(buf) < response.send_file_buffer_size:
+                    self.i = -1
+                    if hasattr(response.body, 'close'):  # pragma: no cover
+                        result = response.body.close()
+                        if _iscoroutine(result):
+                            await result
+                return buf
+
+        return iter()
+
+
+class Microdot(BaseMicrodot):
+    async def start_server(self, host='0.0.0.0', port=5000, debug=False,
+                           ssl=None):
+        """Start the Microdot web server as a coroutine. This coroutine does
+        not normally return, as the server enters an endless listening loop.
+        The :func:`shutdown` function provides a method for terminating the
+        server gracefully.
+
+        :param host: The hostname or IP address of the network interface that
+                     will be listening for requests. A value of ``'0.0.0.0'``
+                     (the default) indicates that the server should listen for
+                     requests on all the available interfaces, and a value of
+                     ``127.0.0.1`` indicates that the server should listen
+                     for requests only on the internal networking interface of
+                     the host.
+        :param port: The port number to listen for requests. The default is
+                     port 5000.
+        :param debug: If ``True``, the server logs debugging information. The
+                      default is ``False``.
+        :param ssl: An ``SSLContext`` instance or ``None`` if the server should
+                    not use TLS. The default is ``None``.
+
+        This method is a coroutine.
+
+        Example::
+
+            import asyncio
+            from microdot_asyncio import Microdot
+
+            app = Microdot()
+
+            @app.route('/')
+            async def index():
+                return 'Hello, world!'
+
+            async def main():
+                await app.start_server(debug=True)
+
+            asyncio.run(main())
+        """
+        self.debug = debug
+
+        async def serve(reader, writer):
+            if not hasattr(writer, 'awrite'):  # pragma: no cover
+                # CPython provides the awrite and aclose methods in 3.8+
+                async def awrite(self, data):
+                    self.write(data)
+                    await self.drain()
+
+                async def aclose(self):
+                    self.close()
+                    await self.wait_closed()
+
+                from types import MethodType
+                writer.awrite = MethodType(awrite, writer)
+                writer.aclose = MethodType(aclose, writer)
+
+            await self.handle_request(reader, writer)
+
+        if self.debug:  # pragma: no cover
+            print('Starting async server on {host}:{port}...'.format(
+                host=host, port=port))
+
+        try:
+            self.server = await asyncio.start_server(serve, host, port,
+                                                     ssl=ssl)
+        except TypeError:
+            self.server = await asyncio.start_server(serve, host, port)
+
+        while True:
+            try:
+                await self.server.wait_closed()
+                break
+            except AttributeError:  # pragma: no cover
+                # the task hasn't been initialized in the server object yet
+                # wait a bit and try again
+                await asyncio.sleep(0.1)
+
+    def run(self, host='0.0.0.0', port=5000, debug=False, ssl=None):
+        """Start the web server. This function does not normally return, as
+        the server enters an endless listening loop. The :func:`shutdown`
+        function provides a method for terminating the server gracefully.
+
+        :param host: The hostname or IP address of the network interface that
+                     will be listening for requests. A value of ``'0.0.0.0'``
+                     (the default) indicates that the server should listen for
+                     requests on all the available interfaces, and a value of
+                     ``127.0.0.1`` indicates that the server should listen
+                     for requests only on the internal networking interface of
+                     the host.
+        :param port: The port number to listen for requests. The default is
+                     port 5000.
+        :param debug: If ``True``, the server logs debugging information. The
+                      default is ``False``.
+        :param ssl: An ``SSLContext`` instance or ``None`` if the server should
+                    not use TLS. The default is ``None``.
+
+        Example::
+
+            from microdot_asyncio import Microdot
+
+            app = Microdot()
+
+            @app.route('/')
+            async def index():
+                return 'Hello, world!'
+
+            app.run(debug=True)
+        """
+        asyncio.run(self.start_server(host=host, port=port, debug=debug,
+                                      ssl=ssl))
+
+    def shutdown(self):
+        self.server.close()
+
+    async def handle_request(self, reader, writer):
+        req = None
+        try:
+            req = await Request.create(self, reader, writer,
+                                       writer.get_extra_info('peername'))
+        except Exception as exc:  # pragma: no cover
+            print_exception(exc)
+
+        res = await self.dispatch_request(req)
+        if res != Response.already_handled:  # pragma: no branch
+            await res.write(writer)
+        try:
+            await writer.aclose()
+        except OSError as exc:  # pragma: no cover
+            if exc.errno in MUTED_SOCKET_ERRORS:
+                pass
+            else:
+                raise
+        if self.debug and req:  # pragma: no cover
+            print('{method} {path} {status_code}'.format(
+                method=req.method, path=req.path,
+                status_code=res.status_code))
+
+    async def dispatch_request(self, req):
+        if req:
+            if req.content_length > req.max_content_length:
+                if 413 in self.error_handlers:
+                    res = await self._invoke_handler(
+                        self.error_handlers[413], req)
+                else:
+                    res = 'Payload too large', 413
+            else:
+                f = self.find_route(req)
+                try:
+                    res = None
+                    if callable(f):
+                        for handler in self.before_request_handlers:
+                            res = await self._invoke_handler(handler, req)
+                            if res:
+                                break
+                        if res is None:
+                            res = await self._invoke_handler(
+                                f, req, **req.url_args)
+                        if isinstance(res, tuple):
+                            body = res[0]
+                            if isinstance(res[1], int):
+                                status_code = res[1]
+                                headers = res[2] if len(res) > 2 else {}
+                            else:
+                                status_code = 200
+                                headers = res[1]
+                            res = Response(body, status_code, headers)
+                        elif not isinstance(res, Response):
+                            res = Response(res)
+                        for handler in self.after_request_handlers:
+                            res = await self._invoke_handler(
+                                handler, req, res) or res
+                        for handler in req.after_request_handlers:
+                            res = await handler(req, res) or res
+                    elif f in self.error_handlers:
+                        res = await self._invoke_handler(
+                            self.error_handlers[f], req)
+                    else:
+                        res = 'Not found', f
+                except HTTPException as exc:
+                    if exc.status_code in self.error_handlers:
+                        res = self.error_handlers[exc.status_code](req)
+                    else:
+                        res = exc.reason, exc.status_code
+                except Exception as exc:
+                    print_exception(exc)
+                    res = None
+                    if exc.__class__ in self.error_handlers:
+                        try:
+                            res = await self._invoke_handler(
+                                self.error_handlers[exc.__class__], req, exc)
+                        except Exception as exc2:  # pragma: no cover
+                            print_exception(exc2)
+                    if res is None:
+                        if 500 in self.error_handlers:
+                            res = await self._invoke_handler(
+                                self.error_handlers[500], req)
+                        else:
+                            res = 'Internal server error', 500
+        else:
+            if 400 in self.error_handlers:
+                res = await self._invoke_handler(self.error_handlers[400], req)
+            else:
+                res = 'Bad request', 400
+        if isinstance(res, tuple):
+            res = Response(*res)
+        elif not isinstance(res, Response):
+            res = Response(res)
+        return res
+
+    async def _invoke_handler(self, f_or_coro, *args, **kwargs):
+        ret = f_or_coro(*args, **kwargs)
+        if _iscoroutine(ret):
+            ret = await ret
+        return ret
+
+
+abort = Microdot.abort
+Response.already_handled = Response()
+redirect = Response.redirect
+send_file = Response.send_file

src/microdot_asyncio_test_client.py

@@ -0,0 +1,208 @@
+from microdot_asyncio import Request, Response, _AsyncBytesIO
+from microdot_test_client import TestClient as BaseTestClient, \
+    TestResponse as BaseTestResponse
+try:
+    from microdot_asyncio_websocket import WebSocket
+except:  # pragma: no cover  # noqa: E722
+    WebSocket = None
+
+
+class TestResponse(BaseTestResponse):
+    """A response object issued by the Microdot test client."""
+
+    @classmethod
+    async def create(cls, res):
+        test_res = cls()
+        test_res._initialize_response(res)
+        await test_res._initialize_body(res)
+        test_res._process_text_body()
+        test_res._process_json_body()
+        return test_res
+
+    async def _initialize_body(self, res):
+        self.body = b''
+        async for body in res.body_iter():  # pragma: no branch
+            if isinstance(body, str):
+                body = body.encode()
+            self.body += body
+
+
+class TestClient(BaseTestClient):
+    """A test client for Microdot's Asynchronous web server.
+
+    :param app: The Microdot application instance.
+    :param cookies: A dictionary of cookies to use when sending requests to the
+                    application.
+
+    The following example shows how to create a test client for an application
+    and send a test request::
+
+        from microdot_asyncio import Microdot
+
+        app = Microdot()
+
+        @app.get('/')
+        async def index():
+            return 'Hello, World!'
+
+        async def test_hello_world(self):
+            client = TestClient(app)
+            res = await client.get('/')
+            assert res.status_code == 200
+            assert res.text == 'Hello, World!'
+    """
+    async def request(self, method, path, headers=None, body=None, sock=None):
+        headers = headers or {}
+        body, headers = self._process_body(body, headers)
+        cookies, headers = self._process_cookies(headers)
+        request_bytes = self._render_request(method, path, headers, body)
+        if sock:
+            reader = sock[0]
+            reader.buffer = request_bytes
+            writer = sock[1]
+        else:
+            reader = _AsyncBytesIO(request_bytes)
+            writer = _AsyncBytesIO(b'')
+
+        req = await Request.create(self.app, reader, writer,
+                                   ('127.0.0.1', 1234))
+        res = await self.app.dispatch_request(req)
+        if res == Response.already_handled:
+            return None
+        res.complete()
+
+        self._update_cookies(res)
+        return await TestResponse.create(res)
+
+    async def get(self, path, headers=None):
+        """Send a GET request to the application.
+
+        :param path: The request URL.
+        :param headers: A dictionary of headers to send with the request.
+
+        This method returns a
+        :class:`TestResponse <microdot_test_client.TestResponse>` object.
+        """
+        return await self.request('GET', path, headers=headers)
+
+    async def post(self, path, headers=None, body=None):
+        """Send a POST request to the application.
+
+        :param path: The request URL.
+        :param headers: A dictionary of headers to send with the request.
+        :param body: The request body. If a dictionary or list is provided,
+                     a JSON-encoded body will be sent. A string body is encoded
+                     to bytes as UTF-8. A bytes body is sent as-is.
+
+        This method returns a
+        :class:`TestResponse <microdot_test_client.TestResponse>` object.
+        """
+        return await self.request('POST', path, headers=headers, body=body)
+
+    async def put(self, path, headers=None, body=None):
+        """Send a PUT request to the application.
+
+        :param path: The request URL.
+        :param headers: A dictionary of headers to send with the request.
+        :param body: The request body. If a dictionary or list is provided,
+                     a JSON-encoded body will be sent. A string body is encoded
+                     to bytes as UTF-8. A bytes body is sent as-is.
+
+        This method returns a
+        :class:`TestResponse <microdot_test_client.TestResponse>` object.
+        """
+        return await self.request('PUT', path, headers=headers, body=body)
+
+    async def patch(self, path, headers=None, body=None):
+        """Send a PATCH request to the application.
+
+        :param path: The request URL.
+        :param headers: A dictionary of headers to send with the request.
+        :param body: The request body. If a dictionary or list is provided,
+                     a JSON-encoded body will be sent. A string body is encoded
+                     to bytes as UTF-8. A bytes body is sent as-is.
+
+        This method returns a
+        :class:`TestResponse <microdot_test_client.TestResponse>` object.
+        """
+        return await self.request('PATCH', path, headers=headers, body=body)
+
+    async def delete(self, path, headers=None):
+        """Send a DELETE request to the application.
+
+        :param path: The request URL.
+        :param headers: A dictionary of headers to send with the request.
+
+        This method returns a
+        :class:`TestResponse <microdot_test_client.TestResponse>` object.
+        """
+        return await self.request('DELETE', path, headers=headers)
+
+    async def websocket(self, path, client, headers=None):
+        """Send a websocket connection request to the application.
+
+        :param path: The request URL.
+        :param client: A generator function that yields client messages.
+        :param headers: A dictionary of headers to send with the request.
+        """
+        gen = client()
+
+        class FakeWebSocket:
+            def __init__(self):
+                self.started = False
+                self.closed = False
+                self.buffer = b''
+
+            async def _next(self, data=None):
+                try:
+                    data = (await gen.asend(data)) if hasattr(gen, 'asend') \
+                        else gen.send(data)
+                except (StopIteration, StopAsyncIteration):
+                    if not self.closed:
+                        self.closed = True
+                        raise OSError(32, 'Websocket connection closed')
+                    return  # pragma: no cover
+                opcode = WebSocket.TEXT if isinstance(data, str) \
+                    else WebSocket.BINARY
+                return WebSocket._encode_websocket_frame(opcode, data)
+
+            async def read(self, n):
+                if not self.buffer:
+                    self.started = True
+                    self.buffer = await self._next()
+                data = self.buffer[:n]
+                self.buffer = self.buffer[n:]
+                return data
+
+            async def readexactly(self, n):  # pragma: no cover
+                return await self.read(n)
+
+            async def readline(self):
+                line = b''
+                while True:
+                    line += await self.read(1)
+                    if line[-1] in [b'\n', 10]:
+                        break
+                return line
+
+            async def awrite(self, data):
+                if self.started:
+                    h = WebSocket._parse_frame_header(data[0:2])
+                    if h[3] < 0:
+                        data = data[2 - h[3]:]
+                    else:
+                        data = data[2:]
+                    if h[1] == WebSocket.TEXT:
+                        data = data.decode()
+                    self.buffer = await self._next(data)
+
+        ws_headers = {
+            'Upgrade': 'websocket',
+            'Connection': 'Upgrade',
+            'Sec-WebSocket-Version': '13',
+            'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',
+        }
+        ws_headers.update(headers or {})
+        sock = FakeWebSocket()
+        return await self.request('GET', path, headers=ws_headers,
+                                  sock=(sock, sock))