microdot 2.3.1__tar.gz → 2.3.3__tar.gz

{microdot-2.3.1/src/microdot.egg-info → microdot-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microdot
-Version: 2.3.1
+Version: 2.3.3
 Summary: The impossibly small web framework for MicroPython
 Author-email: Miguel Grinberg <miguel.grinberg@gmail.com>
 Project-URL: Homepage, https://github.com/miguelgrinberg/microdot

{microdot-2.3.1 → microdot-2.3.3}/docs/api.rst

@@ -13,6 +13,8 @@ Core API
 .. autoclass:: microdot.Response
    :members:
 
+.. autoclass:: microdot.URLPattern
+   :members:
 
 Multipart Forms
 ---------------

{microdot-2.3.1 → microdot-2.3.3}/docs/extensions.rst

@@ -116,6 +116,33 @@ Example::
             message = await ws.receive()
             await ws.send(message)
 
+To end the WebSocket connection, the route handler can exit, without returning
+anything::
+
+    @app.route('/echo')
+    @with_websocket
+    async def echo(request, ws):
+        while True:
+            message = await ws.receive()
+            if message == 'exit':
+                break
+            await ws.send(message)
+        await ws.send('goodbye')
+
+If the client ends the WebSocket connection from their side, the route function
+is cancelled. The route function can catch the ``CancelledError`` exception
+from asyncio to perform cleanup tasks::
+
+    @app.route('/echo')
+    @with_websocket
+    async def echo(request, ws):
+        try:
+            while True:
+                message = await ws.receive()
+                await ws.send(message)
+        except asyncio.CancelledError:
+            print('Client disconnected!')
+
 Server-Sent Events
 ~~~~~~~~~~~~~~~~~~
 
@@ -153,6 +180,25 @@ Example::
             await sse.send({'counter': i})  # unnamed event
         await sse.send('end', event='comment')  # named event
 
+To end the SSE connection, the route handler can exit, without returning
+anything, as shown in the above examples.
+
+If the client ends the SSE connection from their side, the route function is
+cancelled. The route function can catch the ``CancelledError`` exception from
+asyncio to perform cleanup tasks::
+
+    @app.route('/events')
+    @with_sse
+    async def events(request, sse):
+        try:
+            i = 0
+            while True:
+                await asyncio.sleep(1)
+                await sse.send({'counter': i})
+                i += 1
+        except asyncio.CancelledError:
+            print('Client disconnected!')
+
 .. note::
    The SSE protocol is unidirectional, so there is no ``receive()`` method in
    the SSE object. For bidirectional communication with the client, use the
@@ -420,13 +466,13 @@ be protected with the ``auth.optional`` decorator::
     @app.route('/')
     @auth.optional
     async def index(request):
-        if g.current_user:
+        if request.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.
+As shown in the example, a route can check ``request.g.current_user`` to
+determine if the user is authenticated or not.
 
 Token Authentication
 ^^^^^^^^^^^^^^^^^^^^
@@ -446,7 +492,8 @@ or ``None`` if the token is invalid or expired::
         return load_user_from_token(token)
 
 As with Basic authentication, the ``auth`` instance is used as a decorator to
-protect your routes::
+protect your routes, and the authenticated user is accessible from the request
+object as ``request.g.current_user``::
 
     @app.route('/')
     @auth
@@ -458,7 +505,7 @@ Optional authentication can also be used with tokens::
     @app.route('/')
     @auth.optional
     async def index(request):
-        if g.current_user:
+        if request.g.current_user:
             return f'Hello, {request.g.current_user}!'
         else:
             return 'Hello, anonymous user!'

{microdot-2.3.1 → microdot-2.3.3}/docs/intro.rst

@@ -601,6 +601,13 @@ The request object provides access to the request attributes, including:
   specified by the client, or ``None`` if no content type was specified.
 - :attr:`content_length <microdot.Request.content_length>`: The content
   length of the request, or 0 if no content length was specified.
+- :attr:`json <microdot.Request.json>`: The parsed JSON data in the request
+  body. See :ref:`below <JSON Payloads>` for additional details.
+- :attr:`form <microdot.Request.form>`: The parsed form data in the request
+  body, as a dictionary. See :ref:`below <Form Data>` for additional details.
+- :attr:`files <microdot.Request.files>`: A dictionary with the file uploads
+  included in the request body. Note that file uploads are only supported when
+  the :ref:`Multipart Forms` extension is used.
 - :attr:`client_addr <microdot.Request.client_addr>`: The network address of
   the client, as a tuple (host, port).
 - :attr:`app <microdot.Request.app>`: The application instance that created the
@@ -627,8 +634,8 @@ to use this attribute::
    The client must set the ``Content-Type`` header to ``application/json`` for
    the ``json`` attribute of the request object to be populated.
 
-URLEncoded Form Data
-^^^^^^^^^^^^^^^^^^^^
+Form Data
+^^^^^^^^^
 
 The request object also supports standard HTML form submissions through the
 :attr:`form <microdot.Request.form>` attribute, which presents the form data
@@ -642,9 +649,10 @@ as a :class:`MultiDict <microdot.MultiDict>` object. Example::
         return f'Hello {name}'
 
 .. note::
-   Form submissions are only parsed when the ``Content-Type`` header is set by
-   the client to ``application/x-www-form-urlencoded``. Form submissions using
-   the ``multipart/form-data`` content type are currently not supported.
+   Form submissions automatically parsed when the ``Content-Type`` header is
+   set by the client to ``application/x-www-form-urlencoded``. For form
+   submissions that use the ``multipart/form-data`` content type the
+   :ref:`Multipart Forms` extension must be used.
 
 Accessing the Raw Request Body
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -749,15 +757,18 @@ sections describe the different types of responses that are supported.
 The Three Parts of a Response
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Route functions can return one, two or three values. The first or only value is
-always returned to the client in the response body::
+Route functions can return one, two or three values. The first and most
+important value is the response body::
 
     @app.get('/')
     async def index(request):
         return 'Hello, World!'
 
-In the above example, Microdot issues a standard 200 status code response, and
-inserts default headers.
+In the above example, Microdot issues a standard 200 status code response
+indicating a successful request. The body of the response is the
+``'Hello, World!'`` string returned by the function. Microdot includes default
+headers with this response, including the ``Content-Type`` header set to
+``text/plain`` to indicate a response in plain text.
 
 The application can provide its own status code as a second value returned from
 the route to override the 200 default. The example below returns a 202 status
@@ -769,22 +780,30 @@ code::
 
 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::
+The next example returns an HTML response, instead of the default plain text
+response::
 
     @app.get('/')
     async def index(request):
         return '<h1>Hello, World!</h1>', 202, {'Content-Type': 'text/html'}
 
-If the application 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::
+If the application does not need to return a body, then it can omit it and
+have the status code as the first or only returned value::
+
+    @app.get('/')
+    async def index(request):
+        return 204
+
+Likewise, if the application needs to return a body and custom headers, but
+does not need to change the default status code, then it can return two values,
+omitting the status code::
 
     @app.get('/')
     async def index(request):
         return '<h1>Hello, World!</h1>', {'Content-Type': 'text/html'}
 
-The application can also return a :class:`Response <microdot.Response>` object
-containing all the details of the response as a single value.
+Lastly, the application can also return a :class:`Response <microdot.Response>`
+object containing all the details of the response as a single value.
 
 JSON Responses
 ^^^^^^^^^^^^^^

{microdot-2.3.1 → microdot-2.3.3}/pyproject.toml

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

{microdot-2.3.1 → microdot-2.3.3}/src/microdot/auth.py

@@ -85,7 +85,7 @@ class BasicAuth(BaseAuth):
                 return None
             return username, password
 
-    def authentication_error(self, request):
+    async def authentication_error(self, request):
         return '', self.error_status, {
             'WWW-Authenticate': '{} realm="{}", charset="{}"'.format(
                 self.scheme, self.realm, self.charset)}
@@ -158,5 +158,5 @@ class TokenAuth(BaseAuth):
         """
         self.error_callback = f
 
-    def authentication_error(self, request):
+    async def authentication_error(self, request):
         abort(self.error_status)

{microdot-2.3.1 → microdot-2.3.3}/src/microdot/microdot.py

@@ -554,6 +554,7 @@ class Response:
         'json': 'application/json',
         'png': 'image/png',
         'txt': 'text/plain',
+        'svg': 'image/svg+xml',
     }
 
     send_file_buffer_size = 1024
@@ -814,6 +815,17 @@ class Response:
 
 
 class URLPattern():
+    """A class that represents the URL pattern for a route.
+
+    :param url_pattern: The route URL pattern, which can include static and
+                        dynamic path segments. Dynamic segments are enclosed in
+                        ``<`` and ``>``. The type of the segment can be given
+                        as a prefix, separated from the name with a colon.
+                        Supported types are ``string`` (the default),
+                        ``int`` and ``path``. Custom types can be registered
+                        using the :meth:`URLPattern.register_type` method.
+    """
+
     segment_patterns = {
         'string': '/([^/]+)',
         'int': '/(-?\\d+)',
@@ -823,12 +835,32 @@ class URLPattern():
         'int': lambda value: int(value),
     }
 
+    @classmethod
+    def register_type(cls, type_name, pattern='[^/]+', parser=None):
+        """Register a new URL segment type.
+
+        :param type_name: The name of the segment type to register.
+        :param pattern: The regular expression pattern to use when matching
+                        this segment type. If not given, a default matcher for
+                        a single path segment is used.
+        :param parser: A callable that will be used to parse and transform the
+                       value of the segment. If omitted, the value is returned
+                       as a string.
+        """
+        cls.segment_patterns[type_name] = '/({})'.format(pattern)
+        cls.segment_parsers[type_name] = parser
+
     def __init__(self, url_pattern):
         self.url_pattern = url_pattern
         self.segments = []
         self.regex = None
 
     def compile(self):
+        """Generate a regular expression for the URL pattern.
+
+        This method is automatically invoked the first time the URL pattern is
+        matched against a path.
+        """
         pattern = ''
         for segment in self.url_pattern.lstrip('/').split('/'):
             if segment and segment[0] == '<':
@@ -856,12 +888,12 @@ class URLPattern():
         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):
+        """Match a path against the URL pattern.
+
+        Returns a dictionary with the values of all dynamic path segments if a
+        matche is found, or ``None`` if the path does not match this pattern.
+        """
         args = {}
         g = (self.regex or self.compile()).match(path)
         if not g:

{microdot-2.3.1 → microdot-2.3.3}/src/microdot/sse.py

@@ -61,7 +61,14 @@ def sse_response(request, event_function, *args, **kwargs):
     sse = SSE()
 
     async def sse_task_wrapper():
-        await event_function(request, sse, *args, **kwargs)
+        try:
+            await event_function(request, sse, *args, **kwargs)
+        except asyncio.CancelledError:  # pragma: no cover
+            pass
+        except Exception as exc:
+            # the SSE task raised an exception so we need to pass it to the
+            # main route so that it is re-raised there
+            sse.queue.append(exc)
         sse.event.set()
 
     task = asyncio.create_task(sse_task_wrapper())
@@ -79,7 +86,11 @@ def sse_response(request, event_function, *args, **kwargs):
                 except IndexError:
                     await sse.event.wait()
                     sse.event.clear()
-            if event is None:
+            if isinstance(event, Exception):
+                # if the event is an exception we re-raise it here so that it
+                # can be handled appropriately
+                raise event
+            elif event is None:
                 raise StopAsyncIteration
             return event
 

{microdot-2.3.1 → microdot-2.3.3}/src/microdot/test_client.py

@@ -1,3 +1,4 @@
+import asyncio
 from microdot.microdot import Request, Response, AsyncBytesIO
 
 try:
@@ -32,6 +33,11 @@ class TestResponse:
         #: The body of the JSON response, decoded to a dictionary or list. Set
         #: ``Note`` if the response does not have a JSON payload.
         self.json = None
+        #: The body of the SSE response, decoded to a list of events, each
+        #: given as a dictionary with a ``data`` key and optionally also
+        #: ``event`` and ``id`` keys. Set to ``None`` if the response does not
+        #: have an SSE payload.
+        self.events = None
 
     def _initialize_response(self, res):
         self.status_code = res.status_code
@@ -41,10 +47,13 @@ class TestResponse:
     async def _initialize_body(self, res):
         self.body = b''
         iter = res.body_iter()
-        async for body in iter:  # pragma: no branch
-            if isinstance(body, str):
-                body = body.encode()
-            self.body += body
+        try:
+            async for body in iter:  # pragma: no branch
+                if isinstance(body, str):
+                    body = body.encode()
+                self.body += body
+        except asyncio.CancelledError:  # pragma: no cover
+            pass
         if hasattr(iter, 'aclose'):  # pragma: no branch
             await iter.aclose()
 
@@ -60,6 +69,32 @@ class TestResponse:
             if content_type.split(';')[0] == 'application/json':
                 self.json = json.loads(self.text)
 
+    def _process_sse_body(self):
+        if 'Content-Type' in self.headers:  # pragma: no branch
+            content_type = self.headers['Content-Type']
+            if content_type.split(';')[0] == 'text/event-stream':
+                self.events = []
+                for sse_event in self.body.split(b'\n\n'):
+                    data = None
+                    event = None
+                    event_id = None
+                    for line in sse_event.split(b'\n'):
+                        if line.startswith(b'data:'):
+                            data = line[5:].strip()
+                        elif line.startswith(b'event:'):
+                            event = line[6:].strip().decode()
+                        elif line.startswith(b'id:'):
+                            event_id = line[3:].strip().decode()
+                    if data:
+                        data_json = None
+                        try:
+                            data_json = json.loads(data)
+                        except ValueError:
+                            pass
+                        self.events.append({
+                            "data": data, "data_json": data_json,
+                            "event": event, "event_id": event_id})
+
     @classmethod
     async def create(cls, res):
         test_res = cls()
@@ -68,6 +103,7 @@ class TestResponse:
             await test_res._initialize_body(res)
             test_res._process_text_body()
             test_res._process_json_body()
+            test_res._process_sse_body()
         return test_res
 
 

{microdot-2.3.1 → microdot-2.3.3}/src/microdot/websocket.py

@@ -149,18 +149,18 @@ class WebSocket:
             raise WebSocketError('Websocket connection closed')
         fin, opcode, has_mask, length = self._parse_frame_header(header)
         if length == -2:
-            length = await self.request.sock[0].read(2)
+            length = await self.request.sock[0].readexactly(2)
             length = int.from_bytes(length, 'big')
         elif length == -8:
-            length = await self.request.sock[0].read(8)
+            length = await self.request.sock[0].readexactly(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 = await self.request.sock[0].read(4)
-        payload = await self.request.sock[0].read(length)
+            mask = await self.request.sock[0].readexactly(4)
+        payload = await self.request.sock[0].readexactly(length)
         if has_mask:  # pragma: no cover
             payload = bytes(x ^ mask[i % 4] for i, x in enumerate(payload))
         return opcode, payload

{microdot-2.3.1 → microdot-2.3.3/src/microdot.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microdot
-Version: 2.3.1
+Version: 2.3.3
 Summary: The impossibly small web framework for MicroPython
 Author-email: Miguel Grinberg <miguel.grinberg@gmail.com>
 Project-URL: Homepage, https://github.com/miguelgrinberg/microdot

{microdot-2.3.1 → microdot-2.3.3}/tests/test_sse.py

@@ -42,3 +42,40 @@ class TestWebSocket(unittest.TestCase):
                                          'data: [42, "foo", "bar"]\n\n'
                                          'data: foo\n\n'
                                          'data: foo\n\n'))
+        self.assertEqual(len(response.events), 8)
+        self.assertEqual(response.events[0], {
+            'data': b'foo', 'data_json': None, 'event': None,
+            'event_id': None})
+        self.assertEqual(response.events[1], {
+            'data': b'bar', 'data_json': None, 'event': 'test',
+            'event_id': None})
+        self.assertEqual(response.events[2], {
+            'data': b'bar', 'data_json': None, 'event': 'test',
+            'event_id': 'id42'})
+        self.assertEqual(response.events[3], {
+            'data': b'bar', 'data_json': None, 'event': None,
+            'event_id': 'id42'})
+        self.assertEqual(response.events[4], {
+            'data': b'{"foo": "bar"}', 'data_json': {'foo': 'bar'},
+            'event': None, 'event_id': None})
+        self.assertEqual(response.events[5], {
+            'data': b'[42, "foo", "bar"]', 'data_json': [42, 'foo', 'bar'],
+            'event': None, 'event_id': None})
+        self.assertEqual(response.events[6], {
+            'data': b'foo', 'data_json': None, 'event': None,
+            'event_id': None})
+        self.assertEqual(response.events[7], {
+            'data': b'foo', 'data_json': None, 'event': None,
+            'event_id': None})
+
+    def test_sse_exception(self):
+        app = Microdot()
+
+        @app.route('/sse')
+        @with_sse
+        async def handle_sse(request, sse):
+            await sse.send('foo')
+            await sse.send(1 / 0)
+
+        client = TestClient(app)
+        self.assertRaises(ZeroDivisionError, self._run, client.get('/sse'))