Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,10 @@ x86_64 = "registry.example.com/holoscan/sdk-build-x86_64:5.0.0-cuda13"
aarch64 = "registry.example.com/holoscan/sdk-build-aarch64:5.0.0-cuda13"
```

- The default `repo-prefix` joins the segments of `metadata.json`
`module.namespace.python` with `_`, so `holoscan.my_sensor` gives
`holoscan_my_sensor`. Without a Python namespace, it is `module.name` without
its `holoscan-` prefix, with other characters replaced by `_`.
- Naming values use lowercase letters, digits, `.`, `_`, or `-`, starting with
a letter or digit. `HOLOSCAN_CLI_REPO_PREFIX`, `HOLOSCAN_CLI_CONTAINER_PREFIX`,
and `HOLOSCAN_CLI_WORKSPACE_NAME` override their project settings.
Expand Down
2 changes: 1 addition & 1 deletion src/holoscan_cli/project_context.py
Original file line number Diff line number Diff line change
Expand Up @@ -462,7 +462,7 @@ def _module_identity(module: dict, metadata_path: Path) -> tuple[str, Optional[s
f"Module metadata at {metadata_path} has an invalid Python namespace: "
f"{python_namespace!r}."
)
repo_prefix = segments[-1]
repo_prefix = "_".join(segments)
else:
normalized_name = module_name.strip().lower().removeprefix("holoscan-")
repo_prefix = re.sub(r"[^a-z0-9]+", "_", normalized_name).strip("_")
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,12 @@ distributing this Holoscan Module.
└── python/ # pytest suite: OperatorTestHarness + pipeline run
```

The operators are Python classes in the `holoscan_{{ cookiecutter.module_slug }}` package:
The operators are Python classes in the `holoscan_{{ cookiecutter.module_slug }}` package. Import them as
`holoscan.{{ cookiecutter.module_slug }}`:

```python
import holoscan as hs
from holoscan_{{ cookiecutter.module_slug }}.operators import {{ op_class }}
from holoscan.{{ cookiecutter.module_slug }}.operators import {{ op_class }}
```

- Add each new operator in its own `operators/<name>/` directory with an `__init__.py` that exports
Expand All @@ -52,8 +53,9 @@ from holoscan_{{ cookiecutter.module_slug }}.operators import {{ op_class }}
and installed into the wheel as `holoscan_{{ cookiecutter.module_slug }}.operators.<name>`;
`operators/__init__.py` exports whichever are present at runtime. Also add the operator to its
`if TYPE_CHECKING:` imports so type checkers and IDEs resolve it.
- The package's `holoscan.modules` entry point makes `import holoscan.{{ cookiecutter.module_slug }}` load
`holoscan_{{ cookiecutter.module_slug }}`. `pyproject.toml` declares it for the wheel, and `python/CMakeLists.txt` writes
- The package's `holoscan.modules` entry point makes `import holoscan.{{ cookiecutter.module_slug }}` (the
`module.namespace.python` value in `metadata.json`) load `holoscan_{{ cookiecutter.module_slug }}`.
`pyproject.toml` declares it for the wheel, and `python/CMakeLists.txt` writes
the same `holoscan-{{ cookiecutter.module_slug.replace('_', '-') }}` metadata into the build tree's `python/lib`.
- `holoscan build` stages the package in `build/<project>/python/lib`; nothing is compiled.
`holoscan run` adds that directory to `PYTHONPATH`. To run the example from a CMake build tree,
Expand Down Expand Up @@ -196,8 +198,8 @@ Declare Python dependencies, including other Modules' wheels, in `[project].depe

| Context | Convention | Example |
| --- | --- | --- |
| Python package | `holoscan_<slug>` | `holoscan_{{ cookiecutter.module_slug }}` |
| Python alias | `holoscan.<slug>` | `holoscan.{{ cookiecutter.module_slug }}` |
| Python import (`namespace.python`) | `holoscan.<slug>` | `holoscan.{{ cookiecutter.module_slug }}` |
| Python package (implementation) | `holoscan_<slug>` | `holoscan_{{ cookiecutter.module_slug }}` |
| Repository folder | `holoscan-<slug>` (kebab) | `{{ cookiecutter.module_repo_name }}` |
| Wheel distribution | `holoscan-<slug>` (kebab) | `holoscan-{{ cookiecutter.module_slug.replace('_', '-') }}` |
| CMake option prefix | `UPPER_SNAKE` | `{{ cookiecutter.module_slug | upper }}_BUILD_TESTING` |
Expand Down Expand Up @@ -258,11 +260,11 @@ distributing this Holoscan Module.
{% if cookiecutter.__python_bindings == 'yes' -%}
Holoscan SDK 5.0 is C++-first. The C++ operators are the implementation; `python/` adds a
nanobind extension that registers them with the SDK operator registry when
`holoscan_{{ cookiecutter.module_slug }}` is imported. Python code then uses the typed registry proxies:
`holoscan.{{ cookiecutter.module_slug }}` is imported. Python code then uses the typed registry proxies:

```python
import holoscan as hs
from holoscan_{{ cookiecutter.module_slug }}.operators import {{ cookiecutter.operator_slug.split('_')|map('capitalize')|join('') }}
from holoscan.{{ cookiecutter.module_slug }}.operators import {{ cookiecutter.operator_slug.split('_')|map('capitalize')|join('') }}
```

- Register each new operator with `HOLOSCAN_REGISTER_OPERATOR` in
Expand All @@ -279,8 +281,8 @@ from holoscan_{{ cookiecutter.module_slug }}.operators import {{ cookiecutter.op
- The package is not part of the Debian package. Install it on its own with
`cmake --install build --component holoscan-{{ cookiecutter.module_slug }}-python_libs`.
- The build tree and native installs carry the `holoscan-{{ cookiecutter.module_slug.replace('_', '-') }}-cu13` metadata written by
the SDK's `holoscan_install_python_module_metadata()`, so both `import holoscan_{{ cookiecutter.module_slug }}` and
`import holoscan.{{ cookiecutter.module_slug }}` work.
the SDK's `holoscan_install_python_module_metadata()`, so `import holoscan.{{ cookiecutter.module_slug }}` loads the
`holoscan_{{ cookiecutter.module_slug }}` package there too.
- `holoscan package {{ cookiecutter.module_repo_name }} --pkg-generator WHEEL` builds the same package into a
`holoscan-{{ cookiecutter.module_slug.replace('_', '-') }}` wheel with scikit-build-core, configured in `pyproject.toml`. The wheel declares its
own `holoscan.modules` entry point, so wheel builds skip `holoscan_install_python_module_metadata()`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

A **Holoscan Module** — a self-contained, redistributable package that extends
[Holoscan SDK](https://developer.nvidia.com/holoscan-sdk) 5 with reusable operators implemented
in Python, in the `holoscan_{{ cookiecutter.module_slug }}` package (also importable as `holoscan.{{ cookiecutter.module_slug }}`).
in Python, imported as `holoscan.{{ cookiecutter.module_slug }}` (implemented by the `holoscan_{{ cookiecutter.module_slug }}` package).
{%- set op_class = cookiecutter.operator_slug.split('_')|map('capitalize')|join('') %}

> This Module needs no C++ code or compiler. It ships as a pure-Python wheel; build it with
Expand Down Expand Up @@ -49,7 +49,7 @@ dependency.

### Namespace

- Python: `holoscan_{{ cookiecutter.module_slug }}`, also importable as `holoscan.{{ cookiecutter.module_slug }}`
- Python: `holoscan.{{ cookiecutter.module_slug }}` (implemented by the `holoscan_{{ cookiecutter.module_slug }}` package)

---

Expand All @@ -61,7 +61,7 @@ mismatches, missing clocks) are reported as diagnostics at compile time, before

```python
import holoscan as hs
from holoscan_{{ cookiecutter.module_slug }}.operators import {{ op_class }}
from holoscan.{{ cookiecutter.module_slug }}.operators import {{ op_class }}

graph = hs.Graph("my-pipeline", default_clock=hs.RealtimeClock)
op = graph.op({{ op_class }}, "{{ cookiecutter.operator_slug }}")
Expand Down Expand Up @@ -132,7 +132,7 @@ A **Holoscan Module** — a self-contained, redistributable library that extends

{% if cookiecutter.__python_bindings == 'yes' -%}
> Holoscan SDK 5.0 is C++-first. This Module ships C++ operators plus Python bindings that expose
> them through the SDK operator registry (`import holoscan_{{ cookiecutter.module_slug }}`). Build the bindings into a wheel
> them through the SDK operator registry (`import holoscan.{{ cookiecutter.module_slug }}`). Build the bindings into a wheel
> with `holoscan package {{ cookiecutter.module_repo_name }} --pkg-generator WHEEL`.
{%- else -%}
> Holoscan SDK 5.0 is C++-first. This Module ships C++ operators only; Python bindings and wheel
Expand Down Expand Up @@ -183,6 +183,9 @@ The project configuration installs the development tools without building the Mo
### Namespace

- C++: `holoscan::{{ cookiecutter.module_slug }}`
{%- if cookiecutter.__python_bindings == 'yes' %}
- Python: `holoscan.{{ cookiecutter.module_slug }}` (implemented by the `holoscan_{{ cookiecutter.module_slug }}` package)
{%- endif %}

---

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,8 @@
import threading
import time

from holoscan_{{ cookiecutter.module_slug }}.operators import {{ op_class }}

import holoscan as hs
from holoscan.{{ cookiecutter.module_slug }}.operators import {{ op_class }}

TICK_LIMIT = 10

Expand Down Expand Up @@ -108,9 +107,8 @@ def main() -> None:
import threading
import time

from holoscan_{{ cookiecutter.module_slug }}.operators import {{ op_class }}

import holoscan as hs
from holoscan.{{ cookiecutter.module_slug }}.operators import {{ op_class }}

TICK_LIMIT = 10

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@
{%- if cookiecutter.__pure_python == 'yes' %}
"language": ["Python"],
"namespace": {
"python": "holoscan_{{ cookiecutter.module_slug }}"
"python": "holoscan.{{ cookiecutter.module_slug }}"
},
{%- else %}
"language": [{% if cookiecutter.__python_bindings == 'yes' %}"C++", "Python"{% else %}"C++"{% endif %}],
"namespace": {
"cpp": "holoscan::{{ cookiecutter.module_slug }}"{% if cookiecutter.__python_bindings == 'yes' %},
"python": "holoscan_{{ cookiecutter.module_slug }}"{% endif %}
"python": "holoscan.{{ cookiecutter.module_slug }}"{% endif %}
},
{%- endif %}
"holoscan_sdk": {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,9 @@
import sys
from pathlib import Path

from holoscan_{{ cookiecutter.module_slug }}.operators import {{ op_class }}
import pytest

from holoscan.{{ cookiecutter.module_slug }}.operators import {{ op_class }}
from holoscan.testing import OperatorTestHarness

MODULE = "{{ cookiecutter.module_slug }}"
Expand All @@ -25,12 +26,27 @@
)


def test_module_metadata_exposes_holoscan_alias():
def test_module_metadata_exposes_holoscan_namespace():
entries = importlib.metadata.entry_points(group="holoscan.modules", name=MODULE)
assert [entry.value for entry in entries] == [f"holoscan_{MODULE}"]
import holoscan.{{ cookiecutter.module_slug }}.operators as alias
package = importlib.import_module(f"holoscan_{MODULE}.operators")

assert alias.{{ op_class }} is {{ op_class }}
assert package.{{ op_class }} is {{ op_class }}


@pytest.mark.parametrize("first", [f"holoscan.{MODULE}", f"holoscan_{MODULE}"])
def test_import_orders_load_one_package(first):
second = f"holoscan_{MODULE}" if first.startswith("holoscan.") else f"holoscan.{MODULE}"
script = (
"import importlib\n"
f"first = importlib.import_module('{first}.operators')\n"
f"second = importlib.import_module('{second}.operators')\n"
"assert first is second and first.{{ op_class }} is second.{{ op_class }}\n"
)
result = subprocess.run(
[sys.executable, "-c", script], capture_output=True, text=True, timeout=60, check=False
)
assert result.returncode == 0, result.stdout + result.stderr


def test_operator_forwards_each_value():
Expand All @@ -57,9 +73,10 @@ def test_python_pipeline_runs():
from pathlib import Path

import holoscan_{{ cookiecutter.module_slug }}
from holoscan_{{ cookiecutter.module_slug }}.operators import {{ op_class }}
import pytest

import holoscan as hs
from holoscan.{{ cookiecutter.module_slug }}.operators import {{ op_class }}

MODULE = "{{ cookiecutter.module_slug }}"
REGISTRY_NAME = "holoscan.{{ cookiecutter.module_slug }}.{{ op_class }}"
Expand All @@ -76,12 +93,27 @@ def test_extension_uses_the_stable_abi():
assert holoscan_{{ cookiecutter.module_slug }}._{{ cookiecutter.module_slug }}.__file__.endswith(".abi3.so")


def test_module_metadata_exposes_holoscan_alias():
def test_module_metadata_exposes_holoscan_namespace():
entries = importlib.metadata.entry_points(group="holoscan.modules", name=MODULE)
assert [entry.value for entry in entries] == [f"holoscan_{MODULE}"]
import holoscan.{{ cookiecutter.module_slug }}.operators as alias
package = importlib.import_module(f"holoscan_{MODULE}.operators")

assert alias.{{ op_class }} is {{ op_class }}
assert package.{{ op_class }} is {{ op_class }}


@pytest.mark.parametrize("first", [f"holoscan.{MODULE}", f"holoscan_{MODULE}"])
def test_import_orders_load_one_package(first):
second = f"holoscan_{MODULE}" if first.startswith("holoscan.") else f"holoscan.{MODULE}"
script = (
"import importlib\n"
f"first = importlib.import_module('{first}.operators')\n"
f"second = importlib.import_module('{second}.operators')\n"
"assert first is second and first.{{ op_class }} is second.{{ op_class }}\n"
)
result = subprocess.run(
[sys.executable, "-c", script], capture_output=True, text=True, timeout=60, check=False
)
assert result.returncode == 0, result.stdout + result.stderr


def test_operator_is_registered():
Expand Down
5 changes: 3 additions & 2 deletions tests/unit/test_create_module.py
Original file line number Diff line number Diff line change
Expand Up @@ -367,7 +367,7 @@ def test_packaged_template_generates_python_bindings_for_cpp_python(cli, tmp_pat
(project / "operators/my_mod_op/metadata.json").read_text(encoding="utf-8")
)["operator"]
assert operator["language"] == ["C++", "Python"]
assert module["namespace"] == {"cpp": "holoscan::my_mod", "python": "holoscan_my_mod"}
assert module["namespace"] == {"cpp": "holoscan::my_mod", "python": "holoscan.my_mod"}
_validate_generated_metadata(project)
apps = {
lang: json.loads(
Expand Down Expand Up @@ -436,6 +436,7 @@ def test_packaged_template_generates_a_pure_python_module(cli, tmp_path, monkeyp
encoding="utf-8"
)
assert 'graph.op(MyModOp, "my_mod_op")' in application
assert "from holoscan.my_mod.operators import MyModOp" in application
tests = (project / "tests/python/test_my_mod.py").read_text(encoding="utf-8")
assert "OperatorTestHarness(MyModOp)" in tests

Expand Down Expand Up @@ -473,7 +474,7 @@ def test_packaged_template_generates_a_pure_python_module(cli, tmp_path, monkeyp

metadata = json.loads((project / "metadata.json").read_text(encoding="utf-8"))["module"]
assert metadata["language"] == ["Python"]
assert metadata["namespace"] == {"python": "holoscan_my_mod"}
assert metadata["namespace"] == {"python": "holoscan.my_mod"}
assert metadata["binary_packages"]["wheel"] == "holoscan-my-mod"
assert "debian" not in metadata["binary_packages"]
assert metadata["testing"] == {"python": "pytest"}
Expand Down
23 changes: 20 additions & 3 deletions tests/unit/test_project_context.py
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ def test_module_discovery_and_activation(tmp_path, monkeypatch):

assert context.root == root
assert context.module_name == "holoscan-my-sensor"
assert context.repo_prefix == "my_sensor"
assert context.repo_prefix == "holoscan_my_sensor"
assert context.base_sdk_version == "4.6.0"
assert context.forward_env == ()

Expand All @@ -66,8 +66,25 @@ def test_module_discovery_and_activation(tmp_path, monkeypatch):
assert os.environ["HOLOSCAN_CLI_ROOT"] == str(root)
assert os.environ["HOLOSCAN_CLI_BUILD_PARENT_DIR"] == str(root / "build")
assert os.environ["HOLOSCAN_CLI_DATA_DIR"] == "/custom/data"
assert os.environ["HOLOSCAN_CLI_REPO_PREFIX"] == "my_sensor"
assert os.environ["HOLOSCAN_CLI_CONTAINER_PREFIX"] == "my-sensor"
assert os.environ["HOLOSCAN_CLI_REPO_PREFIX"] == "holoscan_my_sensor"
assert os.environ["HOLOSCAN_CLI_CONTAINER_PREFIX"] == "holoscan-my-sensor"


@pytest.mark.parametrize(
("namespace", "expected"),
[
({"python": "holoscan.my_sensor"}, "holoscan_my_sensor"),
({"python": "holoscan_my_sensor"}, "holoscan_my_sensor"),
({"cpp": "holoscan::my_sensor"}, "my_sensor"),
],
)
def test_module_repo_prefix_follows_the_python_namespace(tmp_path, namespace, expected):
root = _module(tmp_path / "module")
metadata = json.loads((root / "metadata.json").read_text(encoding="utf-8"))
metadata["module"]["namespace"] = namespace
(root / "metadata.json").write_text(json.dumps(metadata), encoding="utf-8")

assert discover_project_context(cwd=root, environ={}).repo_prefix == expected


def test_implicit_discovery_tolerates_malformed_module_metadata(tmp_path):
Expand Down
Loading