pyclig 0.1.0__py3-none-any.whl

pyclig/__init__.py

@@ -0,0 +1,44 @@
+"""A click wrapper with Command Line Interface Guidelines (CLIG) paradigms.
+
+License:
+    SPDX-License-Identifier: Apache-2.0
+"""
+
+from pyclig import options
+from pyclig._core import Command, Context, Group, group, pass_context
+from pyclig._exit import ExitCode
+from pyclig._output import hanging, info, notice
+from pyclig._run import run
+
+__all__: list[str] = [
+    "Command",
+    "Context",
+    "ExitCode",
+    "Group",
+    "group",
+    "hanging",
+    "info",
+    "notice",
+    "options",
+    "pass_context",
+    "run",
+]
+
+
+def __getattr__(name: str) -> str:
+    """Resolve `__version__` on first access, not at import.
+
+    Args:
+        name: The attribute name.
+
+    Returns:
+        The installed version, or `0.0.0+unknown` without metadata.
+
+    Raises:
+        AttributeError: For any other name.
+    """
+    if name == "__version__":
+        from pyclig._run import version
+
+        return version("pyclig")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pyclig/_core.py

@@ -0,0 +1,440 @@
+"""click classes applying the CLIG conventions to a command group.
+
+A `pyclig.group()` gets, on top of click:
+
+- per-run Rich consoles (`ctx.out`, `ctx.err`), created when the run starts
+- `-d/--debug` on every command, accepted before or after the command name
+- `-v/--version`, read from the distribution metadata only when asked
+- `USAGE:` & upper-case headings, an `EXAMPLES:` section & concise help on
+  a bare invocation
+- the runner, which maps every outcome to an exit code (see `pyclig._run`)
+
+License:
+    SPDX-License-Identifier: Apache-2.0
+"""
+
+import functools
+import sys
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any, Concatenate, NoReturn, ParamSpec, TypeVar
+
+import click
+from rich.console import Console
+
+from pyclig import _logging, _run
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+_STATE = "pyclig.state"
+
+
+class HelpFormatter(click.HelpFormatter):
+    """Help with `USAGE:` on its own line & upper-case section headings."""
+
+    def write_usage(
+        self, prog: str, args: str = "", prefix: str | None = None
+    ) -> None:
+        """Write the usage block, headed `USAGE:` on its own line.
+
+        Args:
+            prog: The command path, e.g. `dkais list`.
+            args: The usage pieces after it.
+            prefix: The heading, defaulting to `USAGE:`.
+        """
+        self.write(f"{'':>{self.current_indent}}{prefix or 'USAGE:'}\n")
+        with self.indentation():
+            super().write_usage(prog, args, prefix="")
+
+    def write_heading(self, heading: str) -> None:
+        """Write a section heading in upper case, e.g. `OPTIONS:`.
+
+        Args:
+            heading: The heading.
+        """
+        super().write_heading(heading.upper())
+
+
+class Context(click.Context):
+    """A click context with the run's STDOUT & STDERR consoles.
+
+    NOTE: The consoles live in `ctx.meta`, which every context of a run
+    shares, so `ctx.obj` stays free for the application.
+    """
+
+    formatter_class = HelpFormatter
+
+    def __init__(
+        self,
+        *args: Any,
+        pyclig_state: _run.State | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Create the context.
+
+        Args:
+            *args: Positional `click.Context` arguments.
+            pyclig_state: The run's state, given to the root context.
+            **kwargs: Keyword `click.Context` arguments.
+        """
+        super().__init__(*args, **kwargs)
+        if pyclig_state is not None:
+            self.meta[_STATE] = pyclig_state
+
+    @property
+    def out(self) -> Console:
+        """The STDOUT console, for the command's output."""
+        return _require_state(self).out
+
+    @property
+    def err(self) -> Console:
+        """The STDERR console, for messages, logs & live displays."""
+        return _require_state(self).err
+
+
+def _state(ctx: click.Context) -> _run.State | None:
+    """Return the run's state, if the run was started by `Group.main`."""
+    state = ctx.meta.get(_STATE)
+    return state if isinstance(state, _run.State) else None
+
+
+def _require_state(ctx: click.Context) -> _run.State:
+    """Return the run's state, or raise when there is none."""
+    state = _state(ctx)
+    if state is None:
+        raise RuntimeError("the consoles exist only within a pyclig.Group run")
+    return state
+
+
+def _package(ctx: click.Context) -> str:
+    """Return the application package of the run."""
+    state = _state(ctx)
+    return state.package if state else ctx.find_root().info_name or ""
+
+
+def pass_context(f: Callable[Concatenate[Context, P], R]) -> Callable[P, R]:
+    """Pass the current `pyclig.Context` as the first argument.
+
+    Args:
+        f: The command function.
+
+    Returns:
+        The wrapped function.
+    """
+
+    def new_func(*args: P.args, **kwargs: P.kwargs) -> R:
+        ctx = click.get_current_context()
+        if not isinstance(ctx, Context):
+            raise TypeError(
+                f"{f.__name__} must be a command of a pyclig.Group, "
+                "not of a plain click.Group"
+            )
+        return f(ctx, *args, **kwargs)
+
+    return functools.update_wrapper(new_func, f)
+
+
+def _debug(ctx: click.Context, param: click.Parameter, value: bool) -> None:
+    """Switch the run's logging to `DEBUG` as soon as `-d` is parsed."""
+    state = _state(ctx)
+    if value and state and not state.debug and not ctx.resilient_parsing:
+        state.debug = True
+        _logging.configure(state.package, state.err, debug=True)
+
+
+def _show_version(ctx: click.Context) -> str:
+    """Return the `-v/--version` line, e.g. `dkais 0.1.0`."""
+    return f"{ctx.find_root().info_name} {_run.version(_package(ctx))}"
+
+
+class Command(click.Command):
+    """A click command with `-d/--debug` & the pyclig help layout.
+
+    NOTE: `-d` is eager, so it takes effect even when a later option is
+    invalid. Usage errors raised while parsing are bound to this command, so
+    they show its usage.
+    """
+
+    context_class = Context
+
+    def __init__(self, name: str | None = None, **kwargs: Any) -> None:
+        """Create the command.
+
+        Args:
+            name: The command name.
+            **kwargs: Keyword `click.Command` arguments;
+                `options_metavar` defaults to `[options]`.
+        """
+        kwargs.setdefault("options_metavar", "[options]")
+        super().__init__(name, **kwargs)
+        self.params.append(
+            click.Option(
+                ["-d", "--debug"],
+                is_flag=True,
+                is_eager=True,
+                expose_value=False,
+                callback=_debug,
+                help="Show debug logging output.",
+            )
+        )
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        """Parse the arguments, binding a parse-time usage error to `ctx`.
+
+        Args:
+            ctx: The command's context.
+            args: The arguments to parse.
+
+        Returns:
+            The arguments left over for a subcommand.
+        """
+        try:
+            return super().parse_args(ctx, args)
+        except click.UsageError as error:
+            if error.ctx is None:
+                error.ctx = ctx
+            raise
+
+
+class Group(Command, click.Group):
+    """A click group running the CLIG conventions (see module docstring).
+
+    NOTE: Subcommands default to `pyclig.Command` & nested groups to
+    `pyclig.Group`, so `@cli.command()` & `@cli.group()` inherit `-d`.
+
+    Attributes:
+        examples: Example invocations, listed under `EXAMPLES:`.
+        errors: Expected exception types, reported without a traceback.
+    """
+
+    command_class = Command
+    group_class = type
+
+    def __init__(
+        self,
+        name: str | None = None,
+        commands: Any = None,
+        *,
+        examples: Iterable[str] = (),
+        errors: _run.Errors = (),
+        invoke_without_command: bool = True,
+        subcommand_metavar: str | None = "<command>",
+        context_settings: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Create the group.
+
+        Args:
+            name: The group name.
+            commands: The initial subcommands, by name or as a sequence.
+            examples: Example invocations, listed under `EXAMPLES:`.
+            errors: Expected exception types, reported without a traceback.
+            invoke_without_command: Run without a subcommand, printing the
+                concise help.
+            subcommand_metavar: The command placeholder in the usage line.
+            context_settings: Defaults for the context; `-h` & `--help`
+                show help unless `help_option_names` is given.
+            **kwargs: Keyword `click.Group` arguments.
+        """
+        settings = {"help_option_names": ["-h", "--help"]}
+        super().__init__(
+            name,
+            commands=commands,
+            invoke_without_command=invoke_without_command,
+            subcommand_metavar=subcommand_metavar,
+            context_settings=settings | (context_settings or {}),
+            **kwargs,
+        )
+        self.examples = tuple(examples)
+        self.errors = errors
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        """List the subcommands in the order they were added.
+
+        NOTE: click sorts them by name; the order a CLI defines them in is
+        usually its workflow, e.g. `list`, `download`, `process`.
+
+        Args:
+            ctx: The group's context.
+
+        Returns:
+            The subcommand names.
+        """
+        return list(self.commands)
+
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: bool = True,
+        windows_expand_args: bool = False,
+        **extra: Any,
+    ) -> NoReturn:
+        """Run the CLI with fresh consoles & logging, then exit.
+
+        NOTE: Always exits with the mapped code; `standalone_mode` is
+        accepted for click compatibility only. `windows_expand_args`
+        defaults to False, so `*`, `~` & `%VAR%` reach commands as typed on
+        every platform. Use `pyclig.testing.invoke` to run in-process.
+
+        Args:
+            args: The arguments, defaulting to `sys.argv[1:]`.
+            prog_name: The program name, defaulting to the group name.
+            complete_var: The shell completion environment variable.
+            standalone_mode: Ignored.
+            windows_expand_args: Expand globs & variables on Windows.
+            **extra: Keyword `click.Context` arguments.
+        """
+        make_consoles = extra.pop("pyclig_consoles", _run.make_consoles)
+        _run.configure_streams()
+        out, err = make_consoles()
+        prog = prog_name or self.name or "main"
+        package = _run.package_of(self.callback, default=prog)
+        state = _run.State(out, err, package, self.errors)
+        click_main = super().main
+        with _logging.scoped(package):
+            _logging.configure(package, err, debug=False)
+            code = _run.execute(
+                lambda: click_main(
+                    args,
+                    prog,
+                    complete_var,
+                    standalone_mode=False,
+                    windows_expand_args=windows_expand_args,
+                    pyclig_state=state,
+                    **extra,
+                ),
+                state,
+                prog=prog,
+            )
+        sys.exit(code)
+
+    def invoke(self, ctx: click.Context) -> Any:
+        """Invoke the group, printing concise help when no command is given.
+
+        NOTE: Ctrl-C, `EOFError` & broken pipes are carried past click,
+        which would print a blank line, report "Aborted!" or exit silently.
+
+        Args:
+            ctx: The group's context.
+
+        Returns:
+            The subcommand's return value.
+
+        Raises:
+            Interrupted: On Ctrl-C.
+            Escaped: Carrying an `EOFError` or a pipe `OSError`.
+        """
+        try:
+            result = super().invoke(ctx)
+        except KeyboardInterrupt as error:
+            raise _run.Interrupted from error
+        except EOFError as error:
+            raise _run.Escaped(error) from error
+        except OSError as error:
+            if error.errno in _run.PIPE_ERRNOS:
+                raise _run.Escaped(error) from error
+            raise
+        if ctx.invoked_subcommand is None:
+            click.echo(self.get_concise_help(ctx))
+        return result
+
+    def get_concise_help(self, ctx: click.Context) -> str:
+        """Return the concise help printed for a bare invocation.
+
+        Args:
+            ctx: The group's context.
+
+        Returns:
+            The summary & version, description, usage, commands, examples
+            & a `--help` hint.
+        """
+        formatter = ctx.make_formatter()
+        header = _show_version(ctx)
+        formatter.write_text(
+            f"{self.short_help} [{header}]" if self.short_help else header
+        )
+        self.format_help_text(ctx, formatter)
+        formatter.write_paragraph()
+        self.format_usage(ctx, formatter)
+        self.format_commands(ctx, formatter)
+        self.format_examples(ctx, formatter)
+        hint = _run.help_hint(ctx)
+        if hint:
+            formatter.write_paragraph()
+            formatter.write_text(hint)
+        return formatter.getvalue().rstrip("\n")
+
+    def format_examples(
+        self, ctx: click.Context, formatter: click.HelpFormatter
+    ) -> None:
+        """Write the `EXAMPLES:` section, one invocation per line.
+
+        Args:
+            ctx: The group's context.
+            formatter: The help formatter.
+        """
+        if not self.examples:
+            return
+        with formatter.section("Examples"):
+            for example in self.examples:
+                formatter.write(f"{'':>{formatter.current_indent}}{example}\n")
+
+    def format_epilog(
+        self, ctx: click.Context, formatter: click.HelpFormatter
+    ) -> None:
+        """Write the `EXAMPLES:` section, then the epilog.
+
+        Args:
+            ctx: The group's context.
+            formatter: The help formatter.
+        """
+        self.format_examples(ctx, formatter)
+        super().format_epilog(ctx, formatter)
+
+
+def group(
+    name: str | None = None,
+    *,
+    examples: Iterable[str] = (),
+    errors: _run.Errors = (),
+    **kwargs: Any,
+) -> Callable[[Callable[..., Any]], Group]:
+    """Create a `pyclig.Group` with `-v/--version` from a function.
+
+    ```python
+    @pyclig.group(
+        "dkais",
+        short_help="DMA AIS data manager",
+        examples=["dkais list --start 2026-10"],
+        errors=(exceptions.Error,),
+    )
+    def cli() -> None:
+        \"\"\"Download DMA AIS archives and convert them to Parquet.\"\"\"
+    ```
+
+    Args:
+        name: The program name, e.g. `dkais`.
+        examples: Example invocations, listed under `EXAMPLES:`.
+        errors: Expected exception types, reported as `error: message` &
+            exit 1 - the traceback is shown only with `-d`.
+        **kwargs: Keyword `click.Group` arguments, e.g. `short_help` (the
+            concise help summary) & `epilog`.
+
+    Returns:
+        A decorator turning the group callback into a `Group`.
+    """
+
+    def decorator(f: Callable[..., Any]) -> Group:
+        f = click.custom_version_option(
+            _show_version,
+            "-v",
+            "--version",
+            help="Show the version and exit.",
+        )(f)
+        return click.group(
+            name, cls=Group, examples=examples, errors=errors, **kwargs
+        )(f)
+
+    return decorator

pyclig/_exit.py

@@ -0,0 +1,32 @@
+"""Process exit codes shared by every `pyclig` application.
+
+The codes let a script tell a usage mistake from a failed run, a crash or a
+Ctrl-C. `USAGE` is click's own code for usage errors; `INTERNAL` is sysexits
+`EX_SOFTWARE`.
+
+License:
+    SPDX-License-Identifier: Apache-2.0
+"""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """A process exit code.
+
+    NOTE: Members pass `int` type checks (`IntEnum`), so a command can return
+    one & `sys.exit` accepts it.
+
+    Attributes:
+        OK: Success.
+        FAILURE: The command ran but failed, e.g. a download error.
+        USAGE: The command line was invalid.
+        INTERNAL: An unexpected exception, i.e. a bug.
+        INTERRUPT: Interrupted by Ctrl-C (128 + `SIGINT`).
+    """
+
+    OK = 0
+    FAILURE = 1
+    USAGE = 2
+    INTERNAL = 70
+    INTERRUPT = 130

pyclig/_logging.py

@@ -0,0 +1,143 @@
+"""Logging for a CLI run, bound to the run's STDERR console.
+
+Without `-d`, records render as `warning:` / `error:` notices
+(`EventHandler`). With `-d`, a `RichHandler` adds levels, times & call sites.
+
+NOTE: Both handlers write through the console they are given. Pass the same
+STDERR console to any `Progress` or `Status`, so Rich redraws the live
+display around log lines instead of printing through it. The logger's state
+is restored when the run ends, so repeated in-process runs (tests) never
+stack handlers. Library code should only ever add a `NullHandler`, in its
+`__init__.py`:
+
+```python
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+```
+
+License:
+    SPDX-License-Identifier: Apache-2.0
+"""
+
+import contextlib
+import logging
+from collections.abc import Generator
+from datetime import datetime
+
+from rich.console import Console
+from rich.text import Text
+
+from pyclig._output import info, notice, print_exception
+
+DATEFMT = "[%Y-%m-%dT%H:%M:%S%z]"
+"""The `-d` handler's time format, in local time with its UTC offset."""
+
+_MARKER = "_pyclig_handler"
+
+
+class EventHandler(logging.Handler):
+    """Render log records as `warning:` / `error:` lines.
+
+    NOTE: Records below `WARNING` render as dim context lines. A record with
+    `exc_info` (`logger.exception`) is followed by its traceback.
+
+    Attributes:
+        console: The console records are printed to, usually STDERR.
+    """
+
+    def __init__(self, console: Console, level: int = logging.NOTSET) -> None:
+        """Create the handler.
+
+        Args:
+            console: The console to print records to.
+            level: The handler's level.
+        """
+        super().__init__(level)
+        self.console = console
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Print the record as a notice, then any traceback.
+
+        Args:
+            record: The log record.
+        """
+        try:
+            message = record.getMessage()
+            if record.levelno >= logging.ERROR:
+                notice(self.console, level="error", message=message)
+            elif record.levelno >= logging.WARNING:
+                notice(self.console, level="warning", message=message)
+            else:
+                info(self.console, message=message)
+            if record.exc_info and record.exc_info[1] is not None:
+                print_exception(self.console, record.exc_info[1])
+        except Exception:
+            self.handleError(record)
+
+
+def configure(name: str, console: Console, *, debug: bool) -> None:
+    """Attach a CLI handler, bound to `console`, to the `name` logger.
+
+    NOTE: Replaces any handler a previous call added & keeps the rest (e.g.
+    the library `NullHandler`). Records stop at this logger
+    (`propagate = False`), so nothing is printed twice by a root handler.
+
+    Args:
+        name: The logger name, usually the application package.
+        console: The STDERR console of the run.
+        debug: Use the verbose `RichHandler` at `DEBUG`, else the
+            `EventHandler` at `WARNING`.
+    """
+    logger = logging.getLogger(name)
+    _remove_handlers(logger)
+    handler: logging.Handler
+    if debug:
+        from rich.logging import RichHandler
+
+        handler = RichHandler(
+            console=console,
+            show_path=True,
+            rich_tracebacks=True,
+            markup=False,
+            omit_repeated_times=False,
+            log_time_format=_format_time,
+        )
+        handler.setFormatter(logging.Formatter("[%(funcName)s] %(message)s"))
+    else:
+        handler = EventHandler(console)
+    setattr(handler, _MARKER, True)
+    logger.addHandler(handler)
+    logger.setLevel(logging.DEBUG if debug else logging.WARNING)
+    logger.propagate = False
+
+
+@contextlib.contextmanager
+def scoped(name: str) -> Generator[None, None, None]:
+    """Restore the `name` logger's handlers, level & propagation on exit.
+
+    Args:
+        name: The logger name.
+
+    Yields:
+        None, while the run configures the logger.
+    """
+    logger = logging.getLogger(name)
+    saved = logger.handlers[:], logger.level, logger.propagate
+    try:
+        yield
+    finally:
+        _remove_handlers(logger)
+        logger.handlers[:] = saved[0]
+        logger.setLevel(saved[1])
+        logger.propagate = saved[2]
+
+
+def _format_time(when: datetime) -> Text:
+    """Format a record's time with `DATEFMT`, adding the local UTC offset."""
+    return Text(when.astimezone().strftime(DATEFMT))
+
+
+def _remove_handlers(logger: logging.Logger) -> None:
+    """Remove & close the handlers `configure` added to `logger`."""
+    for handler in [h for h in logger.handlers if getattr(h, _MARKER, False)]:
+        logger.removeHandler(handler)
+        handler.close()