microdot 2.0.6__tar.gz → 2.1.0__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: microdot
-Version: 2.0.6
+Version: 2.1.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
@@ -14,6 +14,8 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: tox; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: pyjwt; extra == "docs"

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

@@ -44,6 +44,22 @@ User Sessions
 .. automodule:: microdot.session
    :members:
 
+Authentication
+--------------
+
+.. automodule:: microdot.auth
+   :inherited-members:
+   :special-members: __call__
+   :members:
+
+User Logins
+-----------
+
+.. automodule:: microdot.login
+   :inherited-members:
+   :special-members: __call__
+   :members:
+
 Cross-Origin Resource Sharing (CORS)
 ------------------------------------
 

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

@@ -5,8 +5,8 @@ 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.
 
-WebSocket Support
-~~~~~~~~~~~~~~~~~
+WebSocket
+~~~~~~~~-
 
 .. list-table::
    :align: left
@@ -39,8 +39,8 @@ Example::
                 message = await ws.receive()
                 await ws.send(message)
 
-Server-Sent Events Support
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Server-Sent Events
+~~~~~~~~~~~~~~~~~~
 
 .. list-table::
    :align: left
@@ -78,8 +78,8 @@ Example::
    the SSE object. For bidirectional communication with the client, use the
    WebSocket extension.
 
-Rendering Templates
-~~~~~~~~~~~~~~~~~~~
+Templates
+~~~~~~~~~
 
 Many web applications use HTML templates for rendering content to clients.
 Microdot includes extensions to render templates with the
@@ -202,8 +202,8 @@ must be used.
 .. note::
     The Jinja extension is not compatible with MicroPython.
 
-Maintaining Secure User Sessions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Secure User Sessions
+~~~~~~~~~~~~~~~~~~~~
 
 .. list-table::
    :align: left
@@ -270,6 +270,178 @@ The :func:`save() <microdot.session.SessionDict.save>` and
 :func:`delete() <microdot.session.SessionDict.delete>` methods are used to update
 and destroy the user session respectively.
 
+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``.
+
+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::
+
+    @app.route('/')
+    @auth
+    async def index(request):
+        return f'Hello, {request.g.current_user}!'
+        
+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>`_
+   * - 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('/')
+
 Cross-Origin Resource Sharing (CORS)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -286,7 +458,7 @@ Cross-Origin Resource Sharing (CORS)
      - | None
 
    * - Examples
-     - | `cors.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/cors/cors.py>`_
+     - | `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
@@ -305,8 +477,8 @@ Example::
     cors = CORS(app, allowed_origins=['https://example.com'],
                 allow_credentials=True)
 
-Testing with the Test Client
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Test Client
+~~~~~~~~~~~
 
 .. list-table::
    :align: left
@@ -342,8 +514,8 @@ Example::
 See the documentation for the :class:`TestClient <microdot.test_client.TestClient>`
 class for more details.
 
-Deploying on a Production Web Server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Production Deployments
+~~~~~~~~~~~~~~~~~~~~~~
 
 The ``Microdot`` class creates its own simple web server. This is enough for an
 application deployed with MicroPython, but when using CPython it may be useful
@@ -363,7 +535,7 @@ Using an ASGI Web Server
      - | `asgi.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot/asgi.py>`_
 
    * - Required external dependencies
-     - | An ASGI web server, such as `Uvicorn <https://uvicorn.org/>`_.
+     - | An ASGI web server, such as `Uvicorn <https://www.uvicorn.org/>`_.
 
    * - Examples
      - | `hello_asgi.py <https://github.com/miguelgrinberg/microdot/blob/main/examples/hello/hello_asgi.py>`_

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

@@ -82,8 +82,34 @@ handler functions can be defined as ``async def`` or ``def`` functions, but
 ``async def`` functions are recommended for performance.
 
 The :func:`run() <microdot.Microdot.run>` method starts the application's web
-server on port 5000 by default. This method blocks while it waits for
-connections from clients.
+server on port 5000 by default, and creates its own asynchronous loop. This
+method blocks while it waits for connections from clients.
+
+For some applications it may be necessary to run the web server alongside other
+asynchronous tasks, on an already running loop. In that case, instead of
+``app.run()`` the web server can be started by invoking the
+:func:`start_server() <microdot.Microdot.start_server>` coroutine as shown in
+the following example::
+
+    import asyncio
+    from microdot import Microdot
+
+    app = Microdot()
+
+    @app.route('/')
+    async def index(request):
+        return 'Hello, world!'
+
+    async def main():
+        # start the server in a background task
+        server = asyncio.create_task(app.start_server())
+
+        # ... do other asynchronous work here ...
+
+        # cleanup before ending the application
+        await server
+
+    asyncio.run(main())
 
 Running with CPython
 ^^^^^^^^^^^^^^^^^^^^
@@ -92,7 +118,7 @@ Running with CPython
    :align: left
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
 
    * - Required external dependencies
      - | None
@@ -118,7 +144,7 @@ Running with MicroPython
    :align: left
 
    * - Required Microdot source files
-     - | `microdot.py <https://github.com/miguelgrinberg/microdot/tree/main/src/microdot.py>`_
+     - | `microdot.py <https://github.com/miguelgrinberg/microdot/blob/main/src/microdot/microdot.py>`_
 
    * - Required external dependencies
      - | None
@@ -145,8 +171,9 @@ changed by passing the ``port`` argument to the ``run()`` method.
 Web Server Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-The :func:`run() <microdot.Microdot.run>` method supports a few arguments to
-configure the web server.
+The :func:`run() <microdot.Microdot.run>` and
+:func:`start_server() <microdot.Microdot.start_server>` methods support a few
+arguments to configure the web server.
 
 - ``port``: The port number to listen on. Pass the desired port number in this
   argument to use a port different than the default of 5000. For example::
@@ -418,7 +445,7 @@ Mounting a Sub-Application
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Small Microdot applications can be written as a single source file, but this
-is not the best option for applications that past a certain size. To make it
+is not the best option for applications that pass a certain size. To make it
 simpler to write large applications, Microdot supports the concept of
 sub-applications that can be "mounted" on a larger application, possibly with
 a common URL prefix applied to all of its routes. For developers familiar with
@@ -474,11 +501,25 @@ The resulting application will have the customer endpoints available at
 */customers/* and the order endpoints available at */orders/*.
 
 .. note::
-   Before-request, after-request and error handlers defined in the
-   sub-application are also copied over to the main application at mount time.
-   Once installed in the main application, these handlers will apply to the
-   whole application and not just the sub-application in which they were
-   created.
+   During the handling of a request, the
+   :attr:`Request.url_prefix <microdot.Microdot.url_prefix>` attribute is
+   set to the URL prefix under which the sub-application was mounted, or an
+   empty string if the endpoint did not come from a sub-application or the
+   sub-application was mounted without a URL prefix. It is possible to issue a
+   redirect that is relative to the sub-application as follows::
+
+      return redirect(request.url_prefix + '/relative-url')
+
+When mounting an application as shown above, before-request, after-request and
+error handlers defined in the sub-application are copied over to the main
+application at mount time. Once installed in the main application, these
+handlers will apply to the whole application and not just the sub-application
+in which they were created.
+
+The :func:`mount() <microdot.Microdot.mount>` method has a ``local`` argument
+that defaults to ``False``. When this argument is set to ``True``, the
+before-request, after-request and error handlers defined in the sub-application
+will only apply to the sub-application.
 
 Shutting Down the Server
 ^^^^^^^^^^^^^^^^^^^^^^^^

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

@@ -1,6 +1,6 @@
 [project]
 name = "microdot"
-version = "2.0.6"
+version = "2.1.0"
 authors = [
     { name = "Miguel Grinberg", email = "miguel.grinberg@gmail.com" },
 ]
@@ -14,6 +14,8 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 requires-python = ">=3.8"
+dependencies = [
+]
 
 [project.readme]
 file = "README.md"
@@ -24,9 +26,12 @@ Homepage = "https://github.com/miguelgrinberg/microdot"
 "Bug Tracker" = "https://github.com/miguelgrinberg/microdot/issues"
 
 [project.optional-dependencies]
+dev = [
+    "tox",
+]
 docs = [
     "sphinx",
-    "pyjwt"
+    "pyjwt",
 ]
 
 [tool.setuptools]

microdot-2.1.0/src/microdot/auth.py

@@ -0,0 +1,144 @@
+from microdot import abort
+from microdot.microdot import invoke_handler
+
+
+class BaseAuth:
+    def __init__(self):
+        self.auth_callback = None
+        self.error_callback = None
+
+    def __call__(self, f):
+        """Decorator to protect a route with authentication.
+
+        An instance of this class must be used as a decorator on the routes
+        that need to be protected. Example::
+
+           auth = BasicAuth()  # or TokenAuth()
+
+           @app.route('/protected')
+           @auth
+           def protected(request):
+               # ...
+
+        Routes that are decorated in this way will only be invoked if the
+        authentication callback returned a valid user object, otherwise the
+        error callback will be executed.
+        """
+        async def wrapper(request, *args, **kwargs):
+            auth = self._get_auth(request)
+            if not auth:
+                return await invoke_handler(self.error_callback, request)
+            request.g.current_user = await invoke_handler(
+                self.auth_callback, request, *auth)
+            if not request.g.current_user:
+                return await invoke_handler(self.error_callback, request)
+            return await invoke_handler(f, request, *args, **kwargs)
+
+        return wrapper
+
+
+class BasicAuth(BaseAuth):
+    """Basic Authentication.
+
+    :param realm: The realm that is displayed when the user is prompted to
+                  authenticate in the browser.
+    :param charset: The charset that is used to encode the realm.
+    :param scheme: The authentication scheme. Defaults to 'Basic'.
+    :param error_status: The error status code to return when authentication
+                         fails. Defaults to 401.
+    """
+    def __init__(self, realm='Please login', charset='UTF-8', scheme='Basic',
+                 error_status=401):
+        super().__init__()
+        self.realm = realm
+        self.charset = charset
+        self.scheme = scheme
+        self.error_status = error_status
+        self.error_callback = self.authentication_error
+
+    def _get_auth(self, request):
+        auth = request.headers.get('Authorization')
+        if auth and auth.startswith('Basic '):
+            import binascii
+            try:
+                username, password = binascii.a2b_base64(
+                    auth[6:]).decode().split(':', 1)
+            except Exception:  # pragma: no cover
+                return None
+            return username, password
+
+    def authentication_error(self, request):
+        return '', self.error_status, {
+            'WWW-Authenticate': '{} realm="{}", charset="{}"'.format(
+                self.scheme, self.realm, self.charset)}
+
+    def authenticate(self, f):
+        """Decorator to configure the authentication callback.
+
+        This decorator must be used with a function that accepts the request
+        object, a username and a password and returns a user object if the
+        credentials are valid, or ``None`` if they are not. Example::
+
+           @auth.authenticate
+           async def check_credentials(request, username, password):
+               user = get_user(username)
+               if user and user.check_password(password):
+                   return get_user(username)
+        """
+        self.auth_callback = f
+
+
+class TokenAuth(BaseAuth):
+    """Token based authentication.
+
+    :param header: The name of the header that will contain the token. Defaults
+                   to 'Authorization'.
+    :param scheme: The authentication scheme. Defaults to 'Bearer'.
+    :param error_status: The error status code to return when authentication
+                         fails. Defaults to 401.
+    """
+    def __init__(self, header='Authorization', scheme='Bearer',
+                 error_status=401):
+        super().__init__()
+        self.header = header
+        self.scheme = scheme.lower()
+        self.error_status = error_status
+        self.error_callback = self.authentication_error
+
+    def _get_auth(self, request):
+        auth = request.headers.get(self.header)
+        if auth:
+            if self.header == 'Authorization':
+                try:
+                    scheme, token = auth.split(' ', 1)
+                except Exception:
+                    return None
+                if scheme.lower() == self.scheme:
+                    return (token.strip(),)
+            else:
+                return (auth,)
+
+    def authenticate(self, f):
+        """Decorator to configure the authentication callback.
+
+        This decorator must be used with a function that accepts the request
+        object, a username and a password and returns a user object if the
+        credentials are valid, or ``None`` if they are not. Example::
+
+           @auth.authenticate
+           async def check_credentials(request, token):
+               return get_user(token)
+        """
+        self.auth_callback = f
+
+    def errorhandler(self, f):
+        """Decorator to configure the error callback.
+
+        Microdot calls the error callback to allow the application to generate
+        a custom error response. The default error response is to call
+        ``abort(401)``.
+        """
+        self.error_callback = f
+
+    def authentication_error(self, request):
+        abort(self.error_status)