iker-python-common 1.0.44__tar.gz → 1.0.45__tar.gz

{iker_python_common-1.0.44 → iker_python_common-1.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iker-python-common
-Version: 1.0.44
+Version: 1.0.45
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12

{iker_python_common-1.0.44 → iker_python_common-1.0.45}/src/iker/common/utils/argutils.py

@@ -19,6 +19,14 @@ import sys
 
 
 class ParserTreeNode(object):
+    """
+    Represents a node in the parser tree, holding a command, its parser, and any child nodes. Each node may have
+    subparsers and a list of child nodes representing subcommands.
+
+    :param command: The command string for this node.
+    :param parser: The ``ArgumentParser`` associated with this node.
+    """
+
     def __init__(self, command: str, parser: argparse.ArgumentParser):
         self.command = command
         self.parser = parser
@@ -32,6 +40,16 @@ def construct_parser_tree(
     command_key_prefix: str,
     **kwargs,
 ) -> list[ParserTreeNode]:
+    """
+    Constructs a parser tree by traversing or creating nodes for each command in the command chain. Returns the path
+    from the ``root_node`` to the last node in the chain.
+
+    :param root_node: The root node of the parser tree.
+    :param command_chain: A list of command strings representing the path.
+    :param command_key_prefix: Prefix for command keys in the parser.
+    :param kwargs: Additional keyword arguments for parser creation.
+    :return: A list of ``ParserTreeNode`` objects representing the path from root to the last command.
+    """
     node_path = [root_node]
     if len(command_chain) == 0:
         return node_path
@@ -58,16 +76,37 @@ def construct_parser_tree(
 
 
 class ParserTree(object):
+    """
+    Represents a tree structure for managing ``argparse`` parsers and subcommands. Provides methods to add subcommand
+    parsers and parse arguments, returning the command chain and parsed namespace.
+
+    :param root_parser: The root ``ArgumentParser``.
+    :param command_key_prefix: Prefix for command keys in the parser tree.
+    """
+
     def __init__(self, root_parser: argparse.ArgumentParser, command_key_prefix: str = "command"):
         self.root_node = ParserTreeNode("", root_parser)
         self.command_key_prefix = command_key_prefix
 
     def add_subcommand_parser(self, command_chain: list[str], **kwargs) -> argparse.ArgumentParser:
+        """
+        Adds a subcommand parser for the specified command chain, creating intermediate nodes as needed.
+
+        :param command_chain: A list of command strings representing the subcommand path.
+        :param kwargs: Additional keyword arguments for parser creation.
+        :return: The ``ArgumentParser`` for the last command in the chain.
+        """
         *_, last_node = construct_parser_tree(self.root_node, command_chain, self.command_key_prefix, **kwargs)
         return last_node.parser
 
     def parse_args(self, args: list[str] | None = None) -> tuple[list[str], argparse.Namespace]:
-        # Before Python 3.12 the `exit_on_error` attribute does not take effect properly
+        """
+        Parses the provided argument list, returning the command chain and the parsed namespace.
+
+        :param args: The list of arguments to parse. If ``None``, parses ``sys.argv``.
+        :return: A tuple containing the list of command strings and the parsed ``Namespace``.
+        """
+        # Before Python 3.12 the ``exit_on_error`` attribute does not take effect properly
         # if unknown arguments encountered. We have to employ this workaround
         if sys.version_info < (3, 12):
             if self.root_node.parser.exit_on_error:
@@ -92,6 +131,19 @@ class ParserTree(object):
 
 @dataclasses.dataclass(frozen=True)
 class ArgParseSpec(object):
+    """
+    Specification for an argument to be added to an ``ArgumentParser``. Allows detailed configuration of argument
+    properties such as ``flag``, ``name``, ``type``, ``action``, ``default``, ``choices``, and help text.
+
+    :param flag: The optional flag for the argument (e.g., '-f').
+    :param name: The name of the argument (e.g., '--file').
+    :param action: The action to be taken by the argument parser.
+    :param default: The default value for the argument.
+    :param type: The type of the argument value.
+    :param choices: A list of valid choices for the argument.
+    :param required: Whether the argument is required.
+    :param help: The help text for the argument.
+    """
     flag: str | None = None
     name: str | None = None
     action: str | None = None
@@ -102,6 +154,12 @@ class ArgParseSpec(object):
     help: str | None = None
 
     def make_kwargs(self) -> dict[str, Any]:
+        """
+        Constructs a dictionary of keyword arguments for ``ArgumentParser.add_argument``, omitting any that are
+        ``None``.
+
+        :return: A dictionary of argument properties suitable for ``ArgumentParser.add_argument``.
+        """
         kwargs = dict(
             action=self.action,
             default=self.default,
@@ -118,6 +176,14 @@ argparse_spec = ArgParseSpec
 
 
 def make_argparse(func, parser: argparse.ArgumentParser = None) -> argparse.ArgumentParser:
+    """
+    Automatically generates an ``ArgumentParser`` for the given function by inspecting its signature and parameter
+    annotations. Supports ``ArgParseSpec`` for detailed argument configuration.
+
+    :param func: The function whose parameters will be used to generate arguments.
+    :param parser: An optional ``ArgumentParser`` to add arguments to. If ``None``, a new parser is created.
+    :return: The ``ArgumentParser`` with arguments added based on the function signature.
+    """
     if parser is None:
         parser = argparse.ArgumentParser()
 

{iker_python_common-1.0.44 → iker_python_common-1.0.45}/src/iker/common/utils/csv.py

@@ -11,6 +11,16 @@ __all__ = [
 
 
 class CSVColumn(object):
+    """
+    Represents a column in a CSV schema, including its name, loader function, dumper function, and the string used for
+    null values.
+
+    :param name: The name of the column.
+    :param loader: A function to convert a string to the column's value type.
+    :param dumper: A function to convert the column's value to a string.
+    :param null_str: The string representation of a null value in this column.
+    """
+
     def __init__(
         self,
         name: str,
@@ -25,6 +35,15 @@ class CSVColumn(object):
 
 
 class CSVView(object):
+    """
+    Represents a view for reading and writing CSV data according to a schema. Supports loading and dumping lines or
+    files, with options for headers and dictionary or list output.
+
+    :param schema: The sequence of ``CSVColumn`` objects defining the schema.
+    :param row_delim: The delimiter for rows (default is ``'\n'``).
+    :param col_delim: The delimiter for columns (default is ``','``).
+    """
+
     def __init__(self, schema: Sequence[CSVColumn], *, row_delim: str = "\n", col_delim: str = ","):
         self.schema = schema
         self.row_delim = row_delim
@@ -36,6 +55,15 @@ class CSVView(object):
         has_header: bool = True,
         ret_dict: bool = False,
     ) -> Generator[list[Any] | dict[str, Any], None, None]:
+        """
+        Loads CSV data from an iterable of lines, optionally using the first line as a header. Returns each row as a
+        list or dictionary, depending on ``ret_dict``.
+
+        :param lines: An iterable of CSV lines.
+        :param has_header: Whether the first line is a header.
+        :param ret_dict: Whether to return rows as dictionaries (``True``) or lists (``False``).
+        :return: A generator yielding each row as a list or dictionary.
+        """
         rows_iter = iter(lines)
         if has_header:
             header_row = next(rows_iter)
@@ -59,6 +87,13 @@ class CSVView(object):
         data: Iterable[Sequence[Any] | Mapping[str, Any]],
         has_header: bool = True,
     ) -> Generator[str, None, None]:
+        """
+        Dumps data to CSV lines according to the schema, optionally including a header row.
+
+        :param data: An iterable of rows, each as a sequence or mapping.
+        :param has_header: Whether to include a header row.
+        :return: A generator yielding CSV lines as strings.
+        """
         if has_header:
             yield self.col_delim.join(c.name for c in self.schema)
         for cols in data:
@@ -78,6 +113,15 @@ class CSVView(object):
         ret_dict: bool = False,
         **kwargs,
     ) -> Generator[list[Any] | dict[str, Any], None, None]:
+        """
+        Loads CSV data from a file, splitting by row delimiter and using the ``schema`` for parsing.
+
+        :param file_path: The path to the CSV file.
+        :param has_header: Whether the first line is a header.
+        :param ret_dict: Whether to return rows as dictionaries (``True``) or lists (``False``).
+        :param kwargs: Additional keyword arguments for file opening.
+        :return: A generator yielding each row as a list or dictionary.
+        """
         with open(file_path, mode="r", **kwargs) as fh:
             lines = fh.read().split(self.row_delim)
             yield from self.load_lines(lines, has_header, ret_dict)
@@ -89,6 +133,14 @@ class CSVView(object):
         has_header: bool = True,
         **kwargs,
     ) -> None:
+        """
+        Dumps data to a CSV file according to the ``schema``, optionally including a header row.
+
+        :param data: An iterable of rows, each as a sequence or mapping.
+        :param file_path: The path to the output CSV file.
+        :param has_header: Whether to include a header row.
+        :param kwargs: Additional keyword arguments for file opening.
+        """
         with open(file_path, mode="w", **kwargs) as fh:
             for line in self.dump_lines(data, has_header):
                 fh.write(line)

{iker_python_common-1.0.44 → iker_python_common-1.0.45}/src/iker/common/utils/dbutils.py

@@ -25,7 +25,17 @@ __all__ = [
 
 class ConnectionMaker(object):
     """
-    Provides utilities that make it easier to establish database connections and sessions
+    Provides utilities to simplify establishing database connections and sessions, including connection string
+    construction, engine and session creation, and model management.
+
+    :param driver: The database driver string (e.g., ``mysql+pymysql``).
+    :param host: The database host.
+    :param port: The database port.
+    :param user: The database user.
+    :param password: The database password.
+    :param database: The database name.
+    :param engine_opts: Optional dictionary of SQLAlchemy engine options.
+    :param session_opts: Optional dictionary of SQLAlchemy session options.
     """
 
     class Drivers:
@@ -59,6 +69,15 @@ class ConnectionMaker(object):
         engine_opts: dict[str, Any] | None = None,
         session_opts: dict[str, Any] | None = None,
     ) -> "ConnectionMaker":
+        """
+        Creates a ``ConnectionMaker`` instance from a URL string or ``ParseResult``, extracting connection parameters.
+
+        :param driver: The database driver string.
+        :param url: The database URL as a string or ``ParseResult``.
+        :param engine_opts: Optional dictionary of SQLAlchemy engine options.
+        :param session_opts: Optional dictionary of SQLAlchemy session options.
+        :return: A ``ConnectionMaker`` instance.
+        """
         if isinstance(url, str):
             return ConnectionMaker.from_url(driver, urllib.parse.urlparse(url), engine_opts, session_opts)
         if isinstance(url, urllib.parse.ParseResult):
@@ -74,6 +93,11 @@ class ConnectionMaker(object):
 
     @property
     def connection_string(self) -> str:
+        """
+        Constructs the SQLAlchemy connection string for the database using the provided parameters.
+
+        :return: The connection string as a string.
+        """
         port_part = "" if self.port is None else (":%d" % self.port)
         user_part = urllib.parse.quote(self.user, safe="")
         password_part = "" if is_blank(self.password) else (":%s" % urllib.parse.quote(self.password, safe=""))
@@ -83,15 +107,37 @@ class ConnectionMaker(object):
 
     @property
     def engine(self) -> sqlalchemy.Engine:
+        """
+        Returns a SQLAlchemy ``Engine`` instance for the configured connection string and engine options.
+
+        :return: The SQLAlchemy ``Engine``.
+        """
         return sqlalchemy.create_engine(self.connection_string, **self.engine_opts)
 
     def make_connection(self):
+        """
+        Establishes and returns a new database connection using the SQLAlchemy engine.
+
+        :return: A database connection object.
+        """
         return self.engine.connect()
 
     def make_session(self, **kwargs) -> contextlib.AbstractContextManager[sqlalchemy.orm.Session]:
+        """
+        Creates a context-managed SQLAlchemy session with the configured engine and session options.
+
+        :param kwargs: Additional keyword arguments for session creation.
+        :return: A context manager yielding a SQLAlchemy ``Session``.
+        """
         return contextlib.closing(sqlalchemy.orm.sessionmaker(self.engine, **{**self.session_opts, **kwargs})())
 
     def create_model(self, orm_base):
+        """
+        Creates all tables defined in the given ORM base using the current engine.
+
+        :param orm_base: The SQLAlchemy ORM base class.
+        :return: None.
+        """
         if packaging.version.parse(sqlalchemy.__version__) >= packaging.version.parse("2"):
             if not isinstance(orm_base, type) or not issubclass(orm_base, sqlalchemy.orm.DeclarativeBase):
                 raise TypeError("not a subclass of 'sqlalchemy.orm.DeclarativeBase'")
@@ -99,6 +145,12 @@ class ConnectionMaker(object):
         orm_base.metadata.create_all(self.engine)
 
     def drop_model(self, orm_base):
+        """
+        Drops all tables defined in the given ORM base using the current engine.
+
+        :param orm_base: The SQLAlchemy ORM base class.
+        :return: None.
+        """
         if packaging.version.parse(sqlalchemy.__version__) >= packaging.version.parse("2"):
             if not isinstance(orm_base, type) or not issubclass(orm_base, sqlalchemy.orm.DeclarativeBase):
                 raise TypeError("not a subclass of 'sqlalchemy.orm.DeclarativeBase'")
@@ -107,10 +159,11 @@ class ConnectionMaker(object):
 
     def execute(self, sql: str, **params):
         """
-        Executes the given SQL statement with the specific parameters
+        Executes the given SQL statement with the specified parameters.
 
-        :param sql: SQL statement to execute
-        :param params: parameters dict
+        :param sql: The SQL statement to execute.
+        :param params: The parameters dictionary for the SQL statement.
+        :return: None.
         """
         with self.make_connection() as connection:
             connection.execute(sqlalchemy.text(sql), params)
@@ -118,11 +171,11 @@ class ConnectionMaker(object):
 
     def query_all(self, sql: str, **params) -> list[tuple]:
         """
-        Executes the given SQL query with the specific parameters and returns all the results
+        Executes the given SQL query with the specified parameters and returns all result tuples.
 
-        :param sql: SQL query to execute
-        :param params: parameters dict
-        :return: result tuples list
+        :param sql: The SQL query to execute.
+        :param params: The parameters dictionary for the SQL query.
+        :return: A list of result tuples.
         """
         with self.make_connection() as connection:
             with contextlib.closing(connection.execute(sqlalchemy.text(sql), params)) as proxy:
@@ -130,11 +183,12 @@ class ConnectionMaker(object):
 
     def query_first(self, sql: str, **params) -> tuple | None:
         """
-        Executes the given SQL query with the specific parameters and returns the first result tuple
+        Executes the given SQL query with the specified parameters and returns the first result tuple, or ``None`` if no
+        results are found.
 
-        :param sql: SQL query to execute
-        :param params: parameters dict
-        :return: the first result tuple
+        :param sql: The SQL query to execute.
+        :param params: The parameters dictionary for the SQL query.
+        :return: The first result tuple, or ``None`` if no results are found.
         """
         return head_or_none(self.query_all(sql, **params))
 
@@ -143,6 +197,13 @@ DBAdapter = ConnectionMaker
 
 
 def orm_to_dict(orm, exclude: set[str] = None) -> dict[str, Any]:
+    """
+    Converts an ORM object to a dictionary, optionally excluding specified fields.
+
+    :param orm: The ORM object to convert.
+    :param exclude: An optional set of field names to exclude from the result.
+    :return: A dictionary mapping field names to their values.
+    """
     if packaging.version.parse(sqlalchemy.__version__) >= packaging.version.parse("2"):
         if not isinstance(orm, sqlalchemy.orm.DeclarativeBase):
             raise TypeError("not an instance of 'sqlalchemy.orm.DeclarativeBase'")
@@ -152,6 +213,14 @@ def orm_to_dict(orm, exclude: set[str] = None) -> dict[str, Any]:
 
 
 def orm_clone(orm, exclude: set[str] = None, no_autoincrement: bool = False):
+    """
+    Creates a clone of the given ORM object, optionally excluding specified fields or auto-increment fields.
+
+    :param orm: The ORM object to clone.
+    :param exclude: An optional set of field names to exclude from the clone.
+    :param no_autoincrement: If ``True``, excludes auto-increment fields from the clone.
+    :return: A new ORM object with the specified fields cloned.
+    """
     if packaging.version.parse(sqlalchemy.__version__) >= packaging.version.parse("2"):
         if not isinstance(orm, sqlalchemy.orm.DeclarativeBase):
             raise TypeError("not an instance of 'sqlalchemy.orm.DeclarativeBase'")
@@ -173,6 +242,13 @@ def orm_clone(orm, exclude: set[str] = None, no_autoincrement: bool = False):
 
 
 def mysql_insert_ignore(enabled: bool = True):
+    """
+    Registers a SQLAlchemy compiler extension to add ``IGNORE`` to MySQL ``INSERT`` statements if ``enabled``.
+
+    :param enabled: Whether to enable the ``IGNORE`` prefix for MySQL ``INSERT`` statements.
+    :return: None.
+    """
+
     @sqlalchemy.ext.compiler.compiles(sqlalchemy.sql.Insert, "mysql")
     def dispatch(insert: sqlalchemy.sql.Insert, compiler: sqlalchemy.sql.compiler.SQLCompiler, **kwargs) -> str:
         if not enabled:
@@ -182,13 +258,21 @@ def mysql_insert_ignore(enabled: bool = True):
 
 
 def postgresql_insert_on_conflict_do_nothing(enabled: bool = True):
+    """
+    Registers a SQLAlchemy compiler extension to add ``ON CONFLICT DO NOTHING`` to PostgreSQL ``INSERT`` statements if
+    ``enabled``.
+
+    :param enabled: Whether to enable the ``ON CONFLICT DO NOTHING`` clause for PostgreSQL ``INSERT`` statements.
+    :return: None.
+    """
+
     @sqlalchemy.ext.compiler.compiles(sqlalchemy.sql.Insert, "postgresql")
     def dispatch(insert: sqlalchemy.sql.Insert, compiler: sqlalchemy.sql.compiler.SQLCompiler, **kwargs) -> str:
         if not enabled:
             return compiler.visit_insert(insert, **kwargs)
 
         statement = compiler.visit_insert(insert, **kwargs)
-        # If we have a "RETURNING" clause, we must insert before it
+        # If we have a ``RETURNING`` clause, we must insert before it
         returning_position = statement.find("RETURNING")
         if returning_position >= 0:
             return statement[:returning_position] + " ON CONFLICT DO NOTHING " + statement[returning_position:]