add documentation for algorithm classes and methods

aputils/algorithms.py

@@ -49,12 +49,25 @@ def get(algo: AlgorithmType | str) -> type[Algorithm]:
 
 
 def register(algo: type[Algorithm]) -> type[Algorithm]:
+	"""
+		Register a new algorithm
+
+		:param algo: Class of the new algorithm
+		:raises KeyError: When an algorithm by the same name exists
+	"""
+
+	if algo.__name__.lower() in ALGORITHMS:
+		raise KeyError(algo.__name__)
+
 	ALGORITHMS[algo.__name__.lower()] = algo
 	return algo
 
 
 class Algorithm(ABC):
+	"Represents an algorithm for signing and verifying signatures"
+
 	algo_type: AlgorithmType
+	"Name of the algorithm type"
 
 
 	def __init__(self, signer: Signer) -> None:
@@ -63,15 +76,34 @@ class Algorithm(ABC):
 
 	@staticmethod
 	@abstractmethod
-	def hash_data(data: bytes | str) -> DataHash: ...
+	def hash_data(data: bytes | str) -> DataHash:
+		"""
+			Hash some data and return a `Hash` object
+
+			:param data: Data to hash
+		"""
+		...
 
 
 	@abstractmethod
-	def verify_data(self, data: DataHash, signature: bytes) -> bool: ...
+	def verify_data(self, data: DataHash, signature: bytes) -> bool:
+		"""
+			Verify a signed hash
+
+			:param data: Hash to verify
+			:param signature: HTTP signature of the signed data hash
+		"""
+		...
 
 
 	@abstractmethod
-	def sign_data(self, data: DataHash) -> bytes: ...
+	def sign_data(self, data: DataHash) -> bytes:
+		"""
+			Sign a data hash
+
+			:param data: Hash to sign
+		"""
+		...
 
 
 	@staticmethod
@@ -82,6 +114,15 @@ class Algorithm(ABC):
 			path: str,
 			headers: dict[str, str],
 			body: Message | dict[str, Any] | bytes | str | None = None) -> dict[str, str]:
+		"""
+			Process the headers of a response just before signing them
+
+			:param method: HTTP method of the response
+			:param host: Hostname of the target server
+			:param path: Path of the response
+			:param headers: Headers to be sent with the response
+			:param body: Optional body data to be sent with the response
+		"""
 		...
 
 
@@ -92,6 +133,14 @@ class Algorithm(ABC):
 			path: str,
 			headers: dict[str, str],
 			signature: Signature) -> dict[str, str]:
+		"""
+			Process the headers of a request just before validating them
+
+			:param method: HTTP method of the request
+			:param path: Path of the request
+			:param headers: Headers sent with the request
+			:param signature: HTTP signature for the request
+		"""
 		...
 
 
@@ -119,6 +168,15 @@ class Algorithm(ABC):
 					headers: dict[str, str],
 					used_headers: Sequence | None = None,
 					body: Message | dict[str, Any] | bytes | str | None = None) -> dict[str, str]:
+		"""
+			Create an HTTP signature for a request
+
+			:param method: HTTP method of the request
+			:param url: Location of the request
+			:param headers: Headers to be sent with the request
+			:param used_headers: Name of header keys to include in the signature
+			:param body: Optional body of the request
+		"""
 
 		uri = urlparse(url)
 
@@ -159,6 +217,15 @@ class Algorithm(ABC):
 						headers: dict[str, str],
 						signature: Signature,
 						body: Message | dict[str, Any] | bytes | str | None = None) -> bool:
+		"""
+			Verify the headers of a request
+
+			:param method: HTTP method of the request
+			:param path: Path of the request
+			:param headers: Headers of the request
+			:param signature: HTTP signature include in the request
+			:param body: Body data of the request
+		"""
 
 		headers = self.process_headers_for_validation(method, path, headers, signature)
 
@@ -179,6 +246,12 @@ class Algorithm(ABC):
 
 @register
 class HS2019(Algorithm):
+	"""
+		Represents the
+		`HS2019 <https://datatracker.ietf.org/doc/id/draft-richanna-http-message-signatures-00.html>`_
+		signing standard
+	"""
+
 	algo_type: AlgorithmType = AlgorithmType.HS2019
 
 
@@ -277,6 +350,8 @@ class HS2019(Algorithm):
 
 @register
 class RsaSha256(HS2019):
+	"Represents an old signing standard that is a subset of HS2019"
+
 	algo_type: AlgorithmType = AlgorithmType.RSASHA256
 
 

docs/api.rst

@@ -7,6 +7,12 @@ Signer
 
 * :class:`aputils.Signer`
 
+Algorithms
+----------
+
+* :class:`aputils.HS2019`
+* :class:`aputils.RsaSha256`
+
 Message
 -------
 

docs/api/algorithms.rst

@@ -0,0 +1,25 @@
+Algorithms
+==========
+
+
+.. autoclass:: aputils.HS2019
+	:exclude-members: __init__, __new__
+	:show-inheritance:
+
+
+.. autoclass:: aputils.RsaSha256
+	:exclude-members: __init__, __new__
+	:show-inheritance:
+
+
+Helpers
+-------
+
+.. autofunction:: aputils.get_algorithm
+.. autofunction:: aputils.register_algorithm
+
+
+.. autoclass:: aputils.Algorithm
+	:members:
+	:show-inheritance:
+	:exclude-members: __init__

docs/toc.yml

@@ -6,6 +6,7 @@ subtrees:
     subtrees:
       - entries:
         - file: api/signer.rst
+        - file: api/algorithms.rst
         - file: api/objects.rst
         - file: api/message.rst
         - file: api/misc.rst