user logins

docs/api.rst

@@ -52,6 +52,14 @@ Authentication
    :special-members: __call__
    :members:
 
+User Logins
+-----------
+
+.. automodule:: microdot.login
+   :inherited-members:
+   :special-members: __call__
+   :members:
+
 Cross-Origin Resource Sharing (CORS)
 ------------------------------------
 

docs/extensions.rst

@@ -288,6 +288,7 @@ Authentication
    * - 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.
 
@@ -355,6 +356,91 @@ protect your routes::
     @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)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~