moat-lib-run 0.1.1__tar.gz

moat_lib_run-0.1.1/LICENSE.txt

@@ -0,0 +1,14 @@
+The code in this repository, and all MoaT submodules it refers to,
+is part of the MoaT project.
+
+Unless a submodule's LICENSE.txt states otherwise, all included files are
+licensed under the LGPL V3, as published by the FSF at
+https://www.gnu.org/licenses/lgpl-3.0.html .
+
+In addition to the LGPL's terms, the author(s) respectfully ask all users of
+this code to contribute any bug fixes or enhancements. Also, please link back to
+https://M-o-a-T.org.
+
+Thank you.
+
+Copyright © 2021 ff.: the MoaT contributor(s), as per the git changelog(s).

moat_lib_run-0.1.1/Makefile

@@ -0,0 +1,14 @@
+#!/usr/bin/make -f
+
+PACKAGE = moat-lib-run
+MAKEINCL ?= $(shell python3 -mmoat src path)/make/py
+
+ifneq ($(wildcard $(MAKEINCL)),)
+include $(MAKEINCL)
+# availabe via http://github.com/smurfix/sourcemgr
+
+else
+%:
+	@echo "Please fix 'python3 -mmoat src path'."
+	@exit 1
+endif

moat_lib_run-0.1.1/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: moat-lib-run
+Version: 0.1.1
+Summary: Main command entry point infrastructure for MoaT applications
+Maintainer-email: Matthias Urlichs <matthias@urlichs.de>
+Project-URL: homepage, https://m-o-a-t.org
+Project-URL: repository, https://github.com/M-o-a-T/moat
+Keywords: MoaT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AnyIO
+Classifier: Framework :: Trio
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: anyio~=4.0
+Requires-Dist: moat-util~=0.61.1
+Requires-Dist: asyncclick~=8.0
+Requires-Dist: simpleeval~=1.0
+Requires-Dist: moat-lib-config~=0.1.0
+Requires-Dist: moat-lib-proxy~=0.1.0
+Dynamic: license-file
+
+# moat-lib-run
+
+% start main
+% start synopsis
+
+Main command entry point infrastructure for MoaT applications.
+
+% end synopsis
+
+This module provides the infrastructure for building command-line interfaces
+for MoaT applications. It includes:
+
+- Command-line argument parsing with Click integration
+- Subcommand loading from internal modules and extensions
+- Configuration file handling
+- Logging setup
+- Main entry point wrappers for testing
+
+## Usage
+
+### Basic command setup
+
+```python
+from moat.lib.run import main_, wrap_main
+
+@main_.command()
+async def my_command(ctx):
+    """A simple command"""
+    print("Hello from my command!")
+```
+
+### Loading subcommands
+
+Use `load_subgroup` to create command groups that automatically load subcommands:
+
+```python
+from moat.lib.run import load_subgroup
+import asyncclick as click
+
+@load_subgroup(prefix="myapp.commands")
+@click.pass_context
+async def cli(ctx):
+    """Main command group"""
+    pass
+```
+
+### Processing command-line arguments
+
+The `attr_args` decorator and `process_args` function provide flexible
+argument handling:
+
+```python
+from moat.lib.run import attr_args, process_args
+
+@main_.command()
+@attr_args(with_path=True)
+async def configure(**kw):
+    """Configure the application"""
+    config = process_args({}, **kw)
+    # config now contains parsed arguments
+```
+
+## Key Functions
+
+- `main_`: The default main command handler
+- `wrap_main`: Wrapper for the main command, useful for testing
+- `load_subgroup`: Decorator to create command groups with automatic subcommand loading
+- `attr_args`: Decorator for adding flexible argument handling to commands
+- `process_args`: Function to process command-line arguments into configuration
+- `Loader`: Click group class that loads commands from submodules and extensions
+
+% end main

moat_lib_run-0.1.1/README.md

@@ -0,0 +1,72 @@
+# moat-lib-run
+
+% start main
+% start synopsis
+
+Main command entry point infrastructure for MoaT applications.
+
+% end synopsis
+
+This module provides the infrastructure for building command-line interfaces
+for MoaT applications. It includes:
+
+- Command-line argument parsing with Click integration
+- Subcommand loading from internal modules and extensions
+- Configuration file handling
+- Logging setup
+- Main entry point wrappers for testing
+
+## Usage
+
+### Basic command setup
+
+```python
+from moat.lib.run import main_, wrap_main
+
+@main_.command()
+async def my_command(ctx):
+    """A simple command"""
+    print("Hello from my command!")
+```
+
+### Loading subcommands
+
+Use `load_subgroup` to create command groups that automatically load subcommands:
+
+```python
+from moat.lib.run import load_subgroup
+import asyncclick as click
+
+@load_subgroup(prefix="myapp.commands")
+@click.pass_context
+async def cli(ctx):
+    """Main command group"""
+    pass
+```
+
+### Processing command-line arguments
+
+The `attr_args` decorator and `process_args` function provide flexible
+argument handling:
+
+```python
+from moat.lib.run import attr_args, process_args
+
+@main_.command()
+@attr_args(with_path=True)
+async def configure(**kw):
+    """Configure the application"""
+    config = process_args({}, **kw)
+    # config now contains parsed arguments
+```
+
+## Key Functions
+
+- `main_`: The default main command handler
+- `wrap_main`: Wrapper for the main command, useful for testing
+- `load_subgroup`: Decorator to create command groups with automatic subcommand loading
+- `attr_args`: Decorator for adding flexible argument handling to commands
+- `process_args`: Function to process command-line arguments into configuration
+- `Loader`: Click group class that loads commands from submodules and extensions
+
+% end main

moat_lib_run-0.1.1/debian/.gitignore

@@ -0,0 +1,7 @@
+/files
+/*.log
+/*.debhelper
+/*.debhelper-build-stamp
+/*.substvars
+/debhelper-build-stamp
+/python3-moat-lib-run

moat_lib_run-0.1.1/debian/changelog

@@ -0,0 +1,5 @@
+moat-lib-run (0.1.1-4) unstable; urgency=medium
+
+  * Initial release for 25.7.0
+
+ -- Matthias Urlichs <matthias@urlichs.de>  Wed, 31 Dec 2025 14:01:43 +0100

moat_lib_run-0.1.1/debian/control

@@ -0,0 +1,22 @@
+Source: moat-lib-run
+Maintainer: "Matthias Urlichs" <matthias@urlichs.de>
+Section: python
+Priority: optional
+Build-Depends: dh-python, python3-all, debhelper (>= 13),
+  python3-setuptools,
+  python3-wheel,
+Standards-Version: 3.9.6
+Homepage: https://m-o-a-t.org
+X-DH-Compat: 13
+
+Package: python3-moat-lib-run
+Architecture: all
+Depends: ${misc:Depends}, ${python3:Depends},
+  python3-anyio (>= 4.0),
+  python3-moat-util (>= 0.6),
+  python3-asyncclick (>= 8.0),
+  python3-simpleeval (>= 1.0),
+Description: Main command entry point infrastructure for MoaT applications
+  This module provides the infrastructure for building command-line interfaces
+  for MoaT applications, including command-line argument parsing, subcommand
+  loading, configuration file handling, and logging setup.

moat_lib_run-0.1.1/debian/rules

@@ -0,0 +1,5 @@
+#!/usr/bin/make -f
+
+export PYBUILD_NAME=moat-lib-run
+%:
+	dh $@ --with python3 --buildsystem=pybuild

moat_lib_run-0.1.1/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["wheel","setuptools"]
+
+[project]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AnyIO",
+    "Framework :: Trio",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "anyio ~= 4.0",
+    "moat-util ~= 0.61.1",
+    "asyncclick ~= 8.0",
+    "simpleeval ~= 1.0",
+    "moat-lib-config ~= 0.1.0",
+    "moat-lib-proxy ~= 0.1.0",
+]
+keywords = ["MoaT"]
+requires-python = ">=3.8"
+name = "moat-lib-run"
+maintainers = [{email = "matthias@urlichs.de",name = "Matthias Urlichs"}]
+description='Main command entry point infrastructure for MoaT applications'
+readme = "README.md"
+version = "0.1.1"
+
+[project.urls]
+homepage = "https://m-o-a-t.org"
+repository = "https://github.com/M-o-a-T/moat"
+
+[tool.setuptools]
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.yaml"]

moat_lib_run-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moat_lib_run-0.1.1/src/moat/lib/run/__init__.py

@@ -0,0 +1,947 @@
+"""
+Support for main program, argv, etc.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib
+import logging
+import logging.config
+import sys
+from contextlib import suppress
+from contextvars import ContextVar
+from functools import partial, wraps
+from pathlib import Path as FSPath
+
+import asyncclick as click
+import simpleeval
+
+from moat.util import NotGiven, P, Path, attrdict, ungroup
+from moat.lib.config import CFG, CfgStore, current_cfg
+
+from collections import defaultdict
+from collections.abc import Mapping
+
+try:
+    from moat.lib.proxy import Proxy
+except ImportError:
+    Proxy = None
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Awaitable, Literal, Sequence  # noqa:UP035
+
+logger = logging.getLogger("_loader")
+
+__all__ = [
+    "Loader",
+    "attr_args",
+    "list_ext",
+    "load_ext",
+    "load_subgroup",
+    "main_",
+    "option_ng",
+    "process_args",
+    "wrap_main",
+]
+
+this_load = ContextVar("this_load", default=None)
+
+NoneType = type(None)
+
+# cmd_eval is a simple and safe "eval" replacement.
+_eval = simpleeval.SimpleEval(functions={})
+_eval.nodes[ast.Tuple] = lambda node: tuple(  # pyright: ignore[reportOptionalSubscript]
+    _eval._eval(x) for x in node.elts
+)
+_eval.nodes[ast.List] = lambda node: list(  # pyright: ignore[reportOptionalSubscript]
+    _eval._eval(x) for x in node.elts
+)
+_eval.nodes[ast.Dict] = lambda node: attrdict(  # pyright: ignore[reportOptionalSubscript]
+    (_eval._eval(x), _eval._eval(y)) for x, y in zip(node.keys, node.values, strict=False)
+)
+cmd_eval = _eval.eval
+
+
+def _no_config(*a, **k):  # noqa:ARG001
+    import warnings  # noqa: PLC0415
+
+    warnings.warn("Call to logging config ignored", stacklevel=2)
+
+
+def attr_args(
+    proc=None,
+    with_combined="s",
+    with_arglist=False,
+    with_path=True,
+    with_eval=True,
+    with_var=True,
+    with_proxy=False,
+    par_name="Parameter",
+):
+    """
+    Add an option for setting possibly-hierarchical values to `click.command`.
+
+    ``-s``/``--set`` accepts these prefix-tagged values:
+    * ~str
+    * =value (``=-``/``=t``/``=f``/``=n`` for ``undefined``/`True`/`False`/`None`)
+    * .path (the leading dot is stripped)
+    * :path (the colon is not stripped)
+    * ^named_proxy
+
+    These are enabled (rather, displayed) by passing ``True`` in
+    ``with_val``, ``with_eval``, ``with_path``, and ``with_proxy``,
+    respectively. The latter defaults to `False`, all others to `True`.
+
+    Legacy behavior (hidden unless `with_combined` is False): Adds separate
+    ``-v``/``--var``, ``-e``/``--eval``, -p``/``--path, and
+    ``-P``/``--proxy`` arguments.
+
+    Use ``with_combined=False`` to get legacy behavior.
+    Use ``with_combined=LETTER`` to change the default from ``-s``.
+
+    In new mode, Legacy short options are not availabile;
+    long options are available but hidden.
+
+    All arguments are of the form "-X path value". A path consisting of a
+    single ``+`` expands to ``:n:n`` for easy appending to argument lists.
+    Use ``:=`` if you ever need a path that consist of a single plus character.
+    """
+
+    def _proc(proc):
+        if with_combined:
+            ht = []
+            if with_var:
+                ht.append("~str")
+            if with_eval:
+                ht.append("=expr")
+            if with_path:
+                ht.append(".path, :path")
+            if with_proxy:
+                ht.append("^proxy")
+            ht = " | ".join(ht)
+
+            args = ("--set",) + (
+                ("-" + ("s" if isinstance(with_combined, bool) else with_combined),)
+                if with_combined
+                else ()
+            )
+            proc = click.option(
+                *args,
+                "set_",
+                nargs=2,
+                type=(str, str),
+                multiple=True,
+                metavar="name|path value",
+                help=f"{par_name} (value: {ht})",
+                hidden=not with_eval or not with_combined,
+            )(proc)
+
+        if with_arglist:
+            proc = click.argument(
+                "args_",
+                nargs=-1,
+                type=str,
+            )(proc)
+
+        args = (f"--{with_path}" if isinstance(with_path, str) else "--path",) + (
+            ("-p",) if with_path else ()
+        )
+        proc = click.option(
+            *args,
+            "path_",
+            nargs=2,
+            type=(P, P),
+            multiple=True,
+            help=f"{par_name} (name value), as path",
+            hidden=not with_path or with_combined,
+        )(proc)
+
+        args = (f"--{with_eval}" if isinstance(with_eval, str) else "--eval",) + (
+            ("-e",) if with_eval is True else ()
+        )
+        proc = click.option(
+            *args,
+            "eval_",
+            nargs=2,
+            type=(P, str),
+            multiple=True,
+            help=f"{par_name} (name value), evaluated",
+            hidden=not with_eval or with_combined,
+        )(proc)
+
+        args = (f"--{with_var}" if isinstance(with_var, str) else "--var",) + (
+            ("-v",) if with_var is True else ()
+        )
+        proc = click.option(
+            *args,
+            "vars_",
+            nargs=2,
+            type=(P, str),
+            multiple=True,
+            help=f"{par_name} (name value)",
+            hidden=not with_var or with_combined,
+        )(proc)
+
+        args = (f"--{with_proxy}" if isinstance(with_proxy, str) else "--proxy",) + (
+            ("-P",) if with_proxy is True else ()
+        )
+        proc = click.option(
+            *args,
+            "proxy_",
+            nargs=2,
+            type=(P, str),
+            multiple=True,
+            help="Remote proxy (name value)",
+            hidden=not with_proxy or with_combined,
+        )(proc)
+
+        return proc
+
+    if proc is None:
+        return _proc
+    else:
+        return _proc(proc)
+
+
+def process_args(
+    val: dict | None = None,
+    set_=(),
+    args_=(),
+    vars_=(),
+    eval_=(),
+    path_=(),
+    proxy_=(),
+    no_path=False,
+    vs=None,
+):
+    """
+    process ``set_``/``args_``/``vars_``/``eval_``/``path_``/``proxy_`` args.
+
+    Arguments:
+        val: dict to modify
+        set_, vars_, args_, eval_, path_, proxy_: via `attr_args`
+        vs: if given: set of vars
+    Returns:
+        the new value.
+    """
+    # otherwise these are assumes to be empty tuples.
+    if isinstance(set_, Mapping):
+        set_ = set_.items()
+    if isinstance(vars_, Mapping):
+        vars_ = vars_.items()
+    if isinstance(eval_, Mapping):
+        eval_ = eval_.items()
+    if isinstance(path_, Mapping):
+        path_ = path_.items()
+    if isinstance(proxy_, Mapping):
+        proxy_ = proxy_.items()
+
+    def data():
+        def s_eval(v):
+            if v[0] == "~":
+                v = v[1:]
+            elif v == "=-":
+                v = NotGiven
+            elif v == "=t":
+                v = True
+            elif v == "=f":
+                v = False
+            elif v == "=n":
+                v = None
+            elif v[0] == "=":
+                v = cmd_eval(v[1:])  # pylint: disable=W0631
+            elif v[0] == ":":
+                v = P(v)
+            elif v[0] == ".":
+                v = P(v[1:])
+            elif v[0] == "^":
+                v = Proxy(v[1:])
+            else:
+                try:
+                    v = int(v)
+                except ValueError:
+                    try:
+                        v = float(v)
+                    except ValueError:
+                        pass  # leave it as a string
+            return v
+
+        for k, v in set_:
+            yield k, s_eval(v)
+        for k, v in vars_:
+            yield k, v
+        for k, v in eval_:
+            # ruff:noqa:PLW2901 # var overwritten
+            if v == "-":
+                v = NotGiven
+            elif v == "/":  # pylint: disable=W0631
+                if vs is None:
+                    raise click.BadOptionUsage(
+                        option_name=k,
+                        message="A slash value doesn't work here.",
+                    )
+                v = NoneType
+            else:
+                v = eval(v)  # pylint: disable=W0631
+            yield k, v
+        for k, v in path_:
+            v = P(v)
+            if no_path:
+                v = tuple(v)
+            yield k, v
+        if proxy_:
+            if Proxy is None:
+                raise ImportError("No Proxy")
+            for k, v in proxy_:
+                v = Proxy(v)
+                yield k, v
+
+        # Arguments are given last, thus they get processed last.
+        for v in args_:
+            yield ((None, None), s_eval(v))
+
+    if set_:
+        dd = data()
+    else:
+        dd = [(len(k), k, v) for k, v in data()]
+        dd.sort()
+        dd = [(k, v) for _l, k, v in dd]
+
+    for k, v in dd:
+        if isinstance(k, str):
+            if k == "+":
+                k = Path.build((None, None))
+            else:
+                k = P(k)
+        if val is None:
+            CFG.mod(k, v)
+            continue
+
+        if not len(k):
+            if vs is not None:
+                raise click.BadOptionUsage(
+                    option_name=k,
+                    message="You can't use empty paths here.",
+                )
+            val = v
+            continue
+        if not isinstance(val, Mapping):
+            val = attrdict()
+        if vs is not None:
+            vs.add(str(k))
+        if v is NotGiven:
+            val = attrdict._delete(val, k)  # pylint: disable=protected-access
+        elif v is NoneType:
+            val = attrdict._delete(val, k)  # pylint: disable=protected-access
+            vs.discard(str(k))
+        else:
+            val = attrdict._update(val, k, v)  # pylint: disable=protected-access
+    return val
+
+
+def load_ext(name, *attr, err=False):
+    """
+    Load a module
+    """
+    path = name.split(".")
+    path.extend(attr[:-1])
+    dp = ".".join(path)
+    ".".join(path[:-1])
+    try:
+        mod = importlib.import_module(dp)
+    except ModuleNotFoundError as exc:
+        if err and not exc.name.endswith("._main"):
+            logger.debug("Err %s: %r", dp, exc, exc_info=exc)
+        return None
+    except FileNotFoundError:
+        if err:
+            raise
+        return None
+    else:
+        if attr:
+            try:
+                mod = getattr(mod, attr[-1])
+            except AttributeError:
+                logger.debug("Err %s.%s", dp, attr[-1])
+                return None
+        return mod
+
+
+def _namespaces(name):
+    import pkgutil  # pylint: disable=import-outside-toplevel  # noqa: PLC0415
+
+    if name is NotGiven:
+        return ()
+    try:
+        ext = importlib.import_module(name)
+    except ModuleNotFoundError:
+        logger.debug("No NS: %s", name)
+        return ()
+    try:
+        p = ext.__path__
+    except AttributeError:
+        p = (str(FSPath(ext.__file__).parent),)
+    logger.debug("NS: %s %s", name, p)
+    return pkgutil.iter_modules(p, ext.__name__ + ".")
+
+
+_ext_cache = defaultdict(dict)
+
+
+def _cache_ext(ext_name, pkg_only):
+    """List external modules
+
+    Yields (name,path) tuples.
+
+    TODO: This is not zip safe.
+    """
+    for finder, name, ispkg in _namespaces(ext_name):
+        if pkg_only and not ispkg:
+            logger.debug("ExtNoC %s", name)
+            continue
+        logger.debug("ExtC %s", name)
+        x = name.rsplit(".", 1)[-1]
+        f = FSPath(finder.path) / x
+        _ext_cache[ext_name][x] = f
+
+
+def list_ext(name, func=None, pkg_only=True):
+    """List external modules
+
+    Yields (name,path) tuples.
+
+    TODO: This is not zip safe.
+    """
+    logger.debug("List Ext %s (%s)", name, func)
+    if name not in _ext_cache:
+        with suppress(ModuleNotFoundError):
+            _cache_ext(name, pkg_only)
+    if func is None:
+        for a, b in _ext_cache[name].items():
+            logger.debug("Found %s %s", a, b)
+            yield a, b
+        return
+
+    for x, f in _ext_cache[name].items():
+        if (f / ".no_load").is_file():
+            logger.debug("Skip %s", f)
+            continue
+        fn = f / (func + ".py")
+        if not fn.is_file():
+            fn = f / func / "__init__.py"
+            if not fn.is_file():
+                # XXX this might be a namespace
+                logger.debug("No file: %s/%s", f, func)
+                continue
+        logger.debug("Found2 %s %s", x, f)
+        yield (x, f)
+
+
+def load_subgroup(
+    _fn=None,
+    prefix=None,
+    sub_pre=None,
+    sub_post=None,
+    ext_pre=None,
+    ext_post=None,
+    **kw,
+) -> click.Command:
+    """
+    A decorator like click.group, enabling loading of subcommands
+
+    Internal extensions are loaded as ``{sub_pre}.*.{sub_post}``.
+    External extensions are loaded as ``{ext_pre}.*.{ext_post}``.
+
+    All other arguments are forwarded to `click.command`.
+    """
+
+    def _ext(fn, **kw):
+        return click.command(**kw)(fn)
+
+    kw["cls"] = partial(
+        kw.get("cls", Loader),
+        _util_sub_pre=sub_pre or this_load.get() or prefix,
+        _util_sub_post=sub_post or (None if prefix is None else "cli"),
+        _util_ext_pre=ext_pre or prefix,
+        _util_ext_post=ext_post or (None if prefix is None else "_main.cli"),
+    )
+
+    if _fn is None:
+        return partial(_ext, **kw)
+    else:
+        return _ext(_fn, **kw)
+
+
+class Loader(click.Group):
+    """
+    A `click.group` that loads additional commands from subfolders and/or extensions.
+
+    Subfolders: set _util_sub_pre to your module's name.
+        This works with namespace packages.
+        E.g. "distkv.command" loads "distkv.command.*.cli".
+
+    Extensions: set _util_ext_pre to the extension basename.
+        Set _util_ext_post to the name of the extension.
+
+        E.g. "distkv_ext"+"client" loads "distkv_ext.*.client.cli".
+
+    Both work in parallel.
+
+    Caller:
+
+        from moat.util import Loader
+        from functools import partial
+
+        @click.command(cls=partial(Loader,_util_sub_post='command'))
+        async def cmd()
+            print("I am the main program")
+
+    Sub-Command Usage (``main`` is defined for you), e.g. in ``command/subcmd.py``::
+
+        from moat.util import Loader
+        from functools import partial
+
+        @main.command / group()
+        async def cmd(self):
+            print("I am", self.name)  # prints "subcmd"
+    """
+
+    # ruff:noqa:SLF001
+
+    def __init__(
+        self,
+        *,
+        _util_sub_pre=None,
+        _util_sub_post=None,
+        _util_ext_pre=None,
+        _util_ext_post=None,
+        **kw,
+    ):
+        logger.debug(
+            "* Load: %s.*.%s / %s.*.%s",
+            _util_sub_pre,
+            _util_sub_post,
+            _util_ext_pre,
+            _util_ext_post,
+        )
+        if _util_sub_pre is not None:
+            self._util_sub_pre = _util_sub_pre
+        if _util_sub_post is not None:
+            self._util_sub_post = _util_sub_post
+        if _util_ext_pre is not None:
+            self._util_ext_pre = _util_ext_pre
+        if _util_ext_post is not None:
+            self._util_ext_post = _util_ext_post
+        super().__init__(**kw)
+
+    def get_sub_ext(self, ctx):
+        """Fetch extension variables"""
+        sub_pre = getattr(
+            # pylint: disable=protected-access
+            self,
+            "_util_sub_pre",
+            ctx.obj._util_sub_pre,
+        )
+        sub_post = getattr(
+            # pylint: disable=protected-access
+            self,
+            "_util_sub_post",
+            ctx.obj._util_sub_post,
+        )
+        ext_pre = getattr(
+            # pylint: disable=protected-access
+            self,
+            "_util_ext_pre",
+            ctx.obj._util_ext_pre,
+        )
+        ext_post = getattr(
+            # pylint: disable=protected-access
+            self,
+            "_util_ext_post",
+            ctx.obj._util_ext_post,
+        )
+
+        if sub_pre is None:
+            sub_post = None
+        elif sub_post is None:
+            sub_pre = ("cli",)
+        elif isinstance(sub_post, str):
+            sub_post = sub_post.split(".")
+
+        if ext_pre is None:
+            ext_post = None
+        elif ext_post is None:
+            ext_pre = None
+        elif isinstance(ext_post, str):
+            ext_post = ext_post.split(".")
+            if len(ext_post) == 1:
+                ext_post.append("cli")
+
+        return sub_pre, sub_post, ext_pre, ext_post
+
+    def list_commands(self, ctx):
+        "show subpackages"
+        rv = super().list_commands(ctx)
+        sub_pre, sub_post, ext_pre, ext_post = self.get_sub_ext(ctx)
+        logger.debug("* List: %s.*.%s / %s.*.%s", sub_pre, sub_post, ext_pre, ext_post)
+
+        if sub_pre:
+            logger.debug("Adding sub %s", sub_pre)
+            for _finder, name, _ispkg in _namespaces(sub_pre):
+                # ruff:noqa:PLW2901 # var overwritten
+                name = name.rsplit(".", 1)[1]
+                if name[0] == "_":
+                    continue
+                if load_ext(sub_pre, name, *sub_post, err=ctx.obj.debug_loader):
+                    rv.append(name)
+
+        if ext_pre:
+            logger.debug("Adding ext %s", ext_pre)
+            for n, _ in list_ext(ext_pre):
+                if load_ext(ext_pre, n, *ext_post, err=ctx.obj.debug_loader):
+                    rv.append(n)
+        rv.sort()
+        logger.debug("List: %r", rv)
+        return rv
+
+    def get_command(self, ctx, cmd_name):
+        "add subpackages"
+        command = super().get_command(ctx, cmd_name)
+
+        sub_pre, sub_post, ext_pre, ext_post = self.get_sub_ext(ctx)
+
+        if command is None and ext_pre is not None:
+            command = load_ext(ext_pre, cmd_name, *ext_post)
+            if command is not None:
+                CFG.with_(f"{ext_pre}.{cmd_name}")
+
+        if command is None:
+            if sub_pre is None or sub_pre is NotGiven:
+                return None
+            if sub_post is None or sub_post is NotGiven:
+                pass
+            else:
+                command = load_ext(sub_pre, cmd_name, *sub_post)
+                if command is not None:
+                    CFG.with_(f"{sub_pre}.{cmd_name}")
+
+        if command is None:
+            # raise click.UsageError(f"No such subcommand: {cmd_name}")
+            return None
+        command.__name__ = command.name = cmd_name
+        return command
+
+
+class MainLoader(Loader):
+    """
+    A special loader that runs the main setup code even if there's a
+    subcommand with "--help".
+    """
+
+    async def invoke(self, ctx):
+        if not getattr(ctx, "_moat_invoked", False):
+            await ctx.invoke(self.callback, **ctx.params)
+        return await super().invoke(ctx)
+
+
+#
+# There are two ways this can start up.
+# (a) `main_` is the "real" main function. It sets up the Click environment and then
+#     starts anyio and runs the function body, which calls `wrap_main`
+#     synchronously to set up our object.
+#
+# (b) `wrap_main` is used as a wrapper, used mainly for testing. It sets up the context
+#     and then returns "main_.main()", which is an awaitable, thus
+#     `wrap_main` acts as an async function.
+
+
+@load_subgroup(
+    cls=MainLoader,
+    add_help_option=False,
+    invoke_without_command=True,
+)  # , __file__, "command"))
+@click.option("-V", "--verbose", count=True, help="Be more verbose. Can be used multiple times.")
+@click.option("-L", "--debug-loader", is_flag=True, help="Debug submodule loading.")
+@click.option("-Q", "--quiet", count=True, help="Be less verbose. Opposite of '--verbose'.")
+@click.option("-D", "--debug", count=True, help="Enable debug speed-ups (smaller keys etc).")
+@click.option(
+    "-l",
+    "--log",
+    multiple=True,
+    help="Adjust log level. Example: '--log asyncactor=DEBUG'.",
+)
+@click.option(
+    "-c",
+    "--cfg",
+    "cfg_files",
+    type=click.Path("r"),
+    default=None,
+    help="Configuration file (YAML).",
+    multiple=True,
+)
+@click.option(
+    "-h",
+    "-?",
+    "--help",
+    is_flag=True,
+    help="Show help. Subcommands only understand '--help'.",
+)
+@attr_args(par_name="Config item")
+@click.pass_context
+async def main_(ctx, verbose, quiet, help=False, **kv):  # pylint: disable=redefined-builtin
+    """
+    This is the main command. (You might want to override this text.)
+
+    You need to add a subcommand for this to do anything.
+    """
+    ctx.allow_interspersed_args = True
+
+    # The above `MainLoader.invoke` call causes this code to be called
+    # twice instead of never.
+    if hasattr(ctx, "_moat_invoked"):
+        return
+    ctx._moat_invoked = True  # pylint: disable=protected-access
+    cfg = current_cfg.get()
+    if cfg is not None:
+        kv["cfg"] = cfg
+    wrap_main(ctx=ctx, verbose=max(0, 1 + verbose - quiet), **kv)
+    try:
+        main = ctx.obj.moat.main_cmd
+    except AttributeError:
+        main = None
+    if help or (
+        main is None
+        and ctx.invoked_subcommand is None
+        and not ctx.args
+        and not ctx._protected_args
+    ):
+        print(ctx.get_help())
+        await ctx.aexit()
+    elif main is not None:
+        await main(ctx)
+
+
+def wrap_main(  # pylint: disable=redefined-builtin,inconsistent-return-statements
+    main=main_,
+    *,
+    set_=(),
+    vars_=(),
+    eval_=(),
+    path_=(),
+    proxy_=(),
+    name=None,
+    sub_pre=None,
+    sub_post=None,
+    ext_pre=None,
+    ext_post=None,
+    ext_name: str | None = None,
+    cfg: attrdict | None | Literal[False] = None,
+    cfg_files: str | Sequence[str] = (),
+    cfg_load_all: bool | None = True,
+    args=None,
+    wrap=False,
+    verbose=1,
+    debug=0,
+    debug_loader=False,
+    log=(),
+    ctx=None,
+    help=None,
+) -> Awaitable:
+    """
+    The main command entry point, when testing.
+
+    main: special main function, defaults to moat.run.main_
+    name: command name, defaults to {main}'s toplevel module name.
+    {sub,ext}_{pre,post}: commands to load in submodules or extensions.
+
+    cfg: additional configuration to preconfigure
+    cfg_files: additional configuration file(s) to load
+    cfg_load_all: Flag whether to load the default config file(s): True=all,
+        False=first found, None=No.
+
+    wrap: Flag: this is a subcommand. Don't set up logging, return the awaitable.
+    args: Argument list if called from a test, `None` otherwise.
+    help: Help text of your code.
+
+    Internal extensions are loaded as ``{sub_pre}.*.{sub_post}``.
+    External extensions are loaded as ``{ext_pre}.*.{ext_post}``.
+
+    cfg.moat may contain values for {sub,ext}_{pre,post}.
+    """
+
+    obj = getattr(ctx, "obj", None)
+    if obj is None:
+        obj = attrdict()
+
+    opts = obj.get("moat", None)
+    if opts is None:
+        obj.moat = opts = attrdict()
+
+    if sub_pre is None:
+        sub_pre = opts.get("sub_pre", None)
+    else:
+        opts["sub_pre"] = sub_pre
+
+    if sub_post is None:
+        sub_post = opts.get("sub_post", None)
+    else:
+        opts["sub_post"] = sub_post
+
+    if ext_pre is None:
+        ext_pre = opts.get("ext_pre", None)
+    else:
+        opts["ext_pre"] = ext_pre
+
+    if ext_post is None:
+        ext_post = opts.get("ext_post", None)
+    else:
+        opts["ext_post"] = ext_post
+
+    # Name defaults to "moat", of course ;-)
+    if name is None:
+        name = opts.setdefault("name", "moat")
+    else:
+        opts["name"] = name
+
+    if sub_pre is True:
+        "discover from caller"
+        import inspect  # pylint: disable=import-outside-toplevel  # noqa: PLC0415
+
+        sub_pre = inspect.currentframe().f_back.f_globals["__package__"]
+    elif sub_pre is None:
+        sub_pre = name
+    if sub_post is None:
+        sub_post = "_main.cli"
+
+    if main is None:
+        if help is not None:
+            raise RuntimeError("You can't set the help text this way")
+    else:
+        main.context_settings["obj"] = obj
+        if help is not None:
+            main.help = help
+
+    obj._util_sub_pre = sub_pre  # pylint: disable=protected-access
+    obj._util_sub_post = sub_post  # pylint: disable=protected-access
+    obj._util_ext_pre = ext_pre  # pylint: disable=protected-access
+    obj._util_ext_post = ext_post  # pylint: disable=protected-access
+
+    if not isinstance(cfg, CfgStore):
+        cfg = CfgStore(name, preload=cfg, load_all=cfg_load_all, ext=ext_name)
+        CFG.set_real_cfg(cfg)
+
+    if isinstance(cfg_files, str):
+        cfg_files = (cfg_files,)
+    for fn in cfg_files:
+        cfg.add(fn)
+
+    # our toplevel config file(s)
+    CFG.with_("moat")
+    if name != "moat":
+        CFG.with_(name)
+
+    obj.debug = verbose
+    obj.DEBUG = debug
+
+    if wrap:
+        pass
+    elif hasattr(logging.root, "_MoaT"):
+        logging.debug("Logging already set up")  # noqa:LOG015
+    else:
+        # Configure logging. This is a somewhat arcane art.
+        cfg.mod(
+            P("logging.root.level"),
+            "DEBUG"
+            if verbose > 2
+            else "INFO"
+            if verbose > 1
+            else "WARNING"
+            if verbose
+            else "ERROR",
+        )
+        for k in log:
+            k, v = k.split("=")
+            cfg.mod(P("logging.loggers") / k / "level", v)
+        logging.config.dictConfig(cfg.logging)
+
+    process_args(
+        set_=set_,
+        vars_=vars_,
+        eval_=eval_,
+        path_=path_,
+        proxy_=proxy_,
+    )
+
+    try:
+        in_test = cfg.env.in_test
+    except AttributeError:
+        pass
+    else:
+        in_test(cfg)
+
+    if not wrap and not hasattr(logging.root, "_MoaT"):
+        logging.basicConfig = _no_config
+        logging.config.dictConfig = _no_config
+        logging.config.fileConfig = _no_config
+
+        logging.captureWarnings(verbose > 0)
+        logger.disabled = False
+        if debug_loader:
+            logger.level = logging.DEBUG
+            for p in sys.path:
+                logger.debug("Path: %s", p)
+        logging.root._MoaT = True
+
+    obj.logger = logging.getLogger(name)
+    obj.debug_loader = debug_loader
+    obj.cfg = cfg.result[name]
+    try:
+        obj.stdout = cfg.result.env.stdout
+    except AttributeError:
+        obj.stdout = sys.stdout
+
+    try:
+        # pylint: disable=no-value-for-parameter,unexpected-keyword-arg
+        # NOTE this return an awaitable
+        if ctx is not None:
+            ctx.obj = obj
+        elif main is not None:
+            if wrap:
+                main = main.main
+            with ungroup():
+                return main(args=args, standalone_mode=False, obj=obj)
+
+    except click.exceptions.MissingParameter as exc:
+        print(
+            f"You need to provide an argument {exc.param.name.upper()!r}.\n",
+            file=sys.stderr,
+        )
+        print(exc.cmd.get_help(exc.ctx), file=sys.stderr)
+        sys.exit(2)
+    except click.exceptions.UsageError as exc:
+        try:
+            s = str(exc)
+        except TypeError:
+            logger.exception("??", exc_info=exc)
+        else:
+            print(s, file=sys.stderr)
+        sys.exit(2)
+    except click.exceptions.Abort:
+        print("Aborted.", file=sys.stderr)
+
+
+def _ng(type_):
+    @wraps(type_)
+    def gen(data):
+        if data is NotGiven:
+            return data
+        return type_(data)
+
+    return gen
+
+
+def option_ng(*a, type=str, **kw):  # noqa: A002, D103
+    return click.option(*a, **kw, type=_ng(type), default=NotGiven)

moat_lib_run-0.1.1/src/moat_lib_run.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: moat-lib-run
+Version: 0.1.1
+Summary: Main command entry point infrastructure for MoaT applications
+Maintainer-email: Matthias Urlichs <matthias@urlichs.de>
+Project-URL: homepage, https://m-o-a-t.org
+Project-URL: repository, https://github.com/M-o-a-T/moat
+Keywords: MoaT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AnyIO
+Classifier: Framework :: Trio
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: anyio~=4.0
+Requires-Dist: moat-util~=0.61.1
+Requires-Dist: asyncclick~=8.0
+Requires-Dist: simpleeval~=1.0
+Requires-Dist: moat-lib-config~=0.1.0
+Requires-Dist: moat-lib-proxy~=0.1.0
+Dynamic: license-file
+
+# moat-lib-run
+
+% start main
+% start synopsis
+
+Main command entry point infrastructure for MoaT applications.
+
+% end synopsis
+
+This module provides the infrastructure for building command-line interfaces
+for MoaT applications. It includes:
+
+- Command-line argument parsing with Click integration
+- Subcommand loading from internal modules and extensions
+- Configuration file handling
+- Logging setup
+- Main entry point wrappers for testing
+
+## Usage
+
+### Basic command setup
+
+```python
+from moat.lib.run import main_, wrap_main
+
+@main_.command()
+async def my_command(ctx):
+    """A simple command"""
+    print("Hello from my command!")
+```
+
+### Loading subcommands
+
+Use `load_subgroup` to create command groups that automatically load subcommands:
+
+```python
+from moat.lib.run import load_subgroup
+import asyncclick as click
+
+@load_subgroup(prefix="myapp.commands")
+@click.pass_context
+async def cli(ctx):
+    """Main command group"""
+    pass
+```
+
+### Processing command-line arguments
+
+The `attr_args` decorator and `process_args` function provide flexible
+argument handling:
+
+```python
+from moat.lib.run import attr_args, process_args
+
+@main_.command()
+@attr_args(with_path=True)
+async def configure(**kw):
+    """Configure the application"""
+    config = process_args({}, **kw)
+    # config now contains parsed arguments
+```
+
+## Key Functions
+
+- `main_`: The default main command handler
+- `wrap_main`: Wrapper for the main command, useful for testing
+- `load_subgroup`: Decorator to create command groups with automatic subcommand loading
+- `attr_args`: Decorator for adding flexible argument handling to commands
+- `process_args`: Function to process command-line arguments into configuration
+- `Loader`: Click group class that loads commands from submodules and extensions
+
+% end main

moat_lib_run-0.1.1/src/moat_lib_run.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE.txt
+Makefile
+README.md
+pyproject.toml
+debian/.gitignore
+debian/changelog
+debian/control
+debian/rules
+src/moat/lib/run/__init__.py
+src/moat_lib_run.egg-info/PKG-INFO
+src/moat_lib_run.egg-info/SOURCES.txt
+src/moat_lib_run.egg-info/dependency_links.txt
+src/moat_lib_run.egg-info/requires.txt
+src/moat_lib_run.egg-info/top_level.txt

moat_lib_run-0.1.1/src/moat_lib_run.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

moat_lib_run-0.1.1/src/moat_lib_run.egg-info/requires.txt

@@ -0,0 +1,6 @@
+anyio~=4.0
+asyncclick~=8.0
+moat-lib-config~=0.1.0
+moat-lib-proxy~=0.1.0
+moat-util~=0.61.1
+simpleeval~=1.0

moat_lib_run-0.1.1/src/moat_lib_run.egg-info/top_level.txt

@@ -0,0 +1 @@
+moat