holoscan-cli 2.9.0__py3-none-any.whl

holoscan_cli/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+"""
+.. autosummary::
+    :toctree: _autosummary
+
+    common
+    packager
+    runner
+    version
+"""
+
+import importlib.metadata
+import os
+import sys
+
+__title__ = "holoscan_cli"
+_current_dir = os.path.abspath(os.path.dirname(__file__))
+if sys.path and os.path.abspath(sys.path[0]) != _current_dir:
+    sys.path.insert(0, _current_dir)
+del _current_dir
+
+__version__ = importlib.metadata.version("holoscan-cli")

holoscan_cli/__main__.py

@@ -0,0 +1,164 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+import argparse
+import json
+import logging
+import logging.config
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+from .common.enum_types import Platform, PlatformConfiguration
+
+logging.getLogger("docker.api.build").setLevel(logging.WARNING)
+logging.getLogger("docker.auth").setLevel(logging.WARNING)
+logging.getLogger("docker.utils.config").setLevel(logging.WARNING)
+logging.getLogger("urllib3.connectionpool").setLevel(logging.WARNING)
+logging.getLogger("urllib3").setLevel(logging.WARNING)
+
+LOG_CONFIG_FILENAME = "logging.json"
+
+
+def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
+    from .packager.package_command import create_package_parser
+    from .runner.run_command import create_run_parser
+
+    if argv is None:
+        import sys
+
+        argv = sys.argv
+    argv = list(argv)  # copy argv for manipulation to avoid side-effects
+
+    # We have intentionally not set the default using `default="INFO"` here so that the default
+    # value from here doesn't override the value in `LOG_CONFIG_FILENAME` unless the user indends
+    # to do so. If the user doesn't use this flag to set log level, this argument is set to "None"
+    # and the logging level specified in `LOG_CONFIG_FILENAME` is used.
+
+    command_name = os.path.basename(argv[0])
+    program_name = "holoscan" if command_name == "__main__.py" else command_name
+    parent_parser = argparse.ArgumentParser()
+
+    parent_parser.add_argument(
+        "-l",
+        "--log-level",
+        dest="log_level",
+        type=str.upper,
+        choices=["DEBUG", "INFO", "WARN", "ERROR", "CRITICAL"],
+        help="set the logging level (default: INFO)",
+    )
+
+    parser = argparse.ArgumentParser(
+        parents=[parent_parser],
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        add_help=False,
+        prog=program_name,
+    )
+
+    subparser = parser.add_subparsers(dest="command")
+
+    # Parser for `package` command
+    create_package_parser(subparser, "package", parents=[parent_parser])
+
+    # Parser for `run` command
+    create_run_parser(subparser, "run", parents=[parent_parser])
+
+    # Parser for `version` command
+    subparser.add_parser(
+        "version",
+        formatter_class=argparse.HelpFormatter,
+        parents=[parent_parser],
+        add_help=False,
+    )
+
+    # Parser for `nics` command
+    subparser.add_parser(
+        "nics",
+        formatter_class=argparse.HelpFormatter,
+        parents=[parent_parser],
+        add_help=False,
+    )
+    args = parser.parse_args(argv[1:])
+    args.argv = argv  # save argv for later use in runpy
+
+    # Print help if no command is specified
+    if args.command is None:
+        parser.print_help()
+        parser.exit()
+
+    if args.command == "package":
+        if args.platform[0] == Platform.X64Workstation:
+            args.platform_config = PlatformConfiguration.dGPU
+        elif args.platform_config is None:
+            parser.error(
+                f"'--platform-config' is required for '{args.platform[0].value}'"
+            )
+
+    return args
+
+
+def set_up_logging(
+    level: Optional[str], config_path: Union[str, Path] = LOG_CONFIG_FILENAME
+):
+    """Initializes the logger and sets up logging level.
+
+    Args:
+        level (str): A logging level (DEBUG, INFO, WARN, ERROR, CRITICAL).
+        log_config_path (str): A path to logging config file.
+    """
+    # Default log config path
+    log_config_path = Path(__file__).absolute().parent / LOG_CONFIG_FILENAME
+
+    config_path = Path(config_path)
+
+    # If a logging config file that is specified by `log_config_path` exists in the current folder,
+    # it overrides the default one
+    if config_path.exists():
+        log_config_path = config_path
+
+    config_dict = json.loads(log_config_path.read_bytes())
+
+    if level is not None and "root" in config_dict:
+        config_dict["root"]["level"] = level
+    logging.config.dictConfig(config_dict)
+
+
+def main(argv: Optional[list[str]] = None):
+    args = parse_args(argv)
+
+    set_up_logging(args.log_level)
+
+    if args.command == "package":
+        from .packager.packager import execute_package_command
+
+        execute_package_command(args)
+
+    elif args.command == "run":
+        from .runner.runner import execute_run_command
+
+        execute_run_command(args)
+
+    elif args.command == "version":
+        from .version.version import execute_version_command
+
+        execute_version_command(args)
+
+    elif args.command == "nics":
+        from .nics.nics import execute_nics_command
+
+        execute_nics_command(args)
+
+
+if __name__ == "__main__":
+    main()

holoscan_cli/common/argparse_types.py

@@ -0,0 +1,156 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+import argparse
+import os
+from pathlib import Path
+
+from .constants import SDK
+from .enum_types import Platform, PlatformConfiguration, SdkType
+
+
+def valid_dir_path(path: str, create_if_not_exists: bool = True) -> Path:
+    """Helper type checking and type converting method for ArgumentParser.add_argument
+    to convert string input to pathlib.Path if the given path exists and it is a directory path.
+    If directory does not exist, create the directory and convert string input to pathlib.Path.
+
+    Args:
+        path: string input path
+
+    Returns:
+        If path exists and is a directory, return absolute path as a pathlib.Path object.
+
+        If path exists and is not a directory, raises argparse.ArgumentTypeError.
+
+        If path doesn't exist, create the directory and return absolute path as a pathlib.Path
+        object.
+    """
+    path = os.path.expanduser(path)
+    dir_path = Path(path).absolute()
+    if dir_path.exists():
+        if dir_path.is_dir():
+            return dir_path
+        else:
+            raise argparse.ArgumentTypeError(
+                f"Expected directory path: '{dir_path}' is not a directory"
+            )
+
+    if create_if_not_exists:
+        # create directory
+        dir_path.mkdir(parents=True)
+        return dir_path
+
+    raise argparse.ArgumentTypeError(f"No such directory: '{dir_path}'")
+
+
+def valid_existing_dir_path(path: str) -> Path:
+    """Helper type checking and type converting method for ArgumentParser.add_argument
+    to convert string input to pathlib.Path if the given path exists and it is a directory path.
+
+    Args:
+        path: string input path
+
+    Returns:
+        If path exists and is a directory, return absolute path as a pathlib.Path object.
+
+        If path doesn't exist or it is not a directory, raises argparse.ArgumentTypeError.
+    """
+    return valid_dir_path(path, False)
+
+
+def valid_existing_path(path: str) -> Path:
+    """Helper type checking and type converting method for ArgumentParser.add_argument
+    to convert string input to pathlib.Path if the given file/folder path exists.
+
+    Args:
+        path: string input path
+
+    Returns:
+        If path exists, return absolute path as a pathlib.Path object.
+
+        If path doesn't exist, raises argparse.ArgumentTypeError.
+    """
+    path = os.path.expanduser(path)
+    file_path = Path(path).absolute()
+    if file_path.exists():
+        if file_path.is_dir():
+            if any(os.scandir(file_path)):
+                return file_path
+            raise argparse.ArgumentTypeError(f"Directory is empty: '{file_path}'")
+        return file_path
+    raise argparse.ArgumentTypeError(f"No such file/folder: '{file_path}'")
+
+
+def valid_platforms(platforms_str: str) -> list[Platform]:
+    """Helper type checking and type converting method for ArgumentParser.add_argument
+    to convert platform strings to Platform enum if values are valid.
+
+    Args:
+        platforms_str: string comma separated platforms values
+    Returns:
+        If all values are valid, convert all values to Platform enum.
+
+        Otherwise, raises argparse.ArgumentTypeError.
+    """
+
+    platforms = platforms_str.lower().split(",")
+    platform_enums = []
+    for platform in platforms:
+        if platform not in SDK.PLATFORMS:
+            raise argparse.ArgumentTypeError(
+                f"{platform} is not a valid option for --platforms."
+            )
+        platform_enums.append(Platform(platform))
+
+    return platform_enums
+
+
+def valid_platform_config(platform_config_str: str) -> PlatformConfiguration:
+    """Helper type checking and type converting method for ArgumentParser.add_argument
+    to convert platform configuration string to PlatformConfigurations enum if value is valid.
+
+    Args:
+        platform_config_str: a platforms configuration value
+    Returns:
+        If the value is valid, convert the value to PlatformConfigurations enum.
+
+        Otherwise, raises argparse.ArgumentTypeError.
+    """
+
+    platform_config_str = platform_config_str.lower()
+    if platform_config_str not in SDK.PLATFORM_CONFIGS:
+        raise argparse.ArgumentTypeError(
+            f"{platform_config_str} is not a valid option for --platform-config."
+        )
+
+    return PlatformConfiguration(platform_config_str)
+
+
+def valid_sdk_type(sdk_str: str) -> SdkType:
+    """Helper type checking and type converting method for ArgumentParser.add_argument
+    to convert sdk string to SdkType enum if value is valid.
+
+    Args:
+        sdk_str: sdk string
+    Returns:
+        If the value is valid, convert the value to SdkType enum.
+
+        Otherwise, raises argparse.ArgumentTypeError.
+    """
+
+    sdk_str = sdk_str.lower()
+    if sdk_str not in SDK.SDKS:
+        raise argparse.ArgumentTypeError(f"{sdk_str} is not a valid option for --sdk.")
+
+    return SdkType(sdk_str)

holoscan_cli/common/artifact_sources.py

@@ -0,0 +1,160 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+import json
+import logging
+from typing import Any, Optional
+
+import requests
+
+from holoscan_cli import __version__
+from packaging.version import InvalidVersion, Version
+
+from .enum_types import PlatformConfiguration, SdkType
+from .exceptions import InvalidSourceFileError, ManifestDownloadError
+
+
+class ArtifactSources:
+    """Provides default artifact source URLs with the ability to override."""
+
+    SectionWheelVersion = "wheel-version"
+    SectionDebianVersion = "debian-version"
+    SectionBaseImages = "base-images"
+    SectionBuildImages = "build-images"
+    SectionHealthProbe = "health-probes"
+    HoloscanVersion = None
+    ManifestFileUrl = None
+
+    def __init__(self) -> None:
+        self._logger = logging.getLogger("common")
+        try:
+            ArtifactSources.HoloscanVersion = ".".join(
+                str(i) for i in Version(__version__).release[0:3]
+            )
+        except InvalidVersion as ex:
+            raise RuntimeError(
+                "Unable to detect Holoscan version. Use --sdk-version to specify "
+                "a Holoscan SDK version to use."
+            ) from ex
+
+        ArtifactSources.ManifestFileUrl = f"https://raw.githubusercontent.com/nvidia-holoscan/holoscan-cli/refs/heads/main/releases/{ArtifactSources.HoloscanVersion}/artifacts.json"  # noqa: E501
+
+    @property
+    def holoscan_versions(self) -> list[str]:
+        # logic to dynamically fetch the supported versions
+        return self._data.keys()
+
+    def base_image(self, version) -> str:
+        return self._data[version][SdkType.Holoscan.value][
+            ArtifactSources.SectionBaseImages
+        ]
+
+    def build_images(self, version) -> dict[Any, str]:
+        return self._data[version][SdkType.Holoscan.value][
+            ArtifactSources.SectionBuildImages
+        ]
+
+    def health_probe(self, version) -> dict[Any, str]:
+        return self._data[version][ArtifactSources.SectionHealthProbe]
+
+    def load(self, uri: str):
+        """Overrides the default values from a given JSON file.
+           Validates top-level attributes to ensure the file is valid
+
+        Args:
+            file (Path): Path to JSON file
+        """
+        if uri.startswith("https"):
+            self._download_manifest_internal(uri)
+        elif uri.startswith("http"):
+            raise ManifestDownloadError(
+                "Downloading manifest files from non-HTTPS servers is not supported."
+            )
+        else:
+            self._logger.info(f"Using CLI manifest file from {uri}...")
+            with open(uri) as file:
+                temp = json.load(file)
+
+            try:
+                self.validate(temp)
+                self._data = temp
+            except Exception as ex:
+                raise InvalidSourceFileError(
+                    f"{uri} is missing required data: {ex}"
+                ) from ex
+
+    def validate(self, data: Any):
+        self._logger.debug("Validating CLI manifest file...")
+
+        for key in data:
+            item = data[key]
+            assert SdkType.Holoscan.value in item
+            holoscan = item[SdkType.Holoscan.value]
+
+            assert ArtifactSources.SectionWheelVersion in holoscan
+            assert ArtifactSources.SectionDebianVersion in holoscan
+            assert ArtifactSources.SectionBaseImages in holoscan
+            assert ArtifactSources.SectionBuildImages in holoscan
+
+            for config in PlatformConfiguration:
+                assert config.value in holoscan[ArtifactSources.SectionBuildImages]
+
+    def download_manifest(self):
+        self._download_manifest_internal(
+            ArtifactSources.ManifestFileUrl,
+        )
+
+    def _download_manifest_internal(self, url, headers=None):
+        self._logger.info("Downloading CLI manifest file...")
+        manifest = requests.get(url, headers=headers)
+
+        try:
+            manifest.raise_for_status()
+        except Exception as ex:
+            raise ManifestDownloadError(
+                f"Error downloading manifest file from {url}: {manifest.reason}"
+            ) from ex
+        else:
+            self._data = manifest.json()
+            self.validate(self._data)
+
+    def debian_package_version(self, version: str) -> Optional[str]:
+        """Gets the version of the Debian package based on the version of Holoscan.
+
+        Args:
+            version (str): version of Holoscan
+
+        Returns:
+            Optional[str]: Debian package version
+        """
+        return (
+            self._data[version][SdkType.Holoscan.value][
+                ArtifactSources.SectionDebianVersion
+            ]
+            if version in self._data
+            else None
+        )
+
+    def wheel_package_version(self, version: str) -> Optional[str]:
+        """Gets the version of the PyPI package based on the version of Holoscan.
+
+        Args:
+            version (str): version of Holoscan
+
+        Returns:
+            Optional[str]: PyPI package version
+        """
+        return self._data[version][SdkType.Holoscan.value][
+            ArtifactSources.SectionWheelVersion
+        ]

holoscan_cli/common/constants.py

@@ -0,0 +1,119 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# 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.
+from pathlib import Path
+
+from .enum_types import Arch, Platform, PlatformConfiguration, SdkType
+
+
+class DefaultValues:
+    """
+    This class contains default values for various parameters.
+    """
+
+    API_VERSION = "1.0.0"  # MAP/HAP version number
+    DOCKER_FILE_NAME = "Dockerfile"  # Filename of the generated Dockerfile
+    TIMEOUT = 0  # Default application timeout
+    USERNAME = "holoscan"  # Default user to be created in the container
+    BUILD_CACHE_DIR = Path(
+        "~/.holoscan_build_cache"
+    )  # A local directory used for storing Docker build cache
+
+    HOLOSCAN_APP_DIR = Path("/opt/holoscan/app")  # Path to user's application
+    HOLOSCAN_LIB_DIR = Path("/opt/holoscan/lib")  # Path to user's application
+    HOLOSCAN_CONFIG_PATH = Path(
+        "/var/holoscan/app.yaml"
+    )  # Path to the application config file
+    HOLOSCAN_DOCS_DIR = Path("/opt/holoscan/docs")  # Path to documentation
+    HOLOSCAN_LOGS_DIR = Path("/var/holoscan/logs")  # Path to application logs
+    INPUT_DIR = "input/"  # Relative path to application input data
+    MODELS_DIR = Path("/opt/holoscan/models/")  # Path to user provided model(s)
+    OUTPUT_DIR = "output/"  # Relative path to application generated results
+    WORK_DIR = Path("/var/holoscan/")  # Default working directory
+    APP_MANIFEST_PATH = "/etc/holoscan/app.json"  # Path to app.json manifest file
+    PKG_MANIFEST_PATH = "/etc/holoscan/pkg.json"  # Path to pkg.json manifest file
+
+    DEFAULT_SHM_SIZE = 1073741824
+
+
+class Constants:
+    CPP_CMAKELIST_FILE = "CMakeLists.txt"
+    PYTHON_EXECUTABLE = "python3"
+    PYTHON_MAIN_FILE = "__main__.py"
+
+    TARBALL_FILE_EXTENSION = ".tar"
+
+    DEBIAN_FILE_EXTENSION = ".deb"
+    PYPI_WHEEL_FILE_EXTENSION = ".whl"
+    PYPI_TARGZ_FILE_EXTENSION = ".gz"
+    PYTHON_FILE_EXTENSION = ".py"
+
+    PYPI_FILE_EXTENSIONS = [PYPI_WHEEL_FILE_EXTENSION, PYPI_TARGZ_FILE_EXTENSION]
+
+    LOCAL_BUILDX_BUILDER_NAME = "holoscan_app_builder"
+    LOCAL_DOCKER_REGISTRY_NAME = "holoscan_build_registry"
+    LOCAL_REGISTRY_IMAGE_NAME = "registry:2"
+    LOCAL_REGISTRY_HOST = "localhost"
+    LOCAL_REGISTRY_INTERNAL_PORT = "5000/tcp"
+
+    RESOURCE_SHARED_MEMORY_KEY = "sharedMemory"
+
+
+class SDK:
+    """
+    This class contains lookup tables for various platform and SDK settings.
+
+    """
+
+    # Platform to architecture mappings
+    PLATFORM_MAPPINGS = {
+        Platform.IGXOrinDevIt: Arch.arm64,
+        Platform.JetsonAgxOrinDevKit: Arch.arm64,
+        Platform.SBSA: Arch.arm64,
+        Platform.X64Workstation: Arch.amd64,
+    }
+
+    # Values of all platforms supported by the Packager
+    PLATFORMS = [
+        Platform.IGXOrinDevIt.value,
+        Platform.JetsonAgxOrinDevKit.value,
+        Platform.SBSA.value,
+        Platform.X64Workstation.value,
+    ]
+
+    # Values of all platform configurations supported by the Packager
+    PLATFORM_CONFIGS = [
+        PlatformConfiguration.iGPU.value,
+        PlatformConfiguration.dGPU.value,
+    ]
+
+    # Values of SDKs supported by the Packager
+    SDKS = [SdkType.Holoscan.value, SdkType.MonaiDeploy.value]
+
+
+class EnvironmentVariables:
+    """
+    This class includes all environment variables set in
+    the container and in the app.json manifest file."""
+
+    HOLOSCAN_APPLICATION = "HOLOSCAN_APPLICATION"
+    HOLOSCAN_INPUT_PATH = "HOLOSCAN_INPUT_PATH"
+    HOLOSCAN_OUTPUT_PATH = "HOLOSCAN_OUTPUT_PATH"
+    HOLOSCAN_WORKDIR = "HOLOSCAN_WORKDIR"
+    HOLOSCAN_MODEL_PATH = "HOLOSCAN_MODEL_PATH"
+    HOLOSCAN_CONFIG_PATH = "HOLOSCAN_CONFIG_PATH"
+    HOLOSCAN_APP_MANIFEST_PATH = "HOLOSCAN_APP_MANIFEST_PATH"
+    HOLOSCAN_PKG_MANIFEST_PATH = "HOLOSCAN_PKG_MANIFEST_PATH"
+    HOLOSCAN_DOCS_PATH = "HOLOSCAN_DOCS_PATH"
+    HOLOSCAN_LOGS_PATH = "HOLOSCAN_LOGS_PATH"