Release 2.3.4

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

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

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

.coveragerc

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

.flake8

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

.github/FUNDING.yml

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

.github/workflows/tests.yml

@@ -16,12 +16,13 @@ jobs:
       - run: python -m pip install --upgrade pip wheel
       - run: pip install tox tox-gh-actions
       - run: tox -eflake8
+      - run: tox -edocs
   tests:
     name: tests
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python: ['3.7', '3.8', '3.9', '3.10', '3.11']
+        python: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
@@ -41,6 +42,15 @@ jobs:
       - run: python -m pip install --upgrade pip wheel
       - run: pip install tox tox-gh-actions
       - run: tox -eupy
+  tests-circuitpython:
+    name: tests-circuitpython
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - run: python -m pip install --upgrade pip wheel
+      - run: pip install tox tox-gh-actions
+      - run: tox -ecpy
   coverage:
     name: coverage
     runs-on: ubuntu-latest
@@ -54,6 +64,7 @@ jobs:
         with:
           files: ./coverage.xml
           fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}
   benchmark:
     name: benchmark
     runs-on: ubuntu-latest

.gitignore

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

CHANGES.md

@@ -1,5 +1,118 @@
 # Microdot change log
 
+**Release 2.3.4** - 2025-10-16
+
+- Prevent reading past EOF in multipart parser [#309](https://github.com/miguelgrinberg/microdot/issues/309) ([commit](https://github.com/miguelgrinberg/microdot/commit/6045390cef8735cbbc9f5f7eee7a3912f00e284d))
+- Generate a valid CORS response when the request is badly formatted [#305](https://github.com/miguelgrinberg/microdot/issues/305) ([commit](https://github.com/miguelgrinberg/microdot/commit/cca0b0f693c909134bc19eb41dfb5a86226e032b))
+- Faster HTTP streaming when using ASGI [#318](https://github.com/miguelgrinberg/microdot/issues/318) ([commit](https://github.com/miguelgrinberg/microdot/commit/7addcf4bb51f1caf57663c5bb4d8cc16ee6391e1))
+- Parse empty cookies [#308](https://github.com/miguelgrinberg/microdot/issues/308) ([commit](https://github.com/miguelgrinberg/microdot/commit/c12d4658091ff7eec1ac67c83bcd51eb38af9db7))
+- Add weather dashboard example [#303](https://github.com/miguelgrinberg/microdot/issues/303) ([commit](https://github.com/miguelgrinberg/microdot/commit/7071358b1f95892b1342226b43411e036be67d3a))
+- Add Python 3.13 and 3.14 to the CI builds ([commit](https://github.com/miguelgrinberg/microdot/commit/e9c9937b41e652876241307307f3e855f4f07379))
+
+**Release 2.3.3** - 2025-07-01
+
+- Handle partial reads in WebSocket class [#294](https://github.com/miguelgrinberg/microdot/issues/294) ([commit](https://github.com/miguelgrinberg/microdot/commit/9bc3dced6c1f582dde0496961d25170b448ad8d7))
+- Add SVG to supported mimetypes [#302](https://github.com/miguelgrinberg/microdot/issues/302) ([commit](https://github.com/miguelgrinberg/microdot/commit/1d419ce59bf7006617109c05dc2d6fc6d1dc8235)) (thanks **Ozuba**!)
+- Do not silence exceptions that occur in the SSE task ([commit](https://github.com/miguelgrinberg/microdot/commit/654a85f46b7dd7a1e94f81193c4a78a8a1e99936))
+- Add Support for SSE responses in the test client ([commit](https://github.com/miguelgrinberg/microdot/commit/f5d3d931edfbacedebf5fdf938ef77c5ee910380))
+- Documentation improvements for the `Request` class ([commit](https://github.com/miguelgrinberg/microdot/commit/3dffa05ffb229813156b71e10a85283bdaa26d5e))
+- Additional documentation for the `URLPattern` class ([commit](https://github.com/miguelgrinberg/microdot/commit/786e5e533748e1343612c97123773aec9a1a99fc))
+- More detailed documentation for route responses ([commit](https://github.com/miguelgrinberg/microdot/commit/dc61470fa959549bb43313906ba6ed9f686babc2))
+- Additional documentation on WebSocket and SSE disconnections ([commit](https://github.com/miguelgrinberg/microdot/commit/7c98c4589de4774a88381b393444c75094532550))
+- More detailed documentation for `current_user` ([commit](https://github.com/miguelgrinberg/microdot/commit/e146e2d08deddf9b924c7657f04db28d71f34221))
+- Add a sub-application example ([commit](https://github.com/miguelgrinberg/microdot/commit/d7a9c535639268e415714b12ac898ae38e516308))
+
+**Release 2.3.2** - 2025-05-08
+
+- Use async error handlers in auth module [#298](https://github.com/miguelgrinberg/microdot/issues/298) ([commit](https://github.com/miguelgrinberg/microdot/commit/d9d7ff0825e4c5fbed6564d3684374bf3937df11))
+
+**Release 2.3.1** - 2025-04-13
+
+- Additional support needed when using `orjson` ([commit](https://github.com/miguelgrinberg/microdot/commit/cd0b3234ddb0c8ff4861d369836ec2aed77494db))
+
+**Release 2.3.0** - 2025-04-12
+
+- Support optional authentication methods ([commit](https://github.com/miguelgrinberg/microdot/commit/f317b15bdbf924007e5e3414e0c626baccc3ede6))
+- Catch SSL exceptions while writing the response [#206](https://github.com/miguelgrinberg/microdot/issues/206) ([commit](https://github.com/miguelgrinberg/microdot/commit/e7ee74d6bba74cfd89b9ddc38f28e02514eb1791))
+- Use `orjson` instead of `json` if available ([commit](https://github.com/miguelgrinberg/microdot/commit/086f2af3deab86d4340f3f1feb9e019de59f351d))
+- Addressed typing warnings from pyright ([commit](https://github.com/miguelgrinberg/microdot/commit/b6f232db1125045d79c444c736a2ae59c5501fdd))
+
+**Release 2.2.0** - 2025-03-22
+
+- Support for `multipart/form-data` requests [#287](https://github.com/miguelgrinberg/microdot/issues/287) ([commit](https://github.com/miguelgrinberg/microdot/commit/11a91a60350518e426b557fae8dffe75912f8823))
+- Support custom path components in URLs ([commit #1](https://github.com/miguelgrinberg/microdot/commit/c92b5ae28222af5a1094f5d2f70a45d4d17653d5) [commit #2](https://github.com/miguelgrinberg/microdot/commit/aa76e6378b37faab52008a8aab8db75f81b29323))
+- Expose the Jinja environment as `Template.jinja_env` ([commit](https://github.com/miguelgrinberg/microdot/commit/953dd9432122defe943f0637bbe7e01f2fc7743f))
+- Simplified urldecode logic ([commit #1](https://github.com/miguelgrinberg/microdot/commit/3bc31f10b2b2d4460c62366013278d87665f0f97) [commit #2](https://github.com/miguelgrinberg/microdot/commit/d203df75fef32c7cc0fe7cc6525e77522b37a289))
+- Additional urldecode tests ([commit](https://github.com/miguelgrinberg/microdot/commit/99f65c0198590c0dfb402c24685b6f8dfba1935d))
+- Documentation improvements ([commit](https://github.com/miguelgrinberg/microdot/commit/c6b99b6d8117d4e40e16d5b953dbf4deb023d24d))
+- Update micropython version used in tests to 1.24.1 ([commit](https://github.com/miguelgrinberg/microdot/commit/4cc2e95338a7de3b03742389004147ee21285621))
+
+**Release 2.1.0** - 2025-02-04
+
+- User login support ([commit](https://github.com/miguelgrinberg/microdot/commit/d807011ad006e53e70c4594d7eac04d03bb08681))
+- Basic and token authentication support ([commit](https://github.com/miguelgrinberg/microdot/commit/675c9787974da926af446974cd96ef224e0ee27f))
+- Added `local` argument to the `app.mount()` method, to define sub-application specific before and after request handlers ([commit](https://github.com/miguelgrinberg/microdot/commit/fd7931e1aec173c60f81dad18c1a102ed8f0e081))
+- Added `Request.url_prefix`, `Request.subapp` and local mounts ([commit](https://github.com/miguelgrinberg/microdot/commit/fd7931e1aec173c60f81dad18c1a102ed8f0e081))
+- Added a front end to the SSE example [#281](https://github.com/miguelgrinberg/microdot/issues/281) ([commit](https://github.com/miguelgrinberg/microdot/commit/d487a73c1ea5b3467e23907618b348ca52e0235c)) (thanks **Maxi**!)
+- Additional ``app.mount()`` unit tests ([commit](https://github.com/miguelgrinberg/microdot/commit/cd87abba30206ec6d3928e0aabacb2fccf7baf70))
+
+**Release 2.0.7** - 2024-11-10
+
+- Accept responses with just a status code [#263](https://github.com/miguelgrinberg/microdot/issues/263) ([commit #1](https://github.com/miguelgrinberg/microdot/commit/4eac013087f807cafa244b8a6b7b0ed4c82ff150) [commit #2](https://github.com/miguelgrinberg/microdot/commit/c46e4291061046f1be13f300dd08645b71c16635))
+- Fixed compressed file content-type assignment [#251](https://github.com/miguelgrinberg/microdot/issues/251) ([commit](https://github.com/miguelgrinberg/microdot/commit/482ab6d5ca068d71ea6301f45918946161e9fcc1)) (thanks **Lukas Kremla**!)
+- Better documentation for start_server[#252](https://github.com/miguelgrinberg/microdot/issues/252) ([commit](https://github.com/miguelgrinberg/microdot/commit/0a021462e0c42c249d587a2d600f5a21a408adfc))
+- Fix URLs in documentation [#253](https://github.com/miguelgrinberg/microdot/issues/253) ([commit](https://github.com/miguelgrinberg/microdot/commit/5e5fc5e93e11cbf6e3dc8036494e8732d1815d3e)) (thanks **Stanislav Garanzha**!)
+
+**Release 2.0.6** - 2024-06-18
+
+- Add event ID to the SSE implementation [#213](https://github.com/miguelgrinberg/microdot/issues/213) ([commit](https://github.com/miguelgrinberg/microdot/commit/904d5fcaa2d19d939a719b8e68c4dee3eb470739)) (thanks **Hamsanger**!)
+- Configurable session cookie options [#242](https://github.com/miguelgrinberg/microdot/issues/242) ([commit](https://github.com/miguelgrinberg/microdot/commit/0151611fc84fec450820d673f4c4d70c32c990a7))
+- Improved cookie support in the test client ([commit](https://github.com/miguelgrinberg/microdot/commit/4cb155ee411dc2d9c9f15714cb32b25ba79b156a))
+- Cookie path support in session extension and test client ([commit](https://github.com/miguelgrinberg/microdot/commit/6ffb8a8fe920111c4d8c16e98715a0d5ee2d1da3))
+- Refactor `Session` class to make it more reusable ([commit](https://github.com/miguelgrinberg/microdot/commit/dea79c5ce224dec7858ffef45a42bed442fd3a5a))
+- Use `@functools.wraps` on decorated functions ([commit](https://github.com/miguelgrinberg/microdot/commit/f6876c0d154adcae96098405fb6a1fdf1ea4ec28))
+- Removed outdated import from documentation [#216](https://github.com/miguelgrinberg/microdot/issues/216) ([commit](https://github.com/miguelgrinberg/microdot/commit/6b1fd6191702e7a9ad934fddfcdd0a3cebea7c94)) (thanks **Carlo Colombo**!)
+- Add roadmap details to readme ([commit](https://github.com/miguelgrinberg/microdot/commit/a0ea439def238084c4d68309c0992b66ffd28ad6))
+
+**Release 2.0.5** - 2024-03-09
+
+- Correct handling of 0 as an integer argument (regression from #207) [#212](https://github.com/miguelgrinberg/microdot/issues/212) ([commit](https://github.com/miguelgrinberg/microdot/commit/d0a4cf8fa7dfb1da7466157b18d3329a8cf9a5df))
+
+**Release 2.0.4** - 2024-02-20
+
+- Do not use regexes for parsing simple URLs [#207](https://github.com/miguelgrinberg/microdot/issues/207) ([commit #1](https://github.com/miguelgrinberg/microdot/commit/38262c56d34784401659639b482a4a1224e1e59a) [commit #2](https://github.com/miguelgrinberg/microdot/commit/f6cba2c0f7e18e2f32b5adb779fb037b6c473eab))
+- Added documentation on using alternative uTemplate loaders ([commit](https://github.com/miguelgrinberg/microdot/commit/bf519478cbc6e296785241cd7d01edb23c317cd3))
+- Added CircuitPython builds ([commit](https://github.com/miguelgrinberg/microdot/commit/e44c271bae88f4327d3eda16d8780ac264d1ebab))
+
+**Release 2.0.3** - 2024-01-07
+
+- Add a limit to WebSocket message size [#193](https://github.com/miguelgrinberg/microdot/issues/193) ([commit](https://github.com/miguelgrinberg/microdot/commit/5d188e8c0ddef6ce633ca702dbdd4a90f2799597))
+- Pass keyword arguments to thread executor in the correct way [#195](https://github.com/miguelgrinberg/microdot/issues/195) ([commit](https://github.com/miguelgrinberg/microdot/commit/6712c47400d7c426c88032f65ab74466524eccab))
+- Update uasyncio library used in tests to include new TLS support ([commit](https://github.com/miguelgrinberg/microdot/commit/c8c91e83457d24320f22c9a74e80b15e06b072ca))
+- Documentation improvements ([commit](https://github.com/miguelgrinberg/microdot/commit/b80b6b64d02d21400ca8a5077f5ed1127cc202ae))
+
+**Release 2.0.2** - 2023-12-28
+
+- Support binary data in the SSE extension ([commit](https://github.com/miguelgrinberg/microdot/commit/1fc11193da0d298f5539e2ad218836910a13efb2))
+- Upgrade micropython tests to use v1.22 + initial CircuitPython testing work ([commit](https://github.com/miguelgrinberg/microdot/commit/79452a46992351ccad2c0317c20bf50be0d76641))
+- Improvements to migration guide ([commit](https://github.com/miguelgrinberg/microdot/commit/84842e39c360a8b3ddf36feac8af201fb19bbb0b))
+- Remove spurious async in documentation example [#187](https://github.com/miguelgrinberg/microdot/issues/187) ([commit](https://github.com/miguelgrinberg/microdot/commit/ad368be993e2e3007579f1d3880e36d60c71da92)) (thanks **Tak Tran**!)
+
+**Release 2.0.1** - 2023-12-23
+
+- Addressed some inadvertent mistakes in the template extensions ([commit](https://github.com/miguelgrinberg/microdot/commit/bd18ceb4424e9dfb52b1e6d498edd260aa24fc53))
+
+**Release 2.0.0** - 2023-12-22
+
+- Major redesign [#186](https://github.com/miguelgrinberg/microdot/issues/186) ([commit](https://github.com/miguelgrinberg/microdot/commit/20ea305fe793eb206b52af9eb5c5f3c1e9f57dbb))
+    - Code reorganization as a `microdot` package
+    - Asyncio is now the core implementation
+    - New support for Server-Sent Events (SSE)
+    - Several extensions redesigned
+    - Support for "partitioned" cookies
+    - [Cross-compiling and freezing](https://microdot.readthedocs.io/en/stable/freezing.html) guidance
+    - A [Migration Guide](https://microdot.readthedocs.io/en/stable/migrating.html) to help transition to version 2 from older releases
+
 **Release 1.3.4** - 2023-11-08
 
 - Handle change in `wait_closed()` behavior in Python 3.12 [#177](https://github.com/miguelgrinberg/microdot/issues/177) ([commit](https://github.com/miguelgrinberg/microdot/commit/5550b20cdd347d59e2aa68f6ebf9e9abffaff9fc))

README.md

@@ -3,9 +3,9 @@
 
 *“The impossibly small web framework for Python and MicroPython”*
 
-Microdot is a minimalistic Python web framework inspired by Flask, and designed
-to run on systems with limited resources such as microcontrollers. It runs on
-standard Python and on MicroPython.
+Microdot is a minimalistic Python web framework inspired by Flask. Given its
+small size, it can run on systems with limited resources such as
+microcontrollers. Both standard Python (CPython) and MicroPython are supported.
 
 ```python
 from microdot import Microdot
@@ -13,13 +13,44 @@ from microdot import Microdot
 app = Microdot()
 
 @app.route('/')
-def index(request):
+async def index(request):
     return 'Hello, world!'
 
 app.run()
 ```
 
+## Migrating to Microdot 2
+
+Version 2 of Microdot incorporates feedback received from users of earlier
+releases, and attempts to improve and correct some design decisions that have
+proven to be problematic.
+
+For this reason most applications built for earlier versions will need to be
+updated to work correctly with Microdot 2. The
+[Migration Guide](https://microdot.readthedocs.io/en/stable/migrating.html)
+describes the backwards incompatible changes that were made.
+
 ## Resources
 
-- [Documentation](https://microdot.readthedocs.io/en/latest/)
 - [Change Log](https://github.com/miguelgrinberg/microdot/blob/main/CHANGES.md)
+- Documentation
+    - [Latest](https://microdot.readthedocs.io/en/latest/)
+    - [Stable (v2)](https://microdot.readthedocs.io/en/stable/)
+    - [Legacy (v1)](https://microdot.readthedocs.io/en/v1/) ([Code](https://github.com/miguelgrinberg/microdot/tree/v1))
+
+## Roadmap
+
+The following features are planned for future releases of Microdot, both for
+MicroPython and CPython:
+
+- Authentication support, similar to [Flask-Login](https://github.com/maxcountryman/flask-login) for Flask (**Added in version 2.1**)
+- Support for forms encoded in `multipart/form-data` format (**Added in version 2.2**)
+- OpenAPI integration, similar to [APIFairy](https://github.com/miguelgrinberg/apifairy) for Flask
+
+In addition to the above, the following extensions are also under consideration,
+but only for CPython:
+
+- Database integration through [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy)
+- Socket.IO support through [python-socketio](https://github.com/miguelgrinberg/python-socketio)
+
+Do you have other ideas to propose? Let's [discuss them](https://github.com/:miguelgrinberg/microdot/discussions/new?category=ideas)!

docs/api.rst

@@ -1,8 +1,8 @@
 API Reference
 =============
 
-``microdot`` module
--------------------
+Core API
+--------
 
 .. autoclass:: microdot.Microdot
    :members:
@@ -13,103 +13,83 @@ API Reference
 .. autoclass:: microdot.Response
    :members:
 
-.. autoclass:: microdot.NoCaseDict
+.. autoclass:: microdot.URLPattern
    :members:
 
-.. autoclass:: microdot.MultiDict
+Multipart Forms
+---------------
+
+.. automodule:: microdot.multipart
    :members:
 
-``microdot_asyncio`` module
----------------------------
+WebSocket
+---------
 
-.. autoclass:: microdot_asyncio.Microdot
-   :inherited-members:
+.. automodule:: microdot.websocket
    :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_cors`` module
+Server-Sent Events (SSE)
 ------------------------
 
-.. automodule:: microdot_cors
+.. automodule:: microdot.sse
    :members:
 
-``microdot_websocket`` module
-------------------------------
+Templates (uTemplate)
+---------------------
 
-.. automodule:: microdot_websocket
+.. automodule:: microdot.utemplate
    :members:
 
-``microdot_asyncio_websocket`` module
--------------------------------------
+Templates (Jinja)
+-----------------
 
-.. automodule:: microdot_asyncio_websocket
+.. automodule:: microdot.jinja
    :members:
 
-``microdot_asgi_websocket`` module
--------------------------------------
+User Sessions
+-------------
 
-.. automodule:: microdot_asgi_websocket
+.. automodule:: microdot.session
    :members:
 
-``microdot_ssl`` module
------------------------
+Authentication
+--------------
 
-.. automodule:: microdot_ssl
+.. automodule:: microdot.auth
+   :inherited-members:
+   :special-members: __call__
    :members:
 
-``microdot_test_client`` module
--------------------------------
+User Logins
+-----------
 
-.. autoclass:: microdot_test_client.TestClient
+.. automodule:: microdot.login
+   :inherited-members:
+   :special-members: __call__
    :members:
 
-.. autoclass:: microdot_test_client.TestResponse
+Cross-Origin Resource Sharing (CORS)
+------------------------------------
+
+.. automodule:: microdot.cors
    :members:
 
-``microdot_asyncio_test_client`` module
----------------------------------------
+Test Client
+-----------
 
-.. autoclass:: microdot_asyncio_test_client.TestClient
+.. automodule:: microdot.test_client
    :members:
 
-.. autoclass:: microdot_asyncio_test_client.TestResponse
-   :members:
+ASGI
+----
 
-``microdot_wsgi`` module
-------------------------
-
-.. autoclass:: microdot_wsgi.Microdot
+.. autoclass:: microdot.asgi.Microdot
    :members:
    :exclude-members: shutdown, run
 
-``microdot_asgi`` module
-------------------------
+WSGI
+----
 
-.. autoclass:: microdot_asgi.Microdot
+.. autoclass:: microdot.wsgi.Microdot
    :members:
    :exclude-members: shutdown, run

docs/freezing.rst

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

docs/index.rst

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

docs/intro.rst

@@ -1,26 +1,50 @@
 Installation
 ------------
 
-For standard Python (CPython) projects, Microdot and all of its core extensions
-can be installed with ``pip``::
+The installation method is different depending on the version of Python.
+
+CPython Installation
+~~~~~~~~~~~~~~~~~~~~
+
+For use with standard Python (CPython) projects, Microdot and all of its core
+extensions are installed with ``pip``::
 
     pip install microdot
 
-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
+MicroPython Installation
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+For MicroPython, the recommended approach is to manually copy the necessary
+source files from the
 `GitHub repository <https://github.com/miguelgrinberg/microdot/tree/main/src>`_
-into your device, possibly after
+into your device, ideally after
 `compiling <https://docs.micropython.org/en/latest/reference/mpyfiles.html>`_
 them to *.mpy* files. These source files can also be
 `frozen <https://docs.micropython.org/en/latest/develop/optimizations.html?highlight=frozen#frozen-bytecode>`_
 and incorporated into a custom MicroPython firmware.
 
+Use the following guidelines to know what files to copy:
+
+* For a minimal setup with only the base web server functionality, copy
+  `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
+  into your project.
+* For a configuration that includes one or more optional extensions, create a
+  *microdot* directory in your device and copy the following files:
+
+  * `__init__.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/__init__.py>`_
+  * `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
+  * any needed `extensions <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot>`_.
+
+
 Getting Started
 ---------------
 
-This section describes the main features of Microdot in an informal manner. For
-detailed reference information, consult the :ref:`API Reference`.
+This section describes the main features of Microdot in an informal manner.
+
+For detailed reference information, consult the :ref:`API Reference`.
+
+If you are familiar with releases of Microdot before 2.x, review the
+:ref:`Migration Guide <Migrating to Microdot 2.x from Older Releases>`.
 
 A Simple Microdot Web Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -32,7 +56,7 @@ The following is an example of a simple web server::
     app = Microdot()
 
     @app.route('/')
-    def index(request):
+    async def index(request):
         return 'Hello, world!'
 
     app.run()
@@ -46,23 +70,55 @@ 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.
+when the client requests the URL.
+
+When the function is called, it is passed a :class:`Request <microdot.Request>`
+object as an argument, which provides access to the information passed by the
+client. The value returned by the function is sent back to the client as the
+response.
+
+Microdot is an asynchronous framework that uses the ``asyncio`` package. Route
+handler functions can be defined as ``async def`` or ``def`` functions, but
+``async def`` functions are recommended for performance.
 
 The :func:`run() <microdot.Microdot.run>` method starts the application's web
-server on port 5000 (or the port number passed in the ``port`` argument). This
+server on port 5000 by default, and creates its own asynchronous loop. This
 method blocks while it waits for connections from clients.
 
+For some applications it may be necessary to run the web server alongside other
+asynchronous tasks, on an already running loop. In that case, instead of
+``app.run()`` the web server can be started by invoking the
+:func:`start_server() <microdot.Microdot.start_server>` coroutine as shown in
+the following example::
+
+    import asyncio
+    from microdot import Microdot
+
+    app = Microdot()
+
+    @app.route('/')
+    async def index(request):
+        return 'Hello, world!'
+
+    async def main():
+        # start the server in a background task
+        server = asyncio.create_task(app.start_server())
+
+        # ... do other asynchronous work here ...
+
+        # cleanup before ending the application
+        await server
+
+    asyncio.run(main())
+
 Running with CPython
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 
 .. list-table::
    :align: left
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
 
    * - Required external dependencies
      - | None
@@ -71,23 +127,24 @@ Running with CPython
      - | `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::
+has the ``app.run()`` call at the bottom::
 
     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``.
+After starting the script, open a web browser and navigate to
+*http://localhost:5000/* to access the application at the default address for
+the Microdot web server. From other computers in the same network, use the IP
+address or hostname of the computer running the script instead of
+``localhost``.
 
 Running with MicroPython
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. list-table::
    :align: left
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
 
    * - Required external dependencies
      - | None
@@ -97,11 +154,13 @@ Running with MicroPython
        | `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.
+server code to your device, along with the required Microdot files, as defined
+in the :ref:`MicroPython Installation` section.
+
+MicroPython will automatically run *main.py* when the device is powered on, so
+the web server will automatically start. The application can be accessed on
+port 5000 at the device's IP address. As indicated above, the port can be
+changed by passing the ``port`` argument to the ``run()`` method.
 
 .. note::
    Microdot does not configure the network interface of the device in which it
@@ -109,6 +168,40 @@ device's IP address. As indicated above, the port can be changed by passing the
    advance, for example to a Wi-Fi access point, this must be configured before
    the ``run()`` method is invoked.
 
+Web Server Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :func:`run() <microdot.Microdot.run>` and
+:func:`start_server() <microdot.Microdot.start_server>` methods support a few
+arguments to configure the web server.
+
+- ``port``: The port number to listen on. Pass the desired port number in this
+  argument to use a port different than the default of 5000. For example::
+
+    app.run(port=6000)
+
+- ``host``: The IP address of the network interface to listen on. By default
+  the server listens on all available interfaces. To listen only on the local
+  loopback interface, pass ``'127.0.0.1'`` as value for this argument.
+- ``debug``: when set to ``True``, the server ouputs logging information to the
+  console. The default is ``False``.
+- ``ssl``: an ``SSLContext`` instance that configures the server to use TLS
+  encryption, or ``None`` to disable TLS use. The default is ``None``. The
+  following example demonstrates how to configure the server with an SSL
+  certificate stored in *cert.pem* and *key.pem* files::
+
+    import ssl
+
+    # ...
+
+    sslctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    sslctx.load_cert_chain('cert.pem', 'key.pem')
+    app.run(port=4443, debug=True, ssl=sslctx)
+
+.. note::
+   When using CPython, the certificate and key files must be given in PEM
+   format. When using MicroPython, these files must be given in DER format.
+
 Defining Routes
 ~~~~~~~~~~~~~~~
 
@@ -119,7 +212,7 @@ 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):
+    async def index(request):
         return 'Hello, world!'
 
 When a client requests the root URL (for example, *http://localhost:5000/*),
@@ -127,11 +220,11 @@ 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
+Below is another example, this one with a route for a URL with two components
 in its path::
 
     @app.route('/users/active')
-    def active_users(request):
+    async def active_users(request):
         return 'Active users: Susan, Joe, and Bob'
 
 The complete URL that maps to this route is
@@ -144,46 +237,49 @@ 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.
+All the example routes shown above are associated with ``GET`` requests, which
+are the default. Applications often need to define routes for other HTTP
+methods, such as ``POST``, ``PUT``, ``PATCH`` and ``DELETE``. The ``route()``
+decorator takes a ``methods`` optional argument, in which the application can
+provide a list of HTTP methods that the route should be associated with on the
+given path.
 
 The following example defines a route that handles ``GET`` and ``POST``
 requests within the same function::
 
     @app.route('/invoices', methods=['GET', 'POST'])
-    def invoices(request):
+    async 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::
+As an alternative to the example above, in which a single function is used to
+handle multiple HTTP methods, sometimes it may be desirable to write a separate
+function for each HTTP method. The above example can be implemented with two
+routes as follows::
 
     @app.route('/invoices', methods=['GET'])
-    def get_invoices(request):
+    async def get_invoices(request):
         return 'get invoices'
 
     @app.route('/invoices', methods=['POST'])
-    def create_invoice(request):
+    async def create_invoice(request):
         return 'create an invoice'
 
 Microdot provides the :func:`get() <microdot.Microdot.get>`,
 :func:`post() <microdot.Microdot.post>`, :func:`put() <microdot.Microdot.put>`,
 :func:`patch() <microdot.Microdot.patch>`, and
-:func:`delete() <microdot.Microdot.delete>` decorator shortcuts as well. The
-two example routes above can be written more concisely with them::
+:func:`delete() <microdot.Microdot.delete>` decorators as shortcuts for the
+corresponding HTTP methods. The two example routes above can be written more
+concisely with them::
 
     @app.get('/invoices')
-    def get_invoices(request):
+    async def get_invoices(request):
         return 'get invoices'
 
     @app.post('/invoices')
-    def create_invoice(request):
+    async def create_invoice(request):
         return 'create an invoice'
 
 Including Dynamic Components in the URL Path
@@ -195,19 +291,19 @@ 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):
+    async 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.
+As shown in the example, a path component that is enclosed in angle brackets
+is considered a placeholder. Microdot accepts any values for that portion of
+the URL path, and passes the value received to the function as an argument
+after the request object.
 
 Routes are not limited to a single dynamic component. The following route shows
 how multiple dynamic components can be included in the path::
 
     @app.get('/users/<firstname>/<lastname>')
-    def get_user(request, firstname, lastname):
+    async def get_user(request, firstname, lastname):
         return 'User: ' + firstname + ' ' + lastname
 
 Dynamic path components are considered to be strings by default. An explicit
@@ -216,7 +312,7 @@ 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):
+    async def get_user(request, id, username):
         return 'User: ' + username + ' (' + str(id) + ')'
 
 If a dynamic path component is defined as an integer, the value passed to the
@@ -225,21 +321,60 @@ 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::
+single argument. The difference between an argument of type ``path`` and one of
+type ``string`` is that the latter stops capturing when a ``/`` appears in the
+URL::
 
     @app.get('/tests/<path:path>')
-    def get_test(request, path):
+    async def get_test(request, path):
         return 'Test: ' + path
 
-For the most control, the ``re`` type allows the application to provide a
-custom regular expression for the dynamic component. The next example defines
-a route that only matches usernames that begin with an upper or lower case
-letter, followed by a sequence of letters or numbers::
+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):
+    async def get_user(request, username):
         return 'User: ' + username
 
+The ``re`` type returns the URL component as a string, which sometimes may not
+be the most convenient. To convert a path component to something more
+meaningful than a string, the application can register a custom URL component
+type and provide a parser function that performs the conversion. In the
+following example, a ``hex`` custom type is registered to automatically
+convert hex numbers given in the path to numbers::
+
+    from microdot import URLPattern
+
+    URLPattern.register_type('hex', parser=lambda value: int(value, 16))
+
+    @app.get('/users/<hex:user_id>')
+    async def get_user(request, user_id):
+        user = get_user_by_id(user_id)
+        # ...
+
+In addition to the parser, the custom URL component can include a pattern,
+given as a regular expression. When a pattern is provided, the URL component
+will only match if the regular expression matches the value passed in the URL.
+The ``hex`` example above can be expanded with a pattern as follows::
+
+    URLPattern.register_type('hex', pattern='[0-9a-fA-F]+',
+                             parser=lambda value: int(value, 16))
+
+In cases where a pattern isn't provided, or when the pattern is unable to
+filter out all invalid values, the parser function can return ``None`` to
+indicate a failed match. The next example shows how the parser for the ``hex``
+type can be expanded to do that::
+
+    def hex_parser(value):
+        try:
+            return int(value, 16)
+        except ValueError:
+            return None
+
+    URLPattern.register_type('hex', parser=hex_parser)
+
 .. note::
    Dynamic path components are passed to route functions as keyword arguments,
    so the names of the function arguments must match the names declared in the
@@ -255,54 +390,56 @@ 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
+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):
+    async def authenticate(request):
         user = authorize(request)
         if not user:
             return 'Unauthorized', 401
         request.g.user = user
 
-Before request handlers receive the request object as an argument. If the
+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
+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.
+route.
 
-After request handlers registered with the
+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::
+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):
+    async def start_timer(request):
         request.g.start_time = time.time()
 
     @app.after_request
-    def end_timer(request, response):
+    async def end_timer(request, response):
         duration = time.time() - request.g.start_time
         print(f'Request took {duration:0.2f} seconds')
 
-After request handlers receive the request and response objects as arguments.
-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.
+After-request handlers receive the request and response objects as arguments,
+and they can return a modified response object to replace the original. If
+no value is returned from an after-request handler, then the original response
+object is used.
 
-The after request handlers are only invoked for successful requests. The
+The after-request handlers are only invoked for successful requests. The
 :func:`after_error_request() <microdot.Microdot.after_error_request>`
 decorator can be used to register a function that is called after an error
 occurs. The function receives the request and the error response and is
-expected to return an updated response object.
+expected to return an updated response object after performing any necessary
+cleanup.
 
 .. note::
-   The :ref:`request.g <The "g" Object>` object is a special object that allows
-   the before and after request handlers, as well as the route function to
-   share data during the life of the request.
+   The :ref:`request.g <The "g" Object>` object used in many of the above
+   examples is a special object that allows the before- and after-request
+   handlers, as well as the route function to share data during the life of the
+   request.
 
 Error Handlers
 ^^^^^^^^^^^^^^
@@ -312,10 +449,11 @@ 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.
+- 404 for URLs that are unknown.
+- 405 for URLs that are known, but not implemented for the requested HTTP
+  method.
 - 413 for requests that are larger than the allowed size.
-- 500 when the application raises an exception.
+- 500 when the application raises an unhandled exception.
 
 While the above errors are fully complaint with the HTTP specification, the
 application might want to provide custom responses for them. The
@@ -324,30 +462,31 @@ 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):
+    async def not_found(request):
         return {'error': 'resource not found'}, 404
 
 The ``errorhandler()`` decorator has a second form, in which it takes an
-exception class as an argument. Microdot will then invoke the handler when the
-exception is an instance of the given class is raised. The next example
-provides a custom response for division by zero errors::
+exception class as an argument. Microdot will invoke the handler when an
+unhandled exception that is an instance of the given class is raised. The next
+example provides a custom response for division by zero errors::
 
     @app.errorhandler(ZeroDivisionError)
-    def division_by_zero(request, exception):
+    async def division_by_zero(request, exception):
         return {'error': 'division by zero'}, 500
 
 When the raised exception class does not have an error handler defined, but
-one or more of its base classes do, Microdot makes an attempt to invoke the
+one or more of its parent classes do, Microdot makes an attempt to invoke the
 most specific handler.
 
 Mounting a Sub-Application
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Small Microdot applications can be written an a single source file, but this
-is not the best option for applications that past certain size. To make it
+Small Microdot applications can be written as a single source file, but this
+is not the best option for applications that pass a certain size. To make it
 simpler to write large applications, Microdot supports the concept of
 sub-applications that can be "mounted" on a larger application, possibly with
-a common URL prefix applied to all of its routes.
+a common URL prefix applied to all of its routes. For developers familiar with
+the Flask framework, this is a similar concept to Flask's blueprints.
 
 Consider, for example, a *customers.py* sub-application that implements
 operations on customers::
@@ -357,14 +496,14 @@ operations on customers::
     customers_app = Microdot()
 
     @customers_app.get('/')
-    def get_customers(request):
+    async def get_customers(request):
         # return all customers
 
     @customers_app.post('/')
-    def new_customer(request):
+    async def new_customer(request):
         # create a new customer
 
-In the same way, the *orders.py* sub-application implements operations on
+Similar to the above, the *orders.py* sub-application implements operations on
 customer orders::
 
     from microdot import Microdot
@@ -372,15 +511,15 @@ customer orders::
     orders_app = Microdot()
 
     @orders_app.get('/')
-    def get_orders(request):
+    async def get_orders(request):
         # return all orders
 
     @orders_app.post('/')
-    def new_order(request):
+    async def new_order(request):
         # create a new order
 
 Now the main application, which is stored in *main.py*, can import and mount
-the sub-applications to build the combined application::
+the sub-applications to build the larger combined application::
 
     from microdot import Microdot
     from customers import customers_app
@@ -399,11 +538,25 @@ 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.
+   During the handling of a request, the
+   :attr:`Request.url_prefix <microdot.Microdot.url_prefix>` attribute is
+   set to the URL prefix under which the sub-application was mounted, or an
+   empty string if the endpoint did not come from a sub-application or the
+   sub-application was mounted without a URL prefix. It is possible to issue a
+   redirect that is relative to the sub-application as follows::
+
+      return redirect(request.url_prefix + '/relative-url')
+
+When mounting an application as shown above, before-request, after-request and
+error handlers defined in the sub-application are copied over to the main
+application at mount time. Once installed in the main application, these
+handlers will apply to the whole application and not just the sub-application
+in which they were created.
+
+The :func:`mount() <microdot.Microdot.mount>` method has a ``local`` argument
+that defaults to ``False``. When this argument is set to ``True``, the
+before-request, after-request and error handlers defined in the sub-application
+will only apply to the sub-application.
 
 Shutting Down the Server
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -416,16 +569,20 @@ 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):
+    async def shutdown(request):
         request.app.shutdown()
         return 'The server is shutting down...'
 
+The request that invokes the ``shutdown()`` method will complete, and then the
+server will not accept any new requests and stop once any remaining requests
+complete. At this point the ``app.run()`` call will return.
+
 The Request Object
 ~~~~~~~~~~~~~~~~~~
 
 The :class:`Request <microdot.Request>` object encapsulates all the information
 passed by the client. It is passed as an argument to route handlers, as well as
-to before request, after request and error handlers.
+to before-request, after-request and error handlers.
 
 Request Attributes
 ^^^^^^^^^^^^^^^^^^
@@ -444,10 +601,20 @@ The request object provides access to the request attributes, including:
   specified by the client, or ``None`` if no content type was specified.
 - :attr:`content_length <microdot.Request.content_length>`: The content
   length of the request, or 0 if no content length was specified.
+- :attr:`json <microdot.Request.json>`: The parsed JSON data in the request
+  body. See :ref:`below <JSON Payloads>` for additional details.
+- :attr:`form <microdot.Request.form>`: The parsed form data in the request
+  body, as a dictionary. See :ref:`below <Form Data>` for additional details.
+- :attr:`files <microdot.Request.files>`: A dictionary with the file uploads
+  included in the request body. Note that file uploads are only supported when
+  the :ref:`Multipart Forms` extension is used.
 - :attr:`client_addr <microdot.Request.client_addr>`: The network address of
   the client, as a tuple (host, port).
 - :attr:`app <microdot.Request.app>`: The application instance that created the
   request.
+- :attr:`g <microdot.Request.g>`: The ``g`` object, where handlers can store
+  request-specific data to be shared among handlers. See :ref:`The "g" Object`
+  for details.
 
 JSON Payloads
 ^^^^^^^^^^^^^
@@ -458,7 +625,7 @@ application can access the parsed JSON data using the
 to use this attribute::
 
     @app.post('/customers')
-    def create_customer(request):
+    async def create_customer(request):
         customer = request.json
         # do something with customer
         return {'success': True}
@@ -467,24 +634,25 @@ to use this attribute::
    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
-^^^^^^^^^^^^^^^^^^^^
+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):
+    async def index(req):
         name = 'Unknown'
         if req.method == 'POST':
             name = req.form.get('name')
         return f'Hello {name}'
 
 .. note::
-   Form submissions are only parsed when the ``Content-Type`` header is set by
-   the client to ``application/x-www-form-urlencoded``. Form submissions using
-   the ``multipart/form-data`` content type are currently not supported.
+   Form submissions automatically parsed when the ``Content-Type`` header is
+   set by the client to ``application/x-www-form-urlencoded``. For form
+   submissions that use the ``multipart/form-data`` content type the
+   :ref:`Multipart Forms` extension must be used.
 
 Accessing the Raw Request Body
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -493,9 +661,12 @@ 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.
+If the expected body is too large to fit safely in memory, the application can
+use the :attr:`stream <microdot.Request.stream>` request attribute to read the
+body contents as a file-like object. The
+:attr:`max_body_length <microdot.Request.max_body_length>` attribute of the
+request object defines the size at which bodies are streamed instead of loaded
+into memory.
 
 Cookies
 ^^^^^^^
@@ -508,41 +679,40 @@ 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.
+that it can be shared between the before- and after-request handlers, the
+route function and any error handlers. The request object provides the
+:attr:`g <microdot.Request.g>` attribute for that purpose.
 
-In the following example, a before request handler
-authorizes the client and stores the username so that the route function can
-use it::
+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):
+    async def authorize(request):
         username = authenticate_user(request)
         if not username:
             return 'Unauthorized', 401
         request.g.username = username
 
     @app.get('/')
-    def index(request):
+    async def index(request):
         return f'Hello, {request.g.username}!'
 
-Request-Specific After Request Handlers
+Request-Specific After-Request Handlers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Sometimes applications need to perform operations on the response object,
+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
+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
+Request-specific after-request handlers are called by Microdot after the route
+function returns and all the application-wide after-request handlers have been
 called.
 
 The next example shows how a cookie can be updated using a request-specific
-after request handler defined inside a route function::
+after-request handler defined inside a route function::
 
     @app.post('/logout')
-    def logout(request):
+    async def logout(request):
         @request.after_request
         def reset_session(request, response):
             response.set_cookie('session', '', http_only=True)
@@ -556,22 +726,24 @@ 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
+- :attr:`max_content_length <microdot.Request.max_content_length>`: The
   maximum size accepted for the request body, in bytes. When a client sends a
   request that is larger than this, the server will respond with a 413 error.
   The default is 16KB.
-- :attr:`max_body_length <microdot.Microdot.max_body_length>`: The maximum
+- :attr:`max_body_length <microdot.Request.max_body_length>`: The maximum
   size that is loaded in the :attr:`body <microdot.Request.body>` attribute, in
   bytes. Requests that have a body that is larger than this size but smaller
   than the size set for ``max_content_length`` can only be accessed through the
   :attr:`stream <microdot.Request.stream>` attribute. The default is also 16KB.
-- :attr:`max_readline <microdot.Microdot.max_readline>`: The maximum allowed
+- :attr:`max_readline <microdot.Request.max_readline>`: The maximum allowed
   size for a request line, in bytes. The default is 2KB.
 
 The following example configures the application to accept requests with
-payloads up to 1MB big, but prevents requests that are larger than 8KB from
+payloads up to 1MB in size, but prevents requests that are larger than 8KB from
 being loaded into memory::
 
+    from microdot import Request
+
     Request.max_content_length = 1024 * 1024
     Request.max_body_length = 8 * 1024
 
@@ -585,41 +757,53 @@ 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::
+Route functions can return one, two or three values. The first and most
+important value is the response body::
 
     @app.get('/')
-    def index(request):
+    async def index(request):
         return 'Hello, World!'
 
-In the above example, Microdot issues a standard 200 status code response, and
-inserts the necessary headers.
+In the above example, Microdot issues a standard 200 status code response
+indicating a successful request. The body of the response is the
+``'Hello, World!'`` string returned by the function. Microdot includes default
+headers with this response, including the ``Content-Type`` header set to
+``text/plain`` to indicate a response in plain text.
 
 The application can provide its own status code as a second value returned from
-the route. 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 status
+the route to override the 200 default. The example below returns a 202 status
 code::
 
     @app.get('/')
-    def index(request):
+    async def index(request):
+        return 'Hello, World!', 202
+
+The application can also return a third value, a dictionary with additional
+headers that are added to, or replace the default ones included by Microdot.
+The next example returns an HTML response, instead of the default plain text
+response::
+
+    @app.get('/')
+    async def index(request):
+        return '<h1>Hello, World!</h1>', 202, {'Content-Type': 'text/html'}
+
+If the application does not need to return a body, then it can omit it and
+have the status code as the first or only returned value::
+
+    @app.get('/')
+    async def index(request):
+        return 204
+
+Likewise, if the application needs to return a body and custom headers, but
+does not need to change the default status code, then it can return two values,
+omitting the status code::
+
+    @app.get('/')
+    async def index(request):
         return '<h1>Hello, World!</h1>', {'Content-Type': 'text/html'}
 
-The application can also return a :class:`Response <microdot.Response>` object
-containing all the details of the response as a single value.
+Lastly, the application can also return a :class:`Response <microdot.Response>`
+object containing all the details of the response as a single value.
 
 JSON Responses
 ^^^^^^^^^^^^^^
@@ -631,7 +815,7 @@ automatically format the response as JSON.
 Example::
 
     @app.get('/')
-    def index(request):
+    async def index(request):
         return {'hello': 'world'}
 
 .. note::
@@ -647,7 +831,7 @@ creates redirect responses::
     from microdot import redirect
 
     @app.get('/')
-    def index(request):
+    async def index(request):
         return redirect('/about')
 
 File Responses
@@ -659,7 +843,7 @@ object for a file::
         from microdot import send_file
 
         @app.get('/')
-        def index(request):
+        async def index(request):
             return send_file('/static/index.html')
 
 A suggested caching duration can be returned to the client in the ``max_age``
@@ -668,7 +852,7 @@ argument::
         from microdot import send_file
 
         @app.get('/')
-        def image(request):
+        async def image(request):
             return send_file('/static/image.jpg', max_age=3600)  # in seconds
 
 .. note::
@@ -678,7 +862,7 @@ argument::
    the project::
 
         @app.route('/static/<path:path>')
-        def static(request, path):
+        async def static(request, path):
             if '..' in path:
                 # directory traversal is not allowed
                 return 'Not found', 404
@@ -688,12 +872,12 @@ 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::
+return a response that is generated in chunks, by returning a Python generator.
+The example below returns all the numbers in the fibonacci sequence below 100::
 
     @app.get('/fibonacci')
-    def fibonacci(request):
-        def generate_fibonacci():
+    async def fibonacci(request):
+        async def generate_fibonacci():
             a, b = 0, 1
             while a < 100:
                 yield str(a) + '\n'
@@ -701,6 +885,14 @@ example below returns all the numbers in the fibonacci sequence below 100::
 
         return generate_fibonacci()
 
+.. note::
+   Under CPython, the generator function can be a ``def`` or ``async def``
+   function, as well as a class-based generator.
+
+   Under MicroPython, asynchronous generator functions are not supported, so
+   only ``def`` generator functions can be used. Asynchronous class-based
+   generators are supported.
+
 Changing the Default Response Content Type
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -728,14 +920,14 @@ 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>`.
+:ref:`request-specific after-request handler <Request-Specific After-Request Handlers>`.
 
 Example::
 
     @app.get('/')
-    def index(request):
+    async def index(request):
         @request.after_request
-        def set_cookie(request, response):
+        async def set_cookie(request, response):
             response.set_cookie('name', 'value')
             return response
 
@@ -744,7 +936,7 @@ Example::
 Another option is to create a response object directly in the route function::
 
     @app.get('/')
-    def index(request):
+    async def index(request):
         response = Response('Hello, World!')
         response.set_cookie('name', 'value')
         return response
@@ -759,15 +951,36 @@ Another option is to create a response object directly in the route function::
 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.
+Microdot implements concurrency through the ``asyncio`` package, which means
+that applications must be careful to prevent blocking in their handlers.
 
-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.
+"async def" handlers
+^^^^^^^^^^^^^^^^^^^^
 
-The :ref:`micropython_asyncio <Asynchronous Support with Asyncio>` extension
-provides a more robust concurrency option that is supported even on low-end
-MicroPython boards.
+The recommendation for route handlers in Microdot is to use asynchronous
+functions, declared as ``async def``. Microdot executes these handler
+functions as native asynchronous tasks. The standard considerations for writing
+asynchronous code apply, and in particular blocking calls should be avoided to
+ensure the application runs smoothly and is always responsive.
+
+"def" handlers
+^^^^^^^^^^^^^^
+
+Microdot also supports the use of synchronous route handlers, declared as
+standard ``def`` functions. These handlers are handled differently under
+CPython and MicroPython.
+
+When running on CPython, Microdot executes synchronous handlers in a
+`thread executor <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor>`_,
+which uses a thread pool. The use of blocking or CPU intensive code in these
+handlers does not have such a negative effect on the application, because
+handlers do not run on the same thread as the asynchronous loop. On the other
+hand, the application will be affected by threading issues such as those caused
+by the Global Interpreter Lock.
+
+Under MicroPython the situation is different. Most microcontroller boards
+do not have or have very limited threading support, so Microdot executes
+synchronous handlers in the main and often only thread available. This means
+that these functions will block the asynchronous loop when they take too long
+to complete. The use of properly written asynchronous handlers should be
+preferred.

docs/migrating.rst

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

examples/auth/README.md

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

examples/auth/basic_auth.py

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

examples/auth/pbkdf2.py

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

examples/auth/token_auth.py

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

examples/benchmark/mem.py

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

examples/benchmark/mem_asgi.py

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

examples/benchmark/mem_async.py

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

examples/benchmark/mem_fastapi.py

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

examples/benchmark/mem_quart.py

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

examples/benchmark/mem_wsgi.py

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

examples/benchmark/requirements.in

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

examples/benchmark/requirements.txt

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

examples/benchmark/run.py

@@ -14,13 +14,8 @@ apps = [
     ),
     (
         'micropython mem.py',
-        {'MICROPYPATH': '../../src'},
-        'microdot-micropython-sync'
-    ),
-    (
-        'micropython mem_async.py',
         {'MICROPYPATH': '../../src:../../libs/micropython'},
-        'microdot-micropython-async'
+        'microdot-micropython'
     ),
     (
         ['python', '-c', 'import time; time.sleep(10)'],
@@ -30,47 +25,42 @@ apps = [
     (
         'python mem.py',
         {'PYTHONPATH': '../../src'},
-        'microdot-cpython-sync'
-    ),
-    (
-        'python mem_async.py',
-        {'PYTHONPATH': '../../src'},
-        'microdot-cpython-async'
-    ),
-    (
-        'gunicorn --workers 1 --bind :5000 mem_wsgi:app',
-        {'PYTHONPATH': '../../src'},
-        'microdot-gunicorn-sync'
+        'microdot-cpython'
     ),
     (
         'uvicorn --workers 1 --port 5000 mem_asgi:app',
         {'PYTHONPATH': '../../src'},
-        'microdot-uvicorn-async'
+        'microdot-uvicorn'
+    ),
+    (
+        'gunicorn --workers 1 --bind :5000 mem_wsgi:app',
+        {'PYTHONPATH': '../../src'},
+        'microdot-gunicorn'
     ),
     (
         'flask run',
         {'FLASK_APP': 'mem_flask.py'},
-        'flask-run-sync'
+        'flask-run'
     ),
     (
         'quart run',
         {'QUART_APP': 'mem_quart.py'},
-        'quart-run-async'
+        'quart-run'
     ),
     (
         'gunicorn --workers 1 --bind :5000 mem_flask:app',
         {},
-        'flask-gunicorn-sync'
+        'flask-gunicorn'
     ),
     (
         'uvicorn --workers 1 --port 5000 mem_quart:app',
         {},
-        'quart-uvicorn-async'
+        'quart-uvicorn'
     ),
     (
         'uvicorn --workers 1 --port 5000 mem_fastapi:app',
         {},
-        'fastapi-uvicorn-async'
+        'fastapi-uvicorn'
     ),
 ]
 

examples/cors/app.py

@@ -1,5 +1,5 @@
 from microdot import Microdot
-from microdot_cors import CORS
+from microdot.cors import CORS
 
 app = Microdot()
 CORS(app, allowed_origins=['https://example.org'], allow_credentials=True)

examples/gpio/weather/README.md

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

examples/gpio/weather/config.py

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

examples/gpio/weather/dht.py

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

examples/gpio/weather/index.html

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

examples/gpio/weather/machine.py

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

examples/gpio/weather/main.py

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

examples/gpio/weather/network.py

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

examples/hello/hello.py

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

examples/hello/hello_asgi.py

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

examples/hello/hello_async.py

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

examples/hello/hello_wsgi.py

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

examples/login/README.md

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

examples/login/login.py

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

examples/login/pbkdf2.py

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

examples/sessions/login.py

@@ -1,6 +1,8 @@
+# This is a simple example that demonstrates how to use the user session, but
+# is not intended as a complete login solution. See the login subdirectory for
+# a more complete example.
 from microdot import Microdot, Response, redirect
-from microdot_session import set_session_secret_key, with_session, \
-    update_session, delete_session
+from microdot.session import Session, with_session
 
 BASE_TEMPLATE = '''<!doctype html>
 <html>
@@ -29,18 +31,19 @@ LOGGED_IN = '''<p>Hello <b>{username}</b>!</p>
 </form>'''
 
 app = Microdot()
-set_session_secret_key('top-secret')
+Session(app, secret_key='top-secret')
 Response.default_content_type = 'text/html'
 
 
 @app.get('/')
 @app.post('/')
 @with_session
-def index(req, session):
+async def index(req, session):
     username = session.get('username')
     if req.method == 'POST':
         username = req.form.get('username')
-        update_session(req, {'username': username})
+        session['username'] = username
+        session.save()
         return redirect('/')
     if username is None:
         return BASE_TEMPLATE.format(content=LOGGED_OUT)
@@ -50,8 +53,9 @@ def index(req, session):
 
 
 @app.post('/logout')
-def logout(req):
-    delete_session(req)
+@with_session
+async def logout(req, session):
+    session.delete()
     return redirect('/')
 
 

examples/sse/counter.py

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

examples/sse/index.html

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

examples/static/static.py

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

examples/static/static/index.css

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

examples/static/static_async.py

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

examples/streaming/video_stream.py

@@ -1,8 +1,5 @@
-try:
-    import utime as time
-except ImportError:
-    import time
-
+import sys
+import asyncio
 from microdot import Microdot
 
 app = Microdot()
@@ -14,7 +11,7 @@ for file in ['1.jpg', '2.jpg', '3.jpg']:
 
 
 @app.route('/')
-def index(request):
+async def index(request):
     return '''<!doctype html>
 <html>
   <head>
@@ -29,14 +26,38 @@ def index(request):
 
 
 @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)
+async def video_feed(request):
+    print('Starting video stream.')
+
+    if sys.implementation.name != 'micropython':
+        # CPython supports async generator function
+        async def stream():
+            try:
+                yield b'--frame\r\n'
+                while True:
+                    for frame in frames:
+                        yield b'Content-Type: image/jpeg\r\n\r\n' + frame + \
+                            b'\r\n--frame\r\n'
+                        await asyncio.sleep(1)
+            except GeneratorExit:
+                print('Stopping video stream.')
+    else:
+        # MicroPython can only use class-based async generators
+        class stream():
+            def __init__(self):
+                self.i = 0
+
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                await asyncio.sleep(1)
+                self.i = (self.i + 1) % len(frames)
+                return b'Content-Type: image/jpeg\r\n\r\n' + \
+                    frames[self.i] + b'\r\n--frame\r\n'
+
+            async def aclose(self):
+                print('Stopping video stream.')
 
     return stream(), 200, {'Content-Type':
                            'multipart/x-mixed-replace; boundary=frame'}

examples/streaming/video_stream_async.py

@@ -1,65 +0,0 @@
-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>
-    <meta charset="UTF-8">
-  </head>
-  <body>
-    <h1>Microdot Video Streaming</h1>
-    <img src="/video_feed">
-  </body>
-</html>''', 200, {'Content-Type': 'text/html'}
-
-
-@app.route('/video_feed')
-async def video_feed(request):
-    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/subapps/README.md

@@ -0,0 +1 @@
+This directory contains examples that demonstrate sub-applications.

examples/subapps/app.py

@@ -0,0 +1,27 @@
+from microdot import Microdot
+from subapp import subapp
+
+app = Microdot()
+app.mount(subapp, url_prefix='/subapp')
+
+
+@app.route('/')
+async def hello(request):
+    return '''
+        <!DOCTYPE html>
+        <html>
+            <head>
+                <title>Microdot Sub-App Example</title>
+                <meta charset="UTF-8">
+            </head>
+            <body>
+                <div>
+                    <h1>Microdot Main Page</h1>
+                    <p>Visit the <a href="/subapp">sub-app</a>.</p>
+                </div>
+            </body>
+        </html>
+    ''', 200, {'Content-Type': 'text/html'}
+
+
+app.run(debug=True)

examples/subapps/subapp.py

@@ -0,0 +1,44 @@
+from microdot import Microdot
+
+subapp = Microdot()
+
+
+@subapp.route('')
+async def hello(request):
+    # request.url_prefix can be used in links that are relative to this subapp
+    return f'''
+        <!DOCTYPE html>
+        <html>
+            <head>
+                <title>Microdot Sub-App Example</title>
+                <meta charset="UTF-8">
+            </head>
+            <body>
+                <div>
+                    <h1>Microdot Sub-App Main Page</h1>
+                    <p>Visit the sub-app's <a href="{request.url_prefix}/second">secondary page</a>.</p>
+                    <p>Go back to the app's <a href="/">main page</a>.</p>
+                </div>
+            </body>
+        </html>
+    ''', 200, {'Content-Type': 'text/html'}  # noqa: E501
+
+
+@subapp.route('/second')
+async def second(request):
+    return f'''
+        <!DOCTYPE html>
+        <html>
+            <head>
+                <title>Microdot Sub-App Example</title>
+                <meta charset="UTF-8">
+            </head>
+            <body>
+                <div>
+                    <h1>Microdot Sub-App Secondary Page</h1>
+                    <p>Visit the sub-app's <a href="{request.url_prefix}">main page</a>.</p>
+                    <p>Go back to the app's <a href="/">main page</a>.</p>
+                </div>
+            </body>
+        </html>
+    ''', 200, {'Content-Type': 'text/html'}  # noqa: E501

examples/templates/jinja/async_template.py

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

examples/templates/jinja/bootstrap.py

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

examples/templates/jinja/hello.py

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

examples/templates/jinja/hello_asgi.py

@@ -1,5 +1,5 @@
-from microdot_asyncio import Microdot, Response
-from microdot_utemplate import render_template
+from microdot.asgi import Microdot, Response
+from microdot.jinja import Template
 
 app = Microdot()
 Response.default_content_type = 'text/html'
@@ -10,7 +10,7 @@ async def index(req):
     name = None
     if req.method == 'POST':
         name = req.form.get('name')
-    return render_template('index.html', name=name)
+    return Template('index.html').render(name=name)
 
 
 if __name__ == '__main__':

examples/templates/jinja/hello_wsgi.py

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

examples/templates/jinja/streaming.py

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

examples/templates/utemplate/async_template.py

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

examples/templates/utemplate/bootstrap.py

@@ -1,18 +1,18 @@
 from microdot import Microdot, Response
-from microdot_utemplate import render_template
+from microdot.utemplate import Template
 
 app = Microdot()
 Response.default_content_type = 'text/html'
 
 
 @app.route('/')
-def index(req):
-    return render_template('page1.html', page='Page 1')
+async def index(req):
+    return Template('page1.html').render(page='Page 1')
 
 
 @app.route('/page2')
-def page2(req):
-    return render_template('page2.html', page='Page 2')
+async def page2(req):
+    return Template('page2.html').render(page='Page 2')
 
 
 if __name__ == '__main__':

examples/templates/utemplate/hello.py

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

examples/templates/utemplate/hello_asgi.py

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

examples/templates/utemplate/hello_wsgi.py

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

examples/templates/utemplate/streaming.py

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

examples/tls/echo_async_tls.py

@@ -1,23 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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.py

@@ -1,9 +1,10 @@
 import ssl
-from microdot_asyncio import Microdot
+import sys
+from microdot import Microdot
 
 app = Microdot()
 
-htmldoc = '''<!DOCTYPE html>
+html = '''<!DOCTYPE html>
 <html>
     <head>
         <title>Microdot Example Page</title>
@@ -22,7 +23,7 @@ htmldoc = '''<!DOCTYPE html>
 
 @app.route('/')
 async def hello(request):
-    return htmldoc, 200, {'Content-Type': 'text/html'}
+    return html, 200, {'Content-Type': 'text/html'}
 
 
 @app.route('/shutdown')
@@ -31,6 +32,7 @@ async def shutdown(request):
     return 'The server is shutting down...'
 
 
+ext = 'der' if sys.implementation.name == 'micropython' else 'pem'
 sslctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
-sslctx.load_cert_chain('cert.pem', 'key.pem')
+sslctx.load_cert_chain('cert.' + ext, 'key.' + ext)
 app.run(port=4443, debug=True, ssl=sslctx)

examples/tls/hello_tls.py

@@ -1,37 +0,0 @@
-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>
-        <meta charset="UTF-8">
-    </head>
-    <body>
-        <div>
-            <h1>Microdot Example Page</h1>
-            <p>Hello from Microdot!</p>
-            <p><a href="/shutdown">Click to shutdown the server</a></p>
-        </div>
-    </body>
-</html>
-'''
-
-
-@app.route('/')
-def hello(request):
-    return 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

@@ -1,36 +0,0 @@
-<!doctype html>
-<html>
-  <head>
-    <title>Microdot TLS WebSocket Demo</title>
-    <meta charset="UTF-8">
-  </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

@@ -1 +1,4 @@
 This directory contains file upload examples.
+
+- `simple_uploads.py` demonstrates how to upload a single file.
+- `formdata.py` demonstrates how to process a form that includes file uploads.

examples/uploads/formdata.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Microdot Multipart Form-Data Example</title>
+    <meta charset="UTF-8">
+  </head>
+  <body>
+    <h1>Microdot Multipart Form-Data Example</h1>
+    <form method="POST" action="" enctype="multipart/form-data">
+      <p>Name: <input type="text" name="name" /></p>
+      <p>Age: <input type="text" name="age" /></p>
+      <p>Comments: <textarea name="comments" rows="4"></textarea></p>
+      <p>File: <input type="file" id="file" name="file" /></p>
+      <input type="submit" value="Submit" />
+    </form>
+  </body>
+</html>

examples/uploads/formdata.py

@@ -0,0 +1,26 @@
+from microdot import Microdot, send_file, Request
+from microdot.multipart import with_form_data
+
+app = Microdot()
+Request.max_content_length = 1024 * 1024  # 1MB (change as needed)
+
+
+@app.get('/')
+async def index(request):
+    return send_file('formdata.html')
+
+
+@app.post('/')
+@with_form_data
+async def upload(request):
+    print('Form fields:')
+    for field, value in request.form.items():
+        print(f'- {field}: {value}')
+    print('\nFile uploads:')
+    for field, value in request.files.items():
+        print(f'- {field}: {value.filename}, {await value.read()}')
+    return 'We have received your data!'
+
+
+if __name__ == '__main__':
+    app.run(debug=True)

examples/uploads/simple_uploads.py

@@ -1,4 +1,4 @@
-from microdot_asyncio import Microdot, send_file, Request
+from microdot import Microdot, send_file, Request
 
 app = Microdot()
 Request.max_content_length = 1024 * 1024  # 1MB (change as needed)
@@ -6,7 +6,7 @@ Request.max_content_length = 1024 * 1024  # 1MB (change as needed)
 
 @app.get('/')
 async def index(request):
-    return send_file('index.html')
+    return send_file('simple_uploads.html')
 
 
 @app.post('/upload')

examples/uploads/uploads.py

@@ -1,34 +0,0 @@
-from microdot import Microdot, send_file, Request
-
-app = Microdot()
-Request.max_content_length = 1024 * 1024  # 1MB (change as needed)
-
-
-@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(debug=True)

examples/websocket/echo.py

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

examples/websocket/echo_asgi.py

@@ -1,11 +1,10 @@
-from microdot_asgi import Microdot, send_file
-from microdot_asgi_websocket import with_websocket
+from microdot.asgi import Microdot, send_file, with_websocket
 
 app = Microdot()
 
 
 @app.route('/')
-def index(request):
+async def index(request):
     return send_file('index.html')
 
 
@@ -15,3 +14,7 @@ async def echo(request, ws):
     while True:
         data = await ws.receive()
         await ws.send(data)
+
+
+if __name__ == '__main__':
+    app.run()

examples/websocket/echo_async.py

@@ -1,20 +0,0 @@
-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

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

libs/circuitpython/adafruit_ticks.py

@@ -0,0 +1,139 @@
+# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
+# SPDX-FileCopyrightText: Copyright (c) 2021 Jeff Epler for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_ticks`
+================================================================================
+
+Work with intervals and deadlines in milliseconds
+
+
+* Author(s): Jeff Epler
+
+Implementation Notes
+--------------------
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://github.com/adafruit/circuitpython/releases
+
+"""
+
+# imports
+from micropython import const
+
+__version__ = "0.0.0+auto.0"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_ticks.git"
+
+_TICKS_PERIOD = const(1 << 29)
+_TICKS_MAX = const(_TICKS_PERIOD - 1)
+_TICKS_HALFPERIOD = const(_TICKS_PERIOD // 2)
+
+# Get the correct implementation of ticks_ms.  There are three possibilities:
+#
+#  - supervisor.ticks_ms is present.  This will be the case starting in CP7.0
+#
+#  - time.ticks_ms is present. This is the case for MicroPython & for the "unix
+#    port" of CircuitPython, used for some automated testing.
+#
+#  - time.monotonic_ns is present, and works.  This is the case on most
+#    Express boards in CP6.x, and most host computer versions of Python.
+#
+#  - Otherwise, time.monotonic is assumed to be present.  This is the case
+#    on most non-express boards in CP6.x, and some old host computer versions
+#    of Python.
+#
+#    Note that on microcontrollers, this time source becomes increasingly
+#    inaccurate when the board has not been reset in a long time, losing the
+#    ability to measure 1ms intervals after about 1 hour, and losing the
+#    ability to meausre 128ms intervals after 6 days.  The only solution is to
+#    either upgrade to a version with supervisor.ticks_ms, or to switch to a
+#    board with time.monotonic_ns.
+
+try:
+    from supervisor import ticks_ms  # pylint: disable=unused-import
+except (ImportError, NameError):
+    import time
+
+    if _ticks_ms := getattr(time, "ticks_ms", None):
+
+        def ticks_ms() -> int:
+            """Return the time in milliseconds since an unspecified moment,
+            wrapping after 2**29ms.
+
+            The wrap value was chosen so that it is always possible to add or
+            subtract two `ticks_ms` values without overflow on a board without
+            long ints (or without allocating any long integer objects, on
+            boards with long ints).
+
+            This ticks value comes from a low-accuracy clock internal to the
+            microcontroller, just like `time.monotonic`.  Due to its low
+            accuracy and the fact that it "wraps around" every few days, it is
+            intended for working with short term events like advancing an LED
+            animation, not for long term events like counting down the time
+            until a holiday."""
+            return _ticks_ms() & _TICKS_MAX  # pylint: disable=not-callable
+
+    else:
+        try:
+            from time import monotonic_ns as _monotonic_ns
+
+            _monotonic_ns()  # Check that monotonic_ns is usable
+
+            def ticks_ms() -> int:
+                """Return the time in milliseconds since an unspecified moment,
+                wrapping after 2**29ms.
+
+                The wrap value was chosen so that it is always possible to add or
+                subtract two `ticks_ms` values without overflow on a board without
+                long ints (or without allocating any long integer objects, on
+                boards with long ints).
+
+                This ticks value comes from a low-accuracy clock internal to the
+                microcontroller, just like `time.monotonic`.  Due to its low
+                accuracy and the fact that it "wraps around" every few days, it is
+                intended for working with short term events like advancing an LED
+                animation, not for long term events like counting down the time
+                until a holiday."""
+                return (_monotonic_ns() // 1_000_000) & _TICKS_MAX
+
+        except (ImportError, NameError, NotImplementedError):
+            from time import monotonic as _monotonic
+
+            def ticks_ms() -> int:
+                """Return the time in milliseconds since an unspecified moment,
+                wrapping after 2**29ms.
+
+                The wrap value was chosen so that it is always possible to add or
+                subtract two `ticks_ms` values without overflow on a board without
+                long ints (or without allocating any long integer objects, on
+                boards with long ints).
+
+                This ticks value comes from a low-accuracy clock internal to the
+                microcontroller, just like `time.monotonic`.  Due to its low
+                accuracy and the fact that it "wraps around" every few days, it is
+                intended for working with short term events like advancing an LED
+                animation, not for long term events like counting down the time
+                until a holiday."""
+                return int(_monotonic() * 1000) & _TICKS_MAX
+
+
+def ticks_add(ticks: int, delta: int) -> int:
+    "Add a delta to a base number of ticks, performing wraparound at 2**29ms."
+    return (ticks + delta) % _TICKS_PERIOD
+
+
+def ticks_diff(ticks1: int, ticks2: int) -> int:
+    """Compute the signed difference between two ticks values,
+    assuming that they are within 2**28 ticks"""
+    diff = (ticks1 - ticks2) & _TICKS_MAX
+    diff = ((diff + _TICKS_HALFPERIOD) & _TICKS_MAX) - _TICKS_HALFPERIOD
+    return diff
+
+
+def ticks_less(ticks1: int, ticks2: int) -> bool:
+    """Return true if ticks1 is before ticks2 and false otherwise,
+    assuming that they are within 2**28 ticks"""
+    return ticks_diff(ticks1, ticks2) < 0

libs/circuitpython/asyncio/__init__.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: 2019 Damien P. George
+#
+# SPDX-License-Identifier: MIT
+#
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019 Damien P. George
+#
+# This code comes from MicroPython, and has not been run through black or pylint there.
+# Altering these files significantly would make merging difficult, so we will not use
+# pylint or black.
+# pylint: skip-file
+# fmt: off
+
+from .core import *
+
+__version__ = "0.0.0+auto.0"
+__repo__ = "https://github.com/Adafruit/Adafruit_CircuitPython_asyncio.git"
+
+_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/circuitpython/asyncio/core.py

@@ -0,0 +1,430 @@
+# SPDX-FileCopyrightText: 2019 Damien P. George
+#
+# SPDX-License-Identifier: MIT
+#
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019 Damien P. George
+#
+# This code comes from MicroPython, and has not been run through black or pylint there.
+# Altering these files significantly would make merging difficult, so we will not use
+# pylint or black.
+# pylint: skip-file
+# fmt: off
+"""
+Core
+====
+"""
+
+from adafruit_ticks import ticks_ms as ticks, ticks_diff, ticks_add
+import sys, select
+
+try:
+    from traceback import print_exception
+except:
+    from .traceback import print_exception
+
+# Import TaskQueue and Task, preferring built-in C code over Python code
+try:
+    from _asyncio import TaskQueue, Task
+except ImportError:
+    from .task import TaskQueue, Task
+
+################################################################################
+# Exceptions
+
+
+# Depending on the release of CircuitPython these errors may or may not
+# exist in the C implementation of `_asyncio`.  However, when they
+# do exist, they must be preferred over the Python code.
+try:
+    from _asyncio import CancelledError, InvalidStateError
+except (ImportError, AttributeError):
+    class CancelledError(BaseException):
+        """Injected into a task when calling `Task.cancel()`"""
+        pass
+
+
+    class InvalidStateError(Exception):
+        """Can be raised in situations like setting a result value for a task object that already has a result value set."""
+        pass
+
+
+class TimeoutError(Exception):
+    """Raised when waiting for a task longer than the specified timeout."""
+
+    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 __await__(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()):
+    """Sleep for *t* milliseconds.
+
+    This is a coroutine, and a MicroPython extension.
+    """
+
+    assert sgen.state is None, "Check for a missing `await` in your code"
+    sgen.state = ticks_add(ticks(), max(0, t))
+    return sgen
+
+
+# Pause task execution for the given time (in seconds)
+def sleep(t):
+    """Sleep for *t* seconds
+
+    This is a coroutine.
+    """
+
+    return sleep_ms(int(t * 1000))
+
+
+################################################################################
+# "Never schedule" object"
+# Don't re-schedule the object that awaits _never().
+# For internal use only. Some constructs, like `await event.wait()`,
+# work by NOT re-scheduling the task which calls wait(), but by
+# having some other task schedule it later.
+class _NeverSingletonGenerator:
+    def __init__(self):
+        self.state = None
+        self.exc = StopIteration()
+
+    def __iter__(self):
+        return self
+
+    def __await__(self):
+        return self
+
+    def __next__(self):
+        if self.state is not None:
+            self.state = None
+            return None
+        else:
+           self.exc.__traceback__ = None
+           raise self.exc
+
+def _never(sgen=_NeverSingletonGenerator()):
+    # assert sgen.state is None, "Check for a missing `await` in your code"
+    sgen.state = False
+    return sgen
+
+
+################################################################################
+# 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)
+
+    async def queue_read(self, s):
+        self._enqueue(s, 0)
+        await _never()
+
+    async def queue_write(self, s):
+        self._enqueue(s, 1)
+        await _never()
+
+    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):
+    """Create a new task from the given coroutine and schedule it to run.
+
+    Returns the corresponding `Task` object.
+    """
+
+    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):
+    """Run the given *main_task* until it completes."""
+
+    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:
+                # If the task is finished and on the run queue and gets here, then it
+                # had an exception and was not await'ed on.  Throwing into it now will
+                # raise StopIteration and the code below will catch this and run the
+                # call_exception_handler function.
+                t.data = None
+                t.coro.throw(exc)
+        except excs_all as er:
+            # 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
+            if t.state:
+                # Task was running but is now finished.
+                waiting = False
+                if t.state is True:
+                    # "None" indicates that the task is complete and not await'ed on (yet).
+                    t.state = None
+                elif callable(t.state):
+                    # The task has a callback registered to be called on completion.
+                    t.state(t, er)
+                    t.state = False
+                    waiting = True
+                else:
+                    # Schedule any other tasks waiting on the completion of this task.
+                    while t.state.peek():
+                        _task_queue.push_head(t.state.pop_head())
+                        waiting = True
+                    # "False" indicates that the task is complete and has been await'ed on.
+                    t.state = False
+                if not waiting and not isinstance(er, excs_stop):
+                    # An exception ended this detached task, so queue it for later
+                    # execution to handle the uncaught exception if no other task retrieves
+                    # the exception in the meantime (this is handled by Task.throw).
+                    _task_queue.push_head(t)
+                # Save return value of coro to pass up to caller.
+                t.data = er
+            elif t.state is None:
+                # Task is already finished and nothing await'ed on the task,
+                # so call the exception handler.
+                _exc_context["exception"] = exc
+                _exc_context["future"] = t
+                Loop.call_exception_handler(_exc_context)
+
+
+# Create a new task from a coroutine and run it until it finishes
+def run(coro):
+    """Create a new task from the given coroutine and run it until it completes.
+
+    Returns the value returned by *coro*.
+    """
+
+    return run_until_complete(create_task(coro))
+
+
+################################################################################
+# Event loop wrapper
+
+
+async def _stopper():
+    pass
+
+
+_stop_task = None
+
+
+class Loop:
+    """Class representing the event loop"""
+
+    _exc_handler = None
+
+    def create_task(coro):
+        """Create a task from the given *coro* and return the new `Task` object."""
+
+        return create_task(coro)
+
+    def run_forever():
+        """Run the event loop until `Loop.stop()` is called."""
+
+        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):
+        """Run the given *awaitable* until it completes.  If *awaitable* is not a task then
+        it will be promoted to one.
+        """
+
+        return run_until_complete(_promote_to_task(aw))
+
+    def stop():
+        """Stop the event loop"""
+
+        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():
+        """Close the event loop."""
+
+        pass
+
+    def set_exception_handler(handler):
+        """Set the exception handler to call when a Task raises an exception that is not
+        caught.  The *handler* should accept two arguments: ``(loop, context)``
+        """
+
+        Loop._exc_handler = handler
+
+    def get_exception_handler():
+        """Get the current exception handler. Returns the handler, or ``None`` if no
+        custom handler is set.
+        """
+
+        return Loop._exc_handler
+
+    def default_exception_handler(loop, context):
+        """The default exception handler that is called."""
+
+        exc = context["exception"]
+        print_exception(None, exc, exc.__traceback__)
+
+    def call_exception_handler(context):
+        """Call the current exception handler. The argument *context* is passed through
+        and is a dictionary containing keys:
+        ``'message'``, ``'exception'``, ``'future'``
+        """
+        (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 the event loop used to schedule and run tasks. See `Loop`."""
+
+    return Loop
+
+
+def current_task():
+    """Return the `Task` object associated with the currently running task."""
+
+    return cur_task
+
+
+def new_event_loop():
+    """Reset the event loop and return it.
+
+    **NOTE**: Since MicroPython only has a single event loop, this function just resets
+    the loop's state, it does not create a new one
+    """
+
+    global _task_queue, _io_queue, _exc_context, cur_task
+    # TaskQueue of Task instances
+    _task_queue = TaskQueue()
+    # Task queue and poller for stream IO
+    _io_queue = IOQueue()
+    cur_task = None
+    _exc_context['exception'] = None
+    _exc_context['future'] = None
+    return Loop
+
+
+# Initialise default event loop
+new_event_loop()

libs/circuitpython/asyncio/event.py

@@ -0,0 +1,92 @@
+# SPDX-FileCopyrightText: 2019-2020 Damien P. George
+#
+# SPDX-License-Identifier: MIT
+#
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2020 Damien P. George
+#
+# This code comes from MicroPython, and has not been run through black or pylint there.
+# Altering these files significantly would make merging difficult, so we will not use
+# pylint or black.
+# pylint: skip-file
+# fmt: off
+"""
+Events
+======
+"""
+
+from . import core
+
+# Event class for primitive events that can be waited on, set, and cleared
+class Event:
+    """Create a new event which can be used to synchronize tasks. Events
+    start in the cleared state.
+    """
+
+    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):
+        """Returns ``True`` if the event is set, ``False`` otherwise."""
+
+        return self.state
+
+    def set(self):
+        """Set the event. Any tasks waiting on the event will be scheduled to run.
+        """
+
+        # 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):
+        """Clear the event."""
+
+        self.state = False
+
+    async def wait(self):
+        """Wait for the event to be set. If the event is already set then it returns
+        immediately.
+
+        This is a coroutine.
+        """
+
+        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
+            await core._never()
+        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/circuitpython/asyncio/funcs.py

@@ -0,0 +1,165 @@
+# SPDX-FileCopyrightText: 2019-2020 Damien P. George
+#
+# SPDX-License-Identifier: MIT
+#
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2022 Damien P. George
+#
+# This code comes from MicroPython, and has not been run through black or pylint there.
+# Altering these files significantly would make merging difficult, so we will not use
+# pylint or black.
+# pylint: skip-file
+# fmt: off
+"""
+Functions
+=========
+"""
+
+
+from . import core
+
+
+async def _run(waiter, aw):
+    try:
+        result = await aw
+        status = True
+    except BaseException as er:
+        result = None
+        status = er
+    if waiter.data is None:
+        # The waiter is still waiting, cancel it.
+        if waiter.cancel():
+            # Waiter was cancelled by us, change its CancelledError to an instance of
+            # CancelledError that contains the status and result of waiting on aw.
+            # If the wait_for task subsequently gets cancelled externally then this
+            # instance will be reset to a CancelledError instance without arguments.
+            waiter.data = core.CancelledError(status, result)
+
+async def wait_for(aw, timeout, sleep=core.sleep):
+    """Wait for the *aw* awaitable to complete, but cancel if it takes longer
+    than *timeout* seconds. If *aw* is not a task then a task will be created
+    from it.
+
+    If a timeout occurs, it cancels the task and raises ``asyncio.TimeoutError``:
+    this should be trapped by the caller.
+
+    Returns the return value of *aw*.
+
+    This is a coroutine.
+    """
+
+    aw = core._promote_to_task(aw)
+    if timeout is None:
+        return await aw
+
+    # Run aw in a separate runner task that manages its exceptions.
+    runner_task = core.create_task(_run(core.cur_task, aw))
+
+    try:
+        # Wait for the timeout to elapse.
+        await sleep(timeout)
+    except core.CancelledError as er:
+        status = er.args[0] if er.args else None
+        if status is None:
+            # This wait_for was cancelled externally, so cancel aw and re-raise.
+            runner_task.cancel()
+            raise er
+        elif status is True:
+            # aw completed successfully and cancelled the sleep, so return aw's result.
+            return er.args[1]
+        else:
+            # aw raised an exception, propagate it out to the caller.
+            raise status
+
+    # The sleep finished before aw, so cancel aw and raise TimeoutError.
+    runner_task.cancel()
+    await runner_task
+    raise core.TimeoutError
+
+
+def wait_for_ms(aw, timeout):
+    """Similar to `wait_for` but *timeout* is an integer in milliseconds.
+
+    This is a coroutine, and a MicroPython extension.
+    """
+
+    return wait_for(aw, timeout, core.sleep_ms)
+
+
+class _Remove:
+    @staticmethod
+    def remove(t):
+        pass
+
+
+async def gather(*aws, return_exceptions=False):
+    """Run all *aws* awaitables concurrently. Any *aws* that are not tasks
+    are promoted to tasks.
+
+    Returns a list of return values of all *aws*
+    """
+    if not aws:
+        return []
+
+    def done(t, er):
+        # Sub-task "t" has finished, with exception "er".
+        nonlocal state
+        if gather_task.data is not _Remove:
+            # The main gather task has already been scheduled, so do nothing.
+            # This happens if another sub-task already raised an exception and
+            # woke the main gather task (via this done function), or if the main
+            # gather task was cancelled externally.
+            return
+        elif not return_exceptions and not isinstance(er, StopIteration):
+            # A sub-task raised an exception, indicate that to the gather task.
+            state = er
+        else:
+            state -= 1
+            if state:
+                # Still some sub-tasks running.
+                return
+        # Gather waiting is done, schedule the main gather task.
+        core._task_queue.push_head(gather_task)
+
+    ts = [core._promote_to_task(aw) for aw in aws]
+    for i in range(len(ts)):
+        if ts[i].state is not True:
+            # Task is not running, gather not currently supported for this case.
+            raise RuntimeError("can't gather")
+        # Register the callback to call when the task is done.
+        ts[i].state = done
+
+    # Set the state for execution of the gather.
+    gather_task = core.cur_task
+    state = len(ts)
+    cancel_all = False
+
+    # Wait for the a sub-task to need attention.
+    gather_task.data = _Remove
+    try:
+        await core._never()
+    except core.CancelledError as er:
+        cancel_all = True
+        state = er
+
+    # Clean up tasks.
+    for i in range(len(ts)):
+        if ts[i].state is done:
+            # Sub-task is still running, deregister the callback and cancel if needed.
+            ts[i].state = True
+            if cancel_all:
+                ts[i].cancel()
+        elif isinstance(ts[i].data, StopIteration):
+            # Sub-task ran to completion, get its return value.
+            ts[i] = ts[i].data.value
+        else:
+            # Sub-task had an exception with return_exceptions==True, so get its exception.
+            ts[i] = ts[i].data
+
+    # Either this gather was cancelled, or one of the sub-tasks raised an exception with
+    # return_exceptions==False, so reraise the exception here.
+    if state is not 0:
+        raise state
+
+    # Return the list of return values of each sub-task.
+    return ts

libs/circuitpython/asyncio/lock.py

@@ -0,0 +1,87 @@
+# SPDX-FileCopyrightText: 2019-2020 Damien P. George
+#
+# SPDX-License-Identifier: MIT
+#
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2020 Damien P. George
+#
+# This code comes from MicroPython, and has not been run through black or pylint there.
+# Altering these files significantly would make merging difficult, so we will not use
+# pylint or black.
+# pylint: skip-file
+# fmt: off
+"""
+Locks
+=====
+"""
+
+from . import core
+
+# Lock class for primitive mutex capability
+class Lock:
+    """Create a new lock which can be used to coordinate tasks. Locks start in
+    the unlocked state.
+
+    In addition to the methods below, locks can be used in an ``async with``
+    statement.
+    """
+
+    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):
+        """Returns ``True`` if the lock is locked, otherwise ``False``."""
+
+        return self.state == 1
+
+    def release(self):
+        """Release the lock. If any tasks are waiting on the lock then the next
+        one in the queue is scheduled to run and the lock remains locked. Otherwise,
+        no tasks are waiting and the lock becomes unlocked.
+        """
+
+        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):
+        """Wait for the lock to be in the unlocked state and then lock it in an
+        atomic way. Only one task can acquire the lock at any one time.
+
+        This is a coroutine.
+        """
+
+        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:
+                await core._never()
+            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/circuitpython/asyncio/manifest.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2019 Damien P. George
+#
+# SPDX-License-Identifier: MIT
+#
+#
+# This code comes from MicroPython, and has not been run through black or pylint there.
+# Altering these files significantly would make merging difficult, so we will not use
+# pylint or black.
+# pylint: skip-file
+# fmt: off
+
+# 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/circuitpython/asyncio/stream.py

@@ -0,0 +1,263 @@
+# SPDX-FileCopyrightText: 2019-2020 Damien P. George
+#
+# SPDX-License-Identifier: MIT
+#
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2020 Damien P. George
+#
+# This code comes from MicroPython, and has not been run through black or pylint there.
+# Altering these files significantly would make merging difficult, so we will not use
+# pylint or black.
+# pylint: skip-file
+# fmt: off
+"""
+Streams
+=======
+"""
+
+from . import core
+
+
+class Stream:
+    """This represents a TCP stream connection. To minimise code this class
+    implements both a reader and a writer, and both ``StreamReader`` and
+    ``StreamWriter`` alias to this class.
+    """
+
+    def __init__(self, s, e={}):
+        self.s = s
+        self.e = e
+        self.out_buf = b""
+
+    def get_extra_info(self, v):
+        """Get extra information about the stream, given by *v*. The valid
+        values for *v* are: ``peername``.
+        """
+
+        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):
+        """Wait for the stream to close.
+
+        This is a coroutine.
+        """
+
+        # TODO yield?
+        self.s.close()
+
+    async def read(self, n):
+        """Read up to *n* bytes and return them.
+
+        This is a coroutine.
+        """
+
+        await core._io_queue.queue_read(self.s)
+        return self.s.read(n)
+
+    async def readinto(self, buf):
+        """Read up to n bytes into *buf* with n being equal to the length of *buf*
+
+        Return the number of bytes read into *buf*
+
+        This is a coroutine, and a MicroPython extension.
+        """
+
+        await core._io_queue.queue_read(self.s)
+        return self.s.readinto(buf)
+
+    async def readexactly(self, n):
+        """Read exactly *n* bytes and return them as a bytes object.
+
+        Raises an ``EOFError`` exception if the stream ends before reading
+        *n* bytes.
+
+        This is a coroutine.
+        """
+
+        r = b""
+        while n:
+            await 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):
+        """Read a line and return it.
+
+        This is a coroutine.
+        """
+
+        l = b""
+        while True:
+            await 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):
+        """Accumulated *buf* to the output buffer. The data is only flushed when
+        `Stream.drain` is called. It is recommended to call `Stream.drain`
+        immediately after calling this function.
+        """
+        if not self.out_buf:
+            # Try to write immediately to the underlying stream.
+            ret = self.s.write(buf)
+            if ret == len(buf):
+                return
+            if ret is not None:
+                buf = buf[ret:]
+
+        self.out_buf += buf
+
+    async def drain(self):
+        """Drain (write) all buffered output data out to the stream.
+
+        This is a coroutine.
+        """
+
+        mv = memoryview(self.out_buf)
+        off = 0
+        while off < len(mv):
+            await 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):
+    """Open a TCP connection to the given *host* and *port*. The *host* address will
+    be resolved using `socket.getaddrinfo`, which is currently a blocking call.
+
+    Returns a pair of streams: a reader and a writer stream. Will raise a socket-specific
+    ``OSError`` if the host could not be resolved or if the connection could not be made.
+
+    This is a coroutine.
+    """
+
+    from uerrno import EINPROGRESS
+    import usocket as socket
+
+    ai = socket.getaddrinfo(host, port, 0, socket.SOCK_STREAM)[0]  # TODO this is blocking!
+    s = socket.socket(ai[0], ai[1], ai[2])
+    s.setblocking(False)
+    ss = Stream(s)
+    try:
+        s.connect(ai[-1])
+    except OSError as er:
+        if er.errno != EINPROGRESS:
+            raise er
+    await 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:
+    """This represents the server class returned from `start_server`.  It can be used in
+    an ``async with`` statement to close the server upon exit.
+    """
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        self.close()
+        await self.wait_closed()
+
+    def close(self):
+        """Close the server."""
+
+        self.task.cancel()
+
+    async def wait_closed(self):
+        """Wait for the server to close.
+
+        This is a coroutine.
+        """
+
+        await self.task
+
+    async def _serve(self, s, cb):
+        # Accept incoming connections
+        while True:
+            try:
+                await 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):
+    """Start a TCP server on the given *host* and *port*. The *cb* callback will be
+    called with incoming, accepted connections, and be passed 2 arguments: reader
+    writer streams for the connection.
+
+    Returns a `Server` object.
+
+    This is a coroutine.
+    """
+
+    import usocket as socket
+
+    # Create and bind server socket.
+    host = 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(host[-1])
+    s.listen(backlog)
+
+    # Create and return server object and task.
+    srv = Server()
+    srv.task = core.create_task(srv._serve(s, cb))
+    return srv
+
+
+################################################################################
+# 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/circuitpython/asyncio/task.py

@@ -0,0 +1,215 @@
+# SPDX-FileCopyrightText: 2019-2020 Damien P. George
+#
+# SPDX-License-Identifier: MIT
+#
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2020 Damien P. George
+#
+# This code comes from MicroPython, and has not been run through black or pylint there.
+# Altering these files significantly would make merging difficult, so we will not use
+# pylint or black.
+# pylint: skip-file
+# fmt: off
+"""
+Tasks
+=====
+"""
+
+# 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(self, v, key=None):
+        assert v.ph_child is None
+        assert v.ph_next is None
+        v.data = None
+        v.ph_key = key if key is not None else core.ticks()
+        self.heap = ph_meld(v, self.heap)
+
+    def pop(self):
+        v = self.heap
+        assert v.ph_next is None
+        self.heap = ph_pairing(v.ph_child)
+        v.ph_child = None
+        return v
+
+    def remove(self, v):
+        self.heap = ph_delete(self.heap, v)
+
+    # Compatibility aliases, remove after they are no longer used
+    push_head = push
+    push_sorted = push
+    pop_head = pop
+
+# Task class representing a coroutine, can be waited on and cancelled.
+class Task:
+    """This object wraps a coroutine into a running task. Tasks can be waited on
+    using ``await task``, which will wait for the task to complete and return the
+    return value of the task.
+
+    Tasks should not be created directly, rather use ``create_task`` to create them.
+    """
+
+    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.state = True  # None, False, True, a callable, or a TaskQueue instance
+        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 not self.state:
+            # Task finished, signal that is has been await'ed on.
+            self.state = False
+        elif self.state is True:
+            # Allocated head of linked list of Tasks waiting on completion of this task.
+            self.state = TaskQueue()
+        elif type(self.state) is not TaskQueue:
+            # Task has state used for another purpose, so can't also wait on it.
+            raise RuntimeError("can't wait")
+        return self
+
+    # CircuitPython needs __await()__.
+    __await__ = __iter__
+
+    def __next__(self):
+        if not self.state:
+            if self.data is None:
+                # Task finished but has already been sent to the loop's exception handler.
+                raise StopIteration
+            else:
+                # Task finished, raise return value to caller so it can continue.
+                raise self.data
+        else:
+            # Put calling task on waiting queue.
+            self.state.push(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):
+        """Whether the task is complete."""
+
+        return not self.state
+
+    def cancel(self):
+        """Cancel the task by injecting a ``CancelledError`` into it. The task
+        may or may not ignore this exception.
+        """
+
+        # Check if task is already finished.
+        if not self.state:
+            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(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(self)
+        self.data = core.CancelledError
+        return True

libs/circuitpython/asyncio/traceback.py

@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: 2019-2020 Damien P. George
+#
+# SPDX-License-Identifier: MIT
+#
+# MicroPython uasyncio module
+# MIT license; Copyright (c) 2019-2020 Damien P. George
+"""
+Fallback traceback module if the system traceback is missing.
+"""
+
+try:
+    from typing import List
+except ImportError:
+    pass
+
+import sys
+
+
+def _print_traceback(traceback, limit=None, file=sys.stderr) -> List[str]:
+    if limit is None:
+        if hasattr(sys, "tracebacklimit"):
+            limit = sys.tracebacklimit
+
+    n = 0
+    while traceback is not None:
+        frame = traceback.tb_frame
+        line_number = traceback.tb_lineno
+        frame_code = frame.f_code
+        filename = frame_code.co_filename
+        name = frame_code.co_name
+        print('  File "%s", line %d, in %s' % (filename, line_number, name), file=file)
+        traceback = traceback.tb_next
+        n = n + 1
+        if limit is not None and n >= limit:
+            break
+
+
+def print_exception(exception, value=None, traceback=None, limit=None, file=sys.stderr):
+    """
+    Print exception information and stack trace to file.
+    """
+    if traceback:
+        print("Traceback (most recent call last):", file=file)
+        _print_traceback(traceback, limit=limit, file=file)
+
+    if isinstance(exception, BaseException):
+        exception_type = type(exception).__name__
+    elif hasattr(exception, "__name__"):
+        exception_type = exception.__name__
+    else:
+        exception_type = type(value).__name__
+
+    valuestr = str(value)
+    if value is None or not valuestr:
+        print(exception_type, file=file)
+    else:
+        print("%s: %s" % (str(exception_type), valuestr), file=file)

libs/common/utemplate/README.md

@@ -1,8 +1,6 @@
 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

libs/micropython/asyncio/__init__.py

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

libs/micropython/asyncio/core.py

@@ -1,4 +1,4 @@
-# MicroPython uasyncio module
+# MicroPython asyncio module
 # MIT license; Copyright (c) 2019 Damien P. George
 
 from time import ticks_ms as ticks, ticks_diff, ticks_add
@@ -6,7 +6,7 @@ import sys, select
 
 # Import TaskQueue and Task, preferring built-in C code over Python code
 try:
-    from _uasyncio import TaskQueue, Task
+    from _asyncio import TaskQueue, Task
 except:
     from .task import TaskQueue, Task
 
@@ -30,6 +30,7 @@ _exc_context = {"message": "Task exception wasn't retrieved", "exception": None,
 ################################################################################
 # Sleep functions
 
+
 # "Yield" once, then raise StopIteration
 class SingletonGenerator:
     def __init__(self):
@@ -132,6 +133,7 @@ class IOQueue:
 ################################################################################
 # Main run loop
 
+
 # Ensure the awaitable is a task
 def _promote_to_task(aw):
     return aw if isinstance(aw, Task) else create_task(aw)
@@ -270,9 +272,9 @@ class Loop:
         return Loop._exc_handler
 
     def default_exception_handler(loop, context):
-        print(context["message"])
-        print("future:", context["future"], "coro=", context["future"].coro)
-        sys.print_exception(context["exception"])
+        print(context["message"], file=sys.stderr)
+        print("future:", context["future"], "coro=", context["future"].coro, file=sys.stderr)
+        sys.print_exception(context["exception"], sys.stderr)
 
     def call_exception_handler(context):
         (Loop._exc_handler or Loop.default_exception_handler)(Loop, context)

libs/micropython/asyncio/event.py

@@ -1,8 +1,9 @@
-# MicroPython uasyncio module
+# MicroPython asyncio module
 # MIT license; Copyright (c) 2019-2020 Damien P. George
 
 from . import core
 
+
 # Event class for primitive events that can be waited on, set, and cleared
 class Event:
     def __init__(self):
@@ -23,7 +24,8 @@ class Event:
     def clear(self):
         self.state = False
 
-    async def wait(self):
+    # async
+    def wait(self):
         if not self.state:
             # Event not set, put the calling task on the event's waiting queue
             self.waiting.push(core.cur_task)
@@ -38,16 +40,16 @@ class Event:
 # that asyncio will poll until a flag is set.
 # Note: Unlike Event, this is self-clearing after a wait().
 try:
-    import uio
+    import io
 
-    class ThreadSafeFlag(uio.IOBase):
+    class ThreadSafeFlag(io.IOBase):
         def __init__(self):
             self.state = 0
 
         def ioctl(self, req, flags):
             if req == 3:  # MP_STREAM_POLL
                 return self.state * flags
-            return None
+            return -1  # Other requests are unsupported
 
         def set(self):
             self.state = 1

libs/micropython/asyncio/funcs.py

@@ -1,10 +1,10 @@
-# MicroPython uasyncio module
+# MicroPython asyncio module
 # MIT license; Copyright (c) 2019-2022 Damien P. George
 
 from . import core
 
 
-def _run(waiter, aw):
+async def _run(waiter, aw):
     try:
         result = await aw
         status = True
@@ -61,7 +61,8 @@ class _Remove:
         pass
 
 
-async def gather(*aws, return_exceptions=False):
+# async
+def gather(*aws, return_exceptions=False):
     if not aws:
         return []
 
@@ -122,7 +123,7 @@ async def gather(*aws, return_exceptions=False):
 
     # Either this gather was cancelled, or one of the sub-tasks raised an exception with
     # return_exceptions==False, so reraise the exception here.
-    if state is not 0:
+    if state:
         raise state
 
     # Return the list of return values of each sub-task.

libs/micropython/asyncio/lock.py

@@ -1,8 +1,9 @@
-# MicroPython uasyncio module
+# MicroPython asyncio module
 # MIT license; Copyright (c) 2019-2020 Damien P. George
 
 from . import core
 
+
 # Lock class for primitive mutex capability
 class Lock:
     def __init__(self):
@@ -28,7 +29,8 @@ class Lock:
             # No Task waiting so unlock
             self.state = 0
 
-    async def acquire(self):
+    # async
+    def acquire(self):
         if self.state != 0:
             # Lock unavailable, put the calling Task on the waiting queue
             self.waiting.push(core.cur_task)

libs/micropython/asyncio/manifest.py

@@ -1,7 +1,7 @@
 # This list of package files doesn't include task.py because that's provided
 # by the C module.
 package(
-    "uasyncio",
+    "asyncio",
     (
         "__init__.py",
         "core.py",
@@ -13,3 +13,6 @@ package(
     base_path="..",
     opt=3,
 )
+
+# Backwards-compatible uasyncio module.
+module("uasyncio.py", opt=3)