rosotacom-dev 2.2__tar.gz → 2.3__tar.gz

{rosotacom_dev-2.2 → rosotacom_dev-2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.2
+Version: 2.3
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -218,6 +218,23 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+### Locating packaged resources
+
+rosotacom is installed in an isolated environment (pipx, or a project venv), so
+another tool cannot `import rosotacom` from a system Python to find the files
+that ship with it. Ask the CLI instead — it prints one absolute path, so it
+composes directly in a shell:
+
+```bash
+rosotacom resources path com_msgs   # the ROS 2 message package
+rosotacom resources path ws         # the packaged runtime workspace
+```
+
+Use this wherever another project needs rosotacom's files on the host, for
+example to bake `com_msgs` into its own container image. Ask for the resource by
+name rather than reconstructing a path: the names are part of the CLI contract,
+the layout behind them is not.
+
 See the [example project README](src/rosotacom/resources/examples/README.md)
 for the copyable example layout, the
 [session configuration reference](session-configuration.md) for the session

{rosotacom_dev-2.2 → rosotacom_dev-2.3}/README.md

@@ -173,6 +173,23 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+### Locating packaged resources
+
+rosotacom is installed in an isolated environment (pipx, or a project venv), so
+another tool cannot `import rosotacom` from a system Python to find the files
+that ship with it. Ask the CLI instead — it prints one absolute path, so it
+composes directly in a shell:
+
+```bash
+rosotacom resources path com_msgs   # the ROS 2 message package
+rosotacom resources path ws         # the packaged runtime workspace
+```
+
+Use this wherever another project needs rosotacom's files on the host, for
+example to bake `com_msgs` into its own container image. Ask for the resource by
+name rather than reconstructing a path: the names are part of the CLI contract,
+the layout behind them is not.
+
 See the [example project README](src/rosotacom/resources/examples/README.md)
 for the copyable example layout, the
 [session configuration reference](session-configuration.md) for the session

{rosotacom_dev-2.2 → rosotacom_dev-2.3}/src/rosotacom/cli.py

@@ -82,6 +82,16 @@ PROJECT_DIR = RESOURCE_DIR
 WS_DIR = RESOURCE_DIR / "ws"
 DEFAULT_ROS2DOCKER_CONFIG = RESOURCE_DIR / "ros2docker.json.example"
 EXAMPLE_PROJECT_DIR = RESOURCE_DIR / "examples"
+
+# Packaged resources external tooling may need to locate on the host. rosotacom
+# is installed in an isolated environment (pipx, or a project venv), so a
+# consumer cannot `import rosotacom` to find these; `rosotacom resources path`
+# is the supported lookup. Names are part of the CLI contract, the layout behind
+# them is not — ask for "com_msgs", not for "ws/ros2src/com_msgs".
+NAMED_RESOURCES = {
+    "ws": WS_DIR,
+    "com_msgs": WS_DIR / "ros2src" / "com_msgs",
+}
 SESSION_CONFIG_CONTAINER_DIR = "/session/configs"
 SESSION_DEFINITION_CONTAINER_DIR = "/session/definitions"
 SESSION_INSTANCE_CONTAINER_DIR = "/session/instances"
@@ -4618,6 +4628,20 @@ def examples_create_command(args: argparse.Namespace) -> int:
     return 0
 
 
+def resources_path_command(args: argparse.Namespace) -> int:
+    """Print the host path of a packaged resource, for external tooling."""
+
+    path = NAMED_RESOURCES[args.name].resolve()
+    if not path.exists():
+        raise RuntimeError(
+            f"Packaged resource {args.name!r} is missing from this rosotacom "
+            f"installation (expected at {path}). The install is incomplete: "
+            f"reinstall the package."
+        )
+    print(path)
+    return 0
+
+
 def _require_project_file(raw: str | None) -> Path:
     config = _resolve_path(raw, Path.cwd(), must_exist=True)
     if not config or not config.is_file():
@@ -7801,43 +7825,50 @@ def videoquality_command(args: argparse.Namespace) -> int:
     return 0
 
 
+# `rosotacom <session>` is shorthand for `rosotacom start <session>`. To know when
+# NOT to insert the implicit "start", main() needs the set of real command names.
+# A subparser missing here becomes unreachable — `rosotacom foo` would silently
+# turn into `rosotacom start foo` — so a contract test keeps the two in sync.
+TOP_LEVEL_COMMANDS = {
+    "start",
+    "stop",
+    "doctor",
+    "ps",
+    "smoke",
+    "ota-smoke",
+    "status",
+    "metrics",
+    "videoquality",
+    "geomap",
+    "report",
+    "stream-stats",
+    "test",
+    "expect",
+    "calibrate",
+    "verify",  # retired; keep guarded so it is not rewritten as `start verify`.
+    "probe-publish",
+    "probe-check",
+    "probe-content",
+    "publish-test-topics",
+    "list-sessions",
+    "scenario",
+    "examples",
+    "resources",
+    "config",
+    "bundle",
+    "profile",
+    "completion",
+    "benchmark",
+    "ota-benchmark",
+    "anonymize",
+}
+
+
 def main(argv: list[str] | None = None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
-    commands = {
-        "start",
-        "stop",
-        "doctor",
-        "ps",
-        "smoke",
-        "ota-smoke",
-        "status",
-        "metrics",
-        "videoquality",
-        "geomap",
-        "report",
-        "stream-stats",
-        "test",
-        "expect",
-        "calibrate",
-        "verify",  # retired; keep guarded so it is not rewritten as `start verify`.
-        "probe-publish",
-        "probe-check",
-        "probe-content",
-        "publish-test-topics",
-        "list-sessions",
-        "scenario",
-        "examples",
-        "config",
-        "bundle",
-        "profile",
-        "completion",
-        "benchmark",
-        "ota-benchmark",
-        "anonymize",
-    }
     if not argv:
         argv = ["start"]
-    elif argv[0] not in commands and not argv[0].startswith("-"):
+    elif argv[0] not in TOP_LEVEL_COMMANDS and not argv[0].startswith("-"):
         argv = ["start", *argv]
 
     parser = argparse.ArgumentParser(prog="rosotacom")
@@ -8480,6 +8511,12 @@ def main(argv: list[str] | None = None) -> int:
     examples_create_parser.add_argument("--force", action="store_true", help="Replace the target if it exists.")
     examples_create_parser.set_defaults(func=examples_create_command)
 
+    resources_parser = subparsers.add_parser("resources", help="Locate resources packaged with rosotacom.")
+    resources_subparsers = resources_parser.add_subparsers(dest="resources_action", required=True)
+    resources_path_parser = resources_subparsers.add_parser("path", help="Print the host path of a packaged resource.")
+    resources_path_parser.add_argument("name", choices=sorted(NAMED_RESOURCES))
+    resources_path_parser.set_defaults(func=resources_path_command)
+
     config_parser = subparsers.add_parser("config", help="Inspect or set the active rosotacom project.")
     config_subparsers = config_parser.add_subparsers(dest="config_action", required=True)
 

{rosotacom_dev-2.2 → rosotacom_dev-2.3}/src/rosotacom_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.2
+Version: 2.3
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause
@@ -218,6 +218,23 @@ scripts/
 project-local directories first and shared/example directories later when one
 project should discover both.
 
+### Locating packaged resources
+
+rosotacom is installed in an isolated environment (pipx, or a project venv), so
+another tool cannot `import rosotacom` from a system Python to find the files
+that ship with it. Ask the CLI instead — it prints one absolute path, so it
+composes directly in a shell:
+
+```bash
+rosotacom resources path com_msgs   # the ROS 2 message package
+rosotacom resources path ws         # the packaged runtime workspace
+```
+
+Use this wherever another project needs rosotacom's files on the host, for
+example to bake `com_msgs` into its own container image. Ask for the resource by
+name rather than reconstructing a path: the names are part of the CLI contract,
+the layout behind them is not.
+
 See the [example project README](src/rosotacom/resources/examples/README.md)
 for the copyable example layout, the
 [session configuration reference](session-configuration.md) for the session

{rosotacom_dev-2.2 → rosotacom_dev-2.3}/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "2.2",
+  "tag": "2.3",
   "distance": 0,
-  "node": "g9238899c274aaa7df7778b0348702130527fa1b3",
+  "node": "g60990e425f2700fb3786069ecff1e369d2fac8f8",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-07"

{rosotacom_dev-2.2 → rosotacom_dev-2.3}/tests/contract/test_packaged_resources.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
+import argparse
 import os
 import subprocess
 from importlib import resources
 from pathlib import Path
 
+import pytest
 import yaml
 
 import rosotacom.cli as cli
@@ -238,3 +240,47 @@ def test_native_chatter_waiter_reads_topic_info_without_broken_pipe(tmp_path: Pa
 
     assert result.stdout.strip() == "echo started"
     assert "BrokenPipeError" not in result.stderr
+
+
+def test_every_registered_subcommand_is_exempt_from_implicit_start(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # `rosotacom <session>` is shorthand for `rosotacom start <session>`, so
+    # main() only skips the implicit "start" for names in TOP_LEVEL_COMMANDS.
+    # A subparser missing from that set is unreachable: the CLI silently turns
+    # `rosotacom foo ...` into `rosotacom start foo ...` and fails somewhere
+    # unrelated. Capture what is actually registered and compare.
+    captured: dict[str, argparse._SubParsersAction] = {}
+    original = argparse.ArgumentParser.add_subparsers
+
+    def spy(self: argparse.ArgumentParser, *args: object, **kwargs: object):
+        action = original(self, *args, **kwargs)
+        if self.prog == "rosotacom":
+            captured["top"] = action
+        return action
+
+    monkeypatch.setattr(argparse.ArgumentParser, "add_subparsers", spy)
+    with pytest.raises(SystemExit):
+        cli.main(["--help"])
+
+    registered = set(captured["top"].choices)
+    assert registered, "no top-level subparsers were captured"
+
+    unreachable = registered - cli.TOP_LEVEL_COMMANDS
+    assert not unreachable, f"subcommands missing from TOP_LEVEL_COMMANDS: {sorted(unreachable)}"
+
+    # The reverse direction may legitimately carry retired names (e.g. "verify"),
+    # which stay guarded so they are not rewritten as `start verify`.
+    assert "resources" in registered
+
+
+def test_named_resources_point_at_real_packaged_directories() -> None:
+    for name, path in cli.NAMED_RESOURCES.items():
+        assert path.is_dir(), f"packaged resource {name!r} is not a directory: {path}"
+
+    # com_msgs is consumed by external builds (fleet_mgmt bakes it into its
+    # container images), so it must be a usable ROS 2 package, not just a folder.
+    com_msgs = cli.NAMED_RESOURCES["com_msgs"]
+    assert (com_msgs / "package.xml").is_file()
+    assert (com_msgs / "CMakeLists.txt").is_file()
+    assert list(com_msgs.glob("msg/*.msg"))

{rosotacom_dev-2.2 → rosotacom_dev-2.3}/tests/unit/test_cli.py

@@ -2759,3 +2759,28 @@ def test_content_integrity_skips_transformed_topics() -> None:
         )
     )
     assert rosotacom._content_integrity_specs(cfg, "a") == []
+
+
+def test_resources_path_prints_an_absolute_existing_path(capsys: pytest.CaptureFixture[str]) -> None:
+    # External tooling cannot `import rosotacom` (pipx/venv isolation), so this
+    # command is the only supported way to locate packaged resources. It must
+    # print exactly one absolute path and nothing else, to stay shell-composable.
+    for name in rosotacom.NAMED_RESOURCES:
+        assert rosotacom.resources_path_command(argparse.Namespace(name=name)) == 0
+        out = capsys.readouterr().out
+        assert out.endswith("\n")
+        printed = Path(out.strip())
+        assert printed.is_absolute()
+        assert printed.is_dir()
+        assert len(out.splitlines()) == 1
+
+
+def test_resources_path_rejects_an_unknown_resource_name() -> None:
+    with pytest.raises(SystemExit):
+        rosotacom.main(["resources", "path", "no_such_resource"])
+
+
+def test_resources_path_reports_an_incomplete_installation(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setitem(rosotacom.NAMED_RESOURCES, "ws", tmp_path / "gone")
+    with pytest.raises(RuntimeError, match="missing from this rosotacom installation"):
+        rosotacom.resources_path_command(argparse.Namespace(name="ws"))