airpuls-sdk-cli 0.1.4__py3-none-any.whl

airpuls_sdk_cli/__init__.py

@@ -0,0 +1,39 @@
+"""airpuls-sdk — command-line tool for xApp project scaffolding and lifecycle.
+
+Published as the pure-Python ``airpuls-sdk-cli`` distribution, separate
+from the ``airpuls-ric-sdk`` xApp runtime: the tool never imports the
+runtime, so it installs and works on every platform a developer works
+from, while the runtime ships as a Linux x86_64 binary wheel.  Commands
+that execute an xApp need the runtime in the environment they launch;
+``doctor`` reports whether it is importable, and ``xapp run`` explains
+its absence.
+"""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+DISTRIBUTION_NAME = "airpuls-sdk-cli"
+
+RELEASE_STAGE = "beta"
+
+_FALLBACK_VERSION = "0.0.0.dev0"
+
+
+def distribution_version() -> str:
+    """Return the installed ``airpuls-sdk-cli`` distribution version.
+
+    Falls back to a development placeholder when the distribution
+    metadata is unavailable, e.g. when running from a source checkout
+    that was never installed.
+    """
+    try:
+        return metadata.version(DISTRIBUTION_NAME)
+    except metadata.PackageNotFoundError:
+        return _FALLBACK_VERSION
+
+
+def cli_version() -> str:
+    """Return the human-readable CLI version string, including the
+    release stage, e.g. ``0.1.0 (beta)``."""
+    return f"{distribution_version()} ({RELEASE_STAGE})"

airpuls_sdk_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Module execution entry: ``python -m airpuls_sdk_cli``."""
+
+from .app import main
+
+main()

airpuls_sdk_cli/app.py

@@ -0,0 +1,334 @@
+"""Root application of the airpuls-sdk CLI.
+
+Assembles the command tree and owns the single failure-rendering
+guard: commands raise :class:`~.core.errors.CliError`, and
+:func:`main` maps every outcome — success, typed failure, usage
+error, interrupt, unexpected exception — onto exactly one rendering
+and exit status.
+
+The same guard selects the output mode.  With ``--json`` every
+outcome is written as one document on stdout by :mod:`.core.emit`
+instead of being rendered, which is the interface editor integrations
+consume; exit statuses are identical in both modes.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated, Optional, Sequence
+
+import typer
+
+try:
+    from typer import _click as clicklib
+except ImportError:
+    import click as clicklib
+
+from . import RELEASE_STAGE, cli_version, distribution_version
+from .commands import (
+    config,
+    doctor,
+    xapp_add_sink,
+    xapp_build,
+    xapp_connect,
+    xapp_credentials,
+    xapp_deploy,
+    xapp_info,
+    xapp_new,
+    xapp_package,
+    xapp_run,
+    xapp_test,
+    xapp_undeploy,
+    xapp_validate,
+)
+from .core import console as console_mod
+from .core import emit
+from .core.console import render_error, render_unexpected
+from .core.errors import CliError, UsageError
+
+app = typer.Typer(
+    name="airpuls-sdk",
+    help="Developer tool for airpuls Near-RT RIC xApps (beta).",
+    no_args_is_help=True,
+    add_completion=True,
+    rich_markup_mode="rich",
+)
+
+xapp_app = typer.Typer(
+    help="Create and manage xApp projects.", no_args_is_help=True
+)
+app.add_typer(xapp_app, name="xapp")
+
+config_app = typer.Typer(
+    help="Store and inspect CLI settings.", no_args_is_help=True
+)
+app.add_typer(config_app, name="config")
+
+xapp_app.command("new")(xapp_new.new)
+xapp_app.command("validate")(xapp_validate.validate)
+xapp_app.command("info")(xapp_info.info)
+xapp_app.command("build")(xapp_build.build)
+xapp_app.command("test")(xapp_test.test)
+xapp_app.command("run")(xapp_run.run)
+xapp_app.command("package")(xapp_package.package)
+xapp_app.command("deploy")(xapp_deploy.deploy_cmd)
+xapp_app.command("undeploy")(xapp_undeploy.undeploy)
+xapp_app.command("credentials")(xapp_credentials.credentials)
+xapp_app.command("connect")(xapp_connect.connect)
+add_app = typer.Typer(
+    help="Add optional configuration to the project.", no_args_is_help=True
+)
+xapp_app.add_typer(add_app, name="add")
+add_app.command("sink")(xapp_add_sink.add_sink)
+ric_app = typer.Typer(
+    help="Manage the registry of RIC deployment targets.",
+    no_args_is_help=True,
+)
+config_app.add_typer(ric_app, name="ric")
+ric_app.command("add")(config.ric_add)
+ric_app.command("list")(config.ric_list)
+ric_app.command("remove")(config.ric_remove)
+ric_app.command("use")(config.ric_use)
+ric_app.command("probe")(config.ric_probe)
+ric_app.command("logs")(config.ric_logs)
+config_app.command("show")(config.show)
+app.command("doctor")(doctor.doctor)
+
+
+def _print_version(value: bool) -> None:
+    """Eager ``--version`` callback: report the version and stop.
+
+    :raises typer.Exit: Always, after reporting, when ``value`` is set.
+    """
+    if value:
+        emit.data(version=distribution_version(), stage=RELEASE_STAGE)
+        console_mod.console.print(f"airpuls-sdk {cli_version()}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--version",
+            callback=_print_version,
+            is_eager=True,
+            help="Print the CLI version and exit.",
+        ),
+    ] = None,
+    debug: Annotated[
+        bool,
+        typer.Option(
+            "--debug",
+            help="Show full tracebacks for unexpected errors.",
+        ),
+    ] = False,
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            envvar=emit.ENV_VAR,
+            help="Report the result as one JSON document on stdout "
+            "instead of rendered text, and never prompt. Intended for "
+            "editor integrations and scripts.",
+        ),
+    ] = False,
+) -> None:
+    """Record process-wide presentation flags before any command runs.
+
+    The JSON channel is already active at this point — :func:`main`
+    resolves it from the raw arguments — so the flag is declared here
+    for parsing and help only.
+    """
+    console_mod.state["debug"] = debug
+
+
+INTERRUPT_EXIT_CODE = 130
+"""Exit status of an interrupted command, the shell's SIGINT
+convention.  Reported both as a raised abort and, depending on the
+click generation underneath Typer, as the application call's return
+value."""
+
+
+HELP_FLAG = "--help"
+
+
+def _resolve_command(argv: Sequence[str]):
+    """Resolve ``argv`` against the command tree.
+
+    Walks the leading non-option tokens as long as each names a
+    subcommand, which identifies the invoked command without
+    interpreting its arguments.
+
+    :returns: (click command object, its path components).
+    """
+    command = typer.main.get_command(app)
+    parts: list[str] = []
+    for token in argv:
+        if token.startswith("-"):
+            continue
+        children = getattr(command, "commands", {})
+        if token not in children:
+            break
+        parts.append(token)
+        command = children[token]
+    return command, parts
+
+
+def _command_path(argv: Sequence[str]) -> str:
+    """Name the invoked command as a space-separated path, e.g.
+    ``xapp deploy``; empty when no command was named."""
+    return " ".join(_resolve_command(argv)[1])
+
+
+def _parameter_record(param) -> dict:
+    """Describe one command parameter as document content."""
+    return {
+        "names": list(param.opts),
+        "help": getattr(param, "help", None) or "",
+        "required": bool(param.required),
+        "is_flag": bool(getattr(param, "is_flag", False)),
+        "default": emit.plain(param.default),
+    }
+
+
+def _help_record(command) -> dict:
+    """Describe ``command`` as document content: its own help, the
+    subcommands it groups, and the parameters it accepts.
+
+    Replaces the rendered help in JSON mode, where an integration
+    needs the command surface as data to build its own affordances.
+
+    :returns: The record; caller owns it.
+    """
+    subcommands = getattr(command, "commands", {})
+    return {
+        "help": (command.help or "").strip(),
+        "commands": [
+            {"name": name, "help": sub.get_short_help_str(limit=200)}
+            for name, sub in sorted(subcommands.items())
+        ],
+        "arguments": [
+            _parameter_record(param)
+            for param in command.params
+            if param.param_type_name == "argument"
+        ],
+        "options": [
+            _parameter_record(param)
+            for param in command.params
+            if param.param_type_name == "option"
+        ],
+    }
+
+
+def _record_interrupt() -> None:
+    """Record the interrupt as the invocation's failure."""
+    emit.failure(
+        "interrupted",
+        "command interrupted",
+        exit_code=INTERRUPT_EXIT_CODE,
+    )
+
+
+def _finish(command: str, exit_code: int) -> SystemExit:
+    """Close the invocation in the active output mode.
+
+    Writes the result document when the machine-readable channel is
+    on; text mode has already reported everything at its call sites.
+
+    :returns: The exit the caller raises.
+    """
+    if emit.enabled():
+        emit.write(emit.document(command, exit_code=exit_code))
+    return SystemExit(exit_code)
+
+
+def _fail(command: str, err: CliError) -> SystemExit:
+    """Report a typed failure as a rendered panel or as the result
+    document's ``error`` block.
+
+    :returns: The exit carrying the failure's status.
+    """
+    if emit.enabled():
+        emit.failure_from(err)
+    else:
+        render_error(err)
+    return _finish(command, err.exit_code)
+
+
+def _usage_error(exc: clicklib.ClickException) -> UsageError:
+    """Map a command-line parsing failure onto the CLI's usage error,
+    naming the placement rule when the JSON flag was rejected because
+    it followed the command."""
+    message = exc.format_message()
+    if emit.FLAG in message:
+        return UsageError(
+            message,
+            hint=f"pass {emit.FLAG} before the command: "
+            f"`airpuls-sdk {emit.FLAG} <command>`",
+        )
+    return UsageError(message, hint="run `airpuls-sdk --help` for usage")
+
+
+def main(argv: Optional[Sequence[str]] = None) -> None:
+    """Console-script entry point.
+
+    Resolves the output mode from the raw arguments, then runs the
+    Typer application in non-standalone mode so every failure path
+    funnels through the CLI's own reporting.  Depending on the
+    underlying click generation, a ``typer.Exit`` and an interrupt
+    surface either as the return value of the application call or as a
+    raised exception; both forms are mapped to the same exit status
+    and, in JSON mode, to the same document.
+
+    :param argv: Argument vector override; None uses ``sys.argv[1:]``.
+    :raises SystemExit: Always, carrying the mapped exit status —
+                        0 success, :class:`CliError` codes 1–5,
+                        2 for command-line usage errors, 130 for
+                        interrupts.
+    """
+    argv = list(sys.argv[1:] if argv is None else argv)
+    emit.reset()
+    emit.configure(argv)
+    console_mod.set_quiet(emit.enabled())
+    resolved, parts = _resolve_command(argv)
+    command = " ".join(parts)
+
+    if emit.enabled() and HELP_FLAG in argv:
+        emit.data(**_help_record(resolved))
+        raise _finish(command, 0)
+
+    outcome = 0
+    try:
+        outcome = app(args=argv, prog_name="airpuls-sdk", standalone_mode=False)
+    except CliError as err:
+        raise _fail(command, err) from None
+    except clicklib.exceptions.Exit as exc:
+        raise _finish(command, exc.exit_code) from None
+    except (clicklib.exceptions.Abort, KeyboardInterrupt):
+        _record_interrupt()
+        raise _finish(command, INTERRUPT_EXIT_CODE) from None
+    except clicklib.ClickException as exc:
+        if not exc.format_message().strip():
+            raise _finish(command, exc.exit_code) from None
+        raise _fail(command, _usage_error(exc)) from None
+    except Exception as exc:  # noqa: BLE001 — final guard reports and exits
+        if emit.enabled():
+            emit.failure(
+                "internal",
+                f"{type(exc).__name__}: {exc}",
+                exit_code=1,
+                hint="re-run with --debug for the full traceback",
+            )
+        else:
+            render_unexpected(exc)
+        raise _finish(command, 1) from None
+    status = outcome if isinstance(outcome, int) else 0
+    if status == INTERRUPT_EXIT_CODE:
+        _record_interrupt()
+    raise _finish(command, status)
+
+
+if __name__ == "__main__":
+    main()

airpuls_sdk_cli/commands/__init__.py

@@ -0,0 +1,7 @@
+"""Command layer of the airpuls-sdk CLI.
+
+One module per command; each exposes a single Typer-compatible
+function that parses input, delegates to ``airpuls_sdk_cli.core``,
+and renders the outcome.  Failures propagate as
+:class:`~airpuls_sdk_cli.core.errors.CliError` to the top-level guard
+in ``app.main`` — command modules never print errors themselves."""