microdot 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: microdot
-Version: 2.1.0
+Version: 2.2.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.2.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.2.0}/docs/api.rst

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

{microdot-2.1.0 → microdot-2.2.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/>`_
@@ -369,6 +450,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.2.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.2.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.2.0}/pyproject.toml

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

{microdot-2.1.0 → microdot-2.2.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.2.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

{microdot-2.1.0 → microdot-2.2.0}/src/microdot/microdot.py

@@ -8,6 +8,7 @@ servers for MicroPython and standard Python.
 import asyncio
 import io
 import json
+import re
 import time
 
 try:
@@ -56,23 +57,9 @@ MUTED_SOCKET_ERRORS = [
 ]
 
 
-def urldecode_str(s):
-    s = s.replace('+', ' ')
-    parts = s.split('%')
-    if len(parts) == 1:
-        return s
-    result = [parts[0]]
-    for item in parts[1:]:
-        if item == '':
-            result.append('%')
-        else:
-            code = item[:2]
-            result.append(chr(int(code, 16)))
-            result.append(item[2:])
-    return ''.join(result)
-
-
-def urldecode_bytes(s):
+def urldecode(s):
+    if isinstance(s, str):
+        s = s.encode()
     s = s.replace(b'+', b' ')
     parts = s.split(b'%')
     if len(parts) == 1:
@@ -384,6 +371,7 @@ class Request:
         self.sock = sock
         self._json = None
         self._form = None
+        self._files = None
         self.after_request_handlers = []
 
     @staticmethod
@@ -440,12 +428,12 @@ class Request:
             if isinstance(urlencoded, str):
                 for kv in [pair.split('=', 1)
                            for pair in urlencoded.split('&') if pair]:
-                    data[urldecode_str(kv[0])] = urldecode_str(kv[1]) \
+                    data[urldecode(kv[0])] = urldecode(kv[1]) \
                         if len(kv) > 1 else ''
             elif isinstance(urlencoded, bytes):  # pragma: no branch
                 for kv in [pair.split(b'=', 1)
                            for pair in urlencoded.split(b'&') if pair]:
-                    data[urldecode_bytes(kv[0])] = urldecode_bytes(kv[1]) \
+                    data[urldecode(kv[0])] = urldecode(kv[1]) \
                         if len(kv) > 1 else b''
         return data
 
@@ -478,7 +466,13 @@ class Request:
     def form(self):
         """The parsed form submission body, as a
         :class:`MultiDict <microdot.MultiDict>` object, or ``None`` if the
-        request does not have a form submission."""
+        request does not have a form submission.
+
+        Forms that are URL encoded are processed by default. For multipart
+        forms to be processed, the
+        :func:`with_form_data <microdot.multipart.with_form_data>`
+        decorator must be added to the route.
+        """
         if self._form is None:
             if self.content_type is None:
                 return None
@@ -488,6 +482,17 @@ class Request:
             self._form = self._parse_urlencoded(self.body)
         return self._form
 
+    @property
+    def files(self):
+        """The files uploaded in the request as a dictionary, or ``None`` if
+        the request does not have any files.
+
+        The :func:`with_form_data <microdot.multipart.with_form_data>`
+        decorator must be added to the route that receives file uploads for
+        this property to be set.
+        """
+        return self._files
+
     def after_request(self, f):
         """Register a request-specific function to run after the request is
         handled. Request-specific after request handlers run at the very end,
@@ -805,13 +810,23 @@ class Response:
 
 
 class URLPattern():
+    segment_patterns = {
+        'string': '/([^/]+)',
+        'int': '/(-?\\d+)',
+        'path': '/(.+)',
+    }
+    segment_parsers = {
+        'int': lambda value: int(value),
+    }
+
     def __init__(self, url_pattern):
         self.url_pattern = url_pattern
         self.segments = []
         self.regex = None
+
+    def compile(self):
         pattern = ''
-        use_regex = False
-        for segment in url_pattern.lstrip('/').split('/'):
+        for segment in self.url_pattern.lstrip('/').split('/'):
             if segment and segment[0] == '<':
                 if segment[-1] != '>':
                     raise ValueError('invalid URL pattern')
@@ -822,82 +837,44 @@ class URLPattern():
                     type_ = 'string'
                     name = segment
                 parser = None
-                if type_ == 'string':
-                    parser = self._string_segment
-                    pattern += '/([^/]+)'
-                elif type_ == 'int':
-                    parser = self._int_segment
-                    pattern += '/(-?\\d+)'
-                elif type_ == 'path':
-                    use_regex = True
-                    pattern += '/(.+)'
-                elif type_.startswith('re:'):
-                    use_regex = True
+                if type_.startswith('re:'):
                     pattern += '/({pattern})'.format(pattern=type_[3:])
                 else:
-                    raise ValueError('invalid URL segment type')
+                    if type_ not in self.segment_patterns:
+                        raise ValueError('invalid URL segment type')
+                    pattern += self.segment_patterns[type_]
+                    parser = self.segment_parsers.get(type_)
                 self.segments.append({'parser': parser, 'name': name,
                                       'type': type_})
             else:
                 pattern += '/' + segment
-                self.segments.append({'parser': self._static_segment(segment)})
-        if use_regex:
-            import re
-            self.regex = re.compile('^' + pattern + '$')
+                self.segments.append({'parser': None})
+        self.regex = re.compile('^' + pattern + '$')
+        return self.regex
+
+    @classmethod
+    def register_type(cls, type_name, pattern='[^/]+', parser=None):
+        cls.segment_patterns[type_name] = '/({})'.format(pattern)
+        cls.segment_parsers[type_name] = parser
 
     def match(self, path):
         args = {}
-        if self.regex:
-            g = self.regex.match(path)
-            if not g:
-                return
-            i = 1
-            for segment in self.segments:
-                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)
+        g = (self.regex or self.compile()).match(path)
+        if not g:
+            return
+        i = 1
+        for segment in self.segments:
+            if 'name' not in segment:
+                continue
+            arg = g.group(i)
+            if segment['parser']:
+                arg = self.segment_parsers[segment['type']](arg)
                 if arg is None:
                     return
-                if 'name' in segment:
-                    args[segment['name']] = arg
-            if path is not None:
-                return
+            args[segment['name']] = arg
+            i += 1
         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
-
     def __repr__(self):  # pragma: no cover
         return 'URLPattern: {}'.format(self.url_pattern)