plexus-python-common 1.0.74__py3-none-any.whl → 1.1.82__py3-none-any.whl

plexus/common/utils/argutils.py

@@ -0,0 +1,221 @@
+import argparse
+import dataclasses
+import inspect
+import typing
+from collections.abc import Sequence
+from typing import Any
+
+from plexus.common.utils.typeutils import is_identical_type
+
+__all__ = [
+    "ParserTreeNode",
+    "ParserTree",
+    "ArgParseSpec",
+    "argparse_spec",
+    "make_argparse"
+]
+
+
+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
+        self.subparsers = None
+        self.child_nodes: list[ParserTreeNode] = []
+
+
+def construct_parser_tree(
+    root_node: ParserTreeNode,
+    command_chain: list[str],
+    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
+
+    node = root_node
+    for depth, command in enumerate(command_chain):
+        if node.subparsers is None:
+            node.subparsers = node.parser.add_subparsers(dest=f"{command_key_prefix}:{depth}")
+        for child_node in node.child_nodes:
+            if child_node.command == command:
+                node = child_node
+                break
+        else:
+            if depth == len(command_chain) - 1:
+                child_parser = node.subparsers.add_parser(command, **kwargs)
+            else:
+                child_parser = node.subparsers.add_parser(command)
+            child_node = ParserTreeNode(command, child_parser)
+            node.child_nodes.append(child_node)
+            node = child_node
+        node_path.append(node)
+
+    return node_path
+
+
+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]:
+        """
+        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``.
+        """
+        known_args_namespace = self.root_node.parser.parse_args(args)
+
+        command_pairs = []
+        namespace = argparse.Namespace()
+        for key, value in dict(vars(known_args_namespace)).items():
+            if key.startswith(self.command_key_prefix) and value is not None:
+                command_pairs.append((key, value))
+            else:
+                setattr(namespace, key, value)
+
+        return list(command for _, command in sorted(command_pairs)), namespace
+
+
+@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
+    default: Any = None
+    type: typing.Type | None = None
+    choices: list[Any] | None = None
+    required: bool | None = None
+    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,
+            type=self.type,
+            choices=self.choices,
+            required=self.required,
+            help=self.help,
+        )
+
+        return {key: value for key, value in kwargs.items() if value is not None}
+
+
+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()
+
+    def is_type_of(a: Any, *bs) -> bool:
+        return any(is_identical_type(a, b, strict_optional=False, covariant=True) for b in bs)
+
+    sig = inspect.signature(func)
+    for name, param in sig.parameters.items():
+
+        arg_name = f"--{name.replace('_', '-')}"
+
+        if param.annotation is None:
+            arg_type = str
+        elif is_type_of(param.annotation, str, Sequence[str]):
+            arg_type = str
+        elif is_type_of(param.annotation, int, Sequence[int]):
+            arg_type = int
+        elif is_type_of(param.annotation, float, Sequence[float]):
+            arg_type = float
+        elif is_type_of(param.annotation, bool, Sequence[bool]):
+            arg_type = bool
+        else:
+            arg_type = str
+
+        arg_action = "append" if typing.get_origin(param.annotation) in {list, Sequence} else None
+        arg_default = None if param.default is inspect.Parameter.empty else param.default
+
+        if isinstance(arg_default, ArgParseSpec):
+            spec = arg_default
+            spec = dataclasses.replace(spec,
+                                       name=spec.name or arg_name,
+                                       type=spec.type if spec.type is not None else arg_type,
+                                       action=spec.action if spec.action is not None else arg_action)
+
+            if spec.flag is None:
+                parser.add_argument(spec.name, **spec.make_kwargs())
+            else:
+                parser.add_argument(spec.flag, spec.name, **spec.make_kwargs())
+
+        else:
+            parser.add_argument(arg_name,
+                                type=arg_type,
+                                action=arg_action,
+                                required=arg_default is None,
+                                default=arg_default)
+
+    return parser

plexus/common/utils/config.py

@@ -1,63 +1,124 @@
+import configparser
 import os
+import pathlib
+from typing import Self
 
-from iker.common.utils import logger
-from iker.common.utils.config import Config
-from iker.common.utils.funcutils import memorized
-from iker.common.utils.pathutils import make_path
-
-
-@memorized()
-def config(config_path: str | os.PathLike[str] = "") -> Config:
-    default_items: list[tuple[str, str, str]] = [
-        ("plexus", "logging.level", "INFO"),
-        ("plexus", "logging.format", "%(asctime)s [%(levelname)s] %(name)s: %(message)s"),
-    ]
-
-    instance = Config(config_path or make_path("~/.plexus.cfg", expand=True, normalize=True, absolute=True))
-    instance.restore()
-    instance.update(default_items, overwrite=False)
-
-    return instance
-
-
-def config_print_or_set(config: Config, section: str, key: str, value: str):
-    if value is not None:
-        if section is None or key is None:
-            raise ValueError("cannot specify value without section and key")
-
-        old_value = config.get(section, key)
-        config.set(section, key, value)
-        config.persist()
-
-        print(f"Configuration file '{config.config_path}'", )
-        print(f"Section <{section}>")
-        print(f"  {key} = {old_value} -> {value}")
-
-    else:
-        if section is None and key is None:
-            print(f"Configuration file '{config.config_path}'", )
-            for section in config.config_parser.sections():
-                print(f"Section <{section}>")
-                for key, value in config.config_parser.items(section):
-                    print(f"  {key} = {value}")
-
-        elif section is not None and key is None:
-            if not config.has_section(section):
-                logger.warning("Configuration section '%s' not found", section)
-                return
-            print(f"Configuration file '{config.config_path}'", )
-            print(f"Section <{section}>")
-            for key, value in config.config_parser.items(section):
-                print(f"  {key} = {value}")
-
-        elif section is not None and key is not None:
-            value = config.get(section, key)
-            if value is None:
-                logger.warning("Configuration section '%s' key '%s' not found", section, key)
-                return
-            print(f"Configuration file '{config.config_path}'", )
-            print(f"Section <{section}>")
-            print(f"  {key} = {value}")
+from plexus.common.utils import logger
+from plexus.common.utils.strutils import is_blank, trim_to_empty
 
+
+class Config(object):
+    def __init__(self, config_path: str | os.PathLike[str] | None = None):
+        if not is_blank(config_path := trim_to_empty(None if config_path is None else str(config_path))):
+            self.config_path = pathlib.Path(config_path)
         else:
-            raise ValueError("cannot specify key without section")
+            self.config_path = None
+        self.config_parser: configparser.RawConfigParser = configparser.RawConfigParser(strict=False)
+
+    def __len__(self):
+        return sum(len(self.config_parser.options(section)) for section in self.config_parser.sections())
+
+    def update(self, tuples: list[tuple[str, str, str]], *, overwrite: bool = False):
+        for section, option, value in tuples:
+            if not self.config_parser.has_section(section):
+                self.config_parser.add_section(section)
+            if overwrite or not self.config_parser.has_option(section, option):
+                self.config_parser.set(section, option, value)
+
+    def restore(self) -> bool:
+        self.config_parser = configparser.RawConfigParser(strict=False)
+        if self.config_path is None:
+            return False
+        try:
+            if not self.config_path.exists():
+                raise IOError("file not found")
+            self.config_parser.read(self.config_path, encoding="utf-8")
+            return True
+        except IOError as e:
+            logger.exception("Failed to restore config from file <'%s'>", self.config_path)
+        return False
+
+    def persist(self) -> bool:
+        if self.config_path is None:
+            return False
+        try:
+            with open(self.config_path, "w") as fh:
+                self.config_parser.write(fh)
+            return True
+        except IOError as e:
+            logger.exception("Failed to persist config to file <'%s'>", self.config_path)
+        return False
+
+    def has_section(self, section: str) -> bool:
+        return self.config_parser.has_section(section)
+
+    def has(self, section: str, option: str) -> bool:
+        return self.config_parser.has_option(section, option)
+
+    def get(self, section: str, option: str, default_value: str = None) -> str:
+        if self.config_parser.has_option(section, option):
+            return self.config_parser.get(section, option)
+        return default_value
+
+    def getint(self, section: str, option: str, default_value: int = None) -> int:
+        if self.config_parser.has_option(section, option):
+            return self.config_parser.getint(section, option)
+        return default_value
+
+    def getfloat(self, section: str, option: str, default_value: float = None) -> float:
+        if self.config_parser.has_option(section, option):
+            return self.config_parser.getfloat(section, option)
+        return default_value
+
+    def getboolean(self, section: str, option: str, default_value: bool = None) -> bool:
+        if self.config_parser.has_option(section, option):
+            return self.config_parser.getboolean(section, option)
+        return default_value
+
+    def set(self, section: str, option: str, value: str):
+        if not self.config_parser.has_section(section):
+            self.config_parser.add_section(section)
+        self.config_parser.set(section, option, value)
+
+    def sections(self) -> list[str]:
+        return self.config_parser.sections()
+
+    def options(self, section: str) -> list[str]:
+        if not self.config_parser.has_section(section):
+            return []
+        return self.config_parser.options(section)
+
+    def tuples(self) -> list[tuple[str, str, str]]:
+        result = []
+        for section in self.config_parser.sections():
+            for option in self.config_parser.options(section):
+                value = self.config_parser.get(section, option)
+                result.append((section, option, value))
+        return result
+
+
+class ConfigVisitor(object):
+    def __init__(self, config: Config, section: str, prefix: str = "", separator: str = "."):
+        self.config = config
+        self.section = section
+        self.prefix = prefix
+        self.separator = separator
+
+    def __str__(self):
+        return self.config.get(self.section, self.prefix)
+
+    def __int__(self):
+        return self.config.getint(self.section, self.prefix)
+
+    def __float__(self):
+        return self.config.getfloat(self.section, self.prefix)
+
+    def __bool__(self):
+        return self.config.getboolean(self.section, self.prefix)
+
+    def __getattr__(self, suffix: str) -> Self:
+        return self[suffix]
+
+    def __getitem__(self, suffix: str) -> Self:
+        new_prefix = suffix if is_blank(self.prefix) else self.separator.join([self.prefix, suffix])
+        return ConfigVisitor(self.config, self.section, new_prefix, self.separator)

plexus/common/utils/csvutils.py

@@ -0,0 +1,241 @@
+import csv
+import os
+from collections.abc import Callable, Generator, Iterable, Mapping, Sequence
+from typing import Any
+from typing import overload
+
+__all__ = [
+    "CSVColumn",
+    "CSVView",
+    "column",
+    "view",
+]
+
+
+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,
+        loader: Callable[[str], Any] = str,
+        dumper: Callable[[Any], str] = str,
+        null_str: str = "",
+    ):
+        self.name = name
+        self.loader = loader
+        self.dumper = dumper
+        self.null_str = null_str
+
+
+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 column_delimiter: The delimiter used to separate columns in the CSV (default: ",").
+    :param line_terminator: The string used to terminate lines in the CSV (default: "\n").
+    :param quote_char: The character used to quote fields in the CSV (default: '"').
+    :param strict: Whether to raise an error on malformed CSV (default: ``True``).
+    """
+
+    def __init__(
+        self,
+        schema: Sequence[CSVColumn],
+        *,
+        column_delimiter: str = ",",
+        line_terminator: str = "\n",
+        quote_char: str = '"',
+        strict: bool = True,
+    ):
+        self.schema = schema
+        self.column_delimiter = column_delimiter
+        self.line_terminator = line_terminator
+        self.quote_char = quote_char
+        self.strict = strict
+
+    @overload
+    def load_lines(
+        self,
+        lines: Iterable[Sequence[str]],
+        has_header: bool,
+        ret_dict: False = False,
+    ) -> Generator[list[Any], None, None]:
+        ...
+
+    @overload
+    def load_lines(
+        self,
+        lines: Iterable[Sequence[str]],
+        ret_dict: False = False,
+    ) -> Generator[list[Any], None, None]:
+        ...
+
+    @overload
+    def load_lines(
+        self,
+        lines: Iterable[Sequence[str]],
+        has_header: bool,
+        ret_dict: True = True,
+    ) -> Generator[dict[str, Any], None, None]:
+        ...
+
+    @overload
+    def load_lines(
+        self,
+        lines: Iterable[Sequence[str]],
+        ret_dict: True = True,
+    ) -> Generator[dict[str, Any], None, None]:
+        ...
+
+    def load_lines(
+        self,
+        lines: Iterable[Sequence[str]],
+        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_cols = next(rows_iter)
+            if len(self.schema) != len(header_cols):
+                raise ValueError("size of the schema is not identical to size of the columns")
+            for c, header_col in zip(self.schema, header_cols):
+                if c.name != header_col:
+                    raise ValueError("name of the schema is not equal to the name of the columns")
+        for cols in rows_iter:
+            if len(self.schema) != len(cols):
+                continue
+            if ret_dict:
+                yield {c.name: None if col == c.null_str else c.loader(col) for c, col in zip(self.schema, cols)}
+            else:
+                yield [None if col == c.null_str else c.loader(col) for c, col in zip(self.schema, cols)]
+
+    def dump_lines(
+        self,
+        data: Iterable[Sequence[Any] | Mapping[str, Any]],
+        has_header: bool = True,
+    ) -> Generator[list[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 list(c.name for c in self.schema)
+        for cols in data:
+            if isinstance(cols, Sequence):
+                if len(self.schema) != len(cols):
+                    raise ValueError("size of the schema is not identical to size of the columns")
+                yield list(c.null_str if col is None else c.dumper(col) for c, col in zip(self.schema, cols))
+            if isinstance(cols, Mapping):
+                yield list(c.null_str if cols.get(c.name) is None else c.dumper(cols.get(c.name)) for c in self.schema)
+
+    @overload
+    def load_file(
+        self,
+        file_path: str | os.PathLike[str],
+        has_header: bool,
+        ret_dict: False = False,
+        **kwargs,
+    ) -> Generator[list[Any], None, None]:
+        ...
+
+    @overload
+    def load_file(
+        self,
+        file_path: str | os.PathLike[str],
+        ret_dict: False = False,
+        **kwargs,
+    ) -> Generator[list[Any], None, None]:
+        ...
+
+    @overload
+    def load_file(
+        self,
+        file_path: str | os.PathLike[str],
+        has_header: bool,
+        ret_dict: True = True,
+        **kwargs,
+    ) -> Generator[dict[str, Any], None, None]:
+        ...
+
+    @overload
+    def load_file(
+        self,
+        file_path: str | os.PathLike[str],
+        ret_dict: True = True,
+        **kwargs,
+    ) -> Generator[dict[str, Any], None, None]:
+        ...
+
+    def load_file(
+        self,
+        file_path: str | os.PathLike[str],
+        has_header: bool = True,
+        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:
+            reader = csv.reader(fh,
+                                delimiter=self.column_delimiter,
+                                lineterminator=self.line_terminator,
+                                quotechar=self.quote_char,
+                                strict=self.strict)
+            yield from self.load_lines(reader, has_header, ret_dict)
+
+    def dump_file(
+        self,
+        data: Iterable[Sequence[Any] | Mapping[str, Any]],
+        file_path: str | os.PathLike[str],
+        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:
+            writer = csv.writer(fh,
+                                delimiter=self.column_delimiter,
+                                lineterminator=self.line_terminator,
+                                quotechar=self.quote_char,
+                                strict=self.strict)
+            for line in self.dump_lines(data, has_header):
+                writer.writerow(line)
+
+
+column = CSVColumn
+view = CSVView