docs: Add module level dockstrings and change other

Refs: OPS-68

senju/store_manager.py

@@ -1,3 +1,47 @@
+"""
+Senju Database Management Module
+================================
+
+A database interaction layer for the Senju haiku management system.
+
+This module implements a lightweight document database abstraction using TinyDB
+for persistent storage of haiku poems. It provides a clean interface for storing,
+retrieving, updating, and managing haiku entries in the system.
+
+Classes
+-------
+StoreManager
+    The primary class responsible for all database operations. Handles connection
+    management, CRUD operations, and query capabilities for haiku data.
+
+Functions
+---------
+utility_function
+    Provides simple arithmetic operations to support database functionalities.
+
+Constants
+---------
+DEFAULT_DB_PATH
+    The default filesystem location for the TinyDB database file (/var/lib/senju.json).
+
+Dependencies
+------------
+* future.annotations: Enhanced type hint support
+* logging.Logger: Diagnostic and error logging capabilities
+* pathlib.Path: Cross-platform filesystem path handling
+* typing.Optional: Type annotations for nullable values
+* tinydb.TinyDB: Lightweight document database implementation
+* tinydb.QueryImpl: Query builder for database searches
+* senju.haiku.Haiku: Data model for haiku representation
+
+Implementation Details
+----------------------
+The module uses TinyDB as its storage engine, providing a JSON-based document
+storage solution that balances simplicity with functionality. The StoreManager
+abstracts all database operations behind a clean API, handling connection lifecycle
+and providing methods for common operations on haiku data.
+"""
+
 from __future__ import annotations
 
 from logging import Logger
@@ -20,6 +64,17 @@ def foobar():
 
 
 class StoreManager:
+    """
+    Manages the storage and retrieval of haiku data using TinyDB.
+
+    This class provides an interface for saving and loading haikus from
+    a TinyDB database file.
+
+    :ivar _db: Database instance for storing haiku data.
+    :type _db: TinyDB
+    :ivar logger: Logger for tracking operations and errors.
+    :type logger: Logger
+    """
     __slots__ = "_db", "logger"
     _db: TinyDB
     logger: Logger
@@ -28,9 +83,9 @@ class StoreManager:
         """
         Initialize the StoreManager with a database path.
 
-        Args:
-            path_to_db (Path, optional): Path to the TinyDB database file.
-                Defaults to DEFAULT_DB_PATH.
+        :param path_to_db: Path to the TinyDB database file. Defaults to DEFAULT_DB_PATH.
+        :type path_to_db: Path, optional
+        :return: None
         """
         self._db = TinyDB(path_to_db)
         self.logger = Logger(__name__)
@@ -39,29 +94,25 @@ class StoreManager:
         """
         Execute a query against the database.
 
-        Args:
-            query (QueryImpl): TinyDB query to execute.
-
-        Returns:
-            list[dict]: List of documents matching the query.
+        :param query: TinyDB query to execute.
+        :type query: QueryImpl
+        :return: List of documents matching the query.
+        :rtype: list[dict]
         """
-
         return self._db.search(query)
 
     def _load(self, id: int) -> Optional[dict]:
         """
         Load a document by its ID.
 
-        Args:
-            id (int): Document ID to load.
+        :param id: Document ID to load.
+        :type id: int
+        :return: The document if found, None otherwise.
+        :rtype: Optional[dict]
 
-        Returns:
-            Optional[dict]: The document if found, None otherwise.
-
-        Logs:
-            Warning if document with specified ID is not found.
+        .. note::
+           Logs a warning if document with specified ID is not found.
         """
-
         try:
             return self._db.get(doc_id=id)
         except IndexError as e:
@@ -72,26 +123,22 @@ class StoreManager:
         """
         Save a document to the database.
 
-        Args:
-            data (dict): Document data to save.
-
-        Returns:
-            int: The document ID of the saved document.
+        :param data: Document data to save.
+        :type data: dict
+        :return: The document ID of the saved document.
+        :rtype: int
         """
-
         return self._db.insert(data)
 
     def load_haiku(self, key: int) -> Optional[Haiku]:
         """
         Load a haiku by its ID.
 
-        Args:
-            key (int): The ID of the haiku to load.
-
-        Returns:
-            Optional[Haiku]: A Haiku object if found, None otherwise.
+        :param key: The ID of the haiku to load.
+        :type key: int
+        :return: A Haiku object if found, None otherwise.
+        :rtype: Optional[Haiku]
         """
-
         raw_haiku: dict | None = self._load(key)
         if raw_haiku is None:
             return None
@@ -102,26 +149,23 @@ class StoreManager:
         """
         Save a haiku to the database.
 
-        Args:
-            data (Haiku): The Haiku object to save.
-
-        Returns:
-            int: The document ID of the saved haiku.
+        :param data: The Haiku object to save.
+        :type data: Haiku
+        :return: The document ID of the saved haiku.
+        :rtype: int
         """
-
         return self._save(data.__dict__)
 
     def get_id_of_latest_haiku(self) -> Optional[int]:
         """
         Get the ID of the most recently added haiku.
 
-        Returns:
-            Optional[int]: The ID of the latest haiku if any exists, None otherwise.
+        :return: The ID of the latest haiku if any exists, None otherwise.
+        :rtype: Optional[int]
 
-        Logs:
-            Error if the database is empty.
+        .. note::
+           Logs an error if the database is empty.
         """
-
         try:
             id = self._db.all()[-1].doc_id
             return id