plexus-python-common 1.0.74__tar.gz → 1.1.82__tar.gz

{plexus_python_common-1.0.74 → plexus_python_common-1.1.82}/.github/workflows/pr.yml

@@ -11,7 +11,7 @@ jobs:
   build-python:
     runs-on: ubuntu-latest
     container:
-      image: ruyangshou/plexus-basedev-dev-python:latest
+      image: ruyangshou/plexus-basedev-ci:latest
       options: --user github
     strategy:
       matrix:

{plexus_python_common-1.0.74 → plexus_python_common-1.1.82}/.github/workflows/push.yml

@@ -11,7 +11,7 @@ jobs:
   push:
     runs-on: ubuntu-latest
     container:
-      image: ruyangshou/plexus-basedev-dev-python:latest
+      image: ruyangshou/plexus-basedev-ci:latest
       options: --user github
     steps:
       - name: Checkout

plexus_python_common-1.1.82/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: plexus-python-common
+Version: 1.1.82
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.12
+Requires-Dist: asyncpg>=0.30
+Requires-Dist: numpy>=2.3
+Requires-Dist: psycopg>=3.2
+Requires-Dist: pymysql>=1.1
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: all
+Requires-Dist: plexus-python-common; extra == "all"
+Provides-Extra: test
+Requires-Dist: ddt>=1.7; extra == "test"
+Requires-Dist: pytest-asyncio>=1.2; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: pytest-mysql>=3.0; extra == "test"
+Requires-Dist: pytest-order>=1.3; extra == "test"
+Requires-Dist: pytest-postgresql>=6.1; extra == "test"
+Requires-Dist: pytest>=8.3; extra == "test"

plexus_python_common-1.1.82/README.md

@@ -0,0 +1,29 @@
+# Plexus Python Common Module
+
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/plexus-python-common?style=for-the-badge)
+![PyPI - Version](https://img.shields.io/pypi/v/plexus-python-common?style=for-the-badge)
+![Codecov](https://img.shields.io/codecov/c/github/ruyangshou/plexus-python-common?token=0FGT4M40CD&style=for-the-badge)
+
+## Build and Deploy
+
+### Using Conda
+
+We recommend using Conda. You need to install Anaconda packages from
+the [official site](https://www.anaconda.com/products/distribution)
+
+Create a Conda environment and install the modules and their dependencies in it
+
+```shell
+conda create -n plexus python=3.14
+conda activate plexus
+
+pip install .
+
+conda deactivate
+```
+
+To remove the existing Conda environment (and create a brand new one)
+
+```shell
+conda env remove -n plexus
+```

plexus_python_common-1.1.82/VERSION

@@ -0,0 +1 @@
+1.1

plexus_python_common-1.1.82/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = [
+    "setuptools>=80.0",
+    "setuptools-scm>=9.0",
+    "plexus-python-setup>=1.1",
+]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "asyncpg>=0.30",
+    "numpy>=2.3",
+    "psycopg>=3.2",
+    "pymysql>=1.1",
+    "sqlalchemy>=2.0",
+]
+test = [
+    "ddt>=1.7",
+    "pytest-asyncio>=1.2",
+    "pytest-cov>=5.0",
+    "pytest-mysql>=3.0",
+    "pytest-order>=1.3",
+    "pytest-postgresql>=6.1",
+    "pytest>=8.3",
+]
+
+[project]
+name = "plexus-python-common"
+dynamic = ["version"]
+requires-python = ">=3.12,<3.15"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "asyncpg>=0.30",
+    "numpy>=2.3",
+    "psycopg>=3.2",
+    "pymysql>=1.1",
+    "sqlalchemy>=2.0",
+]
+
+[project.optional-dependencies]
+all = [
+    "plexus-python-common",
+]
+test = [
+    "ddt>=1.7",
+    "pytest-asyncio>=1.2",
+    "pytest-cov>=5.0",
+    "pytest-mysql>=3.0",
+    "pytest-order>=1.3",
+    "pytest-postgresql>=6.1",
+    "pytest>=8.3",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+zip-safe = false
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+branch = true
+include = [
+    "src/plexus/*",
+]

plexus_python_common-1.1.82/resources/unittest/config/config.cfg

@@ -0,0 +1,10 @@
+[dummy_section_1]
+dummy_option_1 = True
+dummy_option_2 = False
+dummy_option_3 = 1
+dummy_option_4 = -1
+dummy_option_5 = 1.0
+dummy_option_6 = -1.0
+dummy_option_7 = 1.e+0
+dummy_option_8 = -1.e-0
+dummy_option_9 = dummy_value_alpha

plexus_python_common-1.1.82/resources/unittest/csvutils/data.csv

@@ -0,0 +1,7 @@
+dummy_str,dummy_bool,dummy_int,dummy_float,dummy_datetime,dummy_params
+foo,True,1,1.0,2020-01-01T00:00:00,
+bar,False,-1,-1.0,2020-01-01T00:00:00,"key_1=value_1,key_2,!key_3"
+baz,\N,100,inf,2020-01-01T00:00:00,\N
+,\N,-100,-inf,2020-01-01T00:00:00,
+\N,\N,0,nan,2020-01-01T00:00:00,\N
+\N,\N,\N,\N,\N,\N

plexus_python_common-1.1.82/resources/unittest/csvutils/data.tsv

@@ -0,0 +1,7 @@
+dummy_str	dummy_bool	dummy_int	dummy_float	dummy_datetime	dummy_params
+foo	True	1	1.0	2020-01-01T00:00:00	
+bar	False	-1	-1.0	2020-01-01T00:00:00	key_1:value_1;key_2;-key_3
+baz	<null>	100	inf	2020-01-01T00:00:00	<null>
+	<null>	-100	-inf	2020-01-01T00:00:00	
+<null>	<null>	0	nan	2020-01-01T00:00:00	<null>
+<null>	<null>	<null>	<null>	<null>	<null>

{plexus_python_common-1.0.74 → plexus_python_common-1.1.82}/setup.py

@@ -1,6 +1,6 @@
 import argparse
 
-from iker.setup import setup, version_string
+from plexus.setup import setup, version_string
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="setup script integrating dynamic version printer")

plexus_python_common-1.1.82/src/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_python_common-1.1.82/src/plexus/common/utils/config.py

@@ -0,0 +1,124 @@
+import configparser
+import os
+import pathlib
+from typing import Self
+
+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:
+            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)