Release 2.0.7

Bumps [werkzeug](https://github.com/pallets/werkzeug) from 3.0.3 to 3.0.6.
- [Release notes](https://github.com/pallets/werkzeug/releases)
- [Changelog](https://github.com/pallets/werkzeug/blob/main/CHANGES.rst)
- [Commits](https://github.com/pallets/werkzeug/compare/3.0.3...3.0.6)

---
updated-dependencies:
- dependency-name: werkzeug
  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/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']
       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

.readthedocs.yaml

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

CHANGES.md

@@ -1,5 +1,81 @@
 # Microdot change log
 
+**Release 2.0.7** - 2024-11-10
+
+- Accept responses with just a status code [#263](https://github.com/miguelgrinberg/microdot/issues/263) ([commit #1](https://github.com/miguelgrinberg/microdot/commit/4eac013087f807cafa244b8a6b7b0ed4c82ff150) [commit #2](https://github.com/miguelgrinberg/microdot/commit/c46e4291061046f1be13f300dd08645b71c16635))
+- Fixed compressed file content-type assignment [#251](https://github.com/miguelgrinberg/microdot/issues/251) ([commit](https://github.com/miguelgrinberg/microdot/commit/482ab6d5ca068d71ea6301f45918946161e9fcc1)) (thanks **Lukas Kremla**!)
+- Better documentation for start_server[#252](https://github.com/miguelgrinberg/microdot/issues/252) ([commit](https://github.com/miguelgrinberg/microdot/commit/0a021462e0c42c249d587a2d600f5a21a408adfc))
+- Fix URLs in documentation [#253](https://github.com/miguelgrinberg/microdot/issues/253) ([commit](https://github.com/miguelgrinberg/microdot/commit/5e5fc5e93e11cbf6e3dc8036494e8732d1815d3e)) (thanks **Stanislav Garanzha**!)
+
+**Release 2.0.6** - 2024-06-18
+
+- Add event ID to the SSE implementation [#213](https://github.com/miguelgrinberg/microdot/issues/213) ([commit](https://github.com/miguelgrinberg/microdot/commit/904d5fcaa2d19d939a719b8e68c4dee3eb470739)) (thanks **Hamsanger**!)
+- Configurable session cookie options [#242](https://github.com/miguelgrinberg/microdot/issues/242) ([commit](https://github.com/miguelgrinberg/microdot/commit/0151611fc84fec450820d673f4c4d70c32c990a7))
+- Improved cookie support in the test client ([commit](https://github.com/miguelgrinberg/microdot/commit/4cb155ee411dc2d9c9f15714cb32b25ba79b156a))
+- Cookie path support in session extension and test client ([commit](https://github.com/miguelgrinberg/microdot/commit/6ffb8a8fe920111c4d8c16e98715a0d5ee2d1da3))
+- Refactor `Session` class to make it more reusable ([commit](https://github.com/miguelgrinberg/microdot/commit/dea79c5ce224dec7858ffef45a42bed442fd3a5a))
+- Use `@functools.wraps` on decorated functions ([commit](https://github.com/miguelgrinberg/microdot/commit/f6876c0d154adcae96098405fb6a1fdf1ea4ec28))
+- Removed outdated import from documentation [#216](https://github.com/miguelgrinberg/microdot/issues/216) ([commit](https://github.com/miguelgrinberg/microdot/commit/6b1fd6191702e7a9ad934fddfcdd0a3cebea7c94)) (thanks **Carlo Colombo**!)
+- Add roadmap details to readme ([commit](https://github.com/miguelgrinberg/microdot/commit/a0ea439def238084c4d68309c0992b66ffd28ad6))
+
+**Release 2.0.5** - 2024-03-09
+
+- Correct handling of 0 as an integer argument (regression from #207) [#212](https://github.com/miguelgrinberg/microdot/issues/212) ([commit](https://github.com/miguelgrinberg/microdot/commit/d0a4cf8fa7dfb1da7466157b18d3329a8cf9a5df))
+
+**Release 2.0.4** - 2024-02-20
+
+- Do not use regexes for parsing simple URLs [#207](https://github.com/miguelgrinberg/microdot/issues/207) ([commit #1](https://github.com/miguelgrinberg/microdot/commit/38262c56d34784401659639b482a4a1224e1e59a) [commit #2](https://github.com/miguelgrinberg/microdot/commit/f6cba2c0f7e18e2f32b5adb779fb037b6c473eab))
+- Added documentation on using alternative uTemplate loaders ([commit](https://github.com/miguelgrinberg/microdot/commit/bf519478cbc6e296785241cd7d01edb23c317cd3))
+- Added CircuitPython builds ([commit](https://github.com/miguelgrinberg/microdot/commit/e44c271bae88f4327d3eda16d8780ac264d1ebab))
+
+**Release 2.0.3** - 2024-01-07
+
+- Add a limit to WebSocket message size [#193](https://github.com/miguelgrinberg/microdot/issues/193) ([commit](https://github.com/miguelgrinberg/microdot/commit/5d188e8c0ddef6ce633ca702dbdd4a90f2799597))
+- Pass keyword arguments to thread executor in the correct way [#195](https://github.com/miguelgrinberg/microdot/issues/195) ([commit](https://github.com/miguelgrinberg/microdot/commit/6712c47400d7c426c88032f65ab74466524eccab))
+- Update uasyncio library used in tests to include new TLS support ([commit](https://github.com/miguelgrinberg/microdot/commit/c8c91e83457d24320f22c9a74e80b15e06b072ca))
+- Documentation improvements ([commit](https://github.com/miguelgrinberg/microdot/commit/b80b6b64d02d21400ca8a5077f5ed1127cc202ae))
+
+**Release 2.0.2** - 2023-12-28
+
+- Support binary data in the SSE extension ([commit](https://github.com/miguelgrinberg/microdot/commit/1fc11193da0d298f5539e2ad218836910a13efb2))
+- Upgrade micropython tests to use v1.22 + initial CircuitPython testing work ([commit](https://github.com/miguelgrinberg/microdot/commit/79452a46992351ccad2c0317c20bf50be0d76641))
+- Improvements to migration guide ([commit](https://github.com/miguelgrinberg/microdot/commit/84842e39c360a8b3ddf36feac8af201fb19bbb0b))
+- Remove spurious async in documentation example [#187](https://github.com/miguelgrinberg/microdot/issues/187) ([commit](https://github.com/miguelgrinberg/microdot/commit/ad368be993e2e3007579f1d3880e36d60c71da92)) (thanks **Tak Tran**!)
+
+**Release 2.0.1** - 2023-12-23
+
+- Addressed some inadvertent mistakes in the template extensions ([commit](https://github.com/miguelgrinberg/microdot/commit/bd18ceb4424e9dfb52b1e6d498edd260aa24fc53))
+
+**Release 2.0.0** - 2023-12-22
+
+- Major redesign [#186](https://github.com/miguelgrinberg/microdot/issues/186) ([commit](https://github.com/miguelgrinberg/microdot/commit/20ea305fe793eb206b52af9eb5c5f3c1e9f57dbb))
+    - Code reorganization as a `microdot` package
+    - Asyncio is now the core implementation
+    - New support for Server-Sent Events (SSE)
+    - Several extensions redesigned
+    - Support for "partitioned" cookies
+    - [Cross-compiling and freezing](https://microdot.readthedocs.io/en/stable/freezing.html) guidance
+    - A [Migration Guide](https://microdot.readthedocs.io/en/stable/migrating.html) to help transition to version 2 from older releases
+
+**Release 1.3.4** - 2023-11-08
+
+- Handle change in `wait_closed()` behavior in Python 3.12 [#177](https://github.com/miguelgrinberg/microdot/issues/177) ([commit](https://github.com/miguelgrinberg/microdot/commit/5550b20cdd347d59e2aa68f6ebf9e9abffaff9fc))
+- Added missing request argument in some documentation examples [#163](https://github.com/miguelgrinberg/microdot/issues/163) ([commit](https://github.com/miguelgrinberg/microdot/commit/744548f8dc33a72512b34c4001ee9c6c1edd22ee))
+- Fix minor documentation typos [#161](https://github.com/miguelgrinberg/microdot/issues/161) ([commit](https://github.com/miguelgrinberg/microdot/commit/2e4911d10826cbb3914de4a45e495c3be36543fa)) (thanks **Andy Piper**!)
+
+**Release 1.3.3** - 2023-07-16
+
+- Handle query string arguments without value [#149](https://github.com/miguelgrinberg/microdot/issues/149) ([commit](https://github.com/miguelgrinberg/microdot/commit/3554bc91cb1523efa5b66fe3ef173f8e86e8c2a0))
+- Support empty responses with ASGI adapter ([commit](https://github.com/miguelgrinberg/microdot/commit/e09e9830f43af41d38775547637558494151a385))
+- Added CORS extension to Python package ([commit](https://github.com/miguelgrinberg/microdot/commit/304ca2ef6881fe718126b3e308211e760109d519))
+- Document access to WSGI and ASGI attributes [#153](https://github.com/miguelgrinberg/microdot/issues/153) ([commit](https://github.com/miguelgrinberg/microdot/commit/d99df2c4010ab70c60b86ab334d656903e04eb26))
+- Upgrade micropython tests to use v1.20 ([commit](https://github.com/miguelgrinberg/microdot/commit/e0f0565551966ee0238a5a1819c78a13639ad704))
+
+**Release 1.3.2** - 2023-06-13
+
+- In ASGI, return headers as strings and not binary [#144](https://github.com/miguelgrinberg/microdot/issues/144) ([commit](https://github.com/miguelgrinberg/microdot/commit/e92310fa55bbffcdcbb33f560e27c3579d7ac451))
+- Incorrect import in `static_async.py` example ([commit](https://github.com/miguelgrinberg/microdot/commit/c07a53943508e64baea160748e67efc92e75b036))
+
 **Release 1.3.1** - 2023-05-21
 
 - Support negative numbers for int path components [#137](https://github.com/miguelgrinberg/microdot/issues/137) ([commit](https://github.com/miguelgrinberg/microdot/commit/a0dd7c8ab6d681932324e56ed101aba861a105a0))

MANIFEST.in

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

README.md

@@ -3,9 +3,9 @@
 
 *“The impossibly small web framework for Python and MicroPython”*
 
-Microdot is a minimalistic Python web framework inspired by Flask, and designed
+Microdot is a minimalistic Python web framework inspired by Flask. Given its
-to run on systems with limited resources such as microcontrollers. It runs on
+small size, it can run on systems with limited resources such as
-standard Python and on MicroPython.
+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:
+
+- Support for forms encoded in `multipart/form-data` format
+- Authentication support, similar to [Flask-Login](https://github.com/maxcountryman/flask-login) for Flask
+- 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,59 @@ API Reference
 .. autoclass:: microdot.Response
    :members:
 
-.. autoclass:: microdot.NoCaseDict
+
+WebSocket
+---------
+
+.. automodule:: microdot.websocket
    :members:
 
-.. autoclass:: microdot.MultiDict
+Server-Sent Events (SSE)
-   :members:
-
-``microdot_asyncio`` module
----------------------------
-
-.. autoclass:: microdot_asyncio.Microdot
-   :inherited-members:
-   :members:
-
-.. autoclass:: microdot_asyncio.Request
-   :inherited-members:
-   :members:
-
-.. autoclass:: microdot_asyncio.Response
-   :inherited-members:
-   :members:
-
-``microdot_utemplate`` module
------------------------------
-
-.. automodule:: microdot_utemplate
-   :members:
-
-``microdot_jinja`` module
--------------------------
-
-.. automodule:: microdot_jinja
-   :members:
-
-``microdot_session`` module
----------------------------
-
-.. automodule:: microdot_session
-   :members:
-
-``microdot_cors`` module
 ------------------------
 
-.. 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
+Cross-Origin Resource Sharing (CORS)
------------------------
+------------------------------------
 
-.. automodule:: microdot_ssl
+.. automodule:: microdot.cors
    :members:
 
-``microdot_test_client`` module
+Test Client
--------------------------------
+-----------
 
-.. autoclass:: microdot_test_client.TestClient
+.. automodule:: microdot.test_client
    :members:
 
-.. autoclass:: microdot_test_client.TestResponse
+ASGI
-   :members:
+----
 
-``microdot_asyncio_test_client`` module
+.. autoclass:: microdot.asgi.Microdot
----------------------------------------
-
-.. autoclass:: microdot_asyncio_test_client.TestClient
-   :members:
-
-.. autoclass:: microdot_asyncio_test_client.TestResponse
-   :members:
-
-``microdot_wsgi`` module
-------------------------
-
-.. autoclass:: microdot_wsgi.Microdot
    :members:
    :exclude-members: shutdown, run
 
-``microdot_asgi`` module
+WSGI
-------------------------
+----
 
-.. autoclass:: microdot_asgi.Microdot
+.. autoclass:: microdot.wsgi.Microdot
    :members:
    :exclude-members: shutdown, run

docs/extensions.rst

@@ -2,11 +2,11 @@ Core Extensions
 ---------------
 
 Microdot is a highly extensible web application framework. The extensions
-described in this section are maintained as part of the Microdot project and
+described in this section are maintained as part of the Microdot project in
-can be obtained from the same source code repository.
+the same source code repository.
 
-Asynchronous Support with Asyncio
+WebSocket Support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
 
 .. list-table::
    :align: left
@@ -15,35 +15,71 @@ Asynchronous Support with Asyncio
      - | CPython & MicroPython
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     -  | `websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/websocket.py>`_
-       | `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
 
    * - Required external dependencies
-     - | CPython: None
+     - | None
-       | MicroPython: `uasyncio <https://github.com/micropython/micropython/tree/master/extmod/uasyncio>`_
 
    * - Examples
-     - | `hello_async.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_async.py>`_
+     - | `echo.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo.py>`_
 
-Microdot can be extended to use an asynchronous programming model based on the
+The WebSocket extension gives the application the ability to handle WebSocket
-``asyncio`` package. When the :class:`Microdot <microdot_asyncio.Microdot>`
+requests. The :func:`with_websocket <microdot.websocket.with_websocket>`
-class is imported from the ``microdot_asyncio`` package, an asynchronous server
+decorator is used to mark a route handler as a WebSocket handler. Decorated
-is used, and handlers can be defined as coroutines.
+routes receive a WebSocket object as a second argument. The WebSocket object
+provides ``send()`` and ``receive()`` asynchronous methods to send and receive
+messages respectively.
 
-The example that follows uses ``asyncio`` coroutines for concurrency::
+Example::
 
-    from microdot_asyncio import Microdot
+        @app.route('/echo')
+        @with_websocket
+        async def echo(request, ws):
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
 
-    app = Microdot()
+Server-Sent Events Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    @app.route('/')
+.. list-table::
-    async def hello(request):
+   :align: left
-        return 'Hello, world!'
 
-    app.run()
+   * - Compatibility
+     - | CPython & MicroPython
 
-Rendering HTML Templates
+   * - Required Microdot source files
-~~~~~~~~~~~~~~~~~~~~~~~~
+     -  | `sse.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/sse.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `counter.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/sse/counter.py>`_
+
+The Server-Sent Events (SSE) extension simplifies the creation of a streaming
+endpoint that follows the SSE web standard. The :func:`with_sse <microdot.sse.with_sse>`
+decorator is used to mark a route as an SSE handler. Decorated routes receive
+an SSE object as second argument. The SSE object provides a ``send()``
+asynchronous method to send an event to the client.
+
+Example::
+
+    @app.route('/events')
+    @with_sse
+    async def events(request, sse):
+        for i in range(10):
+            await asyncio.sleep(1)
+            await sse.send({'counter': i})  # unnamed event
+        await sse.send('end', event='comment')  # named event
+
+.. note::
+   The SSE protocol is unidirectional, so there is no ``receive()`` method in
+   the SSE object. For bidirectional communication with the client, use the
+   WebSocket extension.
+
+Rendering Templates
+~~~~~~~~~~~~~~~~~~~
 
 Many web applications use HTML templates for rendering content to clients.
 Microdot includes extensions to render templates with the
@@ -61,37 +97,57 @@ Using the uTemplate Engine
      - | CPython & MicroPython
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `utemplate.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/utemplate.py>`_
-       | `microdot_utemplate.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_utemplate.py>`_
 
    * - Required external dependencies
      - | `utemplate <https://github.com/pfalcon/utemplate/tree/master/utemplate>`_
 
    * - Examples
      - | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/utemplate/hello.py>`_
-       | `hello_utemplate_async.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_utemplate_async.py>`_
 
-The :func:`render_template <microdot_utemplate.render_template>` function is
+The :class:`Template <microdot.utemplate.Template>` class is used to load a
-used to render HTML templates with the uTemplate engine. The first argument is
+template. The argument is the template filename, relative to the templates
-the template filename, relative to the templates directory, which is
+directory, which is *templates* by default.
-*templates* by default. Any additional arguments are passed to the template
+
-engine to be used as arguments.
+The ``Template`` object has a :func:`render() <microdot.utemplate.Template.render>`
+method that renders the template to a string. This method receives any
+arguments that are used by the template.
 
 Example::
 
-    from microdot_utemplate import render_template
+    from microdot.utemplate import Template
 
     @app.get('/')
-    def index(req):
+    async def index(req):
-        return render_template('index.html')
+        return Template('index.html').render()
+
+The ``Template`` object also has a :func:`generate() <microdot.utemplate.Template.generate>`
+method, which returns a generator instead of a string. The
+:func:`render_async() <microdot.utemplate.Template.render_async>` and
+:func:`generate_async() <microdot.utemplate.Template.generate_async>` methods
+are the asynchronous versions of these two methods.
 
 The default location from where templates are loaded is the *templates*
 subdirectory. This location can be changed with the
-:func:`init_templates <microdot_utemplate.init_templates>` function::
+:func:`Template.initialize <microdot.utemplate.Template.initialize>` class
+method::
 
-    from microdot_utemplate import init_templates
+    Template.initialize('my_templates')
 
-    init_templates('my_templates')
+By default templates are automatically compiled the first time they are
+rendered, or when their last modified timestamp is more recent than the
+compiledo file's timestamp. This loading behavior can be changed by switching
+to a different template loader. For example, if the templates are pre-compiled,
+the timestamp check and compile steps can be removed by switching to the
+"compiled" template loader::
+
+    from utemplate import compiled
+    from microdot.utemplate import Template
+
+    Template.initialize(loader_class=compiled.Loader)
+
+Consult the `uTemplate documentation <https://github.com/pfalcon/utemplate>`_
+for additional information regarding template loaders.
 
 Using the Jinja Engine
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -103,8 +159,7 @@ Using the Jinja Engine
      - | CPython only
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `jinja.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/jinja.py>`_
-       | `microdot_jinja.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_jinja.py>`_
 
    * - Required external dependencies
      - | `Jinja2 <https://jinja.palletsprojects.com/>`_
@@ -112,33 +167,43 @@ Using the Jinja Engine
    * - Examples
      - | `hello.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/jinja/hello.py>`_
 
-The :func:`render_template <microdot_jinja.render_template>` function is used
+The :class:`Template <microdot.jinja.Template>` class is used to load a
-to render HTML templates with the Jinja engine. The first argument is the
+template. The argument is the template filename, relative to the templates
-template filename, relative to the templates directory, which is *templates* by
+directory, which is *templates* by default.
-default. Any additional arguments are passed to the template engine to be used
+
-as arguments.
+The ``Template`` object has a :func:`render() <microdot.jinja.Template.render>`
+method that renders the template to a string. This method receives any
+arguments that are used by the template.
 
 Example::
 
-    from microdot_jinja import render_template
+    from microdot.jinja import Template
 
     @app.get('/')
-    def index(req):
+    async def index(req):
-        return render_template('index.html')
+        return Template('index.html').render()
+
+The ``Template`` object also has a :func:`generate() <microdot.jinja.Template.generate>`
+method, which returns a generator instead of a string.
 
 The default location from where templates are loaded is the *templates*
 subdirectory. This location can be changed with the
-:func:`init_templates <microdot_jinja.init_templates>` function::
+:func:`Template.initialize <microdot.jinja.Template.initialize>` class method::
 
-    from microdot_jinja import init_templates
+    Template.initialize('my_templates')
 
-    init_templates('my_templates')
+The ``initialize()`` method also accepts ``enable_async`` argument, which
+can be set to ``True`` if asynchronous rendering of templates is desired. If
+this option is enabled, then the
+:func:`render_async() <microdot.jinja.Template.render_async>` and
+:func:`generate_async() <microdot.jinja.Template.generate_async>` methods
+must be used.
 
 .. note::
     The Jinja extension is not compatible with MicroPython.
 
-Maintaing Secure User Sessions
+Maintaining Secure User Sessions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. list-table::
    :align: left
@@ -147,56 +212,48 @@ Maintaing Secure User Sessions
      - | CPython & MicroPython
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/session.py>`_
-       | `microdot_session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_session.py>`_
 
    * - Required external dependencies
      - | CPython: `PyJWT <https://pyjwt.readthedocs.io/>`_
        | MicroPython: `jwt.py <https://github.com/micropython/micropython-lib/blob/master/python-ecosys/pyjwt/jwt.py>`_,
-                      `hmac <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/hmac/hmac.py>`_
+                      `hmac.py <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/hmac/hmac.py>`_
 
    * - Examples
      - | `login.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/sessions/login.py>`_
 
 The session extension provides a secure way for the application to maintain
-user sessions. The session is stored as a signed cookie in the client's
+user sessions. The session data is stored as a signed cookie in the client's
 browser, in `JSON Web Token (JWT) <https://en.wikipedia.org/wiki/JSON_Web_Token>`_
 format.
 
-To work with user sessions, the application first must configure the secret key
+To work with user sessions, the application first must configure a secret key
 that will be used to sign the session cookies. It is very important that this
-key is kept secret. An attacker who is in possession of this key can generate
+key is kept secret, as its name implies. An attacker who is in possession of
-valid user session cookies with any contents.
+this key can generate valid user session cookies with any contents.
 
-To set the secret key, use the :func:`set_session_secret_key <microdot_session.set_session_secret_key>` function::
+To initialize the session extension and configure the secret key, create a
+:class:`Session <microdot.session.Session>` object::
 
-    from microdot_session import set_session_secret_key
+    Session(app, secret_key='top-secret')
 
-    set_session_secret_key('top-secret!')
+The :func:`with_session <microdot.session.with_session>` decorator is the
+most convenient way to retrieve the session at the start of a request::
 
-To :func:`get_session <microdot_session.get_session>`,
+    from microdot import Microdot, redirect
-:func:`update_session <microdot_session.update_session>` and
+    from microdot.session import Session, with_session
-:func:`delete_session <microdot_session.delete_session>` functions are used
-inside route handlers to retrieve, store and delete session data respectively.
-The :func:`with_session <microdot_session.with_session>` decorator is provided
-as a convenient way to retrieve the session at the start of a route handler.
-
-Example::
-
-    from microdot import Microdot
-    from microdot_session import set_session_secret_key, with_session, \
-        update_session, delete_session
 
     app = Microdot()
-    set_session_secret_key('top-secret')
+    Session(app, secret_key='top-secret')
 
     @app.route('/', methods=['GET', '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 'Not logged in'
@@ -204,10 +261,15 @@ Example::
             return 'Logged in as ' + username
 
     @app.post('/logout')
-    def logout(req):
+    @with_session
-        delete_session(req)
+    async def logout(req, session):
+        session.delete()
         return redirect('/')
 
+The :func:`save() <microdot.session.SessionDict.save>` and
+:func:`delete() <microdot.session.SessionDict.delete>` methods are used to update
+and destroy the user session respectively.
+
 Cross-Origin Resource Sharing (CORS)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -218,14 +280,13 @@ Cross-Origin Resource Sharing (CORS)
      - | CPython & MicroPython
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `cors.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/cors.py>`_
-       | `microdot_cors.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_cors.py>`_
 
    * - Required external dependencies
      - | None
 
    * - Examples
-     - | `cors.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/cors/cors.py>`_
+     - | `app.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/cors/app.py>`_
 
 The CORS extension provides support for `Cross-Origin Resource Sharing
 (CORS) <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_. CORS is a
@@ -234,18 +295,18 @@ resources from each other. For example, a web application running on
 ``https://example.com`` can access resources from ``https://api.example.com``.
 
 To enable CORS support, create an instance of the
-:class:`CORS <microdot_cors.CORS>` class and configure the desired options.
+:class:`CORS <microdot.cors.CORS>` class and configure the desired options.
 Example::
 
     from microdot import Microdot
-    from microdot_cors import CORS
+    from microdot.cors import CORS
 
     app = Microdot()
     cors = CORS(app, allowed_origins=['https://example.com'],
                 allow_credentials=True)
 
-WebSocket Support
+Testing with the Test Client
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. list-table::
    :align: left
@@ -254,96 +315,18 @@ WebSocket Support
      - | CPython & MicroPython
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/test_client.py>`_
-       | `microdot_websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_websocket.py>`_
 
    * - Required external dependencies
      - | None
 
-   * - Examples
+The Microdot Test Client is a utility class that can be used in tests to send
-     - | `echo.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo.py>`_
+requests into the application without having to start a web server.
-       | `echo_wsgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_wsgi.py>`_
-
-The WebSocket extension provides a way for the application to handle WebSocket
-requests. The :func:`websocket <microdot_websocket.with_websocket>` decorator
-is used to mark a route handler as a WebSocket handler. The handler receives
-a WebSocket object as a second argument. The WebSocket object provides
-``send()`` and ``receive()`` methods to send and receive messages respectively.
-
-Example::
-
-        @app.route('/echo')
-        @with_websocket
-        def echo(request, ws):
-            while True:
-                message = ws.receive()
-                ws.send(message)
-
-.. note::
-   An unsupported *microdot_websocket_alt.py* module, with the same
-   interface, is also provided. This module uses the native WebSocket support
-   in MicroPython that powers the WebREPL, and may provide slightly better
-   performance for MicroPython low-end boards. This module is not compatible
-   with CPython.
-
-Asynchronous WebSocket
-~~~~~~~~~~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
-       | `microdot_websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_websocket.py>`_
-       | `microdot_asyncio_websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio_websocket.py>`_
-
-   * - Required external dependencies
-     - | CPython: None
-       | MicroPython: `uasyncio <https://github.com/micropython/micropython/tree/master/extmod/uasyncio>`_
-
-   * - Examples
-     - | `echo_async.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_async.py>`_
-
-This extension has the same interface as the synchronous WebSocket extension,
-but the ``receive()`` and ``send()`` methods are asynchronous.
-
-.. note::
-   An unsupported *microdot_asgi_websocket.py* module, with the same
-   interface, is also provided. This module must be used instead of
-   *microdot_asyncio_websocket.py* when the ASGI support is used. The
-   `echo_asgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_asgi.py>`_
-   example shows how to use this module.
-
-HTTPS Support
-~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_ssl.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_ssl.py>`_
-
-   * - Examples
-     - | `hello_tls.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/tls/hello_tls.py>`_
-       | `hello_async_tls.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/tls/hello_async_tls.py>`_
-
-The ``run()`` function accepts an optional ``ssl`` argument, through which an
-initialized ``SSLContext`` object can be passed. MicroPython does not currently
-have a ``SSLContext`` implementation, so the ``microdot_ssl`` module provides
-a basic implementation that can be used to create a context.
 
 Example::
 
     from microdot import Microdot
-    from microdot_ssl import create_ssl_context
+    from microdot.test_client import TestClient
 
     app = Microdot()
 
@@ -351,88 +334,13 @@ Example::
     def index(req):
         return 'Hello, World!'
 
-    sslctx = create_ssl_context('cert.der', 'key.der')
-    app.run(port=4443, debug=True, ssl=sslctx)
-
-.. note::
-   The ``microdot_ssl`` module is only needed for MicroPython. When used under
-   CPython, this module creates a standard ``SSLContext`` instance.
-
-.. note::
-   The ``uasyncio`` library for MicroPython does not currently support TLS, so
-   this feature is not available for asynchronous applications on that
-   platform. The ``asyncio`` library for CPython is fully supported.
-
-Test Client
-~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_test_client.py>`_
-
-   * - Required external dependencies
-     - | None
-
-The Microdot Test Client is a utility class that can be used during testing to
-send requests into the application.
-
-Example::
-
-    from microdot import Microdot
-    from microdot_test_client import TestClient
-
-    app = Microdot()
-
-    @app.route('/')
-    def index(req):
-        return 'Hello, World!'
-
-    def test_app():
-        client = TestClient(app)
-        response = client.get('/')
-        assert response.text == 'Hello, World!'
-
-See the documentation for the :class:`TestClient <microdot_test_client.TestClient>`
-class for more details.
-
-Asynchronous Test Client
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython & MicroPython
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
-       | `microdot_test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_test_client.py>`_
-       | `microdot_asyncio_test_client.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio_test_client.py>`_
-
-   * - Required external dependencies
-     - | None
-
-Similar to the :class:`TestClient <microdot_test_client.TestClient>` class
-above, but for asynchronous applications.
-
-Example usage::
-
-    from microdot_asyncio_test_client import TestClient
-
     async def test_app():
         client = TestClient(app)
         response = await client.get('/')
         assert response.text == 'Hello, World!'
 
-See the :class:`reference documentation <microdot_asyncio_test_client.TestClient>`
+See the documentation for the :class:`TestClient <microdot.test_client.TestClient>`
-for details.
+class for more details.
 
 Deploying on a Production Web Server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -440,51 +348,7 @@ Deploying on a Production Web Server
 The ``Microdot`` class creates its own simple web server. This is enough for an
 application deployed with MicroPython, but when using CPython it may be useful
 to use a separate, battle-tested web server. To address this need, Microdot
-provides extensions that implement the WSGI and ASGI protocols.
+provides extensions that implement the ASGI and WSGI protocols.
-
-Using a WSGI Web Server
-^^^^^^^^^^^^^^^^^^^^^^^
-
-.. list-table::
-   :align: left
-
-   * - Compatibility
-     - | CPython only
-
-   * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
-       | `microdot_wsgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_wsgi.py>`_
-
-   * - Required external dependencies
-     - | A WSGI web server, such as `Gunicorn <https://gunicorn.org/>`_.
-
-   * - Examples
-     - | `hello_wsgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_wsgi.py>`_
-
-
-The ``microdot_wsgi`` module provides an extended ``Microdot`` class that
-implements the WSGI protocol and can be used with a compliant WSGI web server
-such as `Gunicorn <https://gunicorn.org/>`_ or
-`uWSGI <https://uwsgi-docs.readthedocs.io/en/latest/>`_.
-
-To use a WSGI web server, the application must import the
-:class:`Microdot <microdot_wsgi.Microdot>` class from the ``microdot_wsgi``
-module::
-
-    from microdot_wsgi import Microdot
-
-    app = Microdot()
-
-    @app.route('/')
-    def index(req):
-        return 'Hello, World!'
-
-The ``app`` application instance created from this class is a WSGI application
-that can be used with any complaint WSGI web server. If the above application
-is stored in a file called *test.py*, then the following command runs the
-web application using the Gunicorn web server::
-
-    gunicorn test:app
 
 Using an ASGI Web Server
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -496,25 +360,25 @@ Using an ASGI Web Server
      - | CPython only
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `asgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/asgi.py>`_
-       | `microdot_asyncio.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asyncio.py>`_
-       | `microdot_asgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot_asgi.py>`_
 
    * - Required external dependencies
-     - | An ASGI web server, such as `Uvicorn <https://uvicorn.org/>`_.
+     - | An ASGI web server, such as `Uvicorn <https://www.uvicorn.org/>`_.
 
    * - Examples
      - | `hello_asgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_asgi.py>`_
+       | `hello_asgi.py (uTemplate) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/utemplate/hello_asgi.py>`_
+       | `hello_asgi.py (Jinja) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/jinja/hello_asgi.py>`_
+       | `echo_asgi.py (WebSocket) <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_asgi.py>`_
 
-The ``microdot_asgi`` module provides an extended ``Microdot`` class that
+The ``asgi`` module provides an extended ``Microdot`` class that
 implements the ASGI protocol and can be used with a compliant ASGI server such
 as `Uvicorn <https://www.uvicorn.org/>`_.
 
 To use an ASGI web server, the application must import the
-:class:`Microdot <microdot_asgi.Microdot>` class from the ``microdot_asgi``
+:class:`Microdot <microdot.asgi.Microdot>` class from the ``asgi`` module::
-module::
 
-    from microdot_asgi import Microdot
+    from microdot.asgi import Microdot
 
     app = Microdot()
 
@@ -522,10 +386,67 @@ module::
     async def index(req):
         return 'Hello, World!'
 
-The ``app`` application instance created from this class is an ASGI application
+The ``app`` application instance created from this class can be used as the
-that can be used with any complaint ASGI web server. If the above application
+ASGI callable with any complaint ASGI web server. If the above example
-is stored in a file called *test.py*, then the following command runs the
+application was stored in a file called *test.py*, then the following command
-web application using the Uvicorn web server::
+runs the web application using the Uvicorn web server::
 
     uvicorn test:app
 
+When using the ASGI support, the ``scope`` dictionary provided by the web
+server is available to request handlers as ``request.asgi_scope``.
+
+Using a WSGI Web Server
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython only
+
+   * - Required Microdot source files
+     - | `wsgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/wsgi.py>`_
+
+   * - Required external dependencies
+     - | A WSGI web server, such as `Gunicorn <https://gunicorn.org/>`_.
+
+   * - Examples
+     - | `hello_wsgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_wsgi.py>`_
+       | `hello_wsgi.py (uTemplate) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/utemplate/hello_wsgi.py>`_
+       | `hello_wsgi.py (Jinja) <https://github.com/miguelgrinberg/microdot/blob/main/examples/templates/jinja/hello_wsgi.py>`_
+       | `echo_wsgi.py (WebSocket) <https://github.com/miguelgrinberg/microdot/blob/main/examples/websocket/echo_wsgi.py>`_
+
+
+The ``wsgi`` module provides an extended ``Microdot`` class that implements the
+WSGI protocol and can be used with a compliant WSGI web server such as 
+`Gunicorn <https://gunicorn.org/>`_ or
+`uWSGI <https://uwsgi-docs.readthedocs.io/en/latest/>`_.
+
+To use a WSGI web server, the application must import the
+:class:`Microdot <microdot.wsgi.Microdot>` class from the ``wsgi`` module::
+
+    from microdot.wsgi import Microdot
+
+    app = Microdot()
+
+    @app.route('/')
+    def index(req):
+        return 'Hello, World!'
+
+The ``app`` application instance created from this class can be used as a WSGI
+callbable with any complaint WSGI web server. If the above application
+was stored in a file called *test.py*, then the following command runs the
+web application using the Gunicorn web server::
+
+    gunicorn test:app
+
+When using the WSGI support, the ``environ`` dictionary provided by the web
+server is available to request handlers as ``request.environ``.
+
+.. note::
+    In spite of WSGI being a synchronous protocol, the Microdot application
+    internally runs under an asyncio event loop. For that reason, the
+    recommendation to prefer ``async def`` handlers over ``def`` still applies
+    under WSGI. Consult the :ref:`Concurrency` section for a discussion of how
+    the two types of functions are handled by Microdot.

docs/freezing.rst

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

docs/index.rst

@@ -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
+`Flask <https://flask.palletsprojects.com/>`_. Given its size, it can run on
-systems with limited resources such as microcontrollers. It runs on standard
+systems with limited resources such as microcontrollers. Both standard Python
-Python and on `MicroPython <https://micropython.org>`_.
+(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
+The installation method is different depending on the version of Python.
-can be installed with ``pip``::
+
+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,
+MicroPython Installation
-but the recommended approach is to manually copy *microdot.py* and any
+~~~~~~~~~~~~~~~~~~~~~~~~
-desired optional extension source files from the
+
+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
+This section describes the main features of Microdot in an informal manner.
-detailed reference information, consult the :ref:`API Reference`.
+
+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
+when the client requests the URL.
-:class:`Request <microdot.Request>` object as an argument, which provides
+
-access to the information passed by the client. The value returned by the
+When the function is called, it is passed a :class:`Request <microdot.Request>`
-function is sent back to the client as the response.
+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
+After starting the script, open a web browser and navigate to
-*http://localhost:5000/*, which is the default address for the Microdot web
+*http://localhost:5000/* to access the application at the default address for
-server. From other computers in the same network, use the IP address or
+the Microdot web server. From other computers in the same network, use the IP
-hostname of the computer running the script instead of ``localhost``.
+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
+server code to your device, along with the required Microdot files, as defined
-automatically run *main.py* when the device is powered on, so the web server
+in the :ref:`MicroPython Installation` section.
-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
+MicroPython will automatically run *main.py* when the device is powered on, so
-``port`` argument to the ``run()`` method.
+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
+All the example routes shown above are associated with ``GET`` requests, which
-applications often need to define routes for other HTTP methods, such as
+are the default. Applications often need to define routes for other HTTP
-``POST``, ``PUT``, ``PATCH`` and ``DELETE``. The ``route()`` decorator takes a
+methods, such as ``POST``, ``PUT``, ``PATCH`` and ``DELETE``. The ``route()``
-``methods`` optional argument, in which the application can provide a list of
+decorator takes a ``methods`` optional argument, in which the application can
-HTTP methods that the route should be associated with on the given path.
+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
+As an alternative to the example above, in which a single function is used to
-methods, it may be desirable to write a separate function for each HTTP method.
+handle multiple HTTP methods, sometimes it may be desirable to write a separate
-The above example can be implemented with two routes as follows::
+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
+:func:`delete() <microdot.Microdot.delete>` decorators as shortcuts for the
-two example routes above can be written more concisely with them::
+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
+As shown in the example, a path component that is enclosed in angle brackets
-is considered dynamic. Microdot accepts any values for that section of the URL
+is considered a placeholder. Microdot accepts any values for that portion of
-path, and passes the value received to the function as an argument after
+the URL path, and passes the value received to the function as an argument
-the request object.
+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,10 +321,12 @@ 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
@@ -237,7 +335,7 @@ 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
 
 .. note::
@@ -255,54 +353,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
+common closing or cleanup tasks. The next example shows a combination of
-and after request handlers that print the time it takes for a request to be
+before- and after-request handlers that print the time it takes for a request
-handled::
+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.
+After-request handlers receive the request and response objects as arguments,
-The function can return a modified response object to replace the original. If
+and they can return a modified response object to replace the original. If
-the function does not return a value, then the original response object is
+no value is returned from an after-request handler, then the original response
-used.
+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 :ref:`request.g <The "g" Object>` object used in many of the above
-   the before and after request handlers, as well sa the route function to
+   examples is a special object that allows the before- and after-request
-   share data during the life of the request.
+   handlers, as well as the route function to share data during the life of the
+   request.
 
 Error Handlers
 ^^^^^^^^^^^^^^
@@ -312,10 +412,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.
+- 404 for URLs that are unknown.
-- 405 for URLs that are defined, but not for the requested HTTP method.
+- 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 +425,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 class as an argument. Microdot will invoke the handler when an
-exception is an instance of the given class is raised. The next example
+unhandled exception that is an instance of the given class is raised. The next
-provides a custom response for division by zero errors::
+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
+Small Microdot applications can be written as a single source file, but this
-is not the best option for applications that past certain size. To make it
+is not the best option for applications that past a certain size. To make it
 simpler to write large applications, Microdot supports the concept of
 sub-applications that can be "mounted" on a larger application, possibly with
-a common URL prefix applied to all of its routes.
+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 +459,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 +474,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,7 +501,7 @@ 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
+   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
@@ -416,16 +518,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
 ^^^^^^^^^^^^^^^^^^
@@ -448,6 +554,9 @@ The request object provides access to the request attributes, including:
   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 +567,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}
@@ -475,7 +584,7 @@ The request object also supports standard HTML form submissions through the
 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')
@@ -493,14 +602,17 @@ 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
+If the expected body is too large to fit safely in memory, the application can
-:attr:`stream <microdot.Request.stream>` request attribute to read the body
+use the :attr:`stream <microdot.Request.stream>` request attribute to read the
-contents as a file-like object.
+body contents as a file-like object. The
+:attr:`max_body_length <microdot.Request.max_body_length>` attribute of the
+request object defines the size at which bodies are streamed instead of loaded
+into memory.
 
 Cookies
 ^^^^^^^
 
-Cookies that are sent by the client are made available throught the
+Cookies that are sent by the client are made available through the
 :attr:`cookies <microdot.Request.cookies>` attribute of the request object in
 dictionary form.
 
@@ -508,41 +620,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
+that it can be shared between the before- and after-request handlers, the
-route function. The request object provides the :attr:`g <microdot.Request.g>`
+route function and any error handlers. The request object provides the
-attribute for that purpose.
+:attr:`g <microdot.Request.g>` attribute for that purpose.
 
-In the following example, a before request handler
+In the following example, a before request handler authorizes the client and
-authorizes the client and stores the username so that the route function can
+stores the username so that the route function can use it::
-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
+Request-specific after-request handlers are called by Microdot after the route
-function returns and all the application's after request handlers have been
+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 +667,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
 
@@ -589,33 +702,34 @@ Route functions can return one, two or three values. The first or only value is
 always returned to the client in the response body::
 
     @app.get('/')
-    def index(request):
+    async def index(request):
         return 'Hello, World!'
 
 In the above example, Microdot issues a standard 200 status code response, and
-inserts the necessary headers.
+inserts default headers.
 
-The applicaton can provide its own status code as a second value returned from
+The application can provide its own status code as a second value returned from
-the route. The example below returns a 202 status code::
+the route to override the 200 default. The example below returns a 202 status
-
-    @app.get('/')
-    def index(request):
-        return 'Hello, World!', 202
-
-The application can also return a third value, a dictionary with additional
-headers that are added to, or replace the default ones provided by Microdot.
-The next example returns an HTML response, instead of a default text response::
-
-    @app.get('/')
-    def index(request):
-        return '<h1>Hello, World!</h1>', 202, {'Content-Type': 'text/html'}
-
-If the application needs to return custom headers, but does not need to change
-the default status code, then it can return two values, omitting the stauts
 code::
 
     @app.get('/')
-    def index(request):
+    async def index(request):
+        return 'Hello, World!', 202
+
+The application can also return a third value, a dictionary with additional
+headers that are added to, or replace the default ones included by Microdot.
+The next example returns an HTML response, instead of a default text response::
+
+    @app.get('/')
+    async def index(request):
+        return '<h1>Hello, World!</h1>', 202, {'Content-Type': 'text/html'}
+
+If the application needs to return custom headers, but does not need to change
+the default status code, then it can return two values, omitting the status
+code::
+
+    @app.get('/')
+    async def index(request):
         return '<h1>Hello, World!</h1>', {'Content-Type': 'text/html'}
 
 The application can also return a :class:`Response <microdot.Response>` object
@@ -631,7 +745,7 @@ automatically format the response as JSON.
 Example::
 
     @app.get('/')
-    def index(request):
+    async def index(request):
         return {'hello': 'world'}
 
 .. note::
@@ -647,7 +761,7 @@ creates redirect responses::
     from microdot import redirect
 
     @app.get('/')
-    def index(request):
+    async def index(request):
         return redirect('/about')
 
 File Responses
@@ -659,7 +773,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 +782,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 +792,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 +802,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
+return a response that is generated in chunks, by returning a Python generator.
-example below returns all the numbers in the fibonacci sequence below 100::
+The example below returns all the numbers in the fibonacci sequence below 100::
 
     @app.get('/fibonacci')
-    def fibonacci(request):
+    async def fibonacci(request):
-        def generate_fibonacci():
+        async def generate_fibonacci():
             a, b = 0, 1
             while a < 100:
                 yield str(a) + '\n'
@@ -701,6 +815,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 +850,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 +866,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
@@ -753,21 +875,24 @@ Another option is to create a response object directly in the route function::
    Standard cookies do not offer sufficient privacy and security controls, so
    never store sensitive information in them unless you are adding additional
    protection mechanisms such as encryption or cryptographic signing. The
-   :ref:`session <Maintaing Secure User Sessions>` extension implements signed
+   :ref:`session <Maintaining Secure User Sessions>` extension implements signed
    cookies that prevent tampering by malicious actors.
 
 Concurrency
 ~~~~~~~~~~~
 
-By default, Microdot runs in synchronous (single-threaded) mode. However, if
+Microdot implements concurrency through the ``asyncio`` package. Applications
-the ``threading`` module is available, each request will be started on a
+must ensure their handlers do not block, as this will prevent other concurrent
-separate thread and requests will be handled concurrently.
+requests from being handled.
 
-Be aware that most microcontroller boards support a very limited form of
+When running under CPython, ``async def`` handler functions run as native 
-multi-threading that is not appropriate for concurrent request handling. For
+asyncio tasks, while ``def`` handler functions are executed in a
-that reason, use of the `threading <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/threading/threading.py>`_
+`thread executor <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor>`_
-module on microcontroller platforms is not recommended.
+to prevent them from blocking the asynchronous loop.
 
-The :ref:`micropython_asyncio <Asynchronous Support with Asyncio>` extension
+Under MicroPython the situation is different. Most microcontroller boards
-provides a more robust concurrency option that is supported even on low-end
+implementing MicroPython do not have threading support or executors, so ``def``
-MicroPython boards.
+handler functions in this platform can only run in the main and only thread.
+These functions will block the asynchronous loop when they take too long to
+complete so ``async def`` handlers properly written to allow other handlers to
+run in parallel should be preferred.

docs/migrating.rst

@@ -0,0 +1,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/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
+# This file is autogenerated by pip-compile with Python 3.12
-blinker==1.5
+# by the following command:
-certifi==2022.12.7
+#
-charset-normalizer==2.1.0
+#    pip-compile requirements.in
-click==8.1.3
+#
-fastapi==0.79.0
+aiofiles==23.2.1
-Flask==2.2.1
+    # via quart
-gunicorn==20.1.0
+annotated-types==0.6.0
-h11==0.13.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==22.0.0
+    # via -r requirements.in
+h11==0.14.0
+    # via
+    #   hypercorn
+    #   uvicorn
+    #   wsproto
 h2==4.1.0
+    # via hypercorn
 hpack==4.0.0
-humanize==4.3.0
+    # via h2
-hypercorn==0.13.2
+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
+    # via
-MarkupSafe==2.1.1
+    #   flask
-microdot
+    #   quart
+jinja2==3.1.4
+    # 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
+    # via hypercorn
-pydantic==1.9.1
+psutil==5.9.6
-quart==0.18.0
+    # via -r requirements.in
-requests==2.28.1
+pydantic==2.5.2
-sniffio==1.2.0
+    # via fastapi
-starlette==0.27.0
+pydantic-core==2.14.5
-toml==0.10.2
+    # via pydantic
-typing_extensions==4.3.0
+pyproject-hooks==1.0.0
-urllib3==1.26.11
+    # via build
-uvicorn==0.18.2
+quart==0.19.7
-Werkzeug==2.2.3
+    # via -r requirements.in
-wsproto==1.1.0
+requests==2.32.0
+    # 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.2.2
+    # 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'
+        'microdot-cpython'
-    ),
-    (
-        'python mem_async.py',
-        {'PYTHONPATH': '../../src'},
-        'microdot-cpython-async'
-    ),
-    (
-        'gunicorn --workers 1 --bind :5000 mem_wsgi:app',
-        {'PYTHONPATH': '../../src'},
-        'microdot-gunicorn-sync'
     ),
     (
         'uvicorn --workers 1 --port 5000 mem_asgi:app',
         {'PYTHONPATH': '../../src'},
-        'microdot-uvicorn-async'
+        '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/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):
+async def hello(request):
-    return htmldoc, 200, {'Content-Type': 'text/html'}
+    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/sessions/login.py

@@ -1,6 +1,5 @@
 from microdot import Microdot, Response, redirect
-from microdot_session import set_session_secret_key, with_session, \
+from microdot.session import Session, with_session
-    update_session, delete_session
 
 BASE_TEMPLATE = '''<!doctype html>
 <html>
@@ -29,18 +28,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 +50,9 @@ def index(req, session):
 
 
 @app.post('/logout')
-def logout(req):
+@with_session
-    delete_session(req)
+async def logout(req, session):
+    session.delete()
     return redirect('/')
 
 

examples/sse/counter.py

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

examples/static/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,19 +0,0 @@
-from microdot_asyncio import Microdot
-from microdot import 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 sys
-    import utime as time
+import asyncio
-except ImportError:
-    import time
-
 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):
+async def video_feed(request):
-    def stream():
+    print('Starting video stream.')
-        yield b'--frame\r\n'
+
-        while True:
+    if sys.implementation.name != 'micropython':
-            for frame in frames:
+        # CPython supports async generator function
-                yield b'Content-Type: image/jpeg\r\n\r\n' + frame + \
+        async def stream():
-                    b'\r\n--frame\r\n'
+            try:
-                time.sleep(1)
+                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/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):
+async def index(req):
-    return render_template('page1.html', page='Page 1')
+    return Template('page1.html').render(page='Page 1')
 
 
 @app.route('/page2')
-def page2(req):
+async def page2(req):
-    return render_template('page2.html', page='Page 2')
+    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.asgi import Microdot, Response
-from microdot_utemplate import render_template
+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):
+async def index(req):
-    return render_template('page1.html', page='Page 1')
+    return Template('page1.html').render(page='Page 1')
 
 
 @app.route('/page2')
-def page2(req):
+async def page2(req):
-    return render_template('page2.html', page='Page 2')
+    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/uploads.py

@@ -5,12 +5,12 @@ Request.max_content_length = 1024 * 1024  # 1MB (change as needed)
 
 
 @app.get('/')
-def index(request):
+async def index(request):
     return send_file('index.html')
 
 
 @app.post('/upload')
-def upload(request):
+async def upload(request):
     # obtain the filename and size from request headers
     filename = request.headers['Content-Disposition'].split(
         'filename=')[1].strip('"')
@@ -22,7 +22,7 @@ def upload(request):
     # 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))
+            chunk = await request.stream.read(min(size, 1024))
             f.write(chunk)
             size -= len(chunk)
 

examples/uploads/uploads_async.py

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

examples/websocket/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()
+        data = await ws.receive()
-        ws.send(data)
+        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 import Microdot, send_file, with_websocket
-from microdot_asgi_websocket import 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.wsgi import Microdot, send_file, 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()
+        data = await ws.receive()
-        ws.send(data)
+        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(context["message"], file=sys.stderr)
-        print("future:", context["future"], "coro=", context["future"].coro)
+        print("future:", context["future"], "coro=", context["future"].coro, file=sys.stderr)
-        sys.print_exception(context["exception"])
+        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)

libs/micropython/asyncio/stream.py

@@ -1,4 +1,4 @@
-# MicroPython uasyncio module
+# MicroPython asyncio module
 # MIT license; Copyright (c) 2019-2020 Damien P. George
 
 from . import core
@@ -13,12 +13,6 @@ class Stream:
     def get_extra_info(self, v):
         return self.e[v]
 
-    async def __aenter__(self):
-        return self
-
-    async def __aexit__(self, exc_type, exc, tb):
-        await self.close()
-
     def close(self):
         pass
 
@@ -26,7 +20,8 @@ class Stream:
         # TODO yield?
         self.s.close()
 
-    async def read(self, n=-1):
+    # async
+    def read(self, n=-1):
         r = b""
         while True:
             yield core._io_queue.queue_read(self.s)
@@ -38,11 +33,13 @@ class Stream:
                     return r
                 r += r2
 
-    async def readinto(self, buf):
+    # async
+    def readinto(self, buf):
         yield core._io_queue.queue_read(self.s)
         return self.s.readinto(buf)
 
-    async def readexactly(self, n):
+    # async
+    def readexactly(self, n):
         r = b""
         while n:
             yield core._io_queue.queue_read(self.s)
@@ -54,11 +51,14 @@ class Stream:
                 n -= len(r2)
         return r
 
-    async def readline(self):
+    # async
+    def readline(self):
         l = b""
         while True:
             yield core._io_queue.queue_read(self.s)
             l2 = self.s.readline()  # may do multiple reads but won't block
+            if l2 is None:
+                continue
             l += l2
             if not l2 or l[-1] == 10:  # \n (check l in case l2 is str)
                 return l
@@ -73,10 +73,11 @@ class Stream:
                 buf = buf[ret:]
         self.out_buf += buf
 
-    async def drain(self):
+    # async
+    def drain(self):
         if not self.out_buf:
             # Drain must always yield, so a tight loop of write+drain can't block the scheduler.
-            return await core.sleep_ms(0)
+            return (yield from core.sleep_ms(0))
         mv = memoryview(self.out_buf)
         off = 0
         while off < len(mv):
@@ -93,19 +94,31 @@ StreamWriter = Stream
 
 
 # Create a TCP stream connection to a remote host
-async def open_connection(host, port):
+#
-    from uerrno import EINPROGRESS
+# async
-    import usocket as socket
+def open_connection(host, port, ssl=None, server_hostname=None):
+    from errno import EINPROGRESS
+    import 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
+    # wrap with SSL, if requested
+    if ssl:
+        if ssl is True:
+            import ssl as _ssl
+
+            ssl = _ssl.SSLContext(_ssl.PROTOCOL_TLS_CLIENT)
+        if not server_hostname:
+            server_hostname = host
+        s = ssl.wrap_socket(s, server_hostname=server_hostname, do_handshake_on_connect=False)
+        s.setblocking(False)
+    ss = Stream(s)
     yield core._io_queue.queue_write(s)
     return ss, ss
 
@@ -120,25 +133,42 @@ class Server:
         await self.wait_closed()
 
     def close(self):
+        # Note: the _serve task must have already started by now due to the sleep
+        # in start_server, so `state` won't be clobbered at the start of _serve.
+        self.state = True
         self.task.cancel()
 
     async def wait_closed(self):
         await self.task
 
-    async def _serve(self, s, cb):
+    async def _serve(self, s, cb, ssl):
+        self.state = False
         # Accept incoming connections
         while True:
             try:
                 yield core._io_queue.queue_read(s)
-            except core.CancelledError:
+            except core.CancelledError as er:
-                # Shutdown server
+                # The server task was cancelled, shutdown server and close socket.
                 s.close()
-                return
+                if self.state:
+                    # If the server was explicitly closed, ignore the cancellation.
+                    return
+                else:
+                    # Otherwise e.g. the parent task was cancelled, propagate
+                    # cancellation.
+                    raise er
             try:
                 s2, addr = s.accept()
             except:
                 # Ignore a failed accept
                 continue
+            if ssl:
+                try:
+                    s2 = ssl.wrap_socket(s2, server_side=True, do_handshake_on_connect=False)
+                except OSError as e:
+                    core.sys.print_exception(e)
+                    s2.close()
+                    continue
             s2.setblocking(False)
             s2s = Stream(s2, {"peername": addr})
             core.create_task(cb(s2s, s2s))
@@ -146,8 +176,8 @@ class Server:
 
 # 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):
+async def start_server(cb, host, port, backlog=5, ssl=None):
-    import usocket as socket
+    import socket
 
     # Create and bind server socket.
     host = socket.getaddrinfo(host, port)[0]  # TODO this is blocking!
@@ -159,7 +189,17 @@ async def start_server(cb, host, port, backlog=5):
 
     # Create and return server object and task.
     srv = Server()
-    srv.task = core.create_task(srv._serve(s, cb))
+    srv.task = core.create_task(srv._serve(s, cb, ssl))
+    try:
+        # Ensure that the _serve task has been scheduled so that it gets to
+        # handle cancellation.
+        await core.sleep_ms(0)
+    except core.CancelledError as er:
+        # If the parent task is cancelled during this first sleep, then
+        # we will leak the task and it will sit waiting for the socket, so
+        # cancel it.
+        srv.task.cancel()
+        raise er
     return srv
 
 

libs/micropython/asyncio/task.py

@@ -1,4 +1,4 @@
-# MicroPython uasyncio module
+# MicroPython asyncio module
 # MIT license; Copyright (c) 2019-2020 Damien P. George
 
 # This file contains the core TaskQueue based on a pairing heap, and the core Task class.

libs/micropython/asyncio/uasyncio.py

@@ -0,0 +1,8 @@
+# This module just allows `import uasyncio` to work. It lazy-loads from
+# `asyncio` without duplicating its globals dict.
+
+
+def __getattr__(attr):
+    import asyncio
+
+    return getattr(asyncio, attr)

libs/micropython/ffilib.py

@@ -1,4 +1,5 @@
 import sys
+
 try:
     import ffi
 except ImportError:
@@ -6,6 +7,7 @@ except ImportError:
 
 _cache = {}
 
+
 def open(name, maxver=10, extra=()):
     if not ffi:
         return None
@@ -13,16 +15,18 @@ def open(name, maxver=10, extra=()):
         return _cache[name]
     except KeyError:
         pass
+
     def libs():
         if sys.platform == "linux":
-            yield '%s.so' % name
+            yield "%s.so" % name
             for i in range(maxver, -1, -1):
-                yield '%s.so.%u' % (name, i)
+                yield "%s.so.%u" % (name, i)
         else:
-            for ext in ('dylib', 'dll'):
+            for ext in ("dylib", "dll"):
-                yield '%s.%s' % (name, ext)
+                yield "%s.%s" % (name, ext)
         for n in extra:
             yield n
+
     err = None
     for n in libs():
         try:
@@ -33,9 +37,11 @@ def open(name, maxver=10, extra=()):
             err = e
     raise err
 
+
 def libc():
     return open("libc", 6)
 
+
 # Find out bitness of the platform, even if long ints are not supported
 # TODO: All bitness differences should be removed from micropython-lib, and
 # this snippet too.

libs/micropython/time.py

@@ -1,76 +0,0 @@
-from utime import *
-from ucollections import namedtuple
-import ustruct
-import uctypes
-import ffi
-import ffilib
-import array
-
-libc = ffilib.libc()
-
-# struct tm *gmtime(const time_t *timep);
-# struct tm *localtime(const time_t *timep);
-# size_t strftime(char *s, size_t max, const char *format,
-#                       const struct tm *tm);
-gmtime_ = libc.func("P", "gmtime", "P")
-localtime_ = libc.func("P", "localtime", "P")
-strftime_ = libc.func("i", "strftime", "sisP")
-mktime_ = libc.func("i", "mktime", "P")
-
-_struct_time = namedtuple("struct_time",
-    ["tm_year", "tm_mon", "tm_mday", "tm_hour", "tm_min", "tm_sec", "tm_wday", "tm_yday", "tm_isdst"])
-
-def _tuple_to_c_tm(t):
-    return ustruct.pack("@iiiiiiiii", t[5], t[4], t[3], t[2], t[1] - 1, t[0] - 1900, (t[6] + 1) % 7, t[7] - 1, t[8])
-
-
-def _c_tm_to_tuple(tm):
-    t = ustruct.unpack("@iiiiiiiii", tm)
-    return _struct_time(t[5] + 1900, t[4] + 1, t[3], t[2], t[1], t[0], (t[6] - 1) % 7, t[7] + 1, t[8])
-
-def struct_time(tm):
-    return _struct_time(*tm)
-
-
-def strftime(format, t=None):
-    if t is None:
-        t = localtime()
-
-    buf = bytearray(32)
-    l = strftime_(buf, 32, format, _tuple_to_c_tm(t))
-    return str(buf[:l], "utf-8")
-
-
-def localtime(t=None):
-    if t is None:
-        t = time()
-
-    t = int(t)
-    a = ustruct.pack('l', t)
-    tm_p = localtime_(a)
-    return _c_tm_to_tuple(uctypes.bytearray_at(tm_p, 36))
-
-
-def gmtime(t=None):
-    if t is None:
-        t = time()
-
-    t = int(t)
-    a = ustruct.pack('l', t)
-    tm_p = gmtime_(a)
-    return _c_tm_to_tuple(uctypes.bytearray_at(tm_p, 36))
-
-
-def mktime(tt):
-    return mktime_(_tuple_to_c_tm(tt))
-
-
-def perf_counter():
-    return time()
-
-def process_time():
-    return clock()
-
-
-daylight = 0
-timezone = 0

libs/micropython/unittest.py

@@ -300,9 +300,10 @@ class TestResult:
         return self.errorsNum == 0 and self.failuresNum == 0
 
     def printErrors(self):
-        print()
+        if self.errors or self.failures:
-        self.printErrorList(self.errors)
+            print()
-        self.printErrorList(self.failures)
+            self.printErrorList(self.errors)
+            self.printErrorList(self.failures)
 
     def printErrorList(self, lst):
         sep = "----------------------------------------------------------------------"

libs/refresh.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# this script downloads updated versions of all the MicroPython libraries
+
+cd micropython
+curl https://codeload.github.com/micropython/micropython/tar.gz/master | tar -xz --strip=2 micropython-master/extmod/asyncio
+curl https://raw.githubusercontent.com/micropython/micropython-lib/master/python-stdlib/datetime/datetime.py > datetime.py
+curl https://raw.githubusercontent.com/micropython/micropython-lib/d8e163bb5f3ef45e71e145c27bc4f207beaad70f/unix-ffi/ffilib/ffilib.py > ffilib.py
+curl https://raw.githubusercontent.com/micropython/micropython-lib/master/python-stdlib/hmac/hmac.py > hmac.py
+curl https://raw.githubusercontent.com/micropython/micropython-lib/master/python-stdlib/time/time.py > time.py
+curl https://raw.githubusercontent.com/micropython/micropython-lib/master/python-stdlib/unittest/unittest/__init__.py > unittest.py
+cd ../common
+curl https://raw.githubusercontent.com/pfalcon/utemplate/master/README.md > utemplate/README.md
+curl https://codeload.github.com/pfalcon/utemplate/tar.gz/master | tar -xz --strip=1 utemplate-master/utemplate
+cd ..

pyproject.toml

@@ -1,6 +1,54 @@
+[project]
+name = "microdot"
+version = "2.0.7"
+authors = [
+    { name = "Miguel Grinberg", email = "miguel.grinberg@gmail.com" },
+]
+description = "The impossibly small web framework for MicroPython"
+classifiers = [
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: Implementation :: MicroPython",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.8"
+dependencies = [
+]
+
+[project.readme]
+file = "README.md"
+content-type = "text/markdown"
+
+[project.urls]
+Homepage = "https://github.com/miguelgrinberg/microdot"
+"Bug Tracker" = "https://github.com/miguelgrinberg/microdot/issues"
+
+[project.optional-dependencies]
+dev = [
+    "tox",
+]
+docs = [
+    "sphinx",
+    "pyjwt",
+]
+
+[tool.setuptools]
+zip-safe = false
+include-package-data = true
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = [
+    "src",
+]
+namespaces = false
+
 [build-system]
 requires = [
-    "setuptools>=42",
+    "setuptools>=61.2",
-    "wheel"
 ]
 build-backend = "setuptools.build_meta"

run_tests.py

@@ -2,7 +2,11 @@ import sys
 
 sys.path.insert(0, 'src')
 sys.path.insert(2, 'libs/common')
-sys.path.insert(3, 'libs/micropython')
+if sys.implementation.name == 'circuitpython':
+    sys.path.insert(3, 'libs/circuitpython')
+    sys.path.insert(4, 'libs/micropython')
+else:
+    sys.path.insert(3, 'libs/micropython')
 
 import unittest
 

setup.cfg

@@ -1,38 +0,0 @@
-[metadata]
-name = microdot
-version = 1.3.1
-author = Miguel Grinberg
-author_email = miguel.grinberg@gmail.com
-description = The impossibly small web framework for MicroPython
-long_description = file: README.md
-long_description_content_type = text/markdown
-url = https://github.com/miguelgrinberg/microdot
-project_urls =
-    Bug Tracker = https://github.com/miguelgrinberg/microdot/issues
-classifiers =
-    Environment :: Web Environment
-    Intended Audience :: Developers
-    Programming Language :: Python :: 3
-    Programming Language :: Python :: Implementation :: MicroPython
-    License :: OSI Approved :: MIT License
-    Operating System :: OS Independent
-
-[options]
-zip_safe = False
-include_package_data = True
-package_dir =
-    = src
-py_modules =
-    microdot
-    microdot_asyncio
-    microdot_utemplate
-    microdot_jinja
-    microdot_session
-    microdot_websocket
-    microdot_websocket_alt
-    microdot_asyncio_websocket
-    microdot_test_client
-    microdot_asyncio_test_client
-    microdot_wsgi
-    microdot_asgi
-    microdot_asgi_websocket

setup.py

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

src/microdot/__init__.py

@@ -0,0 +1,2 @@
+from microdot.microdot import Microdot, Request, Response, abort, redirect, \
+    send_file  # noqa: F401

src/microdot/asgi.py

@@ -1,10 +1,10 @@
 import asyncio
 import os
 import signal
-from microdot_asyncio import *  # noqa: F401, F403
+from microdot import *  # noqa: F401, F403
-from microdot_asyncio import Microdot as BaseMicrodot
+from microdot.microdot import Microdot as BaseMicrodot, Request, Response, \
-from microdot_asyncio import Request
+    NoCaseDict, abort
-from microdot import NoCaseDict
+from microdot.websocket import WebSocket as BaseWebSocket, websocket_wrapper
 
 
 class _BodyStream:  # pragma: no cover
@@ -21,7 +21,7 @@ class _BodyStream:  # pragma: no cover
 
     async def read(self, n=-1):
         while self.more and len(self.data) < n:
-            self.read_more()
+            await self.read_more()
         if len(self.data) < n:
             data = self.data
             self.data = b''
@@ -32,19 +32,25 @@ class _BodyStream:  # pragma: no cover
         return data
 
     async def readline(self):
-        return self.readuntil()
+        return await self.readuntil()
 
     async def readexactly(self, n):
-        return self.read(n)
+        return await self.read(n)
 
     async def readuntil(self, separator=b'\n'):
         if self.more and separator not in self.data:
-            self.read_more()
+            await self.read_more()
         data, self.data = self.data.split(separator, 1)
         return data
 
 
 class Microdot(BaseMicrodot):
+    """A subclass of the core :class:`Microdot <microdot.Microdot>` class that
+    implements the ASGI protocol.
+
+    This class must be used as the application instance when running under an
+    ASGI web server.
+    """
     def __init__(self):
         super().__init__()
         self.embedded_server = False
@@ -59,8 +65,9 @@ class Microdot(BaseMicrodot):
         headers = NoCaseDict()
         content_length = 0
         for key, value in scope.get('headers', []):
-            headers[key] = value
+            key = key.decode().title()
-            if key.lower() == 'content-length':
+            headers[key] = value.decode()
+            if key == 'Content-Length':
                 content_length = int(value)
 
         if content_length and content_length <= Request.max_body_length:
@@ -112,25 +119,31 @@ class Microdot(BaseMicrodot):
 
             while True:
                 event = await receive()
-                if event['type'] == 'http.disconnect':  # pragma: no branch
+                if event is None or \
+                        event['type'] == 'http.disconnect':  # pragma: no cover
                     cancelled = True
                     break
 
-        asyncio.ensure_future(cancel_monitor())
+        monitor_task = asyncio.ensure_future(cancel_monitor())
 
         body_iter = res.body_iter().__aiter__()
+        res_body = b''
         try:
-            body = await body_iter.__anext__()
+            res_body = await body_iter.__anext__()
             while not cancelled:  # pragma: no branch
                 next_body = await body_iter.__anext__()
                 await send({'type': 'http.response.body',
-                            'body': body,
+                            'body': res_body,
                             'more_body': True})
-                body = next_body
+                res_body = next_body
         except StopAsyncIteration:
             await send({'type': 'http.response.body',
-                        'body': body,
+                        'body': res_body,
                         'more_body': False})
+        if hasattr(body_iter, 'aclose'):  # pragma: no branch
+            await body_iter.aclose()
+        cancelled = True
+        await monitor_task
 
     async def __call__(self, scope, receive, send):
         return await self.asgi_app(scope, receive, send)
@@ -150,3 +163,79 @@ class Microdot(BaseMicrodot):
         """
         self.embedded_server = True
         super().run(host=host, port=port, debug=debug, **options)
+
+
+class WebSocket(BaseWebSocket):  # pragma: no cover
+    async def handshake(self):
+        connect = await self.request.sock[0]()
+        if connect['type'] != 'websocket.connect':
+            abort(400)
+        await self.request.sock[1]({'type': 'websocket.accept'})
+
+    async def receive(self):
+        message = await self.request.sock[0]()
+        if message['type'] == 'websocket.disconnect':
+            raise OSError(32, 'Websocket connection closed')
+        elif message['type'] != 'websocket.receive':
+            raise OSError(32, 'Websocket message type not supported')
+        return message.get('bytes', message.get('text'))
+
+    async def send(self, data):
+        if isinstance(data, str):
+            await self.request.sock[1](
+                {'type': 'websocket.send', 'text': data})
+        else:
+            await self.request.sock[1](
+                {'type': 'websocket.send', 'bytes': data})
+
+    async def close(self):
+        if not self.closed:
+            self.closed = True
+            try:
+                await self.request.sock[1]({'type': 'websocket.close'})
+            except:  # noqa E722
+                pass
+
+
+async def websocket_upgrade(request):  # pragma: no cover
+    """Upgrade a request handler to a websocket connection.
+
+    This function can be called directly inside a route function to process a
+    WebSocket upgrade handshake, for example after the user's credentials are
+    verified. The function returns the websocket object::
+
+        @app.route('/echo')
+        async def echo(request):
+            if not (await authenticate_user(request)):
+                abort(401)
+            ws = await websocket_upgrade(request)
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
+    """
+    ws = WebSocket(request) if not request.app.embedded_server else \
+        BaseWebSocket(request)
+    await ws.handshake()
+
+    @request.after_request
+    async def after_request(request, response):
+        return Response.already_handled
+
+    return ws
+
+
+def with_websocket(f):  # pragma: no cover
+    """Decorator to make a route a WebSocket endpoint.
+
+    This decorator is used to define a route that accepts websocket
+    connections. The route then receives a websocket object as a second
+    argument that it can use to send and receive messages::
+
+        @app.route('/echo')
+        @with_websocket
+        async def echo(request, ws):
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
+    """
+    return websocket_wrapper(f, websocket_upgrade)

src/microdot/helpers.py

@@ -0,0 +1,8 @@
+try:
+    from functools import wraps
+except ImportError:  # pragma: no cover
+    # MicroPython does not currently implement functools.wraps
+    def wraps(wrapped):
+        def _(wrapper):
+            return wrapper
+        return _

src/microdot/jinja.py

@@ -0,0 +1,59 @@
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+_jinja_env = None
+
+
+class Template:
+    """A template object.
+
+    :param template: The filename of the template to render, relative to the
+                     configured template directory.
+    """
+    @classmethod
+    def initialize(cls, template_dir='templates', enable_async=False,
+                   **kwargs):
+        """Initialize the templating subsystem.
+
+        :param template_dir: the directory where templates are stored. This
+                             argument is optional. The default is to load
+                             templates from a *templates* subdirectory.
+        :param enable_async: set to ``True`` to enable the async rendering
+                             engine in Jinja, and the ``render_async()`` and
+                             ``generate_async()`` methods.
+        :param kwargs: any additional options to be passed to Jinja's
+                       ``Environment`` class.
+        """
+        global _jinja_env
+        _jinja_env = Environment(
+            loader=FileSystemLoader(template_dir),
+            autoescape=select_autoescape(),
+            enable_async=enable_async,
+            **kwargs
+        )
+
+    def __init__(self, template):
+        if _jinja_env is None:  # pragma: no cover
+            self.initialize()
+        #: The name of the template
+        self.name = template
+        self.template = _jinja_env.get_template(template)
+
+    def generate(self, *args, **kwargs):
+        """Return a generator that renders the template in chunks, with the
+        given arguments."""
+        return self.template.generate(*args, **kwargs)
+
+    def render(self, *args, **kwargs):
+        """Render the template with the given arguments and return it as a
+        string."""
+        return self.template.render(*args, **kwargs)
+
+    def generate_async(self, *args, **kwargs):
+        """Return an asynchronous generator that renders the template in
+        chunks, using the given arguments."""
+        return self.template.generate_async(*args, **kwargs)
+
+    async def render_async(self, *args, **kwargs):
+        """Render the template with the given arguments asynchronously and
+        return it as a string."""
+        return await self.template.render_async(*args, **kwargs)

src/microdot/microdot.py

@@ -3,9 +3,43 @@ microdot
 --------
 
 The ``microdot`` module defines a few classes that help implement HTTP-based
-servers for MicroPython and standard Python, with multithreading support for
+servers for MicroPython and standard Python.
-Python interpreters that support it.
 """
+import asyncio
+import io
+import json
+import time
+
+try:
+    from inspect import iscoroutinefunction, iscoroutine
+    from functools import partial
+
+    async def invoke_handler(handler, *args, **kwargs):
+        """Invoke a handler and return the result.
+
+        This method runs sync handlers in a thread pool executor.
+        """
+        if iscoroutinefunction(handler):
+            ret = await handler(*args, **kwargs)
+        else:
+            ret = await asyncio.get_running_loop().run_in_executor(
+                None, partial(handler, *args, **kwargs))
+        return ret
+except ImportError:  # pragma: no cover
+    def iscoroutine(coro):
+        return hasattr(coro, 'send') and hasattr(coro, 'throw')
+
+    async def invoke_handler(handler, *args, **kwargs):
+        """Invoke a handler and return the result.
+
+        This method runs sync handlers in the asyncio thread, which can
+        potentially cause blocking and performance issues.
+        """
+        ret = handler(*args, **kwargs)
+        if iscoroutine(ret):
+            ret = await ret
+        return ret
+
 try:
     from sys import print_exception
 except ImportError:  # pragma: no cover
@@ -13,45 +47,6 @@ except ImportError:  # pragma: no cover
 
     def print_exception(exc):
         traceback.print_exc()
-try:
-    import uerrno as errno
-except ImportError:
-    import errno
-
-concurrency_mode = 'threaded'
-
-try:  # pragma: no cover
-    import threading
-
-    def create_thread(f, *args, **kwargs):
-        # use the threading module
-        threading.Thread(target=f, args=args, kwargs=kwargs).start()
-except ImportError:  # pragma: no cover
-    def create_thread(f, *args, **kwargs):
-        # no threads available, call function synchronously
-        f(*args, **kwargs)
-
-    concurrency_mode = 'sync'
-
-try:
-    import ujson as json
-except ImportError:
-    import json
-
-try:
-    import ure as re
-except ImportError:
-    import re
-
-socket_timeout_error = OSError
-try:
-    import usocket as socket
-except ImportError:
-    try:
-        import socket
-        socket_timeout_error = socket.timeout
-    except ImportError:  # pragma: no cover
-        socket = None
 
 MUTED_SOCKET_ERRORS = [
     32,  # Broken pipe
@@ -275,7 +270,31 @@ class MultiDict(dict):
         return values
 
 
-class Request():
+class AsyncBytesIO:
+    """An async wrapper for BytesIO."""
+    def __init__(self, data):
+        self.stream = io.BytesIO(data)
+
+    async def read(self, n=-1):
+        return self.stream.read(n)
+
+    async def readline(self):  # pragma: no cover
+        return self.stream.readline()
+
+    async def readexactly(self, n):  # pragma: no cover
+        return self.stream.read(n)
+
+    async def readuntil(self, separator=b'\n'):  # pragma: no cover
+        return self.stream.readuntil(separator=separator)
+
+    async def awrite(self, data):  # pragma: no cover
+        return self.stream.write(data)
+
+    async def aclose(self):  # pragma: no cover
+        pass
+
+
+class Request:
     """An HTTP request."""
     #: Specify the maximum payload size that is accepted. Requests with larger
     #: payloads will be rejected with a 413 status code. Applications can
@@ -306,12 +325,6 @@ class Request():
     #:    Request.max_readline = 16 * 1024  # 16KB lines allowed
     max_readline = 2 * 1024
 
-    #: Specify a suggested read timeout to use when reading the request. Set to
-    #: 0 to disable the use of a timeout. This timeout should be considered a
-    #: suggestion only, as some platforms may not support it. The default is
-    #: 1 second.
-    socket_read_timeout = 1
-
     class G:
         pass
 
@@ -361,82 +374,84 @@ class Request():
         self._body = body
         self.body_used = False
         self._stream = stream
-        self.stream_used = False
         self.sock = sock
         self._json = None
         self._form = None
         self.after_request_handlers = []
 
     @staticmethod
-    def create(app, client_stream, client_addr, client_sock=None):
+    async def create(app, client_reader, client_writer, client_addr):
         """Create a request object.
 
-
         :param app: The Microdot application instance.
-        :param client_stream: An input stream from where the request data can
+        :param client_reader: An input stream from where the request data can
                               be read.
+        :param client_writer: An output stream where the response data can be
+                              written.
         :param client_addr: The address of the client, as a tuple.
-        :param client_sock: The low-level socket associated with the request.
 
-        This method returns a newly created ``Request`` object.
+        This method is a coroutine. It returns a newly created ``Request``
+        object.
         """
         # request line
-        line = Request._safe_readline(client_stream).strip().decode()
+        line = (await Request._safe_readline(client_reader)).strip().decode()
-        if not line:
+        if not line:  # pragma: no cover
             return None
         method, url, http_version = line.split()
         http_version = http_version.split('/', 1)[1]
 
         # headers
         headers = NoCaseDict()
+        content_length = 0
         while True:
-            line = Request._safe_readline(client_stream).strip().decode()
+            line = (await Request._safe_readline(
+                client_reader)).strip().decode()
             if line == '':
                 break
             header, value = line.split(':', 1)
             value = value.strip()
             headers[header] = value
+            if header.lower() == 'content-length':
+                content_length = int(value)
+
+        # body
+        body = b''
+        if content_length and content_length <= Request.max_body_length:
+            body = await client_reader.readexactly(content_length)
+            stream = None
+        else:
+            body = b''
+            stream = client_reader
 
         return Request(app, client_addr, method, url, http_version, headers,
-                       stream=client_stream, sock=client_sock)
+                       body=body, stream=stream,
+                       sock=(client_reader, client_writer))
 
     def _parse_urlencoded(self, urlencoded):
         data = MultiDict()
-        if len(urlencoded) > 0:
+        if len(urlencoded) > 0:  # pragma: no branch
             if isinstance(urlencoded, str):
-                for k, v in [pair.split('=', 1)
+                for kv in [pair.split('=', 1)
-                             for pair in urlencoded.split('&') if pair]:
+                           for pair in urlencoded.split('&') if pair]:
-                    data[urldecode_str(k)] = urldecode_str(v)
+                    data[urldecode_str(kv[0])] = urldecode_str(kv[1]) \
+                        if len(kv) > 1 else ''
             elif isinstance(urlencoded, bytes):  # pragma: no branch
-                for k, v in [pair.split(b'=', 1)
+                for kv in [pair.split(b'=', 1)
-                             for pair in urlencoded.split(b'&') if pair]:
+                           for pair in urlencoded.split(b'&') if pair]:
-                    data[urldecode_bytes(k)] = urldecode_bytes(v)
+                    data[urldecode_bytes(kv[0])] = urldecode_bytes(kv[1]) \
+                        if len(kv) > 1 else b''
         return data
 
     @property
     def body(self):
         """The body of the request, as bytes."""
-        if self.stream_used:
-            raise RuntimeError('Cannot use both stream and body')
-        if self._body is None:
-            self._body = b''
-            if self.content_length and \
-                    self.content_length <= Request.max_body_length:
-                while len(self._body) < self.content_length:
-                    data = self._stream.read(
-                        self.content_length - len(self._body))
-                    if len(data) == 0:  # pragma: no cover
-                        raise EOFError()
-                    self._body += data
-                self.body_used = True
         return self._body
 
     @property
     def stream(self):
-        """The input stream, containing the request body."""
+        """The body of the request, as a bytes stream."""
-        if self.body_used:
+        if self._stream is None:
-            raise RuntimeError('Cannot use both stream and body')
+            self._stream = AsyncBytesIO(self._body)
-        self.stream_used = True
         return self._stream
 
     @property
@@ -492,21 +507,21 @@ class Request():
         return f
 
     @staticmethod
-    def _safe_readline(stream):
+    async def _safe_readline(stream):
-        line = stream.readline(Request.max_readline + 1)
+        line = (await stream.readline())
         if len(line) > Request.max_readline:
             raise ValueError('line too long')
         return line
 
 
-class Response():
+class Response:
     """An HTTP response class.
 
     :param body: The body of the response. If a dictionary or list is given,
                  a JSON formatter is used to generate the body. If a file-like
-                 object or a generator is given, a streaming response is used.
+                 object or an async generator is given, a streaming response is
-                 If a string is given, it is encoded from UTF-8. Else, the
+                 used. If a string is given, it is encoded from UTF-8. Else,
-                 body should be a byte sequence.
+                 the body should be a byte sequence.
     :param status_code: The numeric HTTP status code of the response. The
                         default is 200.
     :param headers: A dictionary of headers to include in the response.
@@ -524,6 +539,7 @@ class Response():
         'png': 'image/png',
         'txt': 'text/plain',
     }
+
     send_file_buffer_size = 1024
 
     #: The content type to use for responses that do not explicitly define a
@@ -556,7 +572,8 @@ class Response():
         self.is_head = False
 
     def set_cookie(self, cookie, value, path=None, domain=None, expires=None,
-                   max_age=None, secure=False, http_only=False):
+                   max_age=None, secure=False, http_only=False,
+                   partitioned=False):
         """Add a cookie to the response.
 
         :param cookie: The cookie's name.
@@ -568,6 +585,7 @@ class Response():
         :param max_age: The cookie's ``Max-Age`` value.
         :param secure: The cookie's ``secure`` flag.
         :param http_only: The cookie's ``HttpOnly`` flag.
+        :param partitioned: Whether the cookie is partitioned.
         """
         http_cookie = '{cookie}={value}'.format(cookie=cookie, value=value)
         if path:
@@ -577,20 +595,32 @@ class Response():
         if expires:
             if isinstance(expires, str):
                 http_cookie += '; Expires=' + expires
-            else:
+            else:  # pragma: no cover
-                http_cookie += '; Expires=' + expires.strftime(
+                http_cookie += '; Expires=' + time.strftime(
-                    '%a, %d %b %Y %H:%M:%S GMT')
+                    '%a, %d %b %Y %H:%M:%S GMT', expires.timetuple())
-        if max_age:
+        if max_age is not None:
             http_cookie += '; Max-Age=' + str(max_age)
         if secure:
             http_cookie += '; Secure'
         if http_only:
             http_cookie += '; HttpOnly'
+        if partitioned:
+            http_cookie += '; Partitioned'
         if 'Set-Cookie' in self.headers:
             self.headers['Set-Cookie'].append(http_cookie)
         else:
             self.headers['Set-Cookie'] = [http_cookie]
 
+    def delete_cookie(self, cookie, **kwargs):
+        """Delete a cookie.
+
+        :param cookie: The cookie's name.
+        :param kwargs: Any cookie opens and flags supported by
+                       ``set_cookie()`` except ``expires`` and ``max_age``.
+        """
+        self.set_cookie(cookie, '', expires='Thu, 01 Jan 1970 00:00:01 GMT',
+                        max_age=0, **kwargs)
+
     def complete(self):
         if isinstance(self.body, bytes) and \
                 'Content-Length' not in self.headers:
@@ -600,54 +630,101 @@ class Response():
             if 'charset=' not in self.headers['Content-Type']:
                 self.headers['Content-Type'] += '; charset=UTF-8'
 
-    def write(self, stream):
+    async def write(self, stream):
         self.complete()
 
-        # status code
+        try:
-        reason = self.reason if self.reason is not None else \
+            # status code
-            ('OK' if self.status_code == 200 else 'N/A')
+            reason = self.reason if self.reason is not None else \
-        stream.write('HTTP/1.0 {status_code} {reason}\r\n'.format(
+                ('OK' if self.status_code == 200 else 'N/A')
-            status_code=self.status_code, reason=reason).encode())
+            await stream.awrite('HTTP/1.0 {status_code} {reason}\r\n'.format(
+                status_code=self.status_code, reason=reason).encode())
 
-        # headers
+            # headers
-        for header, value in self.headers.items():
+            for header, value in self.headers.items():
-            values = value if isinstance(value, list) else [value]
+                values = value if isinstance(value, list) else [value]
-            for value in values:
+                for value in values:
-                stream.write('{header}: {value}\r\n'.format(
+                    await stream.awrite('{header}: {value}\r\n'.format(
-                    header=header, value=value).encode())
+                        header=header, value=value).encode())
-        stream.write(b'\r\n')
+            await stream.awrite(b'\r\n')
 
-        # body
+            # body
-        if not self.is_head:
+            if not self.is_head:
-            can_flush = hasattr(stream, 'flush')
+                iter = self.body_iter()
-            try:
+                async for body in iter:
-                for body in self.body_iter():
                     if isinstance(body, str):  # pragma: no cover
                         body = body.encode()
-                    stream.write(body)
+                    try:
-                    if can_flush:  # pragma: no cover
+                        await stream.awrite(body)
-                        stream.flush()
+                    except OSError as exc:  # pragma: no cover
-            except OSError as exc:  # pragma: no cover
+                        if exc.errno in MUTED_SOCKET_ERRORS or \
-                if exc.errno in MUTED_SOCKET_ERRORS:
+                                exc.args[0] == 'Connection lost':
-                    pass
+                            if hasattr(iter, 'aclose'):
-                else:
+                                await iter.aclose()
-                    raise
+                        raise
+                if hasattr(iter, 'aclose'):  # pragma: no branch
+                    await iter.aclose()
+
+        except OSError as exc:  # pragma: no cover
+            if exc.errno in MUTED_SOCKET_ERRORS or \
+                    exc.args[0] == 'Connection lost':
+                pass
+            else:
+                raise
 
     def body_iter(self):
-        if self.body:
+        if hasattr(self.body, '__anext__'):
-            if hasattr(self.body, 'read'):
+            # response body is an async generator
-                while True:
+            return self.body
-                    buf = self.body.read(self.send_file_buffer_size)
+
-                    if len(buf):
+        response = self
-                        yield buf
+
-                    if len(buf) < self.send_file_buffer_size:
+        class iter:
-                        break
+            ITER_UNKNOWN = 0
-                if hasattr(self.body, 'close'):  # pragma: no cover
+            ITER_SYNC_GEN = 1
-                    self.body.close()
+            ITER_FILE_OBJ = 2
-            elif hasattr(self.body, '__next__'):
+            ITER_NO_BODY = -1
-                yield from self.body
+
-            else:
+            def __aiter__(self):
-                yield self.body
+                if response.body:
+                    self.i = self.ITER_UNKNOWN  # need to determine type
+                else:
+                    self.i = self.ITER_NO_BODY
+                return self
+
+            async def __anext__(self):
+                if self.i == self.ITER_NO_BODY:
+                    await self.aclose()
+                    raise StopAsyncIteration
+                if self.i == self.ITER_UNKNOWN:
+                    if hasattr(response.body, 'read'):
+                        self.i = self.ITER_FILE_OBJ
+                    elif hasattr(response.body, '__next__'):
+                        self.i = self.ITER_SYNC_GEN
+                        return next(response.body)
+                    else:
+                        self.i = self.ITER_NO_BODY
+                        return response.body
+                elif self.i == self.ITER_SYNC_GEN:
+                    try:
+                        return next(response.body)
+                    except StopIteration:
+                        await self.aclose()
+                        raise StopAsyncIteration
+                buf = response.body.read(response.send_file_buffer_size)
+                if iscoroutine(buf):  # pragma: no cover
+                    buf = await buf
+                if len(buf) < response.send_file_buffer_size:
+                    self.i = self.ITER_NO_BODY
+                return buf
+
+            async def aclose(self):
+                if hasattr(response.body, 'close'):
+                    result = response.body.close()
+                    if iscoroutine(result):  # pragma: no cover
+                        await result
+
+        return iter()
 
     @classmethod
     def redirect(cls, location, status_code=302):
@@ -697,7 +774,10 @@ class Response():
         first.
         """
         if content_type is None:
-            ext = filename.split('.')[-1]
+            if compressed and filename.endswith('.gz'):
+                ext = filename[:-3].split('.')[-1]
+            else:
+                ext = filename.split('.')[-1]
             if ext in Response.types_map:
                 content_type = Response.types_map[ext]
             else:
@@ -720,8 +800,9 @@ class Response():
 class URLPattern():
     def __init__(self, url_pattern):
         self.url_pattern = url_pattern
-        self.pattern = ''
+        self.segments = []
-        self.args = []
+        self.regex = None
+        pattern = ''
         use_regex = False
         for segment in url_pattern.lstrip('/').split('/'):
             if segment and segment[0] == '<':
@@ -733,42 +814,83 @@ class URLPattern():
                 else:
                     type_ = 'string'
                     name = segment
+                parser = None
                 if type_ == 'string':
-                    pattern = '[^/]+'
+                    parser = self._string_segment
+                    pattern += '/([^/]+)'
                 elif type_ == 'int':
-                    pattern = '-?\\d+'
+                    parser = self._int_segment
+                    pattern += '/(-?\\d+)'
                 elif type_ == 'path':
-                    pattern = '.+'
+                    use_regex = True
+                    pattern += '/(.+)'
                 elif type_.startswith('re:'):
-                    pattern = type_[3:]
+                    use_regex = True
+                    pattern += '/({pattern})'.format(pattern=type_[3:])
                 else:
                     raise ValueError('invalid URL segment type')
-                use_regex = True
+                self.segments.append({'parser': parser, 'name': name,
-                self.pattern += '/({pattern})'.format(pattern=pattern)
+                                      'type': type_})
-                self.args.append({'type': type_, 'name': name})
             else:
-                self.pattern += '/{segment}'.format(segment=segment)
+                pattern += '/' + segment
+                self.segments.append({'parser': self._static_segment(segment)})
         if use_regex:
-            self.pattern = re.compile('^' + self.pattern + '$')
+            import re
+            self.regex = re.compile('^' + pattern + '$')
 
     def match(self, path):
-        if isinstance(self.pattern, str):
-            if path != self.pattern:
-                return
-            return {}
-        g = self.pattern.match(path)
-        if not g:
-            return
         args = {}
-        i = 1
+        if self.regex:
-        for arg in self.args:
+            g = self.regex.match(path)
-            value = g.group(i)
+            if not g:
-            if arg['type'] == 'int':
+                return
-                value = int(value)
+            i = 1
-            args[arg['name']] = value
+            for segment in self.segments:
-            i += 1
+                if 'name' not in segment:
+                    continue
+                value = g.group(i)
+                if segment['type'] == 'int':
+                    value = int(value)
+                args[segment['name']] = value
+                i += 1
+        else:
+            if len(path) == 0 or path[0] != '/':
+                return
+            path = path[1:]
+            args = {}
+            for segment in self.segments:
+                if path is None:
+                    return
+                arg, path = segment['parser'](path)
+                if arg is None:
+                    return
+                if 'name' in segment:
+                    args[segment['name']] = arg
+            if path is not None:
+                return
         return args
 
+    def _static_segment(self, segment):
+        def _static(value):
+            s = value.split('/', 1)
+            if s[0] == segment:
+                return '', s[1] if len(s) > 1 else None
+            return None, None
+        return _static
+
+    def _string_segment(self, value):
+        s = value.split('/', 1)
+        if len(s[0]) == 0:
+            return None, None
+        return s[0], s[1] if len(s) > 1 else None
+
+    def _int_segment(self, value):
+        s = value.split('/', 1)
+        try:
+            return int(s[0]), s[1] if len(s) > 1 else None
+        except ValueError:
+            return None, None
+
 
 class HTTPException(Exception):
     def __init__(self, status_code, reason=None):
@@ -779,7 +901,7 @@ class HTTPException(Exception):
         return 'HTTPException: {}'.format(self.status_code)
 
 
-class Microdot():
+class Microdot:
     """An HTTP application class.
 
     This class implements an HTTP application instance and is heavily
@@ -1046,6 +1168,88 @@ class Microdot():
         """
         raise HTTPException(status_code, reason)
 
+    async def start_server(self, host='0.0.0.0', port=5000, debug=False,
+                           ssl=None):
+        """Start the Microdot web server as a coroutine. This coroutine does
+        not normally return, as the server enters an endless listening loop.
+        The :func:`shutdown` function provides a method for terminating the
+        server gracefully.
+
+        :param host: The hostname or IP address of the network interface that
+                     will be listening for requests. A value of ``'0.0.0.0'``
+                     (the default) indicates that the server should listen for
+                     requests on all the available interfaces, and a value of
+                     ``127.0.0.1`` indicates that the server should listen
+                     for requests only on the internal networking interface of
+                     the host.
+        :param port: The port number to listen for requests. The default is
+                     port 5000.
+        :param debug: If ``True``, the server logs debugging information. The
+                      default is ``False``.
+        :param ssl: An ``SSLContext`` instance or ``None`` if the server should
+                    not use TLS. The default is ``None``.
+
+        This method is a coroutine.
+
+        Example::
+
+            import asyncio
+            from microdot import Microdot
+
+            app = Microdot()
+
+            @app.route('/')
+            async def index(request):
+                return 'Hello, world!'
+
+            async def main():
+                await app.start_server(debug=True)
+
+            asyncio.run(main())
+        """
+        self.debug = debug
+
+        async def serve(reader, writer):
+            if not hasattr(writer, 'awrite'):  # pragma: no cover
+                # CPython provides the awrite and aclose methods in 3.8+
+                async def awrite(self, data):
+                    self.write(data)
+                    await self.drain()
+
+                async def aclose(self):
+                    self.close()
+                    await self.wait_closed()
+
+                from types import MethodType
+                writer.awrite = MethodType(awrite, writer)
+                writer.aclose = MethodType(aclose, writer)
+
+            await self.handle_request(reader, writer)
+
+        if self.debug:  # pragma: no cover
+            print('Starting async server on {host}:{port}...'.format(
+                host=host, port=port))
+
+        try:
+            self.server = await asyncio.start_server(serve, host, port,
+                                                     ssl=ssl)
+        except TypeError:  # pragma: no cover
+            self.server = await asyncio.start_server(serve, host, port)
+
+        while True:
+            try:
+                if hasattr(self.server, 'serve_forever'):  # pragma: no cover
+                    try:
+                        await self.server.serve_forever()
+                    except asyncio.CancelledError:
+                        pass
+                await self.server.wait_closed()
+                break
+            except AttributeError:  # pragma: no cover
+                # the task hasn't been initialized in the server object yet
+                # wait a bit and try again
+                await asyncio.sleep(0.1)
+
     def run(self, host='0.0.0.0', port=5000, debug=False, ssl=None):
         """Start the web server. This function does not normally return, as
         the server enters an endless listening loop. The :func:`shutdown`
@@ -1072,40 +1276,13 @@ class Microdot():
             app = Microdot()
 
             @app.route('/')
-            def index():
+            async def index(request):
                 return 'Hello, world!'
 
             app.run(debug=True)
         """
-        self.debug = debug
+        asyncio.run(self.start_server(host=host, port=port, debug=debug,
-        self.shutdown_requested = False
+                                      ssl=ssl))  # pragma: no cover
-
-        self.server = socket.socket()
-        ai = socket.getaddrinfo(host, port)
-        addr = ai[0][-1]
-
-        if self.debug:  # pragma: no cover
-            print('Starting {mode} server on {host}:{port}...'.format(
-                mode=concurrency_mode, host=host, port=port))
-        self.server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-        self.server.bind(addr)
-        self.server.listen(5)
-
-        if ssl:
-            self.server = ssl.wrap_socket(self.server, server_side=True)
-
-        while not self.shutdown_requested:
-            try:
-                sock, addr = self.server.accept()
-            except OSError as exc:  # pragma: no cover
-                if exc.errno == errno.ECONNABORTED:
-                    break
-                else:
-                    print_exception(exc)
-            except Exception as exc:  # pragma: no cover
-                print_exception(exc)
-            else:
-                create_thread(self.handle_request, sock, addr)
 
     def shutdown(self):
         """Request a server shutdown. The server will then exit its request
@@ -1120,7 +1297,7 @@ class Microdot():
                 request.app.shutdown()
                 return 'The server is shutting down...'
         """
-        self.shutdown_requested = True
+        self.server.close()
 
     def find_route(self, req):
         method = req.method.upper()
@@ -1149,51 +1326,35 @@ class Microdot():
         allow.append('OPTIONS')
         return {'Allow': ', '.join(allow)}
 
-    def handle_request(self, sock, addr):
+    async def handle_request(self, reader, writer):
-        if Request.socket_read_timeout and \
-                hasattr(sock, 'settimeout'):  # pragma: no cover
-            sock.settimeout(Request.socket_read_timeout)
-        if not hasattr(sock, 'readline'):  # pragma: no cover
-            stream = sock.makefile("rwb")
-        else:
-            stream = sock
-
         req = None
-        res = None
         try:
-            req = Request.create(self, stream, addr, sock)
+            req = await Request.create(self, reader, writer,
-            res = self.dispatch_request(req)
+                                       writer.get_extra_info('peername'))
-        except socket_timeout_error as exc:  # pragma: no cover
-            if exc.errno and exc.errno != errno.ETIMEDOUT:
-                print_exception(exc)  # not a timeout
         except Exception as exc:  # pragma: no cover
             print_exception(exc)
+
+        res = await self.dispatch_request(req)
+        if res != Response.already_handled:  # pragma: no branch
+            await res.write(writer)
         try:
-            if res and res != Response.already_handled:  # pragma: no branch
+            await writer.aclose()
-                res.write(stream)
-            stream.close()
         except OSError as exc:  # pragma: no cover
             if exc.errno in MUTED_SOCKET_ERRORS:
                 pass
             else:
-                print_exception(exc)
+                raise
-        except Exception as exc:  # pragma: no cover
-            print_exception(exc)
-        if stream != sock:  # pragma: no cover
-            sock.close()
-        if self.shutdown_requested:  # pragma: no cover
-            self.server.close()
         if self.debug and req:  # pragma: no cover
             print('{method} {path} {status_code}'.format(
                 method=req.method, path=req.path,
                 status_code=res.status_code))
 
-    def dispatch_request(self, req):
+    async def dispatch_request(self, req):
         after_request_handled = False
         if req:
             if req.content_length > req.max_content_length:
                 if 413 in self.error_handlers:
-                    res = self.error_handlers[413](req)
+                    res = await invoke_handler(self.error_handlers[413], req)
                 else:
                     res = 'Payload too large', 413
             else:
@@ -1202,12 +1363,18 @@ class Microdot():
                     res = None
                     if callable(f):
                         for handler in self.before_request_handlers:
-                            res = handler(req)
+                            res = await invoke_handler(handler, req)
                             if res:
                                 break
                         if res is None:
-                            res = f(req, **req.url_args)
+                            res = await invoke_handler(
+                                f, req, **req.url_args)
+                        if isinstance(res, int):
+                            res = '', res
                         if isinstance(res, tuple):
+                            if isinstance(res[0], int):
+                                res = ('', res[0],
+                                       res[1] if len(res) > 1 else {})
                             body = res[0]
                             if isinstance(res[1], int):
                                 status_code = res[1]
@@ -1219,14 +1386,16 @@ class Microdot():
                         elif not isinstance(res, Response):
                             res = Response(res)
                         for handler in self.after_request_handlers:
-                            res = handler(req, res) or res
+                            res = await invoke_handler(
+                                handler, req, res) or res
                         for handler in req.after_request_handlers:
-                            res = handler(req, res) or res
+                            res = await invoke_handler(
+                                handler, req, res) or res
                         after_request_handled = True
                     elif isinstance(f, dict):
                         res = Response(headers=f)
                     elif f in self.error_handlers:
-                        res = self.error_handlers[f](req)
+                        res = await invoke_handler(self.error_handlers[f], req)
                     else:
                         res = 'Not found', f
                 except HTTPException as exc:
@@ -1247,32 +1416,35 @@ class Microdot():
                                 break
                     if exc_class:
                         try:
-                            res = self.error_handlers[exc_class](req, exc)
+                            res = await invoke_handler(
+                                self.error_handlers[exc_class], req, exc)
                         except Exception as exc2:  # pragma: no cover
                             print_exception(exc2)
                     if res is None:
                         if 500 in self.error_handlers:
-                            res = self.error_handlers[500](req)
+                            res = await invoke_handler(
+                                self.error_handlers[500], req)
                         else:
                             res = 'Internal server error', 500
         else:
             if 400 in self.error_handlers:
-                res = self.error_handlers[400](req)
+                res = await invoke_handler(self.error_handlers[400], req)
             else:
                 res = 'Bad request', 400
-
         if isinstance(res, tuple):
             res = Response(*res)
         elif not isinstance(res, Response):
             res = Response(res)
         if not after_request_handled:
             for handler in self.after_error_request_handlers:
-                res = handler(req, res) or res
+                res = await invoke_handler(
+                    handler, req, res) or res
         res.is_head = (req and req.method == 'HEAD')
         return res
 
 
-abort = Microdot.abort
 Response.already_handled = Response()
+
+abort = Microdot.abort
 redirect = Response.redirect
 send_file = Response.send_file

src/microdot/session.py

@@ -0,0 +1,155 @@
+import jwt
+from microdot.microdot import invoke_handler
+from microdot.helpers import wraps
+
+
+class SessionDict(dict):
+    """A session dictionary.
+
+    The session dictionary is a standard Python dictionary that has been
+    extended with convenience ``save()`` and ``delete()`` methods.
+    """
+    def __init__(self, request, session_dict):
+        super().__init__(session_dict)
+        self.request = request
+
+    def save(self):
+        """Update the session cookie."""
+        self.request.app._session.update(self.request, self)
+
+    def delete(self):
+        """Delete the session cookie."""
+        self.request.app._session.delete(self.request)
+
+
+class Session:
+    """
+    :param app: The application instance.
+    :param key: The secret key, as a string or bytes object.
+    """
+    secret_key = None
+
+    def __init__(self, app=None, secret_key=None, cookie_options=None):
+        self.secret_key = secret_key
+        self.cookie_options = cookie_options or {}
+        if app is not None:
+            self.initialize(app)
+
+    def initialize(self, app, secret_key=None, cookie_options=None):
+        if secret_key is not None:
+            self.secret_key = secret_key
+        if cookie_options is not None:
+            self.cookie_options = cookie_options
+        if 'path' not in self.cookie_options:
+            self.cookie_options['path'] = '/'
+        if 'http_only' not in self.cookie_options:
+            self.cookie_options['http_only'] = True
+        app._session = self
+
+    def get(self, request):
+        """Retrieve the user session.
+
+        :param request: The client request.
+
+        The return value is a session dictionary with the data stored in the
+        user's session, or ``{}`` if the session data is not available or
+        invalid.
+        """
+        if not self.secret_key:
+            raise ValueError('The session secret key is not configured')
+        if hasattr(request.g, '_session'):
+            return request.g._session
+        session = request.cookies.get('session')
+        if session is None:
+            request.g._session = SessionDict(request, {})
+            return request.g._session
+        request.g._session = SessionDict(request, self.decode(session))
+        return request.g._session
+
+    def update(self, request, session):
+        """Update the user session.
+
+        :param request: The client request.
+        :param session: A dictionary with the update session data for the user.
+
+        Applications would normally not call this method directly, instead they
+        would use the :meth:`SessionDict.save` method on the session
+        dictionary, which calls this method. For example::
+
+            @app.route('/')
+            @with_session
+            def index(request, session):
+                session['foo'] = 'bar'
+                session.save()
+                return 'Hello, World!'
+
+        Calling this method adds a cookie with the updated session to the
+        request currently being processed.
+        """
+        if not self.secret_key:
+            raise ValueError('The session secret key is not configured')
+
+        encoded_session = self.encode(session)
+
+        @request.after_request
+        def _update_session(request, response):
+            response.set_cookie('session', encoded_session,
+                                **self.cookie_options)
+            return response
+
+    def delete(self, request):
+        """Remove the user session.
+
+        :param request: The client request.
+
+        Applications would normally not call this method directly, instead they
+        would use the :meth:`SessionDict.delete` method on the session
+        dictionary, which calls this method. For example::
+
+            @app.route('/')
+            @with_session
+            def index(request, session):
+                session.delete()
+                return 'Hello, World!'
+
+        Calling this method adds a cookie removal header to the request
+        currently being processed.
+        """
+        @request.after_request
+        def _delete_session(request, response):
+            response.delete_cookie('session', **self.cookie_options)
+            return response
+
+    def encode(self, payload, secret_key=None):
+        return jwt.encode(payload, secret_key or self.secret_key,
+                          algorithm='HS256')
+
+    def decode(self, session, secret_key=None):
+        try:
+            payload = jwt.decode(session, secret_key or self.secret_key,
+                                 algorithms=['HS256'])
+        except jwt.exceptions.PyJWTError:  # pragma: no cover
+            return {}
+        return payload
+
+
+def with_session(f):
+    """Decorator that passes the user session to the route handler.
+
+    The session dictionary is passed to the decorated function as an argument
+    after the request object. Example::
+
+        @app.route('/')
+        @with_session
+        def index(request, session):
+            return 'Hello, World!'
+
+    Note that the decorator does not save the session. To update the session,
+    call the :func:`session.save() <microdot.session.SessionDict.save>` method.
+    """
+    @wraps(f)
+    async def wrapper(request, *args, **kwargs):
+        return await invoke_handler(
+            f, request, request.app._session.get(request), *args, **kwargs)
+
+    return wrapper

src/microdot/sse.py

@@ -0,0 +1,111 @@
+import asyncio
+import json
+from microdot.helpers import wraps
+
+
+class SSE:
+    """Server-Sent Events object.
+
+    An object of this class is sent to handler functions to manage the SSE
+    connection.
+    """
+    def __init__(self):
+        self.event = asyncio.Event()
+        self.queue = []
+
+    async def send(self, data, event=None, event_id=None):
+        """Send an event to the client.
+
+        :param data: the data to send. It can be given as a string, bytes, dict
+                     or list. Dictionaries and lists are serialized to JSON.
+                     Any other types are converted to string before sending.
+        :param event: an optional event name, to send along with the data. If
+                      given, it must be a string.
+        :param event_id: an optional event id, to send along with the data. If
+                      given, it must be a string.
+        """
+        if isinstance(data, (dict, list)):
+            data = json.dumps(data).encode()
+        elif isinstance(data, str):
+            data = data.encode()
+        elif not isinstance(data, bytes):
+            data = str(data).encode()
+        data = b'data: ' + data + b'\n\n'
+        if event_id:
+            data = b'id: ' + event_id.encode() + b'\n' + data
+        if event:
+            data = b'event: ' + event.encode() + b'\n' + data
+        self.queue.append(data)
+        self.event.set()
+
+
+def sse_response(request, event_function, *args, **kwargs):
+    """Return a response object that initiates an event stream.
+
+    :param request: the request object.
+    :param event_function: an asynchronous function that will send events to
+                           the client. The function is invoked with ``request``
+                           and an ``sse`` object. The function should use
+                           ``sse.send()`` to send events to the client.
+    :param args: additional positional arguments to be passed to the response.
+    :param kwargs: additional keyword arguments to be passed to the response.
+
+    This is a low-level function that can be used to implement a custom SSE
+    endpoint. In general the :func:`microdot.sse.with_sse` decorator should be
+    used instead.
+    """
+    sse = SSE()
+
+    async def sse_task_wrapper():
+        await event_function(request, sse, *args, **kwargs)
+        sse.event.set()
+
+    task = asyncio.create_task(sse_task_wrapper())
+
+    class sse_loop:
+        def __aiter__(self):
+            return self
+
+        async def __anext__(self):
+            event = None
+            while sse.queue or not task.done():
+                try:
+                    event = sse.queue.pop(0)
+                    break
+                except IndexError:
+                    await sse.event.wait()
+                    sse.event.clear()
+            if event is None:
+                raise StopAsyncIteration
+            return event
+
+        async def aclose(self):
+            task.cancel()
+
+    return sse_loop(), 200, {'Content-Type': 'text/event-stream'}
+
+
+def with_sse(f):
+    """Decorator to make a route a Server-Sent Events endpoint.
+
+    This decorator is used to define a route that accepts SSE connections. The
+    route then receives a sse object as a second argument that it can use to
+    send events to the client::
+
+        @app.route('/events')
+        @with_sse
+        async def events(request, sse):
+            # send an unnamed event with string data
+            await sse.send('hello')
+
+            # send an unnamed event with JSON data
+            await sse.send({'foo': 'bar'})
+
+            # send a named event
+            await sse.send('hello', event='greeting')
+    """
+    @wraps(f)
+    async def sse_handler(request, *args, **kwargs):
+        return sse_response(request, f, *args, **kwargs)
+
+    return sse_handler

src/microdot/test_client.py

@@ -1,11 +1,13 @@
-from io import BytesIO
 import json
-from microdot import Request, Response, NoCaseDict
+from microdot.microdot import Request, Response, AsyncBytesIO
+
 try:
-    from microdot_websocket import WebSocket
+    from microdot.websocket import WebSocket
 except:  # pragma: no cover  # noqa: E722
     WebSocket = None
 
+__all__ = ['TestClient', 'TestResponse']
+
 
 class TestResponse:
     """A response object issued by the Microdot test client."""
@@ -32,12 +34,15 @@ class TestResponse:
         self.reason = res.reason
         self.headers = res.headers
 
-    def _initialize_body(self, res):
+    async def _initialize_body(self, res):
         self.body = b''
-        for body in res.body_iter():
+        iter = res.body_iter()
+        async for body in iter:  # pragma: no branch
             if isinstance(body, str):
                 body = body.encode()
             self.body += body
+        if hasattr(iter, 'aclose'):  # pragma: no branch
+            await iter.aclose()
 
     def _process_text_body(self):
         try:
@@ -52,13 +57,13 @@ class TestResponse:
                 self.json = json.loads(self.text)
 
     @classmethod
-    def create(cls, res):
+    async def create(cls, res):
         test_res = cls()
         test_res._initialize_response(res)
-        test_res._initialize_body(res)
+        if not res.is_head:
-        test_res._process_text_body()
+            await test_res._initialize_body(res)
-        test_res._process_json_body()
+            test_res._process_text_body()
-        test_res.is_head = res.is_head
+            test_res._process_json_body()
         return test_res
 
 
@@ -77,12 +82,12 @@ class TestClient:
         app = Microdot()
 
         @app.get('/')
-        def index():
+        async def index():
             return 'Hello, World!'
 
-        def test_hello_world(self):
+        async def test_hello_world(self):
             client = TestClient(app)
-            res = client.get('/')
+            res = await client.get('/')
             assert res.status_code == 200
             assert res.text == 'Hello, World!'
     """
@@ -107,9 +112,13 @@ class TestClient:
             headers['Host'] = 'example.com:1234'
         return body, headers
 
-    def _process_cookies(self, headers):
+    def _process_cookies(self, path, headers):
         cookies = ''
         for name, value in self.cookies.items():
+            if isinstance(value, tuple):
+                value, cookie_path = value
+                if not path.startswith(cookie_path):
+                    continue
             if cookies:
                 cookies += '; '
             cookies += name + '=' + value
@@ -118,7 +127,7 @@ class TestClient:
                 headers['Cookie'] += '; ' + cookies
             else:
                 headers['Cookie'] = cookies
-        return cookies, headers
+        return headers
 
     def _render_request(self, method, path, headers, body):
         request_bytes = '{method} {path} HTTP/1.0\n'.format(
@@ -134,39 +143,65 @@ class TestClient:
         for cookie in cookies:
             cookie_name, cookie_value = cookie.split('=', 1)
             cookie_options = cookie_value.split(';')
+            path = '/'
             delete = False
             for option in cookie_options[1:]:
-                if option.strip().lower().startswith('expires='):
+                option = option.strip().lower()
-                    _, e = option.strip().split('=', 1)
+                if option.startswith(
+                        'max-age='):  # pragma: no cover
+                    _, age = option.split('=', 1)
+                    try:
+                        age = int(age)
+                    except ValueError:  # pragma: no cover
+                        age = 0
+                    if age <= 0:
+                        delete = True
+                elif option.startswith('expires='):
+                    _, e = option.split('=', 1)
                     # this is a very limited parser for cookie expiry
                     # that only detects a cookie deletion request when
                     # the date is 1/1/1970
                     if '1 jan 1970' in e.lower():  # pragma: no branch
                         delete = True
-                        break
+                elif option.startswith('path='):
+                    _, path = option.split('=', 1)
             if delete:
                 if cookie_name in self.cookies:  # pragma: no branch
-                    del self.cookies[cookie_name]
+                    cookie_path = self.cookies[cookie_name][1] \
+                        if isinstance(self.cookies[cookie_name], tuple) \
+                        else '/'
+                    if path == cookie_path:
+                        del self.cookies[cookie_name]
             else:
-                self.cookies[cookie_name] = cookie_options[0]
+                if path == '/':
+                    self.cookies[cookie_name] = cookie_options[0]
+                else:
+                    self.cookies[cookie_name] = (cookie_options[0], path)
 
-    def request(self, method, path, headers=None, body=None, sock=None):
+    async def request(self, method, path, headers=None, body=None, sock=None):
-        headers = NoCaseDict(headers or {})
+        headers = headers or {}
         body, headers = self._process_body(body, headers)
-        cookies, headers = self._process_cookies(headers)
+        headers = self._process_cookies(path, headers)
         request_bytes = self._render_request(method, path, headers, body)
+        if sock:
+            reader = sock[0]
+            reader.buffer = request_bytes
+            writer = sock[1]
+        else:
+            reader = AsyncBytesIO(request_bytes)
+            writer = AsyncBytesIO(b'')
 
-        req = Request.create(self.app, BytesIO(request_bytes),
+        req = await Request.create(self.app, reader, writer,
-                             ('127.0.0.1', 1234), client_sock=sock)
+                                   ('127.0.0.1', 1234))
-        res = self.app.dispatch_request(req)
+        res = await self.app.dispatch_request(req)
         if res == Response.already_handled:
             return None
         res.complete()
 
         self._update_cookies(res)
-        return TestResponse.create(res)
+        return await TestResponse.create(res)
 
-    def get(self, path, headers=None):
+    async def get(self, path, headers=None):
         """Send a GET request to the application.
 
         :param path: The request URL.
@@ -175,9 +210,9 @@ class TestClient:
         This method returns a
         :class:`TestResponse <microdot_test_client.TestResponse>` object.
         """
-        return self.request('GET', path, headers=headers)
+        return await self.request('GET', path, headers=headers)
 
-    def post(self, path, headers=None, body=None):
+    async def post(self, path, headers=None, body=None):
         """Send a POST request to the application.
 
         :param path: The request URL.
@@ -189,9 +224,9 @@ class TestClient:
         This method returns a
         :class:`TestResponse <microdot_test_client.TestResponse>` object.
         """
-        return self.request('POST', path, headers=headers, body=body)
+        return await self.request('POST', path, headers=headers, body=body)
 
-    def put(self, path, headers=None, body=None):
+    async def put(self, path, headers=None, body=None):
         """Send a PUT request to the application.
 
         :param path: The request URL.
@@ -203,9 +238,9 @@ class TestClient:
         This method returns a
         :class:`TestResponse <microdot_test_client.TestResponse>` object.
         """
-        return self.request('PUT', path, headers=headers, body=body)
+        return await self.request('PUT', path, headers=headers, body=body)
 
-    def patch(self, path, headers=None, body=None):
+    async def patch(self, path, headers=None, body=None):
         """Send a PATCH request to the application.
 
         :param path: The request URL.
@@ -217,9 +252,9 @@ class TestClient:
         This method returns a
         :class:`TestResponse <microdot_test_client.TestResponse>` object.
         """
-        return self.request('PATCH', path, headers=headers, body=body)
+        return await self.request('PATCH', path, headers=headers, body=body)
 
-    def delete(self, path, headers=None):
+    async def delete(self, path, headers=None):
         """Send a DELETE request to the application.
 
         :param path: The request URL.
@@ -228,9 +263,9 @@ class TestClient:
         This method returns a
         :class:`TestResponse <microdot_test_client.TestResponse>` object.
         """
-        return self.request('DELETE', path, headers=headers)
+        return await self.request('DELETE', path, headers=headers)
 
-    def websocket(self, path, client, headers=None):
+    async def websocket(self, path, client, headers=None):
         """Send a websocket connection request to the application.
 
         :param path: The request URL.
@@ -245,36 +280,50 @@ class TestClient:
                 self.closed = False
                 self.buffer = b''
 
-            def _next(self, data=None):
+            async def _next(self, data=None):
                 try:
-                    data = gen.send(data)
+                    data = (await gen.asend(data)) if hasattr(gen, 'asend') \
-                except StopIteration:
+                        else gen.send(data)
-                    if self.closed:  # pragma: no cover
+                except (StopIteration, StopAsyncIteration):
-                        return
+                    if not self.closed:
-                    self.closed = True
+                        self.closed = True
-                    raise OSError(32, 'Websocket connection closed')
+                        raise OSError(32, 'Websocket connection closed')
+                    return  # pragma: no cover
                 opcode = WebSocket.TEXT if isinstance(data, str) \
                     else WebSocket.BINARY
                 return WebSocket._encode_websocket_frame(opcode, data)
 
-            def recv(self, n):
+            async def read(self, n):
-                self.started = True
                 if not self.buffer:
-                    self.buffer = self._next()
+                    self.started = True
+                    self.buffer = await self._next()
                 data = self.buffer[:n]
                 self.buffer = self.buffer[n:]
                 return data
 
-            def send(self, data):
+            async def readexactly(self, n):  # pragma: no cover
+                return await self.read(n)
+
+            async def readline(self):
+                line = b''
+                while True:
+                    line += await self.read(1)
+                    if line[-1] in [b'\n', 10]:
+                        break
+                return line
+
+            async def awrite(self, data):
                 if self.started:
                     h = WebSocket._parse_frame_header(data[0:2])
+                    if h[1] not in [WebSocket.TEXT, WebSocket.BINARY]:
+                        return
                     if h[3] < 0:
                         data = data[2 - h[3]:]
                     else:
                         data = data[2:]
                     if h[1] == WebSocket.TEXT:
                         data = data.decode()
-                    self.buffer = self._next(data)
+                    self.buffer = await self._next(data)
 
         ws_headers = {
             'Upgrade': 'websocket',
@@ -283,5 +332,6 @@ class TestClient:
             'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',
         }
         ws_headers.update(headers or {})
-        return self.request('GET', path, headers=ws_headers,
+        sock = FakeWebSocket()
-                            sock=FakeWebSocket())
+        return await self.request('GET', path, headers=ws_headers,
+                                  sock=(sock, sock))

src/microdot/utemplate.py

@@ -0,0 +1,70 @@
+from utemplate import recompile
+
+_loader = None
+
+
+class Template:
+    """A template object.
+
+    :param template: The filename of the template to render, relative to the
+                     configured template directory.
+    """
+    @classmethod
+    def initialize(cls, template_dir='templates',
+                   loader_class=recompile.Loader):
+        """Initialize the templating subsystem.
+
+        :param template_dir: the directory where templates are stored. This
+                             argument is optional. The default is to load
+                             templates from a *templates* subdirectory.
+        :param loader_class: the ``utemplate.Loader`` class to use when loading
+                             templates. This argument is optional. The default
+                             is the ``recompile.Loader`` class, which
+                             automatically recompiles templates when they
+                             change.
+        """
+        global _loader
+        _loader = loader_class(None, template_dir)
+
+    def __init__(self, template):
+        if _loader is None:  # pragma: no cover
+            self.initialize()
+        #: The name of the template
+        self.name = template
+        self.template = _loader.load(template)
+
+    def generate(self, *args, **kwargs):
+        """Return a generator that renders the template in chunks, with the
+        given arguments."""
+        return self.template(*args, **kwargs)
+
+    def render(self, *args, **kwargs):
+        """Render the template with the given arguments and return it as a
+        string."""
+        return ''.join(self.generate(*args, **kwargs))
+
+    def generate_async(self, *args, **kwargs):
+        """Return an asynchronous generator that renders the template in
+        chunks, using the given arguments."""
+        class sync_to_async_iter():
+            def __init__(self, iter):
+                self.iter = iter
+
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                try:
+                    return next(self.iter)
+                except StopIteration:
+                    raise StopAsyncIteration
+
+        return sync_to_async_iter(self.generate(*args, **kwargs))
+
+    async def render_async(self, *args, **kwargs):
+        """Render the template with the given arguments asynchronously and
+        return it as a string."""
+        response = ''
+        async for chunk in self.generate_async(*args, **kwargs):
+            response += chunk
+        return response

src/microdot/websocket.py

@@ -1,9 +1,21 @@
 import binascii
 import hashlib
-from microdot import Response
+from microdot import Request, Response
+from microdot.microdot import MUTED_SOCKET_ERRORS, print_exception
+from microdot.helpers import wraps
+
+
+class WebSocketError(Exception):
+    """Exception raised when an error occurs in a WebSocket connection."""
+    pass
 
 
 class WebSocket:
+    """A WebSocket connection object.
+
+    An instance of this class is sent to handler functions to manage the
+    WebSocket connection.
+    """
     CONT = 0
     TEXT = 1
     BINARY = 2
@@ -11,37 +23,59 @@ class WebSocket:
     PING = 9
     PONG = 10
 
+    #: Specify the maximum message size that can be received when calling the
+    #: ``receive()`` method. Messages with payloads that are larger than this
+    #: size will be rejected and the connection closed. Set to 0 to disable
+    #: the size check (be aware of potential security issues if you do this),
+    #: or to -1 to use the value set in
+    #: ``Request.max_body_length``. The default is -1.
+    #:
+    #: Example::
+    #:
+    #:    WebSocket.max_message_length = 4 * 1024  # up to 4KB messages
+    max_message_length = -1
+
     def __init__(self, request):
         self.request = request
         self.closed = False
 
-    def handshake(self):
+    async def handshake(self):
         response = self._handshake_response()
-        self.request.sock.send(b'HTTP/1.1 101 Switching Protocols\r\n')
+        await self.request.sock[1].awrite(
-        self.request.sock.send(b'Upgrade: websocket\r\n')
+            b'HTTP/1.1 101 Switching Protocols\r\n')
-        self.request.sock.send(b'Connection: Upgrade\r\n')
+        await self.request.sock[1].awrite(b'Upgrade: websocket\r\n')
-        self.request.sock.send(
+        await self.request.sock[1].awrite(b'Connection: Upgrade\r\n')
+        await self.request.sock[1].awrite(
             b'Sec-WebSocket-Accept: ' + response + b'\r\n\r\n')
 
-    def receive(self):
+    async def receive(self):
+        """Receive a message from the client."""
         while True:
-            opcode, payload = self._read_frame()
+            opcode, payload = await self._read_frame()
             send_opcode, data = self._process_websocket_frame(opcode, payload)
             if send_opcode:  # pragma: no cover
-                self.send(data, send_opcode)
+                await self.send(data, send_opcode)
             elif data:  # pragma: no branch
                 return data
 
-    def send(self, data, opcode=None):
+    async def send(self, data, opcode=None):
+        """Send a message to the client.
+
+        :param data: the data to send, given as a string or bytes.
+        :param opcode: a custom frame opcode to use. If not given, the opcode
+                       is ``TEXT`` or ``BINARY`` depending on the type of the
+                       data.
+        """
         frame = self._encode_websocket_frame(
             opcode or (self.TEXT if isinstance(data, str) else self.BINARY),
             data)
-        self.request.sock.send(frame)
+        await self.request.sock[1].awrite(frame)
 
-    def close(self):
+    async def close(self):
+        """Close the websocket connection."""
         if not self.closed:  # pragma: no cover
             self.closed = True
-            self.send(b'', self.CLOSE)
+            await self.send(b'', self.CLOSE)
 
     def _handshake_response(self):
         connection = False
@@ -70,7 +104,7 @@ class WebSocket:
         fin = header[0] & 0x80
         opcode = header[0] & 0x0f
         if fin == 0 or opcode == cls.CONT:  # pragma: no cover
-            raise OSError(32, 'Continuation frames not supported')
+            raise WebSocketError('Continuation frames not supported')
         has_mask = header[1] & 0x80
         length = header[1] & 0x7f
         if length == 126:
@@ -85,7 +119,7 @@ class WebSocket:
         elif opcode == self.BINARY:
             pass
         elif opcode == self.CLOSE:
-            raise OSError(32, 'Websocket connection closed')
+            raise WebSocketError('Websocket connection closed')
         elif opcode == self.PING:
             return self.PONG, payload
         elif opcode == self.PONG:  # pragma: no branch
@@ -109,23 +143,30 @@ class WebSocket:
         frame.extend(payload)
         return frame
 
-    def _read_frame(self):
+    async def _read_frame(self):
-        header = self.request.sock.recv(2)
+        header = await self.request.sock[0].read(2)
         if len(header) != 2:  # pragma: no cover
-            raise OSError(32, 'Websocket connection closed')
+            raise WebSocketError('Websocket connection closed')
         fin, opcode, has_mask, length = self._parse_frame_header(header)
-        if length < 0:
+        if length == -2:
-            length = self.request.sock.recv(-length)
+            length = await self.request.sock[0].read(2)
             length = int.from_bytes(length, 'big')
+        elif length == -8:
+            length = await self.request.sock[0].read(8)
+            length = int.from_bytes(length, 'big')
+        max_allowed_length = Request.max_body_length \
+            if self.max_message_length == -1 else self.max_message_length
+        if length > max_allowed_length:
+            raise WebSocketError('Message too large')
         if has_mask:  # pragma: no cover
-            mask = self.request.sock.recv(4)
+            mask = await self.request.sock[0].read(4)
-        payload = self.request.sock.recv(length)
+        payload = await self.request.sock[0].read(length)
         if has_mask:  # pragma: no cover
             payload = bytes(x ^ mask[i % 4] for i, x in enumerate(payload))
         return opcode, payload
 
 
-def websocket_upgrade(request):
+async def websocket_upgrade(request):
     """Upgrade a request handler to a websocket connection.
 
     This function can be called directly inside a route function to process a
@@ -133,24 +174,46 @@ def websocket_upgrade(request):
     verified. The function returns the websocket object::
 
         @app.route('/echo')
-        def echo(request):
+        async def echo(request):
             if not authenticate_user(request):
                 abort(401)
-            ws = websocket_upgrade(request)
+            ws = await websocket_upgrade(request)
             while True:
-                message = ws.receive()
+                message = await ws.receive()
-                ws.send(message)
+                await ws.send(message)
     """
     ws = WebSocket(request)
-    ws.handshake()
+    await ws.handshake()
 
     @request.after_request
-    def after_request(request, response):
+    async def after_request(request, response):
         return Response.already_handled
 
     return ws
 
 
+def websocket_wrapper(f, upgrade_function):
+    @wraps(f)
+    async def wrapper(request, *args, **kwargs):
+        ws = await upgrade_function(request)
+        try:
+            await f(request, ws, *args, **kwargs)
+        except OSError as exc:
+            if exc.errno not in MUTED_SOCKET_ERRORS:  # pragma: no cover
+                raise
+        except WebSocketError:
+            pass
+        except Exception as exc:
+            print_exception(exc)
+        finally:  # pragma: no cover
+            try:
+                await ws.close()
+            except Exception:
+                pass
+        return Response.already_handled
+    return wrapper
+
+
 def with_websocket(f):
     """Decorator to make a route a WebSocket endpoint.
 
@@ -160,18 +223,9 @@ def with_websocket(f):
 
         @app.route('/echo')
         @with_websocket
-        def echo(request, ws):
+        async def echo(request, ws):
             while True:
-                message = ws.receive()
+                message = await ws.receive()
-                ws.send(message)
+                await ws.send(message)
     """
-    def wrapper(request, *args, **kwargs):
+    return websocket_wrapper(f, websocket_upgrade)
-        ws = websocket_upgrade(request)
-        try:
-            f(request, ws, *args, **kwargs)
-            ws.close()  # pragma: no cover
-        except OSError as exc:
-            if exc.errno not in [32, 54, 104]:  # pragma: no cover
-                raise
-        return ''
-    return wrapper