siegfried - add docstrings to models, improve Siegfried docstring

acacore/siegfried/siegfried.py

@@ -37,11 +37,35 @@ def _check_process(process: CompletedProcess) -> CompletedProcess:
 
 
 class SiegfriedIdentifier(BaseModel):
+    """
+    A class representing an identifiers used by the Siegfried identification tool.
+
+    Attributes:
+        name (str): The name of the Siegfried identifier.
+        details (str): Additional details or description of the identifier.
+    """
+
     name: str
     details: str
 
 
 class SiegfriedMatch(BaseModel):
+    """
+    A class representing a match generated by the Siegfried identification tool.
+
+    Attributes:
+        ns (str): The namespace of the match.
+        id (str, optional): The identifier of the match.
+        format (str): The format of the match.
+        version (str, optional): The version of the match.
+        mime (str): The MIME type of the match.
+        match_class (str, optional): The class of the match.
+        basis (list[str]): The basis of the match.
+        warning (list[str]): The warning messages of the match.
+        URI (AnyUrl, optional): The URI of the match.
+        permalink (HttpUrl, optional): The permalink of the match.
+    """
+
     ns: str
     id: Optional[str]
     format: str
@@ -126,6 +150,19 @@ def unknown_id(cls, data: dict | object):
 
 
 class SiegfriedFile(BaseModel):
+    """
+    The SiegfriedFile class represents a file that has been analyzed by Siegfried.
+    It contains information about the file's name, size, modification date, matching results, and any
+    errors encountered during analysis.
+
+    Attributes:
+        filename (str): The name of the file.
+        filesize (int): The size of the file in bytes.
+        modified (datetime): The modification date of the file.
+        errors (str): Any errors encountered during analysis.
+        matches (list[SiegfriedMatch]): The list of matches found for the file.
+    """
+
     filename: str
     filesize: int
     modified: datetime
@@ -154,6 +191,18 @@ def best_matches(self) -> list[SiegfriedMatch]:
 
 
 class SiegfriedResult(BaseModel):
+    """
+    Represents the result of a Siegfried signature scan.
+
+    Attributes:
+        siegfried (str): The version of Siegfried used for the scan.
+        scandate (datetime): The date and time when the scan was performed.
+        signature (str): The digital signature used for the scan.
+        created (datetime): The date and time when the signature file was created.
+        identifiers (List[SiegfriedIdentifier]): A list of identifiers used for file identification.
+        files (List[SiegfriedFile]): A list of files that were scanned.
+    """
+
     siegfried: str
     scandate: datetime
     signature: str
@@ -165,17 +214,23 @@ class SiegfriedResult(BaseModel):
 
 class Siegfried:
     """
-    A wrapper class to use the Siegfried program with Python and return the results with Pydantic models.
+    A class for interacting with the Siegfried file identification tool.
+
+    Attributes:
+        binary (str): The path to the Siegfried binary or the program name if it is included in the PATH variable.
+        signature (str): The signature file to use with Siegfried.
 
     See Also:
         https://github.com/richardlehane/siegfried
     """
 
     def __init__(self, binary: Union[str, PathLike] = "sf", signature: str = "default.sig"):
         """
+        Initializes a new instance of the Siegfried class.
+
         Args:
-            binary: The path to the Siegfried binary, or the program name if it is included in the PATH variable.
-            signature: The signature file to use with Siegfried.
+            binary: The path or name of the Siegfried binary. Defaults to "sf".
+            signature: The name of the signature file to use. Defaults to "default.sig".
         """
         self.binary: str = str(binary)
         self.signature: str = signature