Advanced to version 0.4.0.

MANIFEST.in

@@ -15,4 +15,8 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+include docs/*
+include docs/source/*
+include docs/source/_static/*
+include docs/source/_templates/*
 include tests/*

README.rst

@@ -6,21 +6,23 @@ Flask HTTP Digest Authentication
 Description
 ===========
 
-*Flask-Digest-Auth* is an `HTTP Digest Authentication`_ implementation
+*Flask-DigestAuth* is an `HTTP Digest Authentication`_ implementation
 for Flask_ applications.  It authenticates the user for the protected
 views.
 
 HTTP Digest Authentication is specified in `RFC 2617`_.
 
+Refer to the full `Flask-DigestAuth readthedocs documentation`_.
+
 
 Why HTTP Digest Authentication?
 -------------------------------
 
-HTTP Digest Authentication has the advantage that it does not send the
+*HTTP Digest Authentication* has the advantage that it does not send
-actual password to the server, which greatly enhances the security.
+thee actual password to the server, which greatly enhances the
-It uses the challenge-response authentication scheme.  The client
+security.  It uses the challenge-response authentication scheme.  The
-returns the response calculated from the challenge and the password,
+client returns the response calculated from the challenge and the
-but not the original password.
+password, but not the original password.
 
 Log in forms has the advantage of freedom, in the senses of both the
 visual design and the actual implementation.  You may implement your
@@ -28,87 +30,54 @@ own challenge-response log in form, but then you are reinventing the
 wheels.  If a pretty log in form is not critical to your project, HTTP
 Digest Authentication should be a good choice.
 
-Flask-Digest-Auth works with Flask-Login_.  Log in protection can be
+Flask-DigestAuth works with Flask-Login_.  Log in protection can be
 separated with the authentication mechanism.  You can create protected
 Flask modules without knowing the actual authentication mechanisms.
 
 
-Features
---------
-
-There are a couple of Flask HTTP digest authentication
-implementations.  Flask-Digest-Auth has the following features:
-
-
-Flask-Login Integration
-#######################
-
-Flask-Digest-Auth features Flask-Login integration.  The views
-can be totally independent with the actual authentication mechanism.
-You can write a Flask module that requires log in, without specify
-the actual authentication mechanism.  The application can specify
-either HTTP Digest Authentication, or the log in forms, as needed.
-
-
-Session Integration
-###################
-
-Flask-Digest-Auth features session integration.  The user log in
-is remembered in the session.  The authentication information is not
-requested again.  This is different to the practice of the HTTP Digest
-Authentication, but is convenient for the log in accounting.
-
-
-Log Out Support
-###############
-
-Flask-Digest-Auth supports log out.  The user will be prompted for
-new username and password.
-
-
-Log In Bookkeeping
-##################
-
-You can register a callback to run when the user logs in.
-
-
-.. _HTTP Digest Authentication: https://en.wikipedia.org/wiki/Digest_access_authentication
-.. _RFC 2617: https://www.rfc-editor.org/rfc/rfc2617
-.. _Flask: https://flask.palletsprojects.com
-.. _Flask-Login: https://flask-login.readthedocs.io
-
-
 Installation
 ============
 
-You can install Flask-Digest-Auth with ``pip``:
+You can install Flask-DigestAuth with ``pip``:
 
 ::
 
-    pip install Flask-Digest-Auth
+    pip install Flask-DigestAuth
 
 You may also install the latest source from the
-`Flask-Digest-Auth GitHub repository`_.
+`Flask-DigestAuth GitHub repository`_.
 
 ::
 
-    git clone git@github.com:imacat/flask-digest-auth.git
+    pip install git+https://github.com/imacat/flask-digestauth.git
-    cd flask-digest-auth
-    pip install .
-
-.. _Flask-Digest-Auth GitHub repository: https://github.com/imacat/flask-digest-auth
 
 
-Flask-Digest-Auth Alone
+Setting the Password
-=======================
+====================
 
-Flask-Digest-Auth can authenticate the users alone.
+The password hash of the HTTP Digest Authentication is composed of the
+realm, the username, and the password.  Example for setting the
+password:
 
-The currently logged-in user can be retrieved at ``g.user``, if any.
+::
+
+    from flask_digest_auth import make_password_hash
+
+    user.password = make_password_hash(realm, username, password)
+
+The username is part of the hash.  If the user changes their username,
+you need to ask their password, to generate and store the new password
+hash.
 
 
-Example for Simple Applications with Flask-Digest-Auth Alone
+Flask-DigestAuth Alone
-------------------------------------------------------------
+======================
+
+Flask-DigestAuth can authenticate the users alone.
+
+
+Simple Applications with Flask-DigestAuth Alone
+-----------------------------------------------
 
 In your ``my_app.py``:
 
@@ -143,8 +112,8 @@ In your ``my_app.py``:
         return redirect(request.form.get("next"))
 
 
-Example for Larger Applications with ``create_app()`` with Flask-Digest-Auth Alone
+Larger Applications with ``create_app()`` with Flask-DigestAuth Alone
-----------------------------------------------------------------------------------
+---------------------------------------------------------------------
 
 In your ``my_app/__init__.py``:
 
@@ -196,23 +165,29 @@ In your ``my_app/views.py``:
         app.register_blueprint(bp)
 
 
+
 Flask-Login Integration
 =======================
 
-Flask-Digest-Auth can work with Flask-Login.  You can write a Flask
+Flask-DigestAuth works with Flask-Login_.  You can write a Flask
-module that requires log in, without specifying the authentication
+module that requires log in, without specifying how to log in.  The
-mechanism.  The Flask application can specify the actual
+application can use either HTTP Digest Authentication, or the log in
-authentication mechanism as it sees fit.
+forms, as needed.
 
+To use Flask-Login with Flask-DigestAuth,
 ``login_manager.init_app(app)`` must be called before
 ``auth.init_app(app)``.
 
 The currently logged-in user can be retrieved at
 ``flask_login.current_user``, if any.
 
+The views only depend on Flask-Login, but not the Flask-DigestAuth.
+You can change the actual authentication mechanism without changing
+the views.
 
-Example for Simple Applications with Flask-Login Integration
+
-------------------------------------------------------------
+Simple Applications with Flask-Login Integration
+------------------------------------------------
 
 In your ``my_app.py``:
 
@@ -252,8 +227,8 @@ In your ``my_app.py``:
         return redirect(request.form.get("next"))
 
 
-Example for Larger Applications with ``create_app()`` with Flask-Login Integration
+Larger Applications with ``create_app()`` with Flask-Login Integration
-----------------------------------------------------------------------------------
+----------------------------------------------------------------------
 
 In your ``my_app/__init__.py``:
 
@@ -315,31 +290,13 @@ authentication mechanism.  You can change the actual authentication
 mechanism without changing the views.
 
 
-Setting the Password Hash
+Session Integration
-=========================
+===================
 
-The password hash of the HTTP Digest Authentication is composed of the
+Flask-DigestAuth features session integration.  The user log in
-realm, the username, and the password.  Example for setting the
+is remembered in the session.  The authentication information is not
-password:
+requested again.  This is different to the practice of the HTTP Digest
-
+Authentication, but is convenient for the log in accounting.
-::
-
-    from flask_digest_auth import make_password_hash
-
-    user.password = make_password_hash(realm, username, password)
-
-The username is part of the hash.  If the user changes their username,
-you need to ask their password, to generate and store the new password
-hash.
-
-
-Log Out
-=======
-
-Call ``auth.logout()`` when the user wants to log out.
-Besides the usual log out routine, ``auth.logout()`` actually causes
-the next browser automatic authentication to fail, forcing the browser
-to ask the user for the username and password again.
 
 
 Log In Bookkeeping
@@ -355,13 +312,22 @@ logging the log in event, adding the log in counter, etc.
         user.visits = user.visits + 1
 
 
-Writing Tests
+Log Out
-=============
+=======
 
-You can write tests with our test client that handles HTTP Digest
+Flask-DigestAuth supports log out.  The user will be prompted for the
-Authentication.
+new username and password.
 
-Example for a unittest_ test case:
+
+Test Client
+===========
+
+Flask-DigestAuth comes with a test client that supports HTTP digest
+authentication.
+
+
+A unittest Test Case
+--------------------
 
 ::
 
@@ -384,12 +350,12 @@ Example for a unittest_ test case:
             response = self.client.get("/admin")
             self.assertEqual(response.status_code, 401)
             response = self.client.get(
-                "/admin", digest_auth=("my_name", "my_pass"))
+                "/admin", digest_auth=(USERNAME, PASSWORD))
             self.assertEqual(response.status_code, 200)
 
 
-
+A pytest Test
-Example for a pytest_ test:
+-------------
 
 ::
 
@@ -413,20 +379,17 @@ Example for a pytest_ test:
 
     def test_admin(app: Flask, client: Client):
         with app.app_context():
-            response = self.client.get("/admin")
+            response = client.get("/admin")
             assert response.status_code == 401
-            response = self.client.get(
+            response = client.get(
-                "/admin", digest_auth=("my_name", "my_pass"))
+                "/admin", digest_auth=(USERNAME, PASSWORD))
             assert response.status_code == 200
 
-.. _unittest: https://docs.python.org/3/library/unittest.html
-.. _pytest: https://pytest.org
-
 
 Copyright
 =========
 
- Copyright (c) 2022 imacat.
+ Copyright (c) 2022-2023 imacat.
 
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
@@ -447,3 +410,10 @@ Authors
 | imacat
 | imacat@mail.imacat.idv.tw
 | 2022/11/23
+
+.. _HTTP Digest Authentication: https://en.wikipedia.org/wiki/Digest_access_authentication
+.. _RFC 2617: https://www.rfc-editor.org/rfc/rfc2617
+.. _Flask: https://flask.palletsprojects.com
+.. _Flask-DigestAuth GitHub repository: https://github.com/imacat/flask-digestauth
+.. _Flask-DigestAuth readthedocs documentation: https://flask-digestauth.readthedocs.io
+.. _Flask-Login: https://flask-login.readthedocs.io

docs/make.bat

@@ -10,8 +10,6 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=source
 set BUILDDIR=build
 
-if "%1" == "" goto help
-
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
@@ -21,10 +19,12 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 
+if "%1" == "" goto help
+
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 

docs/requirements.txt

@@ -0,0 +1 @@
+flask

docs/source/conf.py

@@ -1,59 +1,32 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
+# For the full list of built-in configuration values, see the documentation:
-# list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 import os
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import sys
 
 sys.path.insert(0, os.path.abspath('../../src/'))
 
-
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'Flask-Digest-Auth'
+project = 'Flask-DigestAuth'
-copyright = '2022, imacat'
+copyright = '2022-2023, imacat'
 author = 'imacat'
-
+release = '0.4.0'
-# The full version, including alpha/beta/rc tags
-release = '0.2.1'
-
 
 # -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# Add any Sphinx extension module names here, as strings. They can be
+extensions = ["sphinx.ext.autodoc"]
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    "sphinx.ext.autodoc"
-]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
 
+
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = 'sphinx_rtd_theme'
-
-# 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,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-
-# For readthedocs.io to work properly.
-master_doc = 'index'

docs/source/examples.rst

@@ -4,8 +4,8 @@ Examples
 
 .. _example-alone-simple:
 
-Simple Applications with Flask-Digest-Auth Alone
+Simple Applications with Flask-DigestAuth Alone
-------------------------------------------------
+-----------------------------------------------
 
 In your ``my_app.py``:
 
@@ -42,8 +42,8 @@ In your ``my_app.py``:
 
 .. _example-alone-large:
 
-Larger Applications with ``create_app()`` with Flask-Digest-Auth Alone
+Larger Applications with ``create_app()`` with Flask-DigestAuth Alone
-----------------------------------------------------------------------
+---------------------------------------------------------------------
 
 In your ``my_app/__init__.py``:
 
@@ -229,7 +229,7 @@ A unittest Test Case
             response = self.client.get("/admin")
             self.assertEqual(response.status_code, 401)
             response = self.client.get(
-                "/admin", digest_auth=("my_name", "my_pass"))
+                "/admin", digest_auth=(USERNAME, PASSWORD))
             self.assertEqual(response.status_code, 200)
 
 
@@ -261,8 +261,8 @@ A pytest Test
 
     def test_admin(app: Flask, client: Client):
         with app.app_context():
-            response = self.client.get("/admin")
+            response = client.get("/admin")
             assert response.status_code == 401
-            response = self.client.get(
+            response = client.get(
-                "/admin", digest_auth=("my_name", "my_pass"))
+                "/admin", digest_auth=(USERNAME, PASSWORD))
             assert response.status_code == 200

docs/source/flask_digest_auth.rst

@@ -1,24 +1,37 @@
 flask\_digest\_auth package
 ===========================
 
-The ``DigestAuth`` class
+Submodules
-************************
+----------
-.. autoclass:: flask_digest_auth.DigestAuth
+
+flask\_digest\_auth.algo module
+-------------------------------
+
+.. automodule:: flask_digest_auth.algo
    :members:
    :undoc-members:
    :show-inheritance:
 
-The ``make_password_hash`` Function
+flask\_digest\_auth.auth module
-***********************************
+-------------------------------
-.. autofunction:: flask_digest_auth.make_password_hash
 
-The ``calc_response`` Function
+.. automodule:: flask_digest_auth.auth
-******************************
+   :members:
-.. autofunction:: flask_digest_auth.calc_response
+   :undoc-members:
-
+   :show-inheritance:
-The ``Client`` Test Class
+
-*************************
+flask\_digest\_auth.test module
-.. autoclass:: flask_digest_auth.Client
+-------------------------------
+
+.. automodule:: flask_digest_auth.test
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: flask_digest_auth
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/index.rst

@@ -1,10 +1,16 @@
-.. flask-digest-auth documentation master file, created by
+.. Flask-DigestAuth documentation master file, created by
-   sphinx-quickstart on Tue Dec  6 15:15:08 2022.
+   sphinx-quickstart on Wed Dec  7 09:40:48 2022.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Flask-Digest-Auth's documentation!
+Welcome to Flask-DigestAuth's documentation!
-=============================================
+============================================
+
+*Flask-DigestAuth* is an `HTTP Digest Authentication`_ implementation
+for Flask_ applications.  It authenticates the user for the protected
+views.
+
+HTTP Digest Authentication is specified in `RFC 2617`_.
 
 .. toctree::
    :maxdepth: 2
@@ -22,3 +28,7 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+.. _HTTP Digest Authentication: https://en.wikipedia.org/wiki/Digest_access_authentication
+.. _RFC 2617: https://www.rfc-editor.org/rfc/rfc2617
+.. _Flask: https://flask.palletsprojects.com

docs/source/intro.rst

@@ -2,23 +2,21 @@ Introduction
 ============
 
 
-*Flask-Digest-Auth* is an `HTTP Digest Authentication`_ implementation
+*Flask-DigestAuth* is an `HTTP Digest Authentication`_ implementation
 for Flask_ applications.  It authenticates the user for the protected
 views.
 
 HTTP Digest Authentication is specified in `RFC 2617`_.
 
-See :ref:`example-alone-simple` and :ref:`example-alone-large`.
-
 
 Why HTTP Digest Authentication?
 -------------------------------
 
-HTTP Digest Authentication has the advantage that it does not send the
+*HTTP Digest Authentication* has the advantage that it does not send
-actual password to the server, which greatly enhances the security.
+the actual password to the server, which greatly enhances the
-It uses the challenge-response authentication scheme.  The client
+security.  It uses the challenge-response authentication scheme.  The
-returns the response calculated from the challenge and the password,
+client returns the response calculated from the challenge and the
-but not the original password.
+password, but not the original password.
 
 Log in forms has the advantage of freedom, in the senses of both the
 visual design and the actual implementation.  You may implement your
@@ -26,84 +24,125 @@ own challenge-response log in form, but then you are reinventing the
 wheels.  If a pretty log in form is not critical to your project, HTTP
 Digest Authentication should be a good choice.
 
-Flask-Digest-Auth works with Flask-Login_.  Log in protection can be
+Flask-DigestAuth works with Flask-Login_.  Log in protection can be
 separated with the authentication mechanism.  You can create protected
 Flask modules without knowing the actual authentication mechanisms.
 
 
-Features
+Installation
---------
+------------
 
-There are a couple of Flask HTTP digest authentication
+You can install Flask-DigestAuth with ``pip``:
-implementations.  Flask-Digest-Auth has the following features:
+
+::
+
+    pip install Flask-DigestAuth
+
+You may also install the latest source from the
+`Flask-DigestAuth GitHub repository`_.
+
+::
+
+    pip install git+https://github.com/imacat/flask-digestauth.git
+
+
+Setting the Password
+--------------------
+
+The password hash of the HTTP Digest Authentication is composed of the
+realm, the username, and the password.  Example for setting the
+password:
+
+::
+
+    from flask_digest_auth import make_password_hash
+
+    user.password = make_password_hash(realm, username, password)
+
+The username is part of the hash.  If the user changes their username,
+you need to ask their password, to generate and store the new password
+hash.
+
+See :func:`flask_digest_auth.algo.make_password_hash`.
+
+
+Flask-DigestAuth Alone
+----------------------
+
+Flask-DigestAuth can authenticate the users alone.
+
+See :ref:`example-alone-simple` and :ref:`example-alone-large`.
 
 
 Flask-Login Integration
-#######################
+-----------------------
 
-Flask-Digest-Auth features Flask-Login integration.  The views
+Flask-DigestAuth works with Flask-Login_.  You can write a Flask
-can be totally independent with the actual authentication mechanism.
+module that requires log in, without specifying how to log in.  The
-You can write a Flask module that requires log in, without specify
+application can use either HTTP Digest Authentication, or the log in
-the actual authentication mechanism.  The application can specify
+forms, as needed.
-either HTTP Digest Authentication, or the log in forms, as needed.
+
+To use Flask-Login with Flask-DigestAuth,
+``login_manager.init_app(app)`` must be called before
+``auth.init_app(app)``.
+
+The currently logged-in user can be retrieved at
+``flask_login.current_user``, if any.
 
 See :ref:`example-flask-login-simple` and
 :ref:`example-flask-login-large`.
 
+The views only depend on Flask-Login, but not the Flask-DigestAuth.
+You can change the actual authentication mechanism without changing
+the views.
+
 
 Session Integration
-###################
+-------------------
 
-Flask-Digest-Auth features session integration.  The user log in
+Flask-DigestAuth features session integration.  The user log in
 is remembered in the session.  The authentication information is not
 requested again.  This is different to the practice of the HTTP Digest
 Authentication, but is convenient for the log in accounting.
 
 
 Log In Bookkeeping
-##################
+------------------
 
-You can register a callback to run when the user logs in.
+You can register a callback to run when the user logs in, for ex.,
-See :meth:`flask_digest_auth.DigestAuth.register_on_login`.
+logging the log in event, adding the log in counter, etc.
+
+::
+
+    @auth.register_on_login
+    def on_login(user: User) -> None:
+        user.visits = user.visits + 1
+
+See :meth:`flask_digest_auth.auth.DigestAuth.register_on_login`.
 
 
 Log Out
-#######
+-------
 
-Flask-Digest-Auth supports log out.  The user will be prompted for the
+Flask-DigestAuth supports log out.  The user will be prompted for the
 new username and password.
-See :meth:`flask_digest_auth.DigestAuth.logout`.
+
+See :meth:`flask_digest_auth.auth.DigestAuth.logout`.
 
 
 Test Client
-###########
+-----------
 
-Flask-Digest-Auth comes with a test client that supports HTTP digest
+Flask-DigestAuth comes with a test client that supports HTTP digest
 authentication.
-See :class:`flask_digest_auth.Client`.
+
+See :class:`flask_digest_auth.test.Client`.
 
 Also see :ref:`example-unittest` and :ref:`example-pytest`.
 
 
-Installation
-------------
-
-You can install Flask-Digest-Auth with ``pip``:
-
-::
-
-    pip install Flask-Digest-Auth
-
-You may also install the latest source from the
-`Flask-Digest-Auth GitHub repository`_.
-
-::
-
-    pip install git+https://github.com/imacat/flask-digest-auth
-
-
 .. _HTTP Digest Authentication: https://en.wikipedia.org/wiki/Digest_access_authentication
 .. _RFC 2617: https://www.rfc-editor.org/rfc/rfc2617
 .. _Flask: https://flask.palletsprojects.com
 .. _Flask-Login: https://flask-login.readthedocs.io
-.. _Flask-Digest-Auth GitHub repository: https://github.com/imacat/flask-digest-auth
+.. _Flask-DigestAuth GitHub repository: https://github.com/imacat/flask-digestauth

docs/source/modules.rst

@@ -0,0 +1,7 @@
+src
+===
+
+.. toctree::
+   :maxdepth: 4
+
+   flask_digest_auth

setup.cfg

@@ -1,7 +1,7 @@
 # The Flask HTTP Digest Authentication Project.
 # Author: imacat@mail.imacat.idv.tw (imacat), 2022/11/23
 
-#  Copyright (c) 2022 imacat.
+#  Copyright (c) 2022-2023 imacat.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -16,16 +16,16 @@
 #  limitations under the License.
 
 [metadata]
-name = flask-digest-auth
+name = Flask-DigestAuth
-version = 0.2.1
+version = 0.4.0
 author = imacat
 author_email = imacat@mail.imacat.idv.tw
 description = The Flask HTTP Digest Authentication project.
 long_description = file: README.rst
 long_description_content_type = text/x-rst
-url = https://github.com/imacat/flask-digest-auth
+url = https://github.com/imacat/flask-digestauth
 project_urls =
-    Bug Tracker = https://github.com/imacat/flask-digest-auth/issues
+    Bug Tracker = https://github.com/imacat/flask-digestauth/issues
 classifiers =
     Programming Language :: Python :: 3
     License :: OSI Approved :: Apache Software License

src/flask_digest_auth/algo.py

@@ -26,6 +26,13 @@ from hashlib import md5
 
 def make_password_hash(realm: str, username: str, password: str) -> str:
     """Calculates the password hash for the HTTP digest authentication.
+    Use this function to set the password for the user.
+
+    :Example:
+
+    ::
+
+        user.password = make_password_hash(realm, username, password)
 
     :param realm: The realm.
     :param username: The username.
@@ -47,7 +54,7 @@ def calc_response(
     :param uri: The request URI.
     :param password_hash: The password hash for the HTTP digest authentication.
     :param nonce: The nonce.
-    :param qop: the quality of protection, either ``auth`` or ``auth-int``.
+    :param qop: The quality of protection, either ``auth`` or ``auth-int``.
     :param algorithm: The algorithm, either ``MD5`` or ``MD5-sess``.
     :param cnonce: The client nonce, which must exists when qop exists or
         algorithm is ``MD5-sess``.

src/flask_digest_auth/auth.py

@@ -1,7 +1,7 @@
 # The Flask HTTP Digest Authentication Project.
 # Author: imacat@mail.imacat.idv.tw (imacat), 2022/10/22
 
-#  Copyright (c) 2022 imacat.
+#  Copyright (c) 2022-2023 imacat.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -16,8 +16,9 @@
 #  limitations under the License.
 
 """The HTTP Digest Authentication.
-See RFC 2617 HTTP Authentication: Basic and Digest Access Authentication
+See `RFC 2617`_ HTTP Authentication: Basic and Digest Access Authentication
 
+.. _RFC 2617: https://www.rfc-editor.org/rfc/rfc2617
 """
 from __future__ import annotations
 
@@ -26,7 +27,8 @@ import typing as t
 from functools import wraps
 from secrets import token_urlsafe, randbits
 
-from flask import g, request, Response, session, abort, Flask, Request
+from flask import g, request, Response, session, abort, Flask, Request, \
+    current_app
 from itsdangerous import URLSafeTimedSerializer, BadData
 from werkzeug.datastructures import Authorization
 
@@ -41,22 +43,44 @@ class DigestAuth:
 
         :param realm: The realm.
         """
-        self.secret_key: str = token_urlsafe(32)
+        self.__serializer: URLSafeTimedSerializer \
-        self.serializer: URLSafeTimedSerializer \
+            = URLSafeTimedSerializer(token_urlsafe(32))
-            = URLSafeTimedSerializer(self.secret_key)
+        """The serializer to generate and validate the nonce and opaque."""
         self.realm: str = "" if realm is None else realm
-        self.algorithm: t.Optional[str] = None
+        """The realm.  Default is an empty string."""
+        self.algorithm: t.Optional[t.Literal["MD5", "MD5-sess"]] = None
+        """The algorithm, either None, ``MD5``, or ``MD5-sess``.  Default is
+        None."""
         self.use_opaque: bool = True
-        self.domain: t.List[str] = []
+        """Whether to use an opaque.  Default is True."""
-        self.qop: t.List[str] = ["auth", "auth-int"]
+        self.__domain: t.List[str] = []
-        self.app: t.Optional[Flask] = None
+        """A list of directories that this username and password applies to.
+        Default is empty."""
+        self.__qop: t.List[t.Literal["auth", "auth-int"]] \
+            = ["auth", "auth-int"]
+        """A list of supported quality of protection supported, either
+        ``qop``, ``auth-int``, both, or empty.  Default is both."""
         self.__get_password_hash: BasePasswordHashGetter \
             = BasePasswordHashGetter()
+        """The callback to return the password hash."""
         self.__get_user: BaseUserGetter = BaseUserGetter()
+        """The callback to return the user."""
         self.__on_login: BaseOnLogInCallback = BaseOnLogInCallback()
+        """The callback to run when the user logs in."""
 
     def login_required(self, view) -> t.Callable:
-        """The view decorator for HTTP digest authentication.
+        """The view decorator for the HTTP digest authentication.
+
+        :Example:
+
+        ::
+
+            @app.get("/admin")
+            @auth.login_required
+            def admin():
+                return f"Hello, {g.user.username}!"
+
+        The logged-in user can be retrieved at ``g.user``.
 
         :param view: The view.
         :return: The login-protected view.
@@ -92,7 +116,7 @@ class DigestAuth:
             if authorization.type != "digest":
                 raise UnauthorizedException(
                     "Not an HTTP digest authorization")
-            self.authenticate(state)
+            self.__authenticate(state)
             session["user"] = authorization.username
             return self.__get_user(authorization.username)
 
@@ -121,12 +145,12 @@ class DigestAuth:
                 response: Response = Response()
                 response.status = 401
                 response.headers["WWW-Authenticate"] \
-                    = self.make_response_header(state)
+                    = self.__make_response_header(state)
                 abort(response)
 
         return login_required_view
 
-    def authenticate(self, state: AuthState) -> None:
+    def __authenticate(self, state: AuthState) -> None:
         """Authenticate a user.
 
         :param state: The authorization state.
@@ -142,7 +166,7 @@ class DigestAuth:
                 raise UnauthorizedException(
                     "Missing \"opaque\" in the Authorization header")
             try:
-                self.serializer.loads(
+                self.__serializer.loads(
                     authorization.opaque, salt="opaque", max_age=1800)
             except BadData:
                 raise UnauthorizedException("Invalid opaque")
@@ -163,7 +187,7 @@ class DigestAuth:
             state.stale = False
             raise UnauthorizedException("Incorrect response value")
         try:
-            self.serializer.loads(
+            self.__serializer.loads(
                 authorization.nonce,
                 salt="nonce" if authorization.opaque is None
                 else f"nonce-{authorization.opaque}")
@@ -171,7 +195,7 @@ class DigestAuth:
             state.stale = True
             raise UnauthorizedException("Invalid nonce")
 
-    def make_response_header(self, state: AuthState) -> str:
+    def __make_response_header(self, state: AuthState) -> str:
         """Composes and returns the ``WWW-Authenticate`` response header.
 
         :param state: The authorization state.
@@ -187,16 +211,16 @@ class DigestAuth:
                 return None
             if state.opaque is not None:
                 return state.opaque
-            return self.serializer.dumps(randbits(32), salt="opaque")
+            return self.__serializer.dumps(randbits(32), salt="opaque")
 
         opaque: t.Optional[str] = get_opaque()
-        nonce: str = self.serializer.dumps(
+        nonce: str = self.__serializer.dumps(
             randbits(32),
             salt="nonce" if opaque is None else f"nonce-{opaque}")
 
         header: str = f"Digest realm=\"{self.realm}\""
-        if len(self.domain) > 0:
+        if len(self.__domain) > 0:
-            domain_list: str = ",".join(self.domain)
+            domain_list: str = ",".join(self.__domain)
             header += f", domain=\"{domain_list}\""
         header += f", nonce=\"{nonce}\""
         if opaque is not None:
@@ -205,14 +229,23 @@ class DigestAuth:
             header += f", stale=TRUE" if state.stale else f", stale=FALSE"
         if self.algorithm is not None:
             header += f", algorithm=\"{self.algorithm}\""
-        if len(self.qop) > 0:
+        if len(self.__qop) > 0:
-            qop_list: str = ",".join(self.qop)
+            qop_list: str = ",".join(self.__qop)
             header += f", qop=\"{qop_list}\""
         return header
 
     def register_get_password(self, func: t.Callable[[str], t.Optional[str]])\
             -> None:
-        """Registers the callback to obtain the password hash.
+        """The decorator to register the callback to obtain the password hash.
+
+        :Example:
+
+        ::
+
+            @auth.register_get_password
+            def get_password_hash(username: str) -> Optional[str]:
+                user = User.query.filter(User.username == username).first()
+                return None if user is None else user.password
 
         :param func: The callback that given the username, returns the password
             hash, or None if the user does not exist.
@@ -235,7 +268,15 @@ class DigestAuth:
 
     def register_get_user(self, func: t.Callable[[str], t.Optional[t.Any]])\
             -> None:
-        """Registers the callback to obtain the user.
+        """The decorator to register the callback to obtain the user.
+
+        :Example:
+
+        ::
+
+            @auth.register_get_user
+            def get_user(username: str) -> Optional[User]:
+                return User.query.filter(User.username == username).first()
 
         :param func: The callback that given the username, returns the user,
             or None if the user does not exist.
@@ -257,7 +298,15 @@ class DigestAuth:
         self.__get_user = UserGetter()
 
     def register_on_login(self, func: t.Callable[[t.Any], None]) -> None:
-        """Registers the callback when the user logs in.
+        """The decorator to register the callback to run when the user logs in.
+
+        :Example:
+
+        ::
+
+            @auth.register_on_login
+            def on_login(user: User) -> None:
+                user.visits = user.visits + 1
 
         :param func: The callback given the logged-in user.
         :return: None.
@@ -278,13 +327,22 @@ class DigestAuth:
         self.__on_login = OnLogInCallback()
 
     def init_app(self, app: Flask) -> None:
-        """Initializes the Flask application.
+        """Initializes the Flask application.  The DigestAuth instance will
+        be stored in ``app.extensions["digest_auth"]``.
+
+        :Example:
+
+        ::
+
+            app: flask = Flask(__name__)
+            auth: DigestAuth = DigestAuth()
+            auth.realm = "My Admin"
+            auth.init_app(app)
 
         :param app: The Flask application.
         :return: None.
         """
-        app.digest_auth = self
+        app.extensions["digest_auth"] = self
-        self.app = app
 
         if hasattr(app, "login_manager"):
             from flask_login import LoginManager, login_user
@@ -297,10 +355,13 @@ class DigestAuth:
 
                 :return: None.
                 """
+                state: AuthState = getattr(request, "_digest_auth_state") \
+                    if hasattr(request, "_digest_auth_state") \
+                    else AuthState()
                 response: Response = Response()
                 response.status = 401
                 response.headers["WWW-Authenticate"] \
-                    = self.make_response_header(g.digest_auth_state)
+                    = self.__make_response_header(state)
                 abort(response)
 
             @login_manager.request_loader
@@ -311,7 +372,7 @@ class DigestAuth:
                 :return: The authenticated user, or None if the
                     authentication fails
                 """
-                g.digest_auth_state = AuthState()
+                request._digest_auth_state = AuthState()
                 authorization: Authorization = req.authorization
                 try:
                     if authorization is None:
@@ -319,7 +380,7 @@ class DigestAuth:
                     if authorization.type != "digest":
                         raise UnauthorizedException(
                             "Not an HTTP digest authorization")
-                    self.authenticate(g.digest_auth_state)
+                    self.__authenticate(request._digest_auth_state)
                     user = login_manager.user_callback(
                         authorization.username)
                     login_user(user)
@@ -335,12 +396,22 @@ class DigestAuth:
         This actually causes the next authentication to fail, which forces
         the browser to ask the user for the username and password again.
 
+        :Example:
+
+        ::
+
+            @app.post("/logout")
+            @auth.login_required
+            def logout():
+                auth.logout()
+                return redirect(request.form.get("next"))
+
         :return: None.
         """
         if "user" in session:
             del session["user"]
         try:
-            if hasattr(self.app, "login_manager"):
+            if hasattr(current_app, "login_manager"):
                 from flask_login import logout_user
                 logout_user()
         except ModuleNotFoundError:
@@ -349,21 +420,30 @@ class DigestAuth:
 
 
 class AuthState:
-    """The authorization state."""
+    """The authentication state.  It keeps the status in the earlier
+    authentication stage, so that the latter response stage knows how to
+    response.
+    """
 
     def __init__(self):
         """Constructs the authorization state."""
         self.opaque: t.Optional[str] = None
+        """The opaque value specified by the client, if valid."""
         self.stale: t.Optional[bool] = None
+        """The stale value, if there is a previous log in attempt."""
 
 
 class UnauthorizedException(Exception):
-    """The exception thrown when the authentication is failed."""
+    """The exception thrown when the authentication fails."""
-    pass
 
 
 class BasePasswordHashGetter:
-    """The base password hash getter."""
+    """The base callback that given the username, returns the password hash,
+    or None if the user does not exist.  The default is to raise an
+    :class:`UnboundLocalError` if the callback is not registered yet.
+
+    See :meth:`flask_digest_auth.auth.DigestAuth.register_get_password`
+    """
 
     @staticmethod
     def __call__(username: str) -> t.Optional[str]:
@@ -379,7 +459,12 @@ class BasePasswordHashGetter:
 
 
 class BaseUserGetter:
-    """The base user getter."""
+    """The base callback that given the username, returns the user, or None if
+    the user does not exist.  The default is to raise an
+    :class:`UnboundLocalError` if the callback is not registered yet.
+
+    See :meth:`flask_digest_auth.auth.DigestAuth.register_get_user`
+    """
 
     @staticmethod
     def __call__(username: str) -> t.Optional[t.Any]:
@@ -395,7 +480,11 @@ class BaseUserGetter:
 
 
 class BaseOnLogInCallback:
-    """The base callback when the user logs in."""
+    """The base callback to run when the user logs in, given the logged-in
+    user.  The default does nothing.
+
+    See :meth:`flask_digest_auth.auth.DigestAuth.register_on_login`
+    """
 
     @staticmethod
     def __call__(user: t.Any) -> None:

src/flask_digest_auth/test.py

@@ -29,14 +29,66 @@ from flask_digest_auth.algo import calc_response, make_password_hash
 
 
 class Client(WerkzeugClient):
-    """The test client with HTTP digest authentication enabled."""
+    """The test client with HTTP digest authentication enabled.
+
+    :Example:
+
+    For unittest_:
+
+    ::
+
+        class MyTestCase(flask_testing.TestCase):
+
+            def create_app(self):
+                app: Flask = create_app({
+                    "SECRET_KEY": token_urlsafe(32),
+                    "TESTING": True
+                })
+                app.test_client_class = Client
+                return app
+
+            def test_admin(self):
+                response = self.client.get("/admin")
+                self.assertEqual(response.status_code, 401)
+                response = self.client.get(
+                    "/admin", digest_auth=(USERNAME, PASSWORD))
+                self.assertEqual(response.status_code, 200)
+
+    For pytest_:
+
+    ::
+
+        @pytest.fixture()
+        def app():
+            app: Flask = create_app({
+                "SECRET_KEY": token_urlsafe(32),
+                "TESTING": True
+            })
+            app.test_client_class = Client
+            yield app
+
+        @pytest.fixture()
+        def client(app):
+            return app.test_client()
+
+        def test_admin(app: Flask, client: Client):
+            with app.app_context():
+                response = client.get("/admin")
+                assert response.status_code == 401
+                response = client.get(
+                    "/admin", digest_auth=(USERNAME, PASSWORD))
+                assert response.status_code == 200
+
+    .. _unittest: https://docs.python.org/3/library/unittest.html
+    .. _pytest: https://pytest.org
+    """
 
     def open(self, *args, digest_auth: t.Optional[t.Tuple[str, str]] = None,
              **kwargs) -> TestResponse:
         """Opens a request.
 
         :param args: The arguments.
-        :param digest_auth: A tuple of the username and password for the HTTP
+        :param digest_auth: The (*username*, *password*) tuple for the HTTP
             digest authentication.
         :param kwargs: The keyword arguments.
         :return: The response.

tests/test_flask_login.py

@@ -45,7 +45,6 @@ class User:
         self.password_hash: str = make_password_hash(
             _REALM, username, password)
         self.visits: int = 0
-        self.is_authenticated: bool = True
         self.is_active: bool = True
         self.is_anonymous: bool = False
 
@@ -57,6 +56,16 @@ class User:
         """
         return self.username
 
+    @property
+    def is_authenticated(self) -> bool:
+        """Returns whether the user is authenticated.
+        This is required by Flask-Login.
+        This should return self.is_active.
+
+        :return: True if the user is active, or False otherwise.
+        """
+        return self.is_active
+
 
 class FlaskLoginTestCase(TestCase):
     """The test case with the Flask-Login integration."""
@@ -256,3 +265,34 @@ class FlaskLoginTestCase(TestCase):
         response = self.client.get(admin_uri)
         self.assertEqual(response.status_code, 200)
         self.assertEqual(self.user.visits, 2)
+
+    def test_disabled(self) -> None:
+        """Tests the disabled user.
+
+        :return: None.
+        """
+        if not self.has_flask_login:
+            self.skipTest("Skipped without Flask-Login.")
+
+        response: Response
+
+        self.user.is_active = False
+        response = self.client.get(self.app.url_for("admin-1"))
+        self.assertEqual(response.status_code, 401)
+        response = self.client.get(self.app.url_for("admin-1"),
+                                   digest_auth=(_USERNAME, _PASSWORD))
+        self.assertEqual(response.status_code, 401)
+
+        self.user.is_active = True
+        response = self.client.get(self.app.url_for("admin-1"),
+                                   digest_auth=(_USERNAME, _PASSWORD))
+        self.assertEqual(response.status_code, 200)
+        response = self.client.get(self.app.url_for("admin-1"))
+        self.assertEqual(response.status_code, 200)
+
+        self.user.is_active = False
+        response = self.client.get(self.app.url_for("admin-1"))
+        self.assertEqual(response.status_code, 401)
+        response = self.client.get(self.app.url_for("admin-1"),
+                                   digest_auth=(_USERNAME, _PASSWORD))
+        self.assertEqual(response.status_code, 401)