acacore - convert docstrings to reStructuredText format

acacore/database/column.py

@@ -258,20 +258,19 @@ def __init__(
         """
         A class that stores information regarding a table column.
 
-        Args:
-            name: The name of the column.
-            sql_type: The SQL type to use when creating a table.
-            to_entry: A function that returns a type supported by SQLite
-                (str, bytes, int, float, bool, datetime, or None).
-            from_entry: A function that takes a type returned by SQLite (str, bytes, int, float, or None)
-                and returns another object.
-            unique: True if the column should be set as UNIQUE.
-            primary_key: True if the column is a PRIMARY KEY.
-            not_null: True if the column is NOT NULL.
-            check: A string containing a CHECK expression, {name} substrings will be substituted
-                with the name of the column.
-            default: The column's DEFAULT value, which will be converted using `to_entry`.
-                Note that None is considered a valid default value; to set it to empty use Ellipsis (...).
+        :param name: The name of the column.
+        :param sql_type: The SQL type to use when creating a table.
+        :param to_entry: A function that returns a type supported by SQLite
+            (str, bytes, int, float, bool, datetime, or None).
+        :param from_entry: A function that takes a type returned by SQLite (str, bytes, int, float, or None) and
+            returns another object.
+        :param unique: True if the column should be set as UNIQUE, defaults to False.
+        :param primary_key: True if the column is a PRIMARY KEY, defaults to False.
+        :param not_null: True if the column is NOT NULL, defaults to False.
+        :param check: A string containing a CHECK expression, {name} substrings will be substituted with the name of
+            the column, defaults to None.
+        :param default: The column's DEFAULT value, which will be converted using `to_entry`.
+            Note that None is considered a valid default value; to set it to empty use Ellipsis (...), defaults to ....
         """
         self.name: str = name
         self.sql_type: str = sql_type
@@ -311,11 +310,8 @@ def default_value(self) -> V:
         """
         Get the default value of the column formatted as an SQL parameter.
 
-        Returns:
-            An object of the return type of the column's to_entry function.
-
-        Raises:
-            ValueError: If the column does not have a set default value.
+        :raises ValueError: If the column does not have a set default value.
+        :return: An object of the return type of the column's to_entry function.
         """
         if self.default is Ellipsis:
             raise ValueError("Column does not have a default value")
@@ -325,8 +321,7 @@ def create_statement(self) -> str:
         """
         Generate the statement that creates the column.
 
-        Returns:
-            A column statement for a CREATE TABLE expression.
+        :return: A column statement for a CREATE TABLE expression.
         """
         elements: list[str] = [self.name, self.sql_type]
         if self.unique:
@@ -351,12 +346,11 @@ def __init__(
         """
         A subclass of Column for SELECT expressions that need complex statements and/or an alias.
 
-        Args:
-            name: The name or select statement for the select expression (e.g., count(*)).
-            from_entry: A function that takes a type returned by SQLite (str, bytes, int, float, or None)
-                and returns another object.
-            alias: An alternative name for the select statement, it will be used with the AS keyword
-                and as a key by Cursor.
+        :param name: The name or select statement for the select expression (e.g., count(*)).
+        :param from_entry: A function that takes a type returned by SQLite (str, bytes, int, float, or None) and
+            returns another object.
+        :param alias: An alternative name for the select statement, it will be used with the AS keyword and as a key
+            by Cursor, defaults to None.
         """
         super().__init__(name, "", lambda x: x, from_entry)
         self.alias: str | None = alias
@@ -366,13 +360,10 @@ def from_column(cls, column: Column, alias: str | None = None) -> "SelectColumn"
         """
         Take a Column object and create a SelectColumn with the given alias.
 
-        Args:
-            column: The Column object to be converted.
-            alias: An alternative name for the select statement, it will be used with the AS keyword
-                and as a key by Cursor.
-
-        Returns:
-            SelectColumn: A SelectColumn object.
+        :param column: The Column object to be converted.
+        :param alias: An alternative name for the select statement, it will be used with the AS keyword and as a key
+            by Cursor, defaults to None.
+        :return: A SelectColumn object.
         """
         select_column = SelectColumn(column.name, column.from_entry, alias)
         select_column.sql_type = column.sql_type
@@ -393,10 +384,9 @@ def __init__(self, name: str, columns: Sequence[Column], unique: bool = False) -
         """
         A class that stores information regarding an index.
 
-        Args:
-            name: The name of the index
-            columns: The list of columns that the index applies to.
-            unique: Whether the index is unique or not.
+        :param name: The name of the index.
+        :param columns: The list of columns that the index applies to.
+        :param unique: Whether the index is unique or not, defaults to False.
         """
         self.name: str = name
         self.columns: list[Column] = list(columns)
@@ -415,12 +405,9 @@ def create_statement(self, table: str, exist_ok: bool = True):
         """
         Generate the expression that creates the index.
 
-        Args:
-            table: The name of the table.
-            exist_ok: True if existing tables with the same name should be ignored.
-
-        Returns:
-            A CREATE TABLE expression.
+        :param table: The name of the table.
+        :param exist_ok: True if existing tables with the same name should be ignored, defaults to True.
+        :return: A CREATE TABLE expression.
         """
         return (
             f"create {'unique' if self.unique else ''} index {'if not exists' if exist_ok else ''} {self.name}"

acacore/database/files_db.py

@@ -23,16 +23,12 @@ class HistoryEntryPath(HistoryEntry):
 
 
 class SignatureCount(ACABase):
-    """Signature count datamodel."""
-
     puid: str | None
     signature: str | None
     count: int | None
 
 
 class ChecksumCount(ACABase):
-    """Signature count datamodel."""
-
     checksum: str
     count: int
 
@@ -58,21 +54,21 @@ def __init__(
         """
         A class that handles the SQLite database used by AArhus City Archives to process data archives.
 
-        Args:
-            database: The path or URI to the database.
-            timeout: How many seconds the connection should wait before raising an OperationalError
-                when a table is locked.
-            detect_types: Control whether and how data types not natively supported by SQLite are looked up to be
-                converted to Python types.
-            isolation_level: The isolation_level of the connection, controlling whether
-                and how transactions are implicitly opened.
-            check_same_thread: If True (default), ProgrammingError will be raised if the database connection
-                is used by a thread other than the one that created it.
-            factory: A custom subclass of Connection to create the connection with,
-                if not the default Connection class.
-            cached_statements: The number of statements that sqlite3 should internally cache for this connection,
-                to avoid parsing overhead.
-            uri: If set to True, database is interpreted as a URI with a file path and an optional query string.
+        :param database: The path or URI to the database.
+        :param timeout: How many seconds the connection should wait before raising an OperationalError when a table
+            is locked, defaults to 5.0.
+        :param detect_types: Control whether and how data types not natively supported by SQLite are looked up to be
+            converted to Python types, defaults to 0.
+        :param isolation_level: The isolation_level of the connection, controlling whether and how transactions are
+            implicitly opened, defaults to "DEFERRED".
+        :param check_same_thread: If True (default), ProgrammingError will be raised if the database connection is
+            used by a thread other than the one that created it, defaults to True.
+        :param factory: A custom subclass of Connection to create the connection with, if not the default Connection
+            class, defaults to Connection.
+        :param cached_statements: The number of statements that sqlite3 should internally cache for this connection,
+            to avoid parsing overhead, defaults to 100.
+        :param uri: If set to True, database is interpreted as a URI with a file path and an optional query string,
+            defaults to False.
         """
         super().__init__(
             database,
@@ -204,7 +200,6 @@ def __init__(
         )
 
     def init(self):
-        """Create the default tables and views."""
         self.files.create(True)
         self.history.create(True)
         self.metadata.create(True)

acacore/exceptions/base.py

@@ -1,2 +1,2 @@
 class ACAException(Exception):
-    pass
+    """Base class for acacore exceptions."""

acacore/models/base.py

@@ -5,10 +5,9 @@
 
 
 class ACABase(BaseModel):
-    """Base model with reusable methods & settings."""
-
     def dump(self, to_file: Path) -> None:
         to_file.write_text(super().model_dump_json(), encoding="utf-8")
 
     def encode(self) -> Any:  # noqa: ANN401
+        """Encode function."""
         return super().model_dump(mode="json")

acacore/models/file.py

@@ -60,19 +60,18 @@ class File(ACABase):
     """
     File model containing all information used by the rest of the archival suite of tools.
 
-    Attributes:
-        uuid (UUID4): The UUID of the file.
-        checksum (str): The checksum of the file.
-        puid (str | None): The PUID (PRONOM Unique Identifier) of the file.
-        relative_path (Path): The relative path to the file.
-        is_binary (bool): Indicates whether the file is binary.
-        size (int): The size of the file.
-        signature (str | None): The signature of the file.
-        warning (str | None): Any warning associated with the file PUID.
-        action (str | None): The name of the main action for the file's PUID, if one exists.
-        action_data (ActionData | None): The data for the action for the file's PUID, if one exists.
-        processed (bool): True if the file has been processed, false otherwise.
-        root (Path | None): The root directory for the file.
+    :ivar uuid: The UUID of the file.
+    :ivar checksum: The checksum of the file.
+    :ivar puid: The PUID (PRONOM Unique Identifier) of the file.
+    :ivar relative_path: The relative path to the file.
+    :ivar is_binary: Indicates whether the file is binary.
+    :ivar size: The size of the file.
+    :ivar signature: The signature of the file.
+    :ivar warning: Any warning associated with the file PUID.
+    :ivar action: The name of the main action for the file's PUID, if one exists.
+    :ivar action_data: The data for the action for the file's PUID, if one exists.
+    :ivar processed: True if the file has been processed, false otherwise.
+    :ivar root: The root directory for the file.
     """
 
     uuid: UUID4 = DBField(default_factory=uuid4, index=["idx_uuid"])
@@ -109,17 +108,14 @@ def from_file(
 
         Given a list of CustomSignatures, the file identification will be refined.
 
-        Args:
-            path: The path to the file.
-            root: Optionally, the root to be used to compute the relative path to the file.
-            siegfried: A Siegfried class object to identify the file.
-            actions: A dictionary with PUID keys and Action values to assign an action.
-            custom_signatures: A list of CustomSignature objects to refine the identification.
-            uuid: Optionally, a specific UUID to use for the file.
-            processed: Optionally, the value to be used for the processed property.
-
-        Returns:
-            File: A File object.
+        :param path: The path to the file.
+        :param root: Optionally, the root to be used to compute the relative path to the file, defaults to None.
+        :param siegfried: A Siegfried class object to identify the file, defaults to None.
+        :param actions: A dictionary with PUID keys and Action values to assign an action, defaults to None.
+        :param custom_signatures: A list of CustomSignature objects to refine the identification, defaults to None.
+        :param uuid: Optionally, a specific UUID to use for the file, defaults to None.
+        :param processed: Optionally, the value to be used for the processed property, defaults to False.
+        :return: A File object.
         """
         file = cls(
             uuid=uuid or uuid4(),
@@ -175,12 +171,9 @@ def identify(self, sf: Siegfried, *, set_match: bool = False) -> SiegfriedFile:
         """
         Identify the file using `siegfried`.
 
-        Args:
-            sf (Siegfried): A Siegfried class object
-            set_match (bool): Set results of Siegfried match if True
-
-        Returns:
-            SiegfriedFile: A dataclass object containing the results from the identification
+        :param sf: A Siegfried class object.
+        :param set_match: Set results of Siegfried match if True, defaults to False.
+        :return: A dataclass object containing the results from the identification.
         """
         result = sf.identify(self.get_absolute_path(self.root)).files[0]
         match = result.best_match()
@@ -199,12 +192,11 @@ def identify_custom(
         """
         Uses the BOF and EOF to try to determine a ACAUID for the file.
 
-        The custom_sigs list should be found on the `reference_files` repo.
-        If no match can be found, the method does nothing.
+        The custom_sigs list should be found on the `reference_files` repo. If no match can be found, the method does
+        nothing.
 
-        Args:
-            custom_signatures: A list of the custom_signatures that the file should be checked against
-            set_match (bool): Set results of match if True
+        :param custom_signatures: A list of the custom_signatures that the file should be checked against.
+        :param set_match: Set results of match if True, defaults to False.
         """
         bof = get_bof(self.get_absolute_path(self.root)).hex()
         eof = get_eof(self.get_absolute_path(self.root)).hex()
@@ -282,8 +274,7 @@ def name(self) -> str:
         """
         Get file name.
 
-        Returns:
-            str: File name.
+        :return: File name.
         """
         return self.relative_path.name
 
@@ -296,8 +287,7 @@ def suffix(self) -> str:
         """
         Get file suffix.
 
-        Returns:
-            str: File extension.
+        :return: File extension.
         """
         return self.relative_path.suffix.lower()
 

acacore/models/history.py

@@ -32,18 +32,15 @@ def command_history(
         """
         Create a HistoryEntry for a command.
 
-        Args:
-            ctx: The context object representing the current command execution.
-            operation: The name of the operation for which the command history entry is being created.
-            uuid: Optional. The UUID associated with the command history entry. Default is None.
-            data: Optional. Additional data or parameters associated with the command history entry.
-                It defaults to the params property of the context, if it is a click.Context object, otherwise None.
-            reason: Optional. The reason for the command execution. Default is None.
-            time: Optional. The timestamp of the command execution. Default is None.
-            add_params_to_data: If true, add context parameters to data
-
-        Returns:
-            HistoryEntry: A `HistoryEntry` instance representing the command history entry.
+        :param ctx: The context object representing the current command execution.
+        :param operation: The name of the operation for which the command history entry is being created.
+        :param uuid: Optional. The UUID associated with the command history entry, defaults to None.
+        :param data: Optional. Additional data or parameters associated with the command history entry.
+            It Context object, otherwise None, defaults to None.
+        :param reason: Optional. The reason for the command execution, defaults to None.
+        :param time: Optional. The timestamp of the command execution, defaults to None.
+        :param add_params_to_data: If true, add context parameters to data, defaults to False.
+        :return: A `HistoryEntry` instance representing the command history entry.
         """
         command: str
         current: Context = ctx

acacore/models/identification.py

@@ -6,8 +6,6 @@
 
 
 class Identification(ACABase):
-    """File identification datamodel."""
-
     puid: str | None
     signature: str | None
     warning: str | None
@@ -17,7 +15,6 @@ class Identification(ACABase):
     @model_validator(mode="before")
     @classmethod
     def check_puid_sig(cls, data: dict[Any, Any]) -> dict[Any, Any]:
-        """Validate that a PUID cannot have an empty signature or vice versa."""
         puid, signature = data.get("puid"), data.get("signature")
 
         if puid is not None and signature is None: