Updated documentation; fix dependency

- Improved documentation
- Added missing python-dateutil dependency

Author: pcisar

docs/ref-config.txt

@@ -5,8 +5,14 @@
 firebird.driver.config
 ======================
 
-This module contains firebird-driver configuration. Uses configuration classes from firebird-base
-package.
+This module defines the configuration system for the firebird-driver.
+It uses an INI-style format managed via the `DriverConfig` class, which
+allows defining settings for the driver itself, default server/database
+parameters, and named configurations for specific servers and databases.
+
+Configuration can be loaded from files, strings, or dictionaries, and
+supports environment variable interpolation. The primary interaction point
+is usually the global `driver_config` instance.
 
 Classes
 =======

pyproject.toml

@@ -28,8 +28,9 @@ classifiers = [
   "Topic :: Database",
 ]
 dependencies = [
-  #"firebird-base @file:////home/job/python/projects/firebird-base",
-  "firebird-base~=2.0",
+  "firebird-base @file:////home/job/python/projects/firebird-base",
+  #"firebird-base~=2.0",
+  "python-dateutil~=2.8",
 ]
 
 [project.urls]

src/firebird/driver/config.py

@@ -35,7 +35,14 @@
 
 """firebird-driver - Driver configuration
 
+This module defines the configuration system for the firebird-driver.
+It uses an INI-style format managed via the `DriverConfig` class, which
+allows defining settings for the driver itself, default server/database
+parameters, and named configurations for specific servers and databases.
 
+Configuration can be loaded from files, strings, or dictionaries, and
+supports environment variable interpolation. The primary interaction point
+is usually the global `driver_config` instance.
 """
 
 from __future__ import annotations
@@ -46,7 +53,7 @@
 from .types import NetProtocol, DecfloatRound, DecfloatTraps
 
 class ServerConfig(Config): # pylint: disable=R0902
-    """Server configuration.
+    """Represents configuration options specific to a named Firebird server entry.
     """
     def __init__(self, name: str, *, optional: bool=False, description: str=None):
         super().__init__(name, optional=optional, description=description)
@@ -81,7 +88,7 @@ def __init__(self, name: str, *, optional: bool=False, description: str=None):
             StrOption('encoding_errors', "Handler used for encoding errors", default='strict')
 
 class DatabaseConfig(Config): # pylint: disable=R0902
-    """Database configuration.
+    """Represents configuration options specific to a named Firebird database entry, including connection and creation parameters.
     """
     def __init__(self, name: str, *, optional: bool=False, description: str=None):
         super().__init__(name, optional=optional, description=description)
@@ -94,12 +101,12 @@ def __init__(self, name: str, *, optional: bool=False, description: str=None):
         #: Database file specification or alias
         self.database: StrOption = \
             StrOption('database', "Database file specification or alias")
-        #: Database filename should be passed in UTF8
+        #: Specifies whether the database parameter (filename) is encoded in UTF-8 when passed to the server.
         self.utf8filename: BoolOption = \
-            BoolOption('utf8filename', "Database filename should be passed in UTF8")
-        #: Protocol to be used for databasem value is `.NetProtocol`
+            BoolOption('utf8filename', "Specifies whether the database parameter (filename) is encoded in UTF-8 when passed to the server.")
+        #: Network protocol to use for the connection. Value must be a member of the .NetProtocol enum.
         self.protocol: EnumOption = \
-            EnumOption('protocol', NetProtocol, "Protocol to be used for database")
+            EnumOption('protocol', NetProtocol, "Network protocol to use for the connection. Value must be a member of the .NetProtocol enum.")
         #: Defaul user name, default is envar ISC_USER or None if not specified
         self.user: StrOption = \
             StrOption('user', "Defaul user name", default=os.environ.get('ISC_USER', None))
@@ -147,14 +154,15 @@ def __init__(self, name: str, *, optional: bool=False, description: str=None):
         #: Set DECFLOAT ROUND [Firebird 4], value is `.DecfloatRound`
         self.decfloat_round: EnumOption = \
             EnumOption('decfloat_round', DecfloatRound, "DECFLOAT round mode")
-        #: Set DECFLOAT TRAPS [Firebird 4], values are `.DecfloatTraps`
+        #: Specifies which DECFLOAT exceptional conditions should cause a trap (raise an error) [Firebird 4]. Accepts a list of .DecfloatTraps enum members.
         self.decfloat_traps: ListOption = \
             ListOption('decfloat_traps', DecfloatTraps,
-                       "Which DECFLOAT exceptional conditions cause a trap")
+                       """Specifies which DECFLOAT exceptional conditions should cause a trap
+(raise an error) [Firebird 4]. Accepts a list of .DecfloatTraps enum members.""")
         #: Number of parallel workers
         self.parallel_workers = \
             IntOption('parallel_workers', "Number of parallel workers")
-        # Create options
+        # --- Options specific to Database Creation ---
         #: Database create option. Page size to be used.
         self.page_size: IntOption = \
             IntOption('page_size', "Page size to be used for created database.")
@@ -179,7 +187,12 @@ def __init__(self, name: str, *, optional: bool=False, description: str=None):
                        "Data page space usage for created database (True = reserve space, False = Use all space)")
 
 class DriverConfig(Config):
-    """Firebird driver configuration.
+    """Main configuration object for the Firebird driver. Holds global settings, default
+    configurations, and lists of registered servers and databases.
+
+    Settings loaded from specific server/database sections override those in the `db_defaults`
+    and `server_defaults` sections. When reading multiple files, options from later files
+    override those from earlier ones.
     """
     def __init__(self, name: str):
         super().__init__(name)
@@ -310,4 +323,7 @@ def register_database(self, name: str, config: str=None) -> DatabaseConfig:
 
 # Configuration
 
+#: Global driver configuration instance.
+#: Load settings from files/strings/dicts into this object before connecting,
+#: or modify its attributes directly for programmatic configuration.
 driver_config: DriverConfig = DriverConfig('firebird.driver')

src/firebird/driver/core.py

@@ -34,7 +34,11 @@
 #                 ______________________________________
 # pylint: disable=C0302, W0212, R0902, R0912,R0913, R0914, R0915, R0904
 
-"""firebird-driver - Main driver code (connection, transaction, cursor etc.)
+"""firebird-driver - Main driver code
+
+This module implements the core components of the firebird-driver, including the DB-API 2.0
+compliant Connection, Cursor, and Transaction objects, as well as helper classes for managing
+events, BLOBs, parameter buffers, and accessing database/server information.
 """
 
 from __future__ import annotations
@@ -296,7 +300,7 @@ def temp_database(*args, **kwargs) -> Connection:
 
 # Managers for Parameter buffers
 class TPB: # pylint: disable=R0902
-    """Transaction Parameter Buffer.
+    """Helper class to build and parse Transaction Parameter Buffers (TPB) used when starting transactions.
     """
     def __init__(self, *, access_mode: TraAccessMode=TraAccessMode.WRITE,
                  isolation: Isolation=Isolation.SNAPSHOT,
@@ -412,7 +416,7 @@ def reserve_table(self, name: str, share_mode: TableShareMode, access_mode: Tabl
         self._table_reservation.append((name, share_mode, access_mode))
 
 class DPB:
-    """Database Parameter Buffer.
+    """Helper class to build and parse Database Parameter Buffers (DPB) used when connecting databases.
     """
     def __init__(self, *, user: str=None, password: str=None, role: str=None,
                  trusted_auth: bool=False, sql_dialect: int=3, timeout: int=None,
@@ -684,7 +688,8 @@ def get_buffer(self, *, for_create: bool = False) -> bytes:
         return result
 
 class SPB_ATTACH:
-    """Service Parameter Buffer.
+    """Helper class to build and parse Service Parameter Buffers (SPB) used when connecting
+    to service manager.
     """
     def __init__(self, *, user: str = None, password: str = None, trusted_auth: bool = False,
                  config: str = None, auth_plugin_list: str = None, expected_db: str=None,
@@ -1106,6 +1111,9 @@ def get_engine_version(self, con: Connection | Server) -> float:
 class DatabaseInfoProvider3(InfoProvider):
     """Provides access to information about attached database [Firebird 3+].
 
+    Information can be accessed either via specific properties (preferred) or the lower-level
+    `get_info()` method.
+
     Important:
        Do NOT create instances of this class directly! Use `Connection.info` property to
        access the instance already bound to attached database.
@@ -1316,6 +1324,13 @@ def get_info(self, info_code: DbInfoCode, page_number: int=None) -> Any:
 
         Returns:
             The data type of returned value depends on information required.
+
+        Note:
+            Info codes that return stable values are cached on first call, so subsequent calls do not
+            access the server. These codes are: `CREATION_DATE`, `DB_CLASS`, `DB_PROVIDER`,
+            `DB_SQL_DIALECT`, `ODS_MINOR_VERSION`, `ODS_VERSION`, `PAGE_SIZE`, `VERSION`,
+            `FIREBIRD_VERSION`, `IMPLEMENTATION_OLD`, `IMPLEMENTATION`, `DB_ID`, `BASE_LEVEL`,
+            and `ATTACHMENT_ID`.
         """
         if info_code in self._cache:
             return self._cache[info_code]
@@ -1589,6 +1604,9 @@ def engine_version(self) -> float:
 class DatabaseInfoProvider(DatabaseInfoProvider3):
     """Provides access to information about attached database [Firebird 4+].
 
+    Information can be accessed either via specific properties (preferred) or the lower-level
+    `get_info()` method.
+
     Important:
        Do NOT create instances of this class directly! Use `Connection.info` property to
        access the instance already bound to attached database.
@@ -1754,6 +1772,7 @@ def _prepare(self, sql: str, tra: TransactionManager) -> Statement:
             tra.commit()
         return result
     def _determine_field_precision(self, meta: ItemMetadata) -> int:
+        # This internal method involve database queries using _tra_qry.
         if (not meta.relation) or (not meta.field):
             # Either or both field name and relation name are not provided,
             # so we cannot determine field precision. It's normal situation
@@ -1796,6 +1815,7 @@ def _determine_field_precision(self, meta: ItemMetadata) -> int:
         # We ran out of options
         return 0
     def _get_array_sqlsubtype(self, relation: bytes, column: bytes) -> int | None:
+        # This internal method involve database query using _tra_qry.
         subtype = self.__sqlsubtype_cache.get((relation, column))
         if subtype is not None:
             return subtype
@@ -1820,6 +1840,9 @@ def drop_database(self) -> None:
             Closes all event collectors, transaction managers (with rollback) and statements
             associated with this connection before attempt to drop the database.
 
+        Important:
+            The connection object becomes unusable after this call.
+
         Hooks:
             Event `.ConnectionHook.DROPPED`: Executed after database is sucessfuly dropped.
             Hook must have signature::
@@ -2021,7 +2044,7 @@ def transactions(self) -> list[TransactionManager]:
         return result
     @property
     def schema(self) -> 'firebird.lib.schema.Schema':
-        """Access to database schema. Requires firebird.lib package.
+        """Access to database schema. Requires `firebird.lib` package.
         """
         if self.__schema is None:
             import firebird.lib.schema # pylint: disable=C0415
@@ -2031,7 +2054,7 @@ def schema(self) -> 'firebird.lib.schema.Schema':
         return self.__schema
     @property
     def monitor(self) -> 'firebird.lib.monitor.Monitor':
-        """Access to database monitoring tables. Requires firebird.lib package.
+        """Access to database monitoring tables. Requires `firebird.lib` package.
         """
         if self.__monitor is None:
             import firebird.lib.monitor # pylint: disable=C0415
@@ -2283,6 +2306,9 @@ def create_database(database: str | Path, *, user: str=None, password: str=None,
 class TransactionInfoProvider3(InfoProvider):
     """Provides access to information about transaction [Firebird 3+].
 
+    Information can be accessed either via specific properties (preferred) or the lower-level
+    `get_info()` method.
+
     Important:
        Do NOT create instances of this class directly! Use `TransactionManager.info`
        property to access the instance already bound to transaction context.
@@ -2392,6 +2418,9 @@ def snapshot_number(self) -> int:
 class TransactionInfoProvider(TransactionInfoProvider3):
     """Provides access to information about transaction [Firebird 4+].
 
+    Information can be accessed either via specific properties (preferred) or the lower-level
+    `get_info()` method.
+
     Important:
        Do NOT create instances of this class directly! Use `TransactionManager.info`
        property to access the instance already bound to transaction context.
@@ -2467,6 +2496,8 @@ def _get_handle(self) -> a.FB_API_HANDLE:
     def close(self) -> None:
         """Close the transaction manager and release all associated resources.
 
+        Implicitly ends the current active transaction according to default_action (if active).
+
         Important:
             Closed instance SHALL NOT be used anymore.
         """
@@ -3015,7 +3046,8 @@ def read(self, size: int=-1) -> str | bytes:
         Like `file.read()`.
 
         Note:
-           Performs automatic conversion to `str` for TEXT BLOBs.
+           Performs automatic conversion to `str` for TEXT BLOBs (subtype 1) based on the
+           connection's encoding.
         """
         assert self._blob is not None
         if size >= 0:
@@ -3195,6 +3227,7 @@ def __init__(self, connection: Connection, transaction: TransactionManager): # p
         #: Names of columns that should be returned as `BlobReader`.
         self.stream_blobs: list[str] = []
         #: BLOBs greater than threshold are returned as `BlobReader` instead in materialized form.
+        #: Defaults to the value from `driver_config`.
         self.stream_blob_threshold = driver_config.stream_blob_threshold.value
     def __enter__(self) -> Cursor:
         return self
@@ -3930,7 +3963,7 @@ def executemany(self, operation: str | Statement,
         Note:
             This function simply calls `.execute` in a loop, feeding it with
             parameters from `seq_of_parameters`. Because `.execute` reuses the statement,
-            calling `executemany` is equally efective as direct use of prepared `Statement`
+            calling `executemany` is equally effective as direct use of prepared `Statement`
             and calling `execute` in a loop directly in application.
         """
         for parameters in seq_of_parameters:
@@ -4075,7 +4108,7 @@ def to_dict(self, row: tuple, into: dict=None) -> dict:
 
         Arguments:
             row:  Row data returned by fetch_* method.
-            into: Dictionary that shouold be updated with row data.
+            into: Dictionary that should be updated with row data.
         """
         assert len(self._stmt._names) == len(row), "Length of data must match number of fields"
         if into is None:
@@ -4216,6 +4249,9 @@ def name(self) -> str:
 class ServerInfoProvider(InfoProvider):
     """Provides access to information about attached server.
 
+    Information can be accessed either via specific properties (preferred) or the lower-level
+    `get_info()` method.
+
     Important:
        Do NOT create instances of this class directly! Use `Server.info` property to access
        the instance already bound to connectected server.
@@ -5458,7 +5494,7 @@ def __init__(self, svc: iService, spb: bytes, host: str, encoding: str,
         self.host: str = host
         #: Service output mode (line or eof)
         self.mode: SrvInfoCode = SrvInfoCode.TO_EOF
-        #: Response buffer used to comunicate with service
+        #: Response buffer used to communicate with service
         self.response: CBuffer = CBuffer(USHRT_MAX)
         self._eof: bool = False
         self.__line_buffer: list[str] = []

src/firebird/driver/hooks.py

@@ -33,28 +33,44 @@
 # Contributor(s): Pavel Císař (original code)
 #                 ______________________________________
 
-"""firebird-driver - Drivers hooks
+"""firebird-driver - Driver Hooks
+
+This module defines specific hook points (events) within the firebird-driver
+lifecycle where custom functions can be registered and executed. These hooks
+allow for extending or modifying driver behavior, logging, or monitoring.
+
+Hooks are registered using `firebird.driver.add_hook()` or the `firebird.base.hooks.hook_manager`.
+The specific signature required for each hook function and the context in which
+it's called are documented within the driver methods that trigger these hooks
+(primarily in `firebird.driver.core`).
 """
 
 from __future__ import annotations
 from enum import Enum, auto
 from firebird.base.hooks import register_class, get_callbacks, add_hook, hook_manager
 
 class APIHook(Enum):
-    """Firebird API hooks.
+    """Hooks related to the loading and initialization of the underlying Firebird client API.
     """
+    #: Called after the Firebird client library has been successfully loaded and basic interfaces obtained.
     LOADED = auto()
 
 class ConnectionHook(Enum):
-    """Connection hooks.
+    """Hooks related to the lifecycle of a database connection (attachment, detachment, dropping).
     """
+    #: Called before attempting to attach to a database, allows interception or modification.
     ATTACH_REQUEST = auto()
+    #: Called after a database connection (attachment) has been successfully established.
     ATTACHED = auto()
+    #: Called before attempting to detach from a database, allows cancellation.
     DETACH_REQUEST = auto()
+    #: Called after a database connection has been successfully closed (detached).
     CLOSED = auto()
+    #: Called after a database has been successfully dropped.
     DROPPED = auto()
 
 class ServerHook(Enum):
-    """Server hooks.
+    """Hooks related to the lifecycle of a service manager connection.
     """
+    #: Called after connecting to the Firebird service manager.
     ATTACHED = auto()