microdot 2.5.0__tar.gz → 2.6.0__tar.gz

{microdot-2.5.0/src/microdot.egg-info → microdot-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microdot
-Version: 2.5.0
+Version: 2.6.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
@@ -49,9 +49,16 @@ app.run()
 - Documentation
     - [Latest](https://microdot.readthedocs.io/en/latest/)
     - [Stable (v2)](https://microdot.readthedocs.io/en/stable/)
-- Legacy (v1)
-    - [Code](https://github.com/miguelgrinberg/microdot/tree/v1)
-    - [Documentation](https://microdot.readthedocs.io/en/v1/)
+
+The following links are for version 1 of Microdot:
+
+- [Code](https://github.com/miguelgrinberg/microdot/tree/v1)
+- [Documentation](https://microdot.readthedocs.io/en/v1/)
+
+Note that version 1 is no longer maintained, so you should consider migrating
+to version 2. See the
+[migration notes](https://microdot.readthedocs.io/en/latest/implementation/migrating.html)
+for help.
 
 ## Roadmap
 
@@ -60,7 +67,8 @@ MicroPython and CPython:
 
 - Authentication support, similar to [Flask-Login](https://github.com/maxcountryman/flask-login) for Flask (**Added in version 2.1**)
 - Support for forms encoded in `multipart/form-data` format (**Added in version 2.2**)
-- CSRF protection extension
+- CSRF protection extension (**Added in version 2.5**)
+- Type hints (**Added in version 2.6**)
 - Pub/sub mini-framework for WebSocket and SSE
 - OpenAPI integration, similar to [APIFairy](https://github.com/miguelgrinberg/apifairy) for Flask
 

{microdot-2.5.0 → microdot-2.6.0}/README.md

@@ -25,9 +25,16 @@ app.run()
 - Documentation
     - [Latest](https://microdot.readthedocs.io/en/latest/)
     - [Stable (v2)](https://microdot.readthedocs.io/en/stable/)
-- Legacy (v1)
-    - [Code](https://github.com/miguelgrinberg/microdot/tree/v1)
-    - [Documentation](https://microdot.readthedocs.io/en/v1/)
+
+The following links are for version 1 of Microdot:
+
+- [Code](https://github.com/miguelgrinberg/microdot/tree/v1)
+- [Documentation](https://microdot.readthedocs.io/en/v1/)
+
+Note that version 1 is no longer maintained, so you should consider migrating
+to version 2. See the
+[migration notes](https://microdot.readthedocs.io/en/latest/implementation/migrating.html)
+for help.
 
 ## Roadmap
 
@@ -36,7 +43,8 @@ MicroPython and CPython:
 
 - Authentication support, similar to [Flask-Login](https://github.com/maxcountryman/flask-login) for Flask (**Added in version 2.1**)
 - Support for forms encoded in `multipart/form-data` format (**Added in version 2.2**)
-- CSRF protection extension
+- CSRF protection extension (**Added in version 2.5**)
+- Type hints (**Added in version 2.6**)
 - Pub/sub mini-framework for WebSocket and SSE
 - OpenAPI integration, similar to [APIFairy](https://github.com/miguelgrinberg/apifairy) for Flask
 

{microdot-2.5.0 → microdot-2.6.0}/docs/implementation/migrating.rst

@@ -1,18 +1,14 @@
 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.
+Version 2 of Microdot introduces backwards incompatible changes, so most
+applications built for earlier versions will need to be updated to work
+correctly with Microdot 2. This section describes the changes that were made.
 
 Code reorganization
 ~~~~~~~~~~~~~~~~~~~
 
-The Microdot source code has been moved into a ``microdot`` package,
+The Microdot source code has been moved into a ``microdot`` package in v2,
 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.
@@ -33,11 +29,11 @@ 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.
+server logic directly with asyncio. The asyncio extension does not exist
+anymore.
 
-Any applications built using the asyncio extension will need to update their
-imports from this::
+Any applications built using the legacy asyncio extension will need to update
+their imports from this::
 
     from microdot_asyncio import Microdot
 
@@ -46,7 +42,7 @@ 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
+change their imports, but will now use an asynchronous web server. 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.
@@ -64,9 +60,9 @@ extensions:
 - *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.
+  server, so it is not needed anymore and has been removed.
 - *microdot_websocket_alt.py*: this extension was only used with the
-  synchronous web server, so it is not needed anymore.
+  synchronous web server, so it is not needed anymore and has been removed.
 
 No more ``render_template()`` function
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -87,8 +83,8 @@ 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::
+Also thanks to this redesign, the template can be streamed, which saves memory
+for larger templates::
 
     return Template('index.html').generate(title='Home')
 
@@ -96,6 +92,8 @@ Streamed templates also have an asynchronous version::
 
     return Template('index.html').generate_async(title='Home')
 
+Note that templates that are streamed asynchronously do not use an ``await``.
+
 Class-based user sessions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -136,10 +134,9 @@ 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.
+
+Given that Microdot version 2 is asynchronous, the WSGI extension should be
+considered deprecated. Users of this extension are encouraged to migrate to the
+ASGI extension, which works with compatible ASGI web servers such as Uvicorn
+and Gunicorn.

{microdot-2.5.0 → microdot-2.6.0}/docs/index.rst

@@ -21,7 +21,6 @@ systems with limited resources such as microcontrollers. Both standard Python
    extensions/index
    implementation/index
    api/index
-   contributing
 
 * :ref:`genindex`
 * :ref:`search`

{microdot-2.5.0 → microdot-2.6.0}/pyproject.toml

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

{microdot-2.5.0 → microdot-2.6.0}/src/microdot/__init__.py

@@ -1,4 +1,4 @@
 from microdot.microdot import Microdot, Request, Response, abort, redirect, \
     send_file, URLPattern, AsyncBytesIO, iscoroutine  # noqa: F401
 
-__version__ = '2.5.0'
+__version__ = '2.6.0'

microdot-2.6.0/src/microdot/__init__.pyi

@@ -0,0 +1,7 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from microdot.microdot import AsyncBytesIO as AsyncBytesIO, Microdot as Microdot, Request as Request, Response as Response, URLPattern as URLPattern, abort as abort, redirect as redirect, send_file as send_file
+
+__version__: str

{microdot-2.5.0 → microdot-2.6.0}/src/microdot/asgi.py

@@ -44,7 +44,7 @@ class _BodyStream:  # pragma: no cover
         return data
 
 
-class Microdot(BaseMicrodot):
+class Microdot(BaseMicrodot):  # type: ignore[no-redef]
     """A subclass of the core :class:`Microdot <microdot.Microdot>` class that
     implements the ASGI protocol.
 

microdot-2.6.0/src/microdot/asgi.pyi

@@ -0,0 +1,50 @@
+from typing import Any, Awaitable, Callable
+from microdot import *  # type: ignore
+from microdot.microdot import Microdot as BaseMicrodot, Request
+from microdot.websocket import WebSocket as BaseWebSocket
+
+class Microdot(BaseMicrodot):  # type: ignore[no-redef]
+    lifespan_startup: Callable[[dict[str, Any]], Awaitable[None]]
+    lifespan_shutdown: Callable[[dict[str, Any]], Awaitable[None]]
+    embedded_server: bool
+    def __init__(self, lifespan_startup: Callable[[dict[str, Any]], Awaitable[None]] = ..., lifespan_shutdown: Callable[[dict[str, Any]], Awaitable[None]] = ...) -> None:
+        ...
+    
+    async def handle_lifespan(self, scope: dict[str, Any], receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]) -> None:
+        ...
+    
+    async def asgi_app(self, scope: dict[str, Any], receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]):
+        ...
+    
+    async def __call__(self, scope: dict[str, Any], receive: Callable[[], Awaitable[dict[str, Any]]], send: Callable[[dict[str, Any]], Awaitable[None]]):
+        ...
+    
+    def shutdown(self) -> None:
+        ...
+    
+    def run(self, host: str = ..., port: int = ..., debug: bool = ..., **options: Any) -> None:  # type: ignore[override]
+        ...
+    
+
+
+class WebSocket(BaseWebSocket):
+    closed: bool
+    async def handshake(self) -> None:
+        ...
+    
+    async def receive(self) -> bytes | str:
+        ...
+    
+    async def send(self, data: bytes | str) -> None:  # type: ignore[override]
+        ...
+    
+    async def close(self) -> None:
+        ...
+    
+
+
+async def websocket_upgrade(request: Request) -> BaseWebSocket:
+    ...
+
+def with_websocket(f: Callable[[Request, BaseWebSocket], Awaitable[None]]) -> None:
+    ...

microdot-2.6.0/src/microdot/auth.pyi

@@ -0,0 +1,52 @@
+from typing import Any, Awaitable, Callable
+from microdot import Request
+
+class BaseAuth:
+    auth_callback: Callable[..., Any | Awaitable[Any]]
+    error_callback: Callable[[Request], Any | Awaitable[Any]]
+    def __init__(self) -> None:
+        ...
+    
+    def __call__(self, f: Callable[..., Any]):
+        ...
+    
+    def optional(self, f: Callable[..., Any]):
+        ...
+    
+
+
+class BasicAuth(BaseAuth):
+    realm: str
+    charset: str
+    scheme: str
+    error_status: int
+    error_callback: Callable[[Request], Any | Awaitable[Any]]
+    def __init__(self, realm: str = ..., charset: str = ..., scheme: str = ..., error_status: int = ...) -> None:
+        ...
+    
+    async def authentication_error(self, request):
+        ...
+    
+    auth_callback: Callable[[Request, str, str], Any | Awaitable[Any]]
+    def authenticate(self, f: Callable[[Request, str, str], Any | Awaitable[Any]]) -> None:
+        ...
+    
+
+
+class TokenAuth(BaseAuth):
+    header: str
+    scheme: str
+    error_status: int
+    error_callback: Callable[[Request], Any | Awaitable[Any]]
+    def __init__(self, header: str = ..., scheme: str = ..., error_status: int = ...) -> None:
+        ...
+    
+    auth_callback: Callable[[Request, str], Any | Awaitable[Any]]
+    def authenticate(self, f: Callable[..., Any | Awaitable[Any]]) -> None:
+        ...
+    
+    def errorhandler(self, f: Callable[[Request], Any | Awaitable[Any]]) -> None:
+        ...
+    
+    async def authentication_error(self, request) -> None:
+        ...

{microdot-2.5.0 → microdot-2.6.0}/src/microdot/cors.py

@@ -14,7 +14,7 @@ class CORS:
                             making cross-site requests. If not set, all methods
                             are allowed.
     :param expose_headers: A list of headers that the browser is allowed to
-                           exposed.
+                           expose.
     :param allowed_headers: A list of headers that are allowed to be used when
                             making cross-site requests. If not set, all headers
                             are allowed.

microdot-2.6.0/src/microdot/cors.pyi

@@ -0,0 +1,29 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from typing import Callable, Literal
+from microdot import Microdot, Request, Response
+
+class CORS:
+    allowed_origins: list[str] | Literal['*'] | None
+    allow_credentials: bool
+    allowed_methods: list[str] | None
+    expose_headers: list[str] | None
+    allowed_headers: list[str] | None
+    max_age: int | None
+    def __init__(self, app: Microdot | None = ..., allowed_origins: list[str] | Literal['*'] | None = ..., allow_credentials: bool = ..., allowed_methods: list[str] | None = ..., expose_headers: list[str] | None = ..., allowed_headers: list[str] | None = ..., max_age: int | None = ..., handle_cors: bool = ...) -> None:
+        ...
+    
+    default_options_handler: Callable[[Request], dict[str, str]]
+    def initialize(self, app: Microdot, handle_cors: bool = ...) -> None:
+        ...
+    
+    def options_handler(self, request: Request) -> dict[str, str]:
+        ...
+    
+    def get_cors_headers(self, request: Request) -> dict[str, str]:
+        ...
+    
+    def after_request(self, request: Request, response: Response) -> None:
+        ...

{microdot-2.5.0 → microdot-2.6.0}/src/microdot/csrf.py

@@ -56,6 +56,7 @@ class CSRF:
             ) or request.route in self.protected_routes:
                 allow = False
                 sfs = request.headers.get('Sec-Fetch-Site')
+                origin = request.headers.get('Origin')
                 if sfs:
                     # if the Sec-Fetch-Site header was given, ensure it is not
                     # cross-site
@@ -63,14 +64,11 @@ class CSRF:
                         allow = True
                     elif sfs == 'same-site' and self.allow_subdomains:
                         allow = True
-                elif self.cors and self.cors.allowed_origins != '*':
-                    # if there is no Sec-Fetch-Site header but we have a list
-                    # of allowed origins, then we can validate the origin
-                    origin = request.headers.get('Origin')
-                    if origin is None:
-                        # origin wasn't given so this isn't a browser
-                        allow = True
-                    elif not self.allow_subdomains:
+                if not allow and origin and self.cors and \
+                        self.cors.allowed_origins != '*':
+                    # if we have a list of allowed origins, then we can
+                    # validate the origin
+                    if not self.allow_subdomains:
                         allow = origin in self.cors.allowed_origins
                     else:
                         origin_scheme, origin_host = origin.split('://', 1)
@@ -83,7 +81,7 @@ class CSRF:
                             ):
                                 allow = True
                                 break
-                else:
+                if not allow and not sfs and not origin:
                     allow = True  # no headers to check
 
                 if not allow:

microdot-2.6.0/src/microdot/csrf.pyi

@@ -0,0 +1,22 @@
+from typing import Any, Awaitable, Callable
+from microdot import Microdot
+from microdot.cors import CORS
+
+class CSRF:
+    SAFE_METHODS: list[str]
+    cors: CORS | None
+    protect_all: bool
+    allow_subdomains: bool
+    exempt_routes: list[Callable[..., Any | Awaitable[Any]]]
+    protected_routes: list[Callable[..., Any | Awaitable[Any]]]
+    def __init__(self, app: Microdot | None = ..., cors: CORS | None = ..., protect_all: bool = ..., allow_subdomains: bool = ...) -> None:
+        ...
+    
+    def initialize(self, app: Microdot, cors: CORS | None = ...) -> None:
+        ...
+    
+    def exempt(self, f: Callable[..., Any | Awaitable[Any]]) -> Callable[..., Any | Awaitable[Any]]:
+        ...
+    
+    def protect(self, f: Callable[..., Any | Awaitable[Any]]) -> Callable[..., Any | Awaitable[Any]]:
+        ...

{microdot-2.5.0 → microdot-2.6.0}/src/microdot/helpers.py

@@ -2,7 +2,7 @@ try:
     from functools import wraps
 except ImportError:  # pragma: no cover
     # MicroPython does not currently implement functools.wraps
-    def wraps(wrapped):
+    def wraps(wrapped):  # type: ignore[misc]
         def _(wrapper):
             return wrapper
         return _

microdot-2.6.0/src/microdot/helpers.pyi

@@ -0,0 +1,4 @@
+"""
+This type stub file was generated by pyright.
+"""
+

microdot-2.6.0/src/microdot/jinja.pyi

@@ -0,0 +1,25 @@
+from typing import Any, AsyncIterator, Awaitable, Iterator
+from jinja2 import Environment, Template as JinjaTemplate
+
+class Template:
+    jinja_env: Environment
+    @classmethod
+    def initialize(cls, template_dir: str = ..., enable_async: bool = ..., **kwargs) -> None:
+        ...
+    
+    name: str
+    template: JinjaTemplate
+    def __init__(self, template: str, **kwargs: Any) -> None:
+        ...
+    
+    def generate(self, *args: Any, **kwargs: Any) -> Iterator[str]:
+        ...
+    
+    def render(self, *args: Any, **kwargs: Any) -> str:
+        ...
+    
+    def generate_async(self, *args: Any, **kwargs: Any) -> AsyncIterator[str]:
+        ...
+    
+    async def render_async(self, *args: Any, **kwargs: Any) -> Awaitable[str]:
+        ...

microdot-2.6.0/src/microdot/login.pyi

@@ -0,0 +1,26 @@
+from typing import Any, Awaitable, Callable
+from microdot import Request, Response
+
+class Login:
+    login_url: str
+    user_loader_callback: Callable[[str], Any | Awaitable[Any]]
+    def __init__(self, login_url: str = ...) -> None:
+        ...
+    
+    def user_loader(self, f: Callable[[str], Any | Awaitable[Any]]) -> None:
+        ...
+    
+    async def login_user(self, request: Request, user: Any, remember: bool = ..., redirect_url: str = ...) -> Response:
+        ...
+    
+    async def logout_user(self, request: Request) -> None:
+        ...
+    
+    async def get_current_user(self, request: Request):
+        ...
+    
+    def __call__(self, f: Callable[..., Any | Awaitable[Any]]) -> Callable[..., Any | Awaitable[Any]]:
+        ...
+    
+    def fresh(self, f: Callable[..., Any | Awaitable[Any]]) -> Callable[..., Any | Awaitable[Any]]:
+        ...

{microdot-2.5.0 → microdot-2.6.0}/src/microdot/microdot.py

@@ -11,7 +11,7 @@ import re
 import time
 
 try:
-    import orjson as json
+    import orjson as json  # type: ignore[import-not-found]
 except ImportError:
     import json
 
@@ -31,7 +31,7 @@ try:
                 None, partial(handler, *args, **kwargs))
         return ret
 except ImportError:  # pragma: no cover
-    def iscoroutine(coro):
+    def iscoroutine(coro):  # type: ignore[misc]
         return hasattr(coro, 'send') and hasattr(coro, 'throw')
 
     async def invoke_handler(handler, *args, **kwargs):
@@ -46,7 +46,7 @@ except ImportError:  # pragma: no cover
         return ret
 
 try:
-    from sys import print_exception
+    from sys import print_exception  # type: ignore[attr-defined]
 except ImportError:  # pragma: no cover
     import traceback
 
@@ -578,7 +578,7 @@ class Response:
     #: written to the client. Used to exit WebSocket connections cleanly.
     already_handled = None
 
-    def __init__(self, body='', status_code=200, headers=None, reason=None):
+    def __init__(self, body=b'', status_code=200, headers=None, reason=None):
         if body is None and status_code == 200:
             body = ''
             status_code = 204
@@ -1212,7 +1212,7 @@ class Microdot:
         raise HTTPException(status_code, reason)
 
     async def start_server(self, host='0.0.0.0', port=5000, debug=False,
-                           ssl=None):
+                           ssl=None, start_serving=True):
         """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
@@ -1231,6 +1231,13 @@ class Microdot:
                       default is ``False``.
         :param ssl: An ``SSLContext`` instance or ``None`` if the server should
                     not use TLS. The default is ``None``.
+        :param start_serving: If ``True``, the server starts accepting
+                              connections immediately. When set to ``False``,
+                              this method returns a ``Server`` object. To
+                              accept connections, the
+                              ``Server.serve_forever()`` method should be
+                              called. The default is ``True``. A value of
+                              ``False`` is only supported in CPython.
 
         This method is a coroutine.
 
@@ -1275,10 +1282,18 @@ class Microdot:
                 host=host, port=port))
 
         try:
-            self.server = await asyncio.start_server(serve, host, port,
-                                                     ssl=ssl)
+            self.server = await asyncio.start_server(
+                serve, host, port, ssl=ssl, start_serving=start_serving)
+            if not start_serving:
+                return self.server
         except TypeError:  # pragma: no cover
-            self.server = await asyncio.start_server(serve, host, port)
+            if not start_serving:
+                raise ValueError('start_serving must be True')
+            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:
@@ -1544,7 +1559,7 @@ class Microdot:
         return res
 
 
-Response.already_handled = Response()
+Response.already_handled = Response()  # type: ignore[assignment]
 
 abort = Microdot.abort
 redirect = Response.redirect