Verify docstrings with interrogate.

Signed-off-by: Alexis <[email protected]>

Makefile

@@ -55,7 +55,8 @@ lint: $(VENV)/pyvenv.cfg
 		ruff check
 	cargo fmt --check --manifest-path rust/Cargo.toml
 	cargo fmt --check --manifest-path rust/tsp-asn1/Cargo.toml
-
+	. $(VENV_BIN)/activate && \
+		interrogate -c pyproject.toml .
 
 .PHONY: reformat
 reformat:

pyproject.toml

@@ -22,7 +22,7 @@ dependencies = ["cryptography>=43,<45"]
 [project.optional-dependencies]
 doc = []
 test = ["pytest", "pytest-cov", "pretend", "coverage[toml]"]
-lint = ["ruff >= 0.7,< 0.9"]
+lint = ["ruff >= 0.7,< 0.9", "interrogate"]
 dev = ["rfc3161-client[test,lint,doc]", "maturin>=1.7,<2.0"]
 
 [project.urls]
@@ -52,3 +52,14 @@ select = ["E", "F", "I", "W", "UP", "TCH"]
 
 [tool.coverage.report]
 exclude_also = ["if TYPE_CHECKING:"]
+
+[tool.interrogate]
+# don't enforce documentation coverage for testing, the virtual
+# environment, or the scripts.
+exclude = [
+    ".venv",
+    "test",
+    "scripts",
+]
+ignore-semiprivate = true
+fail-under = 100

src/rfc3161_client/errors.py

@@ -1,2 +1,7 @@
+"""Errors."""
+
+
 class VerificationError(Exception):
+    """Verification errors are raised when the verification of a Timestamp fails."""
+
     pass

src/rfc3161_client/tsp.py

@@ -1,3 +1,5 @@
+"""Timestamp protocol objects."""
+
 from __future__ import annotations
 
 import abc
@@ -66,6 +68,8 @@ def as_bytes(self) -> bytes:
 
 
 class PKIStatus(enum.IntEnum):
+    """Response status."""
+
     GRANTED = 0
     GRANTED_WITH_MODS = 1
     REJECTION = 2
@@ -75,6 +79,8 @@ class PKIStatus(enum.IntEnum):
 
 
 class TimeStampResponse(metaclass=abc.ABCMeta):
+    """Timestamp response (per RFC 3161)."""
+
     @property
     @abc.abstractmethod
     def status(self) -> int:
@@ -108,6 +114,8 @@ def as_bytes(self) -> bytes:
 
 
 class Accuracy(metaclass=abc.ABCMeta):
+    """Accuracy of the timestamp response."""
+
     @property
     @abc.abstractmethod
     def seconds(self) -> int:
@@ -128,6 +136,8 @@ def micros(self) -> int | None:
 
 
 class TimeStampTokenInfo(metaclass=abc.ABCMeta):
+    """Timestamp token info (per RFC 3161)."""
+
     @property
     @abc.abstractmethod
     def version(self) -> int:
@@ -178,6 +188,8 @@ def name(self) -> cryptography.x509.GeneralName:
 
 
 class SignedData(metaclass=abc.ABCMeta):
+    """Signed data (CMS - RFC 2630)"""
+
     @property
     @abc.abstractmethod
     def version(self) -> int:
@@ -205,6 +217,8 @@ def signer_infos(self) -> set[SignerInfo]:
 
 
 class SignerInfo(metaclass=abc.ABCMeta):
+    """Signer info (RFC 2634)."""
+
     @property
     @abc.abstractmethod
     def version(self) -> int:

src/rfc3161_client/verify.py

@@ -14,6 +14,8 @@
 
 
 class VerifierBuilder:
+    """Builder for a Verifier."""
+
     def __init__(
         self,
         policy_id: cryptography.x509.ObjectIdentifier | None = None,
@@ -121,11 +123,22 @@ def from_request(cls, tsp_request: TimeStampRequest) -> VerifierBuilder:
 
 
 class Verifier(metaclass=abc.ABCMeta):
+    """Verifier.
+
+    This class should not be instantiated directly but through a VerifierBuilder.
+    """
+
     @abc.abstractmethod
-    def verify(self, timestamp_response: TimeStampResponse, hashed_message: bytes) -> bool: ...
+    def verify(self, timestamp_response: TimeStampResponse, hashed_message: bytes) -> bool:
+        """Verify a timestamp response."""
 
 
 class _Verifier(Verifier):
+    """Inner implementation of the Verifier.
+
+    This pattern helps us ensure that the Verifier is never created directly.
+    """
+
     def __init__(
         self,
         policy_id: cryptography.x509.ObjectIdentifier | None,