microdot 2.1.0__tar.gz → 2.3.0__tar.gz

{microdot-2.1.0/src/microdot.egg-info → microdot-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: microdot
-Version: 2.1.0
+Version: 2.3.0
 Summary: The impossibly small web framework for MicroPython
 Author-email: Miguel Grinberg <miguel.grinberg@gmail.com>
 Project-URL: Homepage, https://github.com/miguelgrinberg/microdot
@@ -19,6 +19,7 @@ Requires-Dist: tox; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: pyjwt; extra == "docs"
+Dynamic: license-file
 
 # microdot
 [![Build status](https://github.com/miguelgrinberg/microdot/workflows/build/badge.svg)](https://github.com/miguelgrinberg/microdot/actions) [![codecov](https://codecov.io/gh/miguelgrinberg/microdot/branch/main/graph/badge.svg)](https://codecov.io/gh/miguelgrinberg/microdot)
@@ -65,8 +66,8 @@ describes the backwards incompatible changes that were made.
 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
+- Authentication support, similar to [Flask-Login](https://github.com/maxcountryman/flask-login) for Flask (**Added in version 2.1**)
+- Support for forms encoded in `multipart/form-data` format (**Added in version 2.2**)
 - OpenAPI integration, similar to [APIFairy](https://github.com/miguelgrinberg/apifairy) for Flask
 
 In addition to the above, the following extensions are also under consideration,
@@ -75,4 +76,4 @@ 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)!
+Do you have other ideas to propose? Let's [discuss them](https://github.com/:miguelgrinberg/microdot/discussions/new?category=ideas)!

{microdot-2.1.0 → microdot-2.3.0}/README.md

@@ -43,8 +43,8 @@ describes the backwards incompatible changes that were made.
 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
+- Authentication support, similar to [Flask-Login](https://github.com/maxcountryman/flask-login) for Flask (**Added in version 2.1**)
+- Support for forms encoded in `multipart/form-data` format (**Added in version 2.2**)
 - OpenAPI integration, similar to [APIFairy](https://github.com/miguelgrinberg/apifairy) for Flask
 
 In addition to the above, the following extensions are also under consideration,
@@ -53,4 +53,4 @@ 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)!
+Do you have other ideas to propose? Let's [discuss them](https://github.com/:miguelgrinberg/microdot/discussions/new?category=ideas)!

{microdot-2.1.0 → microdot-2.3.0}/docs/api.rst

@@ -14,6 +14,12 @@ Core API
    :members:
 
 
+Multipart Forms
+---------------
+
+.. automodule:: microdot.multipart
+   :members:
+
 WebSocket
 ---------
 

{microdot-2.1.0 → microdot-2.3.0}/docs/extensions.rst

@@ -5,8 +5,82 @@ Microdot is a highly extensible web application framework. The extensions
 described in this section are maintained as part of the Microdot project in
 the same source code repository.
 
+Multipart Forms
+~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     -  | `multipart.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/multipart.py>`_
+        | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `formdata.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/uploads/formdata.py>`_
+
+The multipart extension handles multipart forms, including those that have file
+uploads.
+
+The :func:`with_form_data <microdot.multipart.with_form_data>` decorator
+provides the simplest way to work with these forms. With this decorator added
+to the route, whenever the client sends a multipart request the
+:attr:`request.form <microdot.Request.form>` and
+:attr:`request.files <microdot.Request.files>` properties are populated with
+the submitted data. For form fields the field values are always strings. For
+files, they are instances of the
+:class:`FileUpload <microdot.multipart.FileUpload>` class.
+
+Example::
+
+    from microdot.multipart import with_form_data
+
+    @app.post('/upload')
+    @with_form_data
+    async def upload(request):
+        print('form fields:', request.form)
+        print('files:', request.files)
+
+One disadvantage of the ``@with_form_data`` decorator is that it has to copy
+any uploaded files to memory or temporary disk files, depending on their size.
+The :attr:`FileUpload.max_memory_size <microdot.multipart.FileUpload.max_memory_size>`
+attribute can be used to control the cutoff size above which a file upload
+is transferred to a temporary file.
+
+A more performant alternative to the ``@with_form_data`` decorator is the
+:class:`FormDataIter <microdot.multipart.FormDataIter>` class, which iterates
+over the form fields sequentially, giving the application the option to parse
+the form fields on the fly and decide what to copy and what to discard. When
+using ``FormDataIter`` the ``request.form`` and ``request.files`` attributes
+are not used.
+
+Example::
+
+
+    from microdot.multipart import FormDataIter
+
+    @app.post('/upload')
+    async def upload(request):
+        async for name, value in FormDataIter(request):
+            print(name, value)
+
+For fields that contain an uploaded file, the ``value`` returned by the
+iterator is the same ``FileUpload`` instance. The application can choose to
+save the file with the :meth:`save() <microdot.multipart.FileUpload.save>`
+method, or read it with the :meth:`read() <microdot.multipart.FileUpload.read>`
+method, optionally passing a size to read it in chunks. The
+:meth:`copy() <microdot.multipart.FileUpload.copy>` method is also available to
+apply the copying logic used by the ``@with_form_data`` decorator, which is
+inefficient but allows the file to be set aside to be processed later, after
+the remaining form fields.
+
 WebSocket
-~~~~~~~~-
+~~~~~~~~~
 
 .. list-table::
    :align: left
@@ -16,6 +90,7 @@ WebSocket
 
    * - Required Microdot source files
      -  | `websocket.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/websocket.py>`_
+        | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
 
    * - Required external dependencies
      - | None
@@ -32,12 +107,14 @@ messages respectively.
 
 Example::
 
-        @app.route('/echo')
-        @with_websocket
-        async def echo(request, ws):
-            while True:
-                message = await ws.receive()
-                await ws.send(message)
+    from microdot.websocket import with_websocket
+
+    @app.route('/echo')
+    @with_websocket
+    async def echo(request, ws):
+        while True:
+            message = await ws.receive()
+            await ws.send(message)
 
 Server-Sent Events
 ~~~~~~~~~~~~~~~~~~
@@ -50,6 +127,7 @@ Server-Sent Events
 
    * - Required Microdot source files
      -  | `sse.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/sse.py>`_
+        | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
 
    * - Required external dependencies
      - | None
@@ -65,6 +143,8 @@ asynchronous method to send an event to the client.
 
 Example::
 
+    from microdot.sse import with_sse
+
     @app.route('/events')
     @with_sse
     async def events(request, sse):
@@ -213,6 +293,7 @@ Secure User Sessions
 
    * - Required Microdot source files
      - | `session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/session.py>`_
+       | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
 
    * - Required external dependencies
      - | CPython: `PyJWT <https://pyjwt.readthedocs.io/>`_
@@ -333,10 +414,25 @@ decorator::
 While running an authenticated request, the user object returned by the
 authenticaction function is accessible as ``request.g.current_user``.
 
+If an endpoint is intended to work with or without authentication, then it can
+be protected with the ``auth.optional`` decorator::
+
+    @app.route('/')
+    @auth.optional
+    async def index(request):
+        if g.current_user:
+            return f'Hello, {request.g.current_user}!'
+        else:
+            return 'Hello, anonymous user!'
+
+As shown in the example, a route can check ``g.current_user`` to determine if
+the user is authenticated or not.
+
 Token Authentication
 ^^^^^^^^^^^^^^^^^^^^
 
-To set up token authentication, create an instance of :class:`TokenAuth <microdot.auth.TokenAuth>`::
+To set up token authentication, create an instance of
+:class:`TokenAuth <microdot.auth.TokenAuth>`::
 
     from microdot.auth import TokenAuth
 
@@ -356,7 +452,17 @@ protect your routes::
     @auth
     async def index(request):
         return f'Hello, {request.g.current_user}!'
-        
+
+Optional authentication can also be used with tokens::
+
+    @app.route('/')
+    @auth.optional
+    async def index(request):
+        if g.current_user:
+            return f'Hello, {request.g.current_user}!'
+        else:
+            return 'Hello, anonymous user!'
+
 User Logins
 ~~~~~~~~~~~
 
@@ -369,6 +475,7 @@ User Logins
    * - Required Microdot source files
      - | `login.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/auth.py>`_
        | `session.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/session.py>`_
+       | `helpers.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/helpers.py>`_
    * - Required external dependencies
      - | CPython: `PyJWT <https://pyjwt.readthedocs.io/>`_
        | MicroPython: `jwt.py <https://github.com/micropython/micropython-lib/blob/master/python-ecosys/pyjwt/jwt.py>`_,

{microdot-2.1.0 → microdot-2.3.0}/docs/freezing.rst

@@ -1,5 +1,8 @@
-Cross-Compiling and Freezing Microdot (MicroPython Only)
---------------------------------------------------------
+Cross-Compiling and Freezing Microdot
+-------------------------------------
+
+.. note::
+   This section only applies when using Microdot on MicroPython.
 
 Microdot is a fairly small framework, so its size is not something you need to
 be concerned about unless you are working with MicroPython on hardware with a
@@ -36,7 +39,7 @@ 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.
+once the code is compiled they are able to run it just fine.
 
 To address this, MicroPython allows you to cross-compile source files on your
 desktop or laptop computer and then upload their compiled versions to the
@@ -82,8 +85,8 @@ 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.
+different for each microcontroller platform, so you will need to consult the
+MicroPython documentation that applies to your device to learn how to do this.
 
 The part of the process that is common to all devices is the creation of a
 `manifest file <https://docs.micropython.org/en/latest/reference/manifest.html>`_

{microdot-2.1.0 → microdot-2.3.0}/docs/intro.rst

@@ -329,15 +329,52 @@ URL::
     async def get_test(request, path):
         return 'Test: ' + path
 
-For the most control, the ``re`` type allows the application to provide a
-custom regular expression for the dynamic component. The next example defines
-a route that only matches usernames that begin with an upper or lower case
-letter, followed by a sequence of letters or numbers::
+The ``re`` type allows the application to provide a custom regular expression
+for the dynamic component. The next example defines a route that only matches
+usernames that begin with an upper or lower case letter, followed by a sequence
+of letters or numbers::
 
     @app.get('/users/<re:[a-zA-Z][a-zA-Z0-9]*:username>')
     async def get_user(request, username):
         return 'User: ' + username
 
+The ``re`` type returns the URL component as a string, which sometimes may not
+be the most convenient. To convert a path component to something more
+meaningful than a string, the application can register a custom URL component
+type and provide a parser function that performs the conversion. In the
+following example, a ``hex`` custom type is registered to automatically
+convert hex numbers given in the path to numbers::
+
+    from microdot import URLPattern
+
+    URLPattern.register_type('hex', parser=lambda value: int(value, 16))
+
+    @app.get('/users/<hex:user_id>')
+    async def get_user(request, user_id):
+        user = get_user_by_id(user_id)
+        # ...
+
+In addition to the parser, the custom URL component can include a pattern,
+given as a regular expression. When a pattern is provided, the URL component
+will only match if the regular expression matches the value passed in the URL.
+The ``hex`` example above can be expanded with a pattern as follows::
+
+    URLPattern.register_type('hex', pattern='[0-9a-fA-F]+',
+                             parser=lambda value: int(value, 16))
+
+In cases where a pattern isn't provided, or when the pattern is unable to
+filter out all invalid values, the parser function can return ``None`` to
+indicate a failed match. The next example shows how the parser for the ``hex``
+type can be expanded to do that::
+
+    def hex_parser(value):
+        try:
+            return int(value, 16)
+        except ValueError:
+            return None
+
+    URLPattern.register_type('hex', parser=hex_parser)
+
 .. note::
    Dynamic path components are passed to route functions as keyword arguments,
    so the names of the function arguments must match the names declared in the
@@ -895,18 +932,36 @@ Another option is to create a response object directly in the route function::
 Concurrency
 ~~~~~~~~~~~
 
-Microdot implements concurrency through the ``asyncio`` package. Applications
-must ensure their handlers do not block, as this will prevent other concurrent
-requests from being handled.
+Microdot implements concurrency through the ``asyncio`` package, which means
+that applications must be careful to prevent blocking in their handlers.
+
+"async def" handlers
+^^^^^^^^^^^^^^^^^^^^
+
+The recommendation for route handlers in Microdot is to use asynchronous
+functions, declared as ``async def``. Microdot executes these handler
+functions as native asynchronous tasks. The standard considerations for writing
+asynchronous code apply, and in particular blocking calls should be avoided to
+ensure the application runs smoothly and is always responsive.
+
+"def" handlers
+^^^^^^^^^^^^^^
+
+Microdot also supports the use of synchronous route handlers, declared as
+standard ``def`` functions. These handlers are handled differently under
+CPython and MicroPython.
 
-When running under CPython, ``async def`` handler functions run as native 
-asyncio tasks, while ``def`` handler functions are executed in a
-`thread executor <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor>`_
-to prevent them from blocking the asynchronous loop.
+When running on CPython, Microdot executes synchronous handlers in a
+`thread executor <https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.run_in_executor>`_,
+which uses a thread pool. The use of blocking or CPU intensive code in these
+handlers does not have such a negative effect on the application, because
+handlers do not run on the same thread as the asynchronous loop. On the other
+hand, the application will be affected by threading issues such as those caused
+by the Global Interpreter Lock.
 
 Under MicroPython the situation is different. Most microcontroller boards
-implementing MicroPython do not have threading support or executors, so ``def``
-handler functions in this platform can only run in the main and only thread.
-These functions will block the asynchronous loop when they take too long to
-complete so ``async def`` handlers properly written to allow other handlers to
-run in parallel should be preferred.
+do not have or have very limited threading support, so Microdot executes
+synchronous handlers in the main and often only thread available. This means
+that these functions will block the asynchronous loop when they take too long
+to complete. The use of properly written asynchronous handlers should be
+preferred.

{microdot-2.1.0 → microdot-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "microdot"
-version = "2.1.0"
+version = "2.3.0"
 authors = [
     { name = "Miguel Grinberg", email = "miguel.grinberg@gmail.com" },
 ]

{microdot-2.1.0 → microdot-2.3.0}/src/microdot/__init__.py

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

{microdot-2.1.0 → microdot-2.3.0}/src/microdot/auth.py

@@ -36,6 +36,24 @@ class BaseAuth:
 
         return wrapper
 
+    def optional(self, f):
+        """Decorator to protect a route with optional authentication.
+
+        This decorator makes authentication for the decorated route optional,
+        meaning that the route is allowed to run with or with
+        authentication given in the request.
+        """
+        async def wrapper(request, *args, **kwargs):
+            auth = self._get_auth(request)
+            if not auth:
+                request.g.current_user = None
+            else:
+                request.g.current_user = await invoke_handler(
+                    self.auth_callback, request, *auth)
+            return await invoke_handler(f, request, *args, **kwargs)
+
+        return wrapper
+
 
 class BasicAuth(BaseAuth):
     """Basic Authentication.

{microdot-2.1.0 → microdot-2.3.0}/src/microdot/jinja.py

@@ -1,19 +1,27 @@
 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.
+    :param kwargs: any additional options to be passed to the Jinja
+                   environment's ``get_template()`` method.
     """
+    #: The Jinja environment. The ``initialize()`` method must be called before
+    #: this attribute is accessed.
+    jinja_env = None
+
     @classmethod
     def initialize(cls, template_dir='templates', enable_async=False,
                    **kwargs):
         """Initialize the templating subsystem.
 
+        This method is automatically invoked when the first template is
+        created. The application can call it explicitly if custom options need
+        to be provided.
+
         :param template_dir: the directory where templates are stored. This
                              argument is optional. The default is to load
                              templates from a *templates* subdirectory.
@@ -23,20 +31,19 @@ class Template:
         :param kwargs: any additional options to be passed to Jinja's
                        ``Environment`` class.
         """
-        global _jinja_env
-        _jinja_env = Environment(
+        cls.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
+    def __init__(self, template, **kwargs):
+        if self.jinja_env is None:  # pragma: no cover
             self.initialize()
-        #: The name of the template
+        #: The name of the template.
         self.name = template
-        self.template = _jinja_env.get_template(template)
+        self.template = self.jinja_env.get_template(template, **kwargs)
 
     def generate(self, *args, **kwargs):
         """Return a generator that renders the template in chunks, with the