cohaerum-cli 0.1.0__tar.gz

cohaerum_cli-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

cohaerum_cli-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.5
+Name: cohaerum-cli
+Version: 0.1.0
+Requires-Python: >=3.12
+Requires-Dist: cohaerum

cohaerum_cli-0.1.0/pyproject.toml

@@ -0,0 +1,12 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cohaerum-cli"
+version = "0.1.0"
+requires-python = ">=3.12"
+
+dependencies = [
+    "cohaerum",
+]

cohaerum_cli-0.1.0/pyrightconfig.json

@@ -0,0 +1,7 @@
+{
+  "venvPath": "../..",
+  "venv": ".venv",
+  "include": ["src"],
+  "exclude": [".venv", "__pycache__"],
+  "pythonVersion": "3.12"
+}

cohaerum_cli-0.1.0/src/cohaerum_cli/__init__.py

@@ -0,0 +1,5 @@
+from .provider import CLIProvider as Provider
+
+name = "cli"
+
+__all__ = ["Provider", "name"]

cohaerum_cli-0.1.0/src/cohaerum_cli/auto.py

@@ -0,0 +1,4 @@
+from cohaerum import register_factory
+from .provider import CLIProvider
+
+register_factory("cli", CLIProvider)

cohaerum_cli-0.1.0/src/cohaerum_cli/provider.py

@@ -0,0 +1,99 @@
+import re
+from collections.abc import Callable, Mapping, Sequence
+from threading import RLock
+from types import MappingProxyType
+from typing import Any
+
+from cohaerum.api import CLI
+
+from .runner import run
+
+_COMMAND_COMPONENT = re.compile(
+    r"^[A-Za-z][A-Za-z0-9_-]*$"
+)
+
+
+class CLIProvider(CLI):
+    """
+    In-memory command registry and CLI dispatcher.
+
+    Commands are registered when application modules containing
+    decorated functions are imported.
+    """
+
+    def __init__(self) -> None:
+        self._commands: dict[
+            str,
+            Callable[..., Any],
+        ] = {}
+        self._lock = RLock()
+
+    @property
+    def commands(
+        self,
+    ) -> Mapping[str, Callable[..., Any]]:
+        return MappingProxyType(self._commands)
+
+    def register[**P, R](
+        self,
+        name: str,
+        function: Callable[P, R],
+    ) -> None:
+        self._validate_name(name)
+
+        if not callable(function):
+            raise TypeError(
+                f"implementation for command {name!r} "
+                "must be callable"
+            )
+
+        with self._lock:
+            if name in self._commands:
+                existing = self._commands[name]
+
+                raise RuntimeError(
+                    f"command {name!r} is already registered by "
+                    f"{existing.__module__}."
+                    f"{existing.__qualname__}"
+                )
+
+            self._commands[name] = function
+
+    def run(
+        self,
+        argv: Sequence[str] | None = None,
+    ) -> int:
+        return run(self.commands, argv)
+
+    @staticmethod
+    def _validate_name(name: str) -> None:
+        if not isinstance(name, str):
+            raise TypeError(
+                "command name must be a string"
+            )
+
+        if not name:
+            raise ValueError(
+                "command name must not be empty"
+            )
+
+        components = name.split(".")
+
+        for component in components:
+            if not component:
+                raise ValueError(
+                    f"command name {name!r} contains "
+                    "an empty component"
+                )
+
+            if _COMMAND_COMPONENT.fullmatch(
+                component
+            ) is None:
+                raise ValueError(
+                    f"invalid command component "
+                    f"{component!r} in {name!r}"
+                )
+
+
+__all__ = ["CLIProvider"]
+

cohaerum_cli-0.1.0/src/cohaerum_cli/runner.py

@@ -0,0 +1,630 @@
+import argparse
+import asyncio
+import difflib
+import inspect
+import sys
+import types
+from collections.abc import Callable, Mapping, Sequence
+from enum import Enum
+from pathlib import Path
+from typing import (
+    IO,
+    Annotated,
+    Any,
+    Literal,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+from uuid import UUID
+
+
+def run(
+    commands: Mapping[str, Callable[..., Any]],
+    argv: Sequence[str] | None = None,
+) -> int:
+    """
+    Resolve and invoke one command from ``argv``.
+    """
+
+    arguments = (
+        list(sys.argv[1:])
+        if argv is None
+        else list(argv)
+    )
+    program = Path(sys.argv[0]).name
+
+    if not arguments:
+        _print_global_help(program, commands)
+        return 0
+
+    if arguments == ["--help"] or arguments == ["-h"]:
+        _print_global_help(program, commands)
+        return 0
+
+    if arguments[0] in commands:
+        return _invoke(
+            program,
+            arguments[0],
+            commands[arguments[0]],
+            list(arguments[1:]),
+        )
+
+    # Prefer the longest matching command. This permits both
+    # "user" and "user.create" to be registered.
+    for count in range(len(arguments), 0, -1):
+        name = ".".join(arguments[:count])
+
+        if name in commands:
+            return _invoke(
+                program,
+                name,
+                commands[name],
+                list(arguments[count:]),
+            )
+
+    # No full command matched; the arguments may name a group
+    # such as "object" when "object.get" is registered.
+    match = _match_group(commands, arguments)
+
+    if match is not None:
+        group, rest = match
+        return _group(program, commands, group, rest)
+
+    _unknown_command(program, commands, arguments)
+    return 2
+
+
+def _print_global_help(
+    program: str,
+    commands: Mapping[str, Callable[..., Any]],
+) -> None:
+    print(
+        f"usage: {program} COMMAND [ARGUMENT ...]\n"
+        "\n"
+        "Invoke a registered command.\n"
+    )
+
+    if not commands:
+        print("No commands are registered.")
+        return
+
+    print("commands:")
+
+    entries: list[tuple[str, str]] = []
+
+    for top in sorted(
+        {name.split(".", 1)[0] for name in commands}
+    ):
+        if top in commands:
+            entries.append((top, _summary(commands[top])))
+        else:
+            entries.append(
+                (top, ", ".join(_children(commands, top)))
+            )
+
+    width = max(len(name) for name, _ in entries)
+
+    for name, summary in entries:
+        if summary:
+            print(f"  {name:<{width}}  {summary}")
+        else:
+            print(f"  {name}")
+
+
+def _summary(
+    function: Callable[..., Any],
+) -> str:
+    documentation = inspect.getdoc(function)
+
+    if not documentation:
+        return ""
+
+    return documentation.splitlines()[0]
+
+
+def _children(
+    commands: Mapping[str, Callable[..., Any]],
+    group: str,
+) -> list[str]:
+    prefix = group + "."
+
+    return sorted(
+        {
+            name[len(prefix):].split(".", 1)[0]
+            for name in commands
+            if name.startswith(prefix)
+        }
+    )
+
+
+def _child_summaries(
+    commands: Mapping[str, Callable[..., Any]],
+    group: str,
+) -> dict[str, str]:
+    summaries: dict[str, str] = {}
+
+    for child in _children(commands, group):
+        name = group + "." + child
+
+        if name in commands:
+            summaries[child] = _summary(commands[name])
+        else:
+            summaries[child] = ", ".join(_children(commands, name))
+
+    return summaries
+
+
+def _print_group_help(
+    program: str,
+    commands: Mapping[str, Callable[..., Any]],
+    group: str,
+    file: IO[str] | None = None,
+) -> None:
+    if file is None:
+        file = sys.stdout
+
+    print(
+        f"usage: {program} {group.replace('.', ' ')} "
+        f"<command> [ARGUMENT ...]\n"
+        "\n"
+        f"Subcommands of '{group}':\n",
+        file=file,
+    )
+
+    summaries = _child_summaries(commands, group)
+    width = max((len(name) for name in summaries), default=0)
+
+    for name, summary in summaries.items():
+        if summary:
+            print(
+                f"  {name:<{width}}  {summary}",
+                file=file,
+            )
+        else:
+            print(f"  {name}", file=file)
+
+
+def _match_group(
+    commands: Mapping[str, Callable[..., Any]],
+    arguments: Sequence[str],
+) -> tuple[str, list[str]] | None:
+    match: tuple[str, list[str]] | None = None
+
+    for count in range(1, len(arguments) + 1):
+        prefix = ".".join(arguments[:count])
+
+        if any(
+            name.startswith(prefix + ".")
+            for name in commands
+        ):
+            match = (
+                prefix,
+                list(arguments[count:]),
+            )
+
+    return match
+
+
+def _group(
+    program: str,
+    commands: Mapping[str, Callable[..., Any]],
+    group: str,
+    rest: Sequence[str],
+) -> int:
+    if not rest:
+        _print_group_help(
+            program,
+            commands,
+            group,
+            file=sys.stderr,
+        )
+        return 2
+
+    if rest == ["--help"] or rest == ["-h"]:
+        _print_group_help(program, commands, group)
+        return 0
+
+    children = _children(commands, group)
+    suggestion = _suggest(rest[0], children)
+
+    message = (
+        f"unknown command: {' '.join([group, *rest])}"
+    )
+
+    if suggestion is not None:
+        message += f"\ndid you mean '{group} {suggestion}'?"
+
+    message += (
+        f"\ntry '{program} {group.replace('.', ' ')} --help'"
+        " for a list of subcommands."
+    )
+
+    parser = argparse.ArgumentParser(
+        prog=program,
+        add_help=False,
+    )
+    parser.error(message)
+
+
+def _unknown_command(
+    program: str,
+    commands: Mapping[str, Callable[..., Any]],
+    arguments: Sequence[str],
+) -> None:
+    tops = sorted(
+        {name.split(".", 1)[0] for name in commands}
+    )
+    suggestion = _suggest(
+        arguments[0],
+        tops + sorted(commands),
+    )
+
+    message = f"unknown command: {' '.join(arguments)}"
+
+    if suggestion is not None:
+        message += f"\ndid you mean '{suggestion}'?"
+
+    message += (
+        f"\navailable: {', '.join(tops)}"
+    )
+
+    parser = argparse.ArgumentParser(
+        prog=program,
+        add_help=False,
+    )
+    parser.error(message)
+
+
+def _suggest(
+    value: str,
+    candidates: Sequence[str],
+) -> str | None:
+    matches = difflib.get_close_matches(
+        value,
+        sorted(set(candidates)),
+        n=1,
+        cutoff=0.6,
+    )
+
+    return matches[0] if matches else None
+
+
+def _invoke(
+    program: str,
+    command_name: str,
+    function: Callable[..., Any],
+    arguments: Sequence[str],
+) -> int:
+    parser, positional_names, keyword_names = (
+        _create_command_parser(
+            program,
+            command_name,
+            function,
+        )
+    )
+
+    values = vars(parser.parse_args(arguments))
+
+    positional = [
+        values[name]
+        for name in positional_names
+    ]
+    keyword = {
+        name: values[name]
+        for name in keyword_names
+    }
+
+    result = function(*positional, **keyword)
+
+    if inspect.isawaitable(result):
+        result = asyncio.run(result)
+
+    if result is None:
+        return 0
+
+    if isinstance(result, int) and not isinstance(
+        result,
+        bool,
+    ):
+        return result
+
+    print(result)
+    return 0
+
+
+def _create_command_parser(
+    program: str,
+    command_name: str,
+    function: Callable[..., Any],
+) -> tuple[
+    argparse.ArgumentParser,
+    list[str],
+    list[str],
+]:
+    signature = inspect.signature(function)
+
+    try:
+        annotations = get_type_hints(
+            function,
+            include_extras=True,
+        )
+    except Exception as error:
+        raise TypeError(
+            f"cannot resolve annotations for command "
+            f"{command_name!r}"
+        ) from error
+
+    parser = argparse.ArgumentParser(
+        prog=(
+            f"{program} "
+            f"{command_name.replace('.', ' ')}"
+        ),
+        description=inspect.getdoc(function),
+        formatter_class=(
+            argparse.RawDescriptionHelpFormatter
+        ),
+    )
+
+    positional_names: list[str] = []
+    keyword_names: list[str] = []
+
+    for parameter in signature.parameters.values():
+        if parameter.kind is (
+            inspect.Parameter.VAR_POSITIONAL
+        ):
+            raise TypeError(
+                f"command {command_name!r} uses "
+                f"unsupported *{parameter.name}"
+            )
+
+        if parameter.kind is (
+            inspect.Parameter.VAR_KEYWORD
+        ):
+            raise TypeError(
+                f"command {command_name!r} uses "
+                f"unsupported **{parameter.name}"
+            )
+
+        annotation = annotations.get(
+            parameter.name,
+            parameter.annotation,
+        )
+
+        if annotation is inspect.Parameter.empty:
+            annotation = str
+
+        converter, choices = _converter(annotation)
+
+        if parameter.kind in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        ):
+            _add_positional(
+                parser,
+                parameter,
+                converter,
+                choices,
+            )
+            positional_names.append(parameter.name)
+            continue
+
+        if parameter.kind is (
+            inspect.Parameter.KEYWORD_ONLY
+        ):
+            _add_option(
+                parser,
+                parameter,
+                annotation,
+                converter,
+                choices,
+            )
+            keyword_names.append(parameter.name)
+            continue
+
+        raise TypeError(
+            f"unsupported parameter kind for "
+            f"{parameter.name!r}"
+        )
+
+    return parser, positional_names, keyword_names
+
+
+def _add_positional(
+    parser: argparse.ArgumentParser,
+    parameter: inspect.Parameter,
+    converter: Callable[[str], Any],
+    choices: Sequence[Any] | None,
+) -> None:
+    options: dict[str, Any] = {
+        "type": converter,
+    }
+
+    if choices is not None:
+        options["choices"] = choices
+
+    if parameter.default is not inspect.Parameter.empty:
+        options["nargs"] = "?"
+        options["default"] = parameter.default
+
+    parser.add_argument(
+        parameter.name,
+        **options,
+    )
+
+
+def _add_option(
+    parser: argparse.ArgumentParser,
+    parameter: inspect.Parameter,
+    annotation: Any,
+    converter: Callable[[str], Any],
+    choices: Sequence[Any] | None,
+) -> None:
+    option = (
+        "--"
+        + parameter.name.replace("_", "-")
+    )
+    required = (
+        parameter.default
+        is inspect.Parameter.empty
+    )
+    default = (
+        None
+        if required
+        else parameter.default
+    )
+
+    base_annotation = _normalize_optional(
+        _strip_annotated(annotation)
+    )
+
+    if base_annotation is bool:
+        parser.add_argument(
+            option,
+            dest=parameter.name,
+            action=argparse.BooleanOptionalAction,
+            required=required,
+            default=default,
+        )
+        return
+
+    options: dict[str, Any] = {
+        "dest": parameter.name,
+        "type": converter,
+        "required": required,
+        "default": default,
+    }
+
+    if choices is not None:
+        options["choices"] = choices
+
+    parser.add_argument(option, **options)
+
+
+def _converter(
+    annotation: Any,
+) -> tuple[
+    Callable[[str], Any],
+    Sequence[Any] | None,
+]:
+    annotation = _strip_annotated(annotation)
+    annotation = _normalize_optional(annotation)
+
+    origin = get_origin(annotation)
+
+    if origin is Literal:
+        values = get_args(annotation)
+
+        if not values:
+            raise TypeError(
+                "empty Literal is not supported"
+            )
+
+        value_types = {
+            type(value)
+            for value in values
+        }
+
+        if len(value_types) != 1:
+            raise TypeError(
+                "Literal parameters must contain "
+                "one value type"
+            )
+
+        value_type = next(iter(value_types))
+        converter, _ = _converter(value_type)
+
+        return converter, values
+
+    if annotation in (Any, str):
+        return str, None
+
+    if annotation is int:
+        return int, None
+
+    if annotation is float:
+        return float, None
+
+    if annotation is bool:
+        return _parse_bool, None
+
+    if annotation is Path:
+        return Path, None
+
+    if annotation is UUID:
+        return UUID, None
+
+    if (
+        inspect.isclass(annotation)
+        and issubclass(annotation, Enum)
+    ):
+        return annotation, list(annotation)
+
+    raise TypeError(
+        "unsupported CLI parameter annotation: "
+        f"{annotation!r}"
+    )
+
+
+def _strip_annotated(annotation: Any) -> Any:
+    if get_origin(annotation) is Annotated:
+        return get_args(annotation)[0]
+
+    return annotation
+
+
+def _normalize_optional(annotation: Any) -> Any:
+    origin = get_origin(annotation)
+
+    if origin not in (Union, types.UnionType):
+        return annotation
+
+    arguments = get_args(annotation)
+    non_none = [
+        argument
+        for argument in arguments
+        if argument is not type(None)
+    ]
+
+    if len(non_none) == len(arguments):
+        raise TypeError(
+            f"unsupported union annotation: "
+            f"{annotation!r}"
+        )
+
+    if len(non_none) != 1:
+        raise TypeError(
+            f"unsupported union annotation: "
+            f"{annotation!r}"
+        )
+
+    return non_none[0]
+
+
+def _parse_bool(value: str) -> bool:
+    normalized = value.casefold()
+
+    if normalized in {
+        "1",
+        "true",
+        "yes",
+        "on",
+    }:
+        return True
+
+    if normalized in {
+        "0",
+        "false",
+        "no",
+        "off",
+    }:
+        return False
+
+    raise argparse.ArgumentTypeError(
+        f"expected a boolean value, got {value!r}"
+    )
+
+
+__all__ = ["run"]
+