botgauge-cli 0.1.0__py3-none-any.whl

botgauge/cli/__init__.py

@@ -0,0 +1,42 @@
+"""The ``botgauge`` command.
+
+Owns the ``botgauge`` console script and its short alias, and dispatches each command to the
+installed BotGauge component that registers it in the ``botgauge.commands`` entry-point group.
+Standard library only.
+"""
+from __future__ import annotations
+
+from ._dispatch import main
+from ._names import ENTRY_POINT_GROUP, RESERVED, command_names
+
+#: Read from the installed metadata on first access (see ``__getattr__``); declared here for type checkers.
+__version__: str
+__all__ = ["ENTRY_POINT_GROUP", "RESERVED", "__version__", "command_names", "main"]
+
+
+def __getattr__(name: str) -> str:
+    """Resolve ``__version__`` lazily from the installed distribution metadata.
+
+    The value is cached in the module globals after the first lookup.
+
+    Args:
+        name: The attribute being looked up on the module.
+
+    Returns:
+        The installed ``botgauge-cli`` version, or ``"0+unknown"`` when it is not installed.
+
+    Raises:
+        AttributeError: ``name`` is not ``__version__``.
+    """
+    # The version is defined once, in pyproject.toml, and read from the installed metadata the first
+    # time something asks for it. A source tree that was never installed reports "0+unknown".
+    if name == "__version__":
+        from importlib import metadata
+
+        try:
+            version = metadata.version("botgauge-cli")
+        except metadata.PackageNotFoundError:
+            version = "0+unknown"
+        globals()["__version__"] = version
+        return version
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

botgauge/cli/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m botgauge.cli`` runs the same dispatcher as the ``botgauge`` console script."""
+import sys
+
+from . import main
+
+sys.exit(main())

botgauge/cli/_dispatch.py

@@ -0,0 +1,241 @@
+"""Dispatch ``botgauge <command>`` to the component that owns it.
+
+Components register commands in the ``botgauge.commands`` entry-point group; this module only finds
+and runs them. Rules, so a command never silently changes meaning:
+
+* a reserved name (``_names.RESERVED``) runs only from its owner; another distribution registering it
+  is ignored and reported by ``--help``;
+* a reserved name is resolved from the owner's metadata alone, never a scan of every installed
+  distribution, so ``botgauge instrument`` (which execs the application) stays cheap;
+* an unreserved name registered twice is refused, naming every registering distribution; nothing
+  wins silently;
+* a command whose owner is not installed says which distribution provides it;
+* a component that fails to import fails only its own command, with a message naming it.
+
+Exit codes: the command's own; 0 for help/version; 2 for usage errors (no, unknown, ambiguous,
+unavailable or unloadable command).
+"""
+from __future__ import annotations
+
+import os
+import sys
+from importlib import metadata
+
+from ._names import (
+    BUILTINS,
+    DISTRIBUTION,
+    ENTRY_POINT_GROUP,
+    PLATFORM,
+    RESERVED,
+    command_names,
+    install_hint,
+)
+
+_USAGE = "usage: {prog} <command> [args]    ({prog} help for every installed command)\n"
+
+
+def _prog() -> str:
+    """Return the console-script name the user invoked, or ``botgauge`` if it is not one of ours."""
+    invoked = os.path.basename(sys.argv[0] or "")
+    invoked = invoked[:-4] if invoked.lower().endswith(".exe") else invoked
+    return invoked if invoked in command_names() else "botgauge"
+
+
+def _distribution(ep: metadata.EntryPoint) -> str:
+    """Return the name of the distribution that registered ``ep``, or a placeholder if unknown."""
+    return getattr(getattr(ep, "dist", None), "name", None) or "<unknown distribution>"
+
+
+def _all_command_entry_points() -> dict[str, list[metadata.EntryPoint]]:
+    """Scan every installed distribution and group its ``botgauge.commands`` entry points by name."""
+    found: dict[str, list[metadata.EntryPoint]] = {}
+    for ep in metadata.entry_points(group=ENTRY_POINT_GROUP):
+        found.setdefault(ep.name, []).append(ep)
+    return found
+
+
+def _owner_entry_point(name: str, owner: str) -> tuple[metadata.EntryPoint | None, str]:
+    """Find the owner's entry point for a reserved name, reading only the owner's metadata.
+
+    Args:
+        name: The reserved command name.
+        owner: The distribution that must provide ``name``.
+
+    Returns:
+        ``(entry_point, "")`` on success, or ``(None, problem)`` when the owner is not installed or
+        does not register ``name``.
+    """
+    try:
+        dist = metadata.distribution(owner)
+    except metadata.PackageNotFoundError:
+        return None, f"'{name}' is provided by {owner}, which is not installed ({install_hint(owner)})"
+    for ep in dist.entry_points:
+        if ep.group == ENTRY_POINT_GROUP and ep.name == name:
+            return ep, ""
+    return None, f"{owner} is installed but does not register '{name}' (a version mismatch?)"
+
+
+def _resolve(name: str) -> tuple[metadata.EntryPoint | None, str]:
+    """Resolve a command name to the single entry point allowed to run it.
+
+    Args:
+        name: The command name typed after ``botgauge``.
+
+    Returns:
+        ``(entry_point, "")`` on success, or ``(None, problem)`` for an unknown, ambiguous or
+        unavailable command.
+    """
+    if name in RESERVED:
+        return _owner_entry_point(name, RESERVED[name])
+    candidates = _all_command_entry_points().get(name, [])
+    if not candidates:
+        return None, f"unknown command '{name}'"
+    if len(candidates) > 1:
+        owners = ", ".join(sorted(_distribution(ep) for ep in candidates))
+        return None, f"'{name}' is registered by more than one package ({owners}); refusing to guess"
+    return candidates[0], ""
+
+
+def _run(name: str, rest: list[str], prog: str) -> int:
+    """Load and run one command, reporting resolution and import failures on stderr.
+
+    Args:
+        name: The command name.
+        rest: Arguments passed to the command's handler.
+        prog: The invoked program name, used in error messages.
+
+    Returns:
+        The handler's return value as an int (``None`` counts as 0), or 2 if the command could not be
+        resolved or loaded.
+    """
+    ep, problem = _resolve(name)
+    if ep is None:
+        print(f"{prog}: {problem}", file=sys.stderr)
+        print(f"Run '{prog} help' to list the installed commands.", file=sys.stderr)
+        return 2
+    try:
+        handler = ep.load()
+    except Exception as exc:  # noqa: BLE001 - a broken component must not take the whole CLI down
+        print(f"{prog}: the '{name}' command (from {_distribution(ep)}) could not be loaded: "
+              f"{type(exc).__name__}: {exc}", file=sys.stderr)
+        return 2
+    result = handler(rest)
+    return int(result) if result is not None else 0
+
+
+def _summary(ep: metadata.EntryPoint) -> str:
+    """Return the first line of the handler's docstring for ``help``; this imports the component.
+
+    For a command that ``help`` lists, the handler's docstring is therefore user-visible help
+    text: changing its first line changes the ``botgauge help`` output. (An unreserved name
+    registered more than once is not listed, and neither is a reserved name registered only by a
+    non-owner; a reserved name is listed from its owner's entry even when other distributions
+    also register it.)
+
+    Args:
+        ep: Entry point of the command whose summary is wanted.
+
+    Returns:
+        The summary line; an empty string for a handler without a docstring, or
+        ``(could not be loaded: <type>)`` when the component fails to import.
+    """
+    try:
+        doc = ep.load().__doc__ or ""
+    except Exception as exc:  # noqa: BLE001 - list it as unavailable, keep listing the rest
+        return f"(could not be loaded: {type(exc).__name__})"
+    return doc.strip().splitlines()[0] if doc.strip() else ""
+
+
+def _print_help(prog: str) -> None:
+    """Print every installed command by section, the reserved commands not installed, and ignored registrations."""
+    others = [n for n in command_names() if n != prog]
+    alias = f"  (also: {', '.join(others)})" if others else ""
+    print(_USAGE.format(prog=prog).rstrip("\n") + alias)
+    found = _all_command_entry_points()
+    rows: dict[str, list[tuple[str, str, str]]] = {"Platform": [], "Groups": [], "Other": []}
+    ignored: list[str] = []
+    for name in BUILTINS:
+        rows["Platform"].append((name, "this help" if name == "help" else "installed versions", DISTRIBUTION))
+    for name, eps in sorted(found.items()):
+        owner = RESERVED.get(name)
+        if owner is not None:
+            ignored += [f"{_distribution(ep)} registers '{name}', which is reserved for {owner}"
+                        for ep in eps if _distribution(ep) != owner]
+            eps = [ep for ep in eps if _distribution(ep) == owner]
+            if not eps:
+                continue
+            section = "Platform" if name in PLATFORM else "Groups"
+        elif len(eps) > 1:
+            owners = ", ".join(sorted(_distribution(ep) for ep in eps))
+            ignored.append(f"'{name}' is registered by {owners}; refused")
+            continue
+        else:
+            section = "Other"
+        rows[section].append((name, _summary(eps[0]), _distribution(eps[0])))
+    titles = {"Platform": "Commands", "Groups": f"Groups ({prog} <group> <verb>; {prog} <group> --help)",
+              "Other": "Other installed commands"}
+    for section, entries in rows.items():
+        if entries:
+            print(f"\n{titles[section]}:")
+            for name, summary, dist in entries:
+                print(f"  {name:<12} {summary}  [{dist}]")
+    installed = {name for name, eps in found.items() for ep in eps if _distribution(ep) == RESERVED.get(name)}
+    missing: dict[str, list[str]] = {}
+    for name, owner in RESERVED.items():
+        if name not in installed:
+            missing.setdefault(owner, []).append(name)
+    if missing:
+        print("\nNot installed:")
+        for owner, cmds in sorted(missing.items()):
+            print(f"  {', '.join(cmds):<40} {install_hint(owner)}")
+    for line in ignored:
+        print(f"\nignored: {line}")
+
+
+def _print_version() -> None:
+    """Print this distribution's version and that of every distribution registering a command."""
+    try:
+        own = metadata.version(DISTRIBUTION)
+    except metadata.PackageNotFoundError:
+        own = "(not installed)"
+    print(f"{DISTRIBUTION} {own}")
+    dists = sorted({_distribution(ep) for eps in _all_command_entry_points().values() for ep in eps})
+    for dist in dists:
+        try:
+            print(f"  {dist} {metadata.version(dist)}")
+        except metadata.PackageNotFoundError:
+            print(f"  {dist}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Dispatch one ``botgauge`` command.
+
+    Args:
+        argv: Command arguments, or None to use ``sys.argv[1:]``.
+
+    Returns:
+        The command's exit code (``help <command>`` returns that command's exit code for
+        ``--help``); 0 for help/version; 2 for a missing, unknown, ambiguous, uninstalled or
+        unloadable command. ``help`` followed by a built-in name (``help`` or ``version``) is
+        looked up like any other command name: it is an unknown command (2) unless a plugin
+        registers that name, in which case the plugin runs with ``--help``.
+
+    Raises:
+        SystemExit: A command's argument parser exits for help or invalid options.
+        Exception: Any other exception raised by a command handler propagates unchanged.
+    """
+    args = sys.argv[1:] if argv is None else list(argv)
+    prog = _prog()
+    if not args:
+        print(_USAGE.format(prog=prog), end="")
+        return 2
+    first, rest = args[0], args[1:]
+    if first in ("-h", "--help", "help"):
+        if first == "help" and rest:
+            return _run(rest[0], ["--help"], prog)
+        _print_help(prog)
+        return 0
+    if first in ("-V", "--version", "version"):
+        _print_version()
+        return 0
+    return _run(first, rest, prog)

botgauge/cli/_names.py

@@ -0,0 +1,78 @@
+"""Who owns which ``botgauge`` command.
+
+Every top-level name a BotGauge distribution may register is listed here with its owner. The
+dispatcher runs a reserved name only from its owner, so another package can never take over
+``botgauge instrument``, and resolving a reserved name reads only the owner's
+metadata instead of scanning every installed distribution (``botgauge instrument`` stays cheap).
+Third-party plugins may register other names; they never shadow these.
+
+Adding a component's command is a reviewed change to this file, released with that component
+(lockstep versions). A BotGauge distribution must not register a name that is not reserved for it
+here.
+"""
+from __future__ import annotations
+
+from importlib import metadata
+
+#: The entry-point group every component registers its commands under: ``name = "pkg.mod:fn"``,
+#: where ``fn(argv: list[str]) -> int``.
+ENTRY_POINT_GROUP = "botgauge.commands"
+
+#: This distribution; its console scripts are the command names.
+DISTRIBUTION = "botgauge-cli"
+
+#: Built into the dispatcher itself.
+BUILTINS = ("help", "version")
+
+#: Platform verbs stay top-level; every other name is a noun group: ``botgauge <noun> <verb>``.
+PLATFORM = ("instrument", "probe", "doctor", "setup", *BUILTINS)
+
+#: name -> the distribution that must provide it.
+RESERVED: dict[str, str] = {
+    "instrument": "botgauge-tracing",
+    "probe": "botgauge-tracing",
+    "doctor": "botgauge-tracing",
+    "setup": "botgauge-tracing",
+}
+
+#: Distributions published on PyPI. Only these get a `pip install` hint: an unpublished name is
+#: either a 404 or, once someone else registers it, a third party's code. Add a distribution here in
+#: the release that first publishes it.
+PUBLISHED = frozenset({"botgauge", "botgauge-cli", "botgauge-tracing"})
+
+
+def install_hint(owner: str) -> str:
+    """Return how to install ``owner``'s commands.
+
+    Args:
+        owner: A distribution name.
+
+    Returns:
+        ``"pip install <owner>"`` for a published distribution, otherwise a note that this release
+        does not publish it.
+    """
+    return f"pip install {owner}" if owner in PUBLISHED else "not published in this release"
+
+
+_PRIMARY = "botgauge"
+
+
+def command_names() -> tuple[str, ...]:
+    """Return the installed console-script names for this dispatcher, ``botgauge`` first.
+
+    Read from this distribution's own metadata, so the short alias is defined once, in
+    ``pyproject.toml``.
+
+    Returns:
+        ``botgauge`` followed by every other console script of ``botgauge-cli``, or
+        ``("botgauge",)`` when the metadata is unavailable (a source checkout run without
+        installing) or declares no console scripts.
+    """
+    try:
+        eps = metadata.distribution(DISTRIBUTION).entry_points
+    except metadata.PackageNotFoundError:
+        return (_PRIMARY,)
+    # Every console script of this distribution, whatever it points at: a script aimed at the wrong
+    # function must show up here (and fail the release gates), not silently drop out.
+    names = sorted(ep.name for ep in eps if ep.group == "console_scripts")
+    return (_PRIMARY, *(n for n in names if n != _PRIMARY)) if names else (_PRIMARY,)

botgauge_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: botgauge-cli
+Version: 0.1.0
+Summary: The `botgauge` command: one entry point that dispatches to every installed BotGauge component.
+Author-email: "BotGauge AI Inc." <support@botgauge.com>
+License-Expression: FSL-1.1-ALv2
+Project-URL: Homepage, https://www.botgauge.com/
+Keywords: botgauge,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# botgauge-cli
+
+The `botgauge` command. It owns the `botgauge` console script (plus a short alias, `botg`) and
+dispatches each command to the installed BotGauge component that provides it:
+
+```bash
+botgauge help          # every installed command, and which package provides the rest
+botgauge version       # installed BotGauge versions
+botgauge instrument python app.py      # provided by botgauge-tracing
+botgauge doctor                        # provided by botgauge-tracing
+```
+
+Components register commands in the `botgauge.commands` entry-point group. Top-level names are
+reserved per package (`src/botgauge/cli/_names.py`), so one package can never take over another's
+command. Standard library only; every BotGauge component depends on it. You normally get it through
+`pip install botgauge` rather than installing it directly.

botgauge_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+botgauge/cli/__init__.py,sha256=a4_oVNm2VKBQaHuNDQQ05C-6hHqt_4PdoONlvba9KHU,1579
+botgauge/cli/__main__.py,sha256=YgvCeaA_NXPq8B-R_ArNqlOVse0w-12As4qjSIOJj1w,143
+botgauge/cli/_dispatch.py,sha256=A4-y1ePaihfHD8v4v_TaGWrG0I3trduXtUeFbyN6TFU,10161
+botgauge/cli/_names.py,sha256=rIO6hlZDDzUOAJGbEon-38ZzeQRsCNOAgaOK_wcFrX0,3160
+botgauge_cli-0.1.0.dist-info/licenses/LICENSE,sha256=EplDjGiYxLsggvWIv03TjBXk_gABXU88NMWtl_T26cU,3748
+botgauge_cli-0.1.0.dist-info/METADATA,sha256=ByNii7uEBR8P3-wxANjkUSdunVFboicEycJPopHnkhU,1697
+botgauge_cli-0.1.0.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
+botgauge_cli-0.1.0.dist-info/entry_points.txt,sha256=GiQBZ1kSGAPZa2GRMJgJVlSuxpOpChYhteLBtRR9xK0,72
+botgauge_cli-0.1.0.dist-info/top_level.txt,sha256=qr2kZrd0gkelTuQTeCyA68V8ewK04QkEynqd-So9t88,9
+botgauge_cli-0.1.0.dist-info/RECORD,,

botgauge_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

botgauge_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+botg = botgauge.cli:main
+botgauge = botgauge.cli:main

botgauge_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 BotGauge AI Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

botgauge_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+botgauge