Advanced to version 0.3.0.

docs/source/conf.py

@@ -22,7 +22,7 @@ copyright = '2022, imacat'
 author = 'imacat'
 
 # The full version, including alpha/beta/rc tags
-release = '0.2.4'
+release = '0.3.0'
 
 
 # -- General configuration ---------------------------------------------------

setup.cfg

@@ -17,7 +17,7 @@
 
 [metadata]
 name = flask-digest-auth
-version = 0.2.4
+version = 0.3.0
 author = imacat
 author_email = imacat@mail.imacat.idv.tw
 description = The Flask HTTP Digest Authentication project.

src/flask_digest_auth/algo.py

@@ -28,7 +28,7 @@ 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.
 
-    For example:
+    :Example:
 
     ::
 
@@ -54,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

@@ -41,15 +41,24 @@ class DigestAuth:
 
         :param realm: The realm.
         """
-        self.secret_key: str = token_urlsafe(32)
-        self.serializer: URLSafeTimedSerializer \
-            = URLSafeTimedSerializer(self.secret_key)
+        self.__serializer: URLSafeTimedSerializer \
+            = URLSafeTimedSerializer(token_urlsafe(32))
         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] = []
-        self.qop: t.List[str] = ["auth", "auth-int"]
+        """Whether to use an opaque.  Default is True."""
+        self.__domain: t.List[str] = []
+        """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.app: t.Optional[Flask] = None
+        """The current Flask application."""
         self.__get_password_hash: BasePasswordHashGetter \
             = BasePasswordHashGetter()
         self.__get_user: BaseUserGetter = BaseUserGetter()
@@ -58,10 +67,11 @@ class DigestAuth:
     def login_required(self, view) -> t.Callable:
         """The view decorator for HTTP digest authentication.
 
-        For example:
+        :Example:
 
         ::
 
+            @app.get("/admin")
             @auth.login_required
             def admin():
                 return f"Hello, {g.user.username}!"
@@ -152,7 +162,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")
@@ -173,7 +183,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}")
@@ -197,16 +207,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:
-            domain_list: str = ",".join(self.domain)
+        if len(self.__domain) > 0:
+            domain_list: str = ",".join(self.__domain)
             header += f", domain=\"{domain_list}\""
         header += f", nonce=\"{nonce}\""
         if opaque is not None:
@@ -215,8 +225,8 @@ 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:
-            qop_list: str = ",".join(self.qop)
+        if len(self.__qop) > 0:
+            qop_list: str = ",".join(self.__qop)
             header += f", qop=\"{qop_list}\""
         return header
 
@@ -224,7 +234,7 @@ class DigestAuth:
             -> None:
         """The decorator to register the callback to obtain the password hash.
 
-        For example:
+        :Example:
 
         ::
 
@@ -256,7 +266,7 @@ class DigestAuth:
             -> None:
         """The decorator to register the callback to obtain the user.
 
-        For example:
+        :Example:
 
         ::
 
@@ -286,7 +296,7 @@ class DigestAuth:
     def register_on_login(self, func: t.Callable[[t.Any], None]) -> None:
         """The decorator to register the callback to run when the user logs in.
 
-        For example:
+        :Example:
 
         ::
 
@@ -315,7 +325,7 @@ class DigestAuth:
     def init_app(self, app: Flask) -> None:
         """Initializes the Flask application.
 
-        For example:
+        :Example:
 
         ::
 
@@ -379,7 +389,7 @@ class DigestAuth:
         This actually causes the next authentication to fail, which forces
         the browser to ask the user for the username and password again.
 
-        For example:
+        :Example:
 
         ::
 

src/flask_digest_auth/test.py

@@ -31,7 +31,9 @@ from flask_digest_auth.algo import calc_response, make_password_hash
 class Client(WerkzeugClient):
     """The test client with HTTP digest authentication enabled.
 
-    For unittest example:
+    :Example:
+
+    For unittest_:
 
     ::
 
@@ -52,7 +54,7 @@ class Client(WerkzeugClient):
                     "/admin", digest_auth=("my_name", "my_pass"))
                 self.assertEqual(response.status_code, 200)
 
-    For pytest example:
+    For pytest_:
 
     ::
 
@@ -76,12 +78,19 @@ class Client(WerkzeugClient):
                 response = client.get(
                     "/admin", digest_auth=("my_name", "my_pass"))
                 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.
 
+        .. warning::
+            This is to override the parent ``open`` method.  You should call
+            the ``get``, ``post``, ``put``, and ``delete`` methods instead.
+
         :param args: The arguments.
         :param digest_auth: A tuple of the username and password for the HTTP
             digest authentication.
@@ -106,6 +115,9 @@ class Client(WerkzeugClient):
                            username: str, password: str) -> Authorization:
         """Composes and returns the request authorization.
 
+        .. warning::
+            This method is not for public.
+
         :param www_authenticate: The ``WWW-Authenticate`` response.
         :param uri: The request URI.
         :param username: The username.