microdot 2.4.0__tar.gz → 2.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microdot
-Version: 2.4.0
+Version: 2.5.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
@@ -18,6 +18,7 @@ Provides-Extra: dev
 Requires-Dist: tox; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: furo; extra == "docs"
 Requires-Dist: pyjwt; extra == "docs"
 Dynamic: license-file
 
@@ -42,24 +43,15 @@ async def index(request):
 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
 
 - [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))
+- Legacy (v1)
+    - [Code](https://github.com/miguelgrinberg/microdot/tree/v1)
+    - [Documentation](https://microdot.readthedocs.io/en/v1/)
 
 ## Roadmap
 
@@ -68,12 +60,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
+- Pub/sub mini-framework for WebSocket and SSE
 - 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)!

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

@@ -19,24 +19,15 @@ async def index(request):
 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
 
 - [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))
+- Legacy (v1)
+    - [Code](https://github.com/miguelgrinberg/microdot/tree/v1)
+    - [Documentation](https://microdot.readthedocs.io/en/v1/)
 
 ## Roadmap
 
@@ -45,12 +36,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
+- Pub/sub mini-framework for WebSocket and SSE
 - 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)!

microdot-2.5.0/docs/api/asgi.rst

@@ -0,0 +1,6 @@
+ASGI
+----
+
+.. autoclass:: microdot.asgi.Microdot
+   :members:
+   :exclude-members: shutdown, run

microdot-2.5.0/docs/api/auth.rst

@@ -0,0 +1,7 @@
+Authentication
+--------------
+
+.. automodule:: microdot.auth
+   :inherited-members:
+   :special-members: __call__
+   :members:

microdot-2.5.0/docs/api/cors.rst

@@ -0,0 +1,5 @@
+Cross-Origin Resource Sharing (CORS)
+------------------------------------
+
+.. automodule:: microdot.cors
+   :members:

microdot-2.5.0/docs/api/csrf.rst

@@ -0,0 +1,5 @@
+Cross-Site Request Forgery (CSRF) Protection
+--------------------------------------------
+
+.. automodule:: microdot.csrf
+   :members:

microdot-2.5.0/docs/api/index.rst

@@ -0,0 +1,21 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   microdot
+   multipart
+   websocket
+   sse
+   utemplate
+   jinja
+   sessions
+   auth
+   login
+   cors
+   csrf
+   test_client
+   asgi
+   wsgi
+

microdot-2.5.0/docs/api/jinja.rst

@@ -0,0 +1,5 @@
+Templates (Jinja)
+-----------------
+
+.. automodule:: microdot.jinja
+   :members:

microdot-2.5.0/docs/api/login.rst

@@ -0,0 +1,7 @@
+User Logins
+-----------
+
+.. automodule:: microdot.login
+   :inherited-members:
+   :special-members: __call__
+   :members:

microdot-2.5.0/docs/api/microdot.rst

@@ -0,0 +1,14 @@
+Core API
+--------
+
+.. autoclass:: microdot.Microdot
+   :members:
+
+.. autoclass:: microdot.Request
+   :members:
+
+.. autoclass:: microdot.Response
+   :members:
+
+.. autoclass:: microdot.URLPattern
+   :members:

microdot-2.5.0/docs/api/multipart.rst

@@ -0,0 +1,5 @@
+Multipart Forms
+---------------
+
+.. automodule:: microdot.multipart
+   :members:

microdot-2.5.0/docs/api/sessions.rst

@@ -0,0 +1,5 @@
+User Sessions
+-------------
+
+.. automodule:: microdot.session
+   :members:

microdot-2.5.0/docs/api/sse.rst

@@ -0,0 +1,5 @@
+Server-Sent Events (SSE)
+------------------------
+
+.. automodule:: microdot.sse
+   :members:

microdot-2.5.0/docs/api/test_client.rst

@@ -0,0 +1,5 @@
+Test Client
+-----------
+
+.. automodule:: microdot.test_client
+   :members:

microdot-2.5.0/docs/api/utemplate.rst

@@ -0,0 +1,5 @@
+Templates (uTemplate)
+---------------------
+
+.. automodule:: microdot.utemplate
+   :members:

microdot-2.5.0/docs/api/websocket.rst

@@ -0,0 +1,5 @@
+WebSocket
+---------
+
+.. automodule:: microdot.websocket
+   :members:

microdot-2.5.0/docs/api/wsgi.rst

@@ -0,0 +1,6 @@
+WSGI
+----
+
+.. autoclass:: microdot.wsgi.Microdot
+   :members:
+   :exclude-members: shutdown, run

{microdot-2.4.0 → microdot-2.5.0}/docs/conf.py

@@ -46,7 +46,8 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'furo'
+html_title = 'Microdot'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -58,12 +59,6 @@ html_css_files = [
 ]
 
 html_theme_options = {
-    'github_user': 'miguelgrinberg',
-    'github_repo': 'microdot',
-    'github_banner': True,
-    'github_button': True,
-    'github_type': 'star',
-    'fixed_sidebar': True,
 }
 
 autodoc_default_options = {

microdot-2.5.0/docs/contributing.rst

@@ -0,0 +1,7 @@
+Contributing
+------------
+
+Thank you for your interest in Microdot!
+
+Please visit the `GitHub repository <https://github.com/miguelgrinberg/microdot>`_
+to learn about the project and find open issues and pull requests.

microdot-2.5.0/docs/extensions/auth.rst

@@ -0,0 +1,112 @@
+Authentication
+~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `auth.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/auth.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `basic_auth.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/auth/basic_auth.py>`_
+       | `token_auth.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/auth/token_auth.py>`_
+
+The authentication extension provides helper classes for two commonly used
+authentication patterns, described below.
+
+Basic Authentication
+^^^^^^^^^^^^^^^^^^^^
+
+`Basic Authentication <https://en.wikipedia.org/wiki/Basic_access_authentication>`_
+is a method of authentication that is part of the HTTP specification. It allows
+clients to authenticate to a server using a username and a password. Web
+browsers have native support for Basic Authentication and will automatically
+prompt the user for a username and a password when a protected resource is
+accessed.
+
+To use Basic Authentication, create an instance of the :class:`BasicAuth <microdot.auth.BasicAuth>`
+class::
+
+    from microdot.auth import BasicAuth
+
+    auth = BasicAuth(app)
+
+Next, create an authentication function. The function must accept a request
+object and a username and password pair provided by the user. If the
+credentials are valid, the function must return an object that represents the
+user. If the authentication function cannot validate the user provided
+credentials it must return ``None``. Decorate the function with
+``@auth.authenticate``::
+
+    @auth.authenticate
+    async def verify_user(request, username, password):
+        user = await load_user_from_database(username)
+        if user and user.verify_password(password):
+            return user
+
+To protect a route with authentication, add the ``auth`` instance as a
+decorator::
+
+    @app.route('/')
+    @auth
+    async def index(request):
+        return f'Hello, {request.g.current_user}!'
+
+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 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 ``request.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>`::
+
+    from microdot.auth import TokenAuth
+
+    auth = TokenAuth()
+
+Then add a function that verifies the token and returns the user it belongs to,
+or ``None`` if the token is invalid or expired::
+
+    @auth.authenticate
+    async def verify_token(request, token):
+        return load_user_from_token(token)
+
+As with Basic authentication, the ``auth`` instance is used as a decorator to
+protect your routes, and the authenticated user is accessible from the request
+object as ``request.g.current_user``::
+
+    @app.route('/')
+    @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 request.g.current_user:
+            return f'Hello, {request.g.current_user}!'
+        else:
+            return 'Hello, anonymous user!'

microdot-2.5.0/docs/extensions/cors.rst

@@ -0,0 +1,34 @@
+Cross-Origin Resource Sharing (CORS)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `cors.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/cors.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `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
+mechanism that allows web applications running on different origins to access
+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.
+Example::
+
+    from microdot import Microdot
+    from microdot.cors import CORS
+
+    app = Microdot()
+    cors = CORS(app, allowed_origins=['https://example.com'],
+                allow_credentials=True)

microdot-2.5.0/docs/extensions/csrf.rst

@@ -0,0 +1,94 @@
+Cross-Site Request Forgery (CSRF) Protection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - Required Microdot source files
+     - | `csrf.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/csrf.py>`_
+
+   * - Required external dependencies
+     - | None
+
+   * - Examples
+     - | `app.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/csrf/app.py>`_
+
+The CSRF extension provides protection against `Cross-Site Request Forgery
+(CSRF) <https://owasp.org/www-community/attacks/csrf>`_ attacks. This
+protection defends against attackers attempting to submit forms or other
+state-changing requests from their own site on behalf of unsuspecting victims,
+while taking advantage of the victims previously established sessions or
+cookies to impersonate them.
+
+This extension checks the ``Sec-Fetch-Site`` header sent by all modern web
+browsers to achieve this protection. As a fallback mechanism for older browsers
+that do not support this header, this extension can be linked to the CORS
+extension to validate the ``Origin`` header. If you are interested in the
+details of this protection mechanism, it is described in the
+`OWASP CSRF Prevention Cheat Sheet <https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#fetch-metadata-headers>`_
+page.
+
+.. note::
+   As of December 2025, OWASP considers the use of Fetch Metadata Headers for
+   CSRF protection a
+   `defense in depth <https://en.wikipedia.org/wiki/Defence_in_depth>`_
+   technique that is insufficient on its own.
+
+   There is an interesting
+   `discussion <https://github.com/OWASP/CheatSheetSeries/issues/1803>`_ on
+   this topic in the OWASP GitHub repository where it appears to be agreement
+   that this technique provides complete protection for the vast majority of
+   use cases. If you are unsure if this method works for your use case, please
+   read this discussion to have more context and make the right decision. 
+
+To enable CSRF protection, create an instance of the
+:class:`CSRF <microdot.csrf.CSRF>` class and configure the desired options.
+Example::
+
+    from microdot import Microdot
+    from microdot.cors import CORS
+    from microdot.csrf import CSRF
+
+    app = Microdot()
+    cors = CORS(app, allowed_origins=['https://example.com'])
+    csrf = CSRF(app, cors)
+
+This will protect all routes that use a state-changing method (``POST``,
+``PUT``, ``PATCH`` or ``DELETE``) and will return a 403 status code response to
+any requests that fail the CSRF check.
+
+If there are routes that need to be exempted from the CSRF check, they can be
+decorated with the :meth:`csrf.exempt <microdot.csrf.CSRF.exempt>` decorator::
+
+    @app.post('/webhook')
+    @csrf.exempt
+    async def webhook(request):
+        # ...
+
+For some applications it may be more convenient to have CSRF checks turned off
+by default, and only apply them to explicitly selected routes. In this case,
+pass ``protect_all=False`` when you construct the ``CSRF`` instance and use the
+:meth:`csrf.protect <microdot.csrf.CSRF.protect>` decorator::
+
+    csrf = CSRF(app, cors, protect_all=False)
+
+    @app.post('/submit-form')
+    @csrf.protect
+    async def submit_form(request):
+        # ...
+
+By default, requests coming from different subdomains are considered to be
+cross-site, and as such they will not pass the CSRF check. If you'd like
+subdomain requests to be considered safe, then set the
+``allow_subdomains=True`` option when you create the ``CSRF`` class.
+
+.. note::
+   This extension is designed to block requests issued by web browsers when
+   they are found to be unsafe or unauthorized by the application owner. The
+   method used to determine if a request should be allowed or not is based on
+   the value of headers that are only sent by web browsers. Clients other than
+   web browsers are not affected by this extension and can send requests
+   freely.

microdot-2.5.0/docs/extensions/index.rst

@@ -0,0 +1,21 @@
+Core Extensions
+---------------
+
+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.
+
+.. toctree::
+   :maxdepth: 1
+
+   multipart
+   websocket
+   sse
+   templates
+   sessions
+   auth
+   login
+   cors
+   csrf
+   test_client
+   production

microdot-2.5.0/docs/extensions/login.rst

@@ -0,0 +1,85 @@
+User Logins
+~~~~~~~~~~~
+
+.. list-table::
+   :align: left
+
+   * - Compatibility
+     - | CPython & MicroPython
+
+   * - 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>`_,
+                      `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/login/login.py>`_
+
+The login extension provides user login functionality. The logged in state of
+the user is stored in the user session cookie, and an optional "remember me"
+cookie can also be added to keep the user logged in across browser sessions.
+
+To use this extension, create instances of the
+:class:`Session <microdot.session.Session>` and :class:`Login <microdot.login.Login>`
+class::
+
+    Session(app, secret_key='top-secret!')
+    login = Login()
+
+The ``Login`` class accept an optional argument with the URL of the login page.
+The default for this URL is */login*.
+
+The application must represent users as objects with an ``id`` attribute. A
+function decorated with ``@login.user_loader`` is used to load a user object::
+
+    @login.user_loader
+    async def get_user(user_id):
+        return database.get_user(user_id)
+
+The application must implement the login form. At the point in which the user
+credentials have been received and verified, a call to the
+:func:`login_user() <microdot.login.Login.login_user>` function must be made to
+record the user in the user session::
+
+    @app.route('/login', methods=['GET', 'POST'])
+    async def login(request):
+        # ...
+        if user.check_password(password):
+            return await login.login_user(request, user, remember=remember_me)
+        return redirect('/login')
+
+The optional ``remember`` argument is used to add a remember me cookie that
+will log the user in automatically in future sessions. A value of ``True`` will
+keep the log in active for 30 days. Alternatively, an integer number of days
+can be passed in this argument.
+
+Any routes that require the user to be logged in must be decorated with
+:func:`@login <microdot.login.Login.__call__>`::
+
+    @app.route('/')
+    @login
+    async def index(request):
+        # ...
+
+Routes that are of a sensitive nature can be decorated with
+:func:`@login.fresh <microdot.login.Login.fresh>`
+instead. This decorator requires that the user has logged in during the current
+session, and will ask the user to logged in again if the session was
+authenticated through a remember me cookie::
+
+    @app.get('/fresh')
+    @login.fresh
+    async def fresh(request):
+        # ...
+
+To log out a user, the :func:`logout_user() <microdot.auth.Login.logout_user>`
+is used::
+
+    @app.post('/logout')
+    @login
+    async def logout(request):
+        await login.logout_user(request)
+        return redirect('/')