pysdccc 0.1.0__py3-none-any.whl

pysdccc/__init__.py

@@ -0,0 +1,25 @@
+"""Python wrapper to the SDCcc tool for testing SDC devices."""
+
+from pysdccc._common import DEFAULT_STORAGE_DIRECTORY
+from pysdccc._download import adownload, ais_downloaded, download, is_downloaded
+from pysdccc._result_parser import TestCase, TestSuite
+from pysdccc._runner import (
+    SdcccRunner,
+    SdcccRunnerAsync,
+    check_requirements,
+)
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'DEFAULT_STORAGE_DIRECTORY',
+    'SdcccRunner',
+    'SdcccRunnerAsync',
+    'TestCase',
+    'TestSuite',
+    'adownload',
+    'ais_downloaded',
+    'check_requirements',
+    'download',
+    'is_downloaded',
+]

pysdccc/_cli.py

@@ -0,0 +1,145 @@
+"""Command line interface."""
+
+import contextlib
+import io
+import pathlib
+import subprocess
+import sys
+import tempfile
+import zipfile
+
+import httpx
+
+from pysdccc import _common, _download
+
+try:
+    import click
+except ImportError as import_error:
+    msg = 'Cli not installed. Please install "pysdccc[cli]" package.'
+    raise ImportError(msg) from import_error
+
+
+class UrlType(click.ParamType):
+    """Url type."""
+
+    name = 'url'
+
+    def convert(self, value: str, param: click.Parameter | None, ctx: click.Context | None) -> httpx.URL:
+        """Convert value to url."""
+        try:
+            return httpx.URL(value)
+        except Exception as e:  # noqa: BLE001
+            self.fail(f'{value!r} is not a valid url: {e}', param, ctx)
+
+
+URL = UrlType()
+
+
+class ProxyType(click.ParamType):
+    """Proxy type."""
+
+    name = 'proxy'
+
+    def convert(self, value: str, param: click.Parameter | None, ctx: click.Context | None) -> httpx.Proxy | None:
+        """Convert value to proxy."""
+        try:
+            return httpx.Proxy(value)
+        except Exception as e:  # noqa: BLE001
+            self.fail(f'{value!r} is not a valid proxy: {e}', param, ctx)
+
+
+PROXY = ProxyType()
+
+
+def _download_to_stream(url: httpx.URL, stream: io.IOBase, proxy: httpx.Proxy | None = None) -> None:
+    with _download.open_download_stream(url, proxy) as response:
+        total = response.headers.get('Content-Length')
+        with click.progressbar(
+            response.iter_bytes(),
+            length=int(total) if total is not None else None,
+            label='Downloading',
+            show_eta=True,
+            width=0,
+        ) as progress:
+            num_bytes_downloaded = response.num_bytes_downloaded
+            for chunk in progress:
+                stream.write(chunk)
+                progress.update(response.num_bytes_downloaded - num_bytes_downloaded)
+                num_bytes_downloaded = response.num_bytes_downloaded
+
+
+def download(url: httpx.URL, output: pathlib.Path, proxy: httpx.Proxy | None = None):
+    """Download and extract the executable from an url."""
+    click.echo(f'Downloading SDCcc from {url}.')
+    with tempfile.NamedTemporaryFile('wb', suffix='.zip', delete=False) as temporary_file:
+        _download_to_stream(url, temporary_file, proxy=proxy)  # type: ignore[arg-type]
+    click.echo(f'Extracting SDCcc to {output}.')
+    with (
+        zipfile.ZipFile(temporary_file.name) as f,
+        click.progressbar(f.infolist(), label='Extracting', width=0) as progress,
+    ):
+        for member in progress:
+            f.extract(member, output)
+
+
+@click.group(help='Manage SDCcc installation.')
+@click.version_option(message='%(version)s')
+def cli():
+    pass
+
+
+@click.command(
+    short_help='Install the SDCcc executable from the specified URL. Releases can be found at https://github.com/Draegerwerk/SDCcc/releases.',
+)
+@click.argument('url', type=URL)
+@click.option('--proxy', help='Proxy server to use for the download.', type=PROXY)
+@click.pass_context
+def install(ctx: click.Context, url: httpx.URL, proxy: httpx.Proxy | None):
+    """Download the specified version from the default URL to a temporary directory.
+
+    This function downloads the SDCcc executable from the given URL to a temporary directory.
+    It optionally uses a proxy and a specified timeout for the download operation.
+    The downloaded file is extracted to a local path determined by the version string in the URL.
+
+    :param ctx: context from click
+    :param url: The parsed URL from which to download the executable.
+    :param proxy: Optional proxy to be used for the download.
+    """
+    ctx.invoke(uninstall)
+    try:
+        download(url, _common.DEFAULT_STORAGE_DIRECTORY, proxy)
+    except Exception as e:
+        msg = f'Failed to download and extract SDCcc from {url}: {e}.'
+        raise click.ClickException(msg) from e
+
+
+@click.command(short_help='Uninstall the SDCcc executable by removing the directory.')
+def uninstall():
+    """Uninstall the SDCcc executable.
+
+    This function removes the SDCcc executable from the directory.
+    """
+    import shutil
+
+    with contextlib.suppress(FileNotFoundError):
+        shutil.rmtree(_common.DEFAULT_STORAGE_DIRECTORY)
+
+
+cli.add_command(install)
+cli.add_command(uninstall)
+
+
+def sdccc():
+    try:
+        sdccc_exe = _common.get_exe_path(_common.DEFAULT_STORAGE_DIRECTORY)
+        subprocess.run(  # noqa: S603
+            [sdccc_exe, *sys.argv[1:]],
+            check=True,
+            cwd=sdccc_exe.parent,
+        )
+    except FileNotFoundError as e:
+        click.ClickException("SDCcc is not installed. Please install using 'pysdccc install <url>'.").show()
+        raise SystemExit(1) from e
+    except subprocess.CalledProcessError as e:
+        click.echo(e, err=True)
+        raise SystemExit(e.returncode) from e

pysdccc/_common.py

@@ -0,0 +1,57 @@
+"""Contains commonly used constants and functions."""
+
+import locale
+import os
+import pathlib
+import sys
+from collections.abc import Iterable
+
+DEFAULT_STORAGE_DIRECTORY = pathlib.Path(__file__).parent.joinpath('_sdccc')
+"""Default directory to store the downloaded SDCcc versions."""
+
+PATH_TYPE = str | os.PathLike[str]
+
+ENCODING = 'utf-8' if sys.flags.utf8_mode else locale.getencoding()
+
+SINGLE_CMD_TYPE = str | int | bool | pathlib.Path
+CMD_TYPE = SINGLE_CMD_TYPE | Iterable[str | int | pathlib.Path] | None
+
+
+def build_command(*args: str, **kwargs: CMD_TYPE) -> list[str]:
+    """Build the command string from the arguments and keyword arguments."""
+    command = list(args)
+    for arg, value in kwargs.items():
+        if isinstance(value, SINGLE_CMD_TYPE):
+            if value is True:
+                command.append(f'--{arg}')
+            elif value is False:
+                continue  # ignore False flags
+            else:
+                command.append(f'--{arg}')
+                command.append(str(value))
+        elif isinstance(value, Iterable) and not isinstance(value, dict | bytes):
+            for item in value:
+                command.append(f'--{arg}')
+                command.append(str(item))
+        elif value is not None:
+            err = f'Unsupported value type: {type(value)}'
+            raise TypeError(err)
+    return command
+
+
+def get_exe_path(local_path: pathlib.Path) -> pathlib.Path:
+    """Get the path to the SDCcc executable.
+
+    This function searches the specified local path for the SDCcc executable file. It expects exactly one executable
+    file matching the pattern "sdccc-*.exe" to be present in the directory. If no such file or more than one file is
+    found, a FileNotFoundError is raised.
+
+    :param local_path: The local path where the SDCcc executable is expected to be found.
+    :return: The path to the SDCcc executable file.
+    :raises FileNotFoundError: If no executable file or more than one executable file is found in the specified path.
+    """
+    files = [f for f in local_path.glob('*.exe') if f.is_file()]
+    if len(files) != 1:
+        msg = f'Expected a single executable file, got {files} in path {local_path}'
+        raise FileNotFoundError(msg)
+    return files[0]

pysdccc/_download.py

@@ -0,0 +1,119 @@
+"""Everything needed for downloading SDCcc."""
+
+import contextlib
+import logging
+import pathlib
+import subprocess
+import tempfile
+import zipfile
+from collections.abc import AsyncGenerator, Generator
+
+import httpx
+
+from pysdccc import _common, _runner
+
+logger = logging.getLogger('pysdccc.download')
+
+
+@contextlib.contextmanager
+def open_download_stream(
+    url: httpx.URL, proxy: httpx.Proxy | None = None, timeout: float | None = None
+) -> Generator[httpx.Response, None, None]:
+    """Open a stream from which SDCcc can be downloaded chunk by chunk."""
+    with httpx.stream('GET', url, follow_redirects=True, proxy=proxy, timeout=timeout) as response:
+        response.raise_for_status()
+        yield response
+
+
+def download(
+    url: httpx.URL | str,
+    proxy: httpx.Proxy | None = None,
+    output: pathlib.Path | None = None,
+    timeout: float | None = None,
+) -> pathlib.Path:
+    """Download and extract the specified version from the URL.
+
+    :param url: The parsed URL from which to download the executable.
+    :param proxy: Optional proxy to be used for the download.
+    :param output: The path to the directory where the downloaded executable will be extracted. If None,
+    `DEFAULT_STORAGE_DIRECTORY` is used.
+    :param timeout: Optional timeout in seconds for the download.
+    :return: Path to the executable.
+    """
+    url = httpx.URL(url)
+    logger.info('Downloading SDCcc from %s.', url)
+    with (
+        tempfile.NamedTemporaryFile('wb', suffix='.zip', delete=False) as temporary_file,
+        open_download_stream(url, proxy, timeout) as response,
+    ):
+        for chunk in response.iter_bytes():
+            temporary_file.write(chunk)
+    output = output or _common.DEFAULT_STORAGE_DIRECTORY
+    logger.info('Extracting SDCcc to %s.', output)
+    with zipfile.ZipFile(temporary_file.name) as f:
+        f.extractall(output)
+    return _common.get_exe_path(output)
+
+
+def is_downloaded(version: str) -> bool:
+    """Check if the SDCcc version is already downloaded.
+
+    This function checks if the SDCcc executable is already downloaded.
+
+    :return: True if the executable is already downloaded, False otherwise.
+    """
+    try:
+        return _runner.SdcccRunner(pathlib.Path().absolute()).get_version() == version
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return False
+
+
+@contextlib.asynccontextmanager
+async def aopen_download_stream(
+    url: httpx.URL,
+    proxy: httpx.Proxy | None = None,
+) -> AsyncGenerator[httpx.Response, None]:
+    """Open a stream from which SDCcc can be downloaded chunk by chunk."""
+    client = httpx.AsyncClient(follow_redirects=True, proxy=proxy)
+    async with client.stream('GET', url) as response:
+        response.raise_for_status()
+        yield response
+
+
+async def adownload(
+    url: httpx.URL | str,
+    proxy: httpx.Proxy | None = None,
+    output: pathlib.Path | None = None,
+) -> pathlib.Path:
+    """Download and extract the specified version from the URL.
+
+    :param url: The parsed URL from which to download the executable.
+    :param proxy: Optional proxy to be used for the download.
+    :param output: The path to the directory where the downloaded executable will be extracted. If None,
+    `DEFAULT_STORAGE_DIRECTORY` is used.
+    :return: Path to the executable.
+    """
+    url = httpx.URL(url)
+    logger.info('Downloading SDCcc from %s.', url)
+    with tempfile.NamedTemporaryFile('wb', suffix='.zip', delete=False) as temporary_file:
+        async with aopen_download_stream(url, proxy=proxy) as response:
+            async for chunk in response.aiter_bytes():
+                temporary_file.write(chunk)
+    output = output or _common.DEFAULT_STORAGE_DIRECTORY
+    logger.info('Extracting SDCcc to %s.', output)
+    with zipfile.ZipFile(temporary_file.name) as f:
+        f.extractall(output)
+    return _common.get_exe_path(output)
+
+
+async def ais_downloaded(version: str) -> bool:
+    """Check if the SDCcc version is already downloaded.
+
+    This function checks if the SDCcc executable is already downloaded.
+
+    :return: True if the executable is already downloaded, False otherwise.
+    """
+    try:
+        return await _runner.SdcccRunnerAsync(pathlib.Path().absolute()).get_version() == version
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return False

pysdccc/_result_parser.py

@@ -0,0 +1,130 @@
+"""Parser for the JUnit XML test results provided by SDCcc including custom elements.
+
+This module provides classes to parse and handle JUnit XML test results with custom elements specific to SDCcc.
+It includes custom elements for test identifiers and descriptions, as well as custom test case and test suite classes.
+
+Classes
+-------
+
+TestIdentifierElement
+    Represents the test identifier element in the JUnit XML.
+TestDescriptionElement
+    Represents the test description element in the JUnit XML.
+TestCase
+    Represents a test case with custom elements.
+TestSuite
+    Represents a test suite with custom test cases.
+
+Usage
+-----
+
+.. code-block:: python
+
+    from result_parser import TestSuite
+
+    # Parse a test suite from a file
+    test_suite = TestSuite.from_file("path/to/test_results.xml")
+
+    # Iterate over test cases in the test suite
+    for test_case in test_suite:
+        print(test_case.test_identifier)
+        print(test_case.test_description)
+"""
+
+import pathlib
+import typing
+
+from junitparser import junitparser
+
+
+class TestIdentifierElement(junitparser.Element):
+    """Element containing the test identifier.
+
+    This class represents a custom XML element for the test identifier in the JUnit XML test results.
+    It extends the `junitparser.Element` class and provides a property to access the text content of the element.
+    """
+
+    __test__ = False
+    _tag = 'test-identifier'
+
+    @property
+    def text(self) -> str | None:
+        """Retrieve the text content of the XML element.
+
+        :return: The text content of the XML element, or None if the element has no text.
+        """
+        return self._elem.text
+
+
+class TestDescriptionElement(junitparser.Element):
+    """Element containing the test description.
+
+    This class represents a custom XML element for the test description in the JUnit XML test results.
+    It extends the `junitparser.Element` class and provides a property to access the text content of the element.
+    """
+
+    __test__ = False
+    _tag = 'test-description'
+
+    @property
+    def text(self) -> str | None:
+        """Retrieve the text content of the XML element.
+
+        :return: The text content of the XML element, or None if the element has no text.
+        """
+        return self._elem.text
+
+
+class TestCase(junitparser.TestCase):
+    """Test case containing custom elements.
+
+    This class extends the `junitparser.TestCase` class to include custom elements such as test identifier and test
+    description. It provides properties to access these custom elements.
+    """
+
+    @property
+    def test_identifier(self) -> str | None:
+        """Links a test case with a unique test identifier.
+
+        :return: The unique identifier for the test case.
+        """
+        elem = self.child(TestIdentifierElement)
+        return elem.text if elem is not None else None
+
+    @property
+    def test_description(self) -> str | None:
+        """Description of the test case itself, i.e. what is tested and how.
+
+        :return: The description of the test case.
+        """
+        elem = self.child(TestDescriptionElement)
+        return elem.text if elem is not None else None
+
+
+class TestSuite(junitparser.TestSuite):
+    """Test suite containing custom test cases.
+
+    This class extends the `junitparser.TestSuite` class to include custom test cases with additional elements.
+    It provides methods to iterate over the test cases and parse a test suite from a file.
+    """
+
+    def __iter__(self) -> typing.Iterator[TestCase]:  # pyright: ignore [reportIncompatibleMethodOverride]
+        for elem in super().__iter__():
+            yield TestCase.fromelem(elem)  # type: ignore[no-untyped-call]
+
+    @classmethod
+    def from_file(cls, file: pathlib.Path | str) -> 'TestSuite':
+        """Parse a test suite from a given file.
+
+        This method reads a JUnit XML file and parses it into a `TestSuite` object containing custom elements.
+
+        :param file: The path to the test suite file to be parsed. Can be a `pathlib.Path` object or a string.
+        :return: A `TestSuite` object containing the parsed test cases with custom elements.
+        :raises ValueError: If the parsed file does not contain a `TestSuite` object.
+        :raises FileNotFoundError: If the file does not exist.
+        """
+        suite = junitparser.JUnitXml.fromfile(str(file))
+        if not isinstance(suite, junitparser.TestSuite):
+            msg = f'Expected class {junitparser.TestSuite}, got {type(suite)}'
+            raise TypeError(msg)
+        return cls.fromelem(suite)  # type: ignore[no-untyped-call,no-any-return]

pysdccc/_runner.py

@@ -0,0 +1,311 @@
+"""Implements the runner for the SDCcc executable.
+
+This module provides the `SdcccRunner` class to manage and execute the SDCcc tests. It handles the configuration,
+requirements, and execution of the SDCcc executable, as well as parsing the test results.
+
+Classes
+-------
+
+SdcccRunner
+    Runner for the SDCcc tests.
+
+Functions
+---------
+
+check_requirements(provided: dict[str, dict[str, bool]], available: dict[str, dict[str, bool]]) -> None
+    Check if the provided requirements are supported by the available requirements.
+
+Usage
+-----
+
+.. code-block:: python
+
+    from pysdccc import SdcccRunner
+    import pathlib
+
+    # Initialize the runner with the path to the SDCcc executable and the test run directory
+    runner = SdcccRunner(
+        exe=pathlib.Path("/absolute/path/to/sdccc-executable"),
+        test_run_dir=pathlib.Path("/absolute/path/to/test-run-directory")
+    )
+
+    # Load the default configuration
+    config = runner.get_config()
+
+    # Load the default requirements
+    requirements = runner.get_requirements()
+
+    # Check user-provided requirements against the SDCcc provided requirements
+    runner.check_requirements(pathlib.Path("/absolute/path/to/user-requirements.toml"))
+
+    # Run the SDCcc executable with the specified configuration and requirements
+    exit_code, direct_result, invariant_result = runner.run(
+        config=pathlib.Path("/absolute/path/to/config.toml"),
+        requirements=pathlib.Path("/absolute/path/to/requirements.toml"),
+        timeout=3600  # 1 hour timeout
+    )
+"""
+
+import pathlib
+import subprocess
+import sys
+import tomllib
+import typing
+
+import anyio
+
+from pysdccc import _common
+from pysdccc._result_parser import TestSuite
+
+DIRECT_TEST_RESULT_FILE_NAME = 'TEST-SDCcc_direct.xml'
+INVARIANT_TEST_RESULT_FILE_NAME = 'TEST-SDCcc_invariant.xml'
+
+
+def check_requirements(provided: dict[str, dict[str, bool]], available: dict[str, dict[str, bool]]) -> None:
+    """Check if the provided requirements are supported by the available requirements.
+
+    This function verifies that all the requirements specified in the `provided` dictionary are supported by the
+    requirements in the `available` dictionary. If any requirement in `provided` is not found in `available`, a KeyError
+    is raised.
+
+    :param provided: A dictionary of provided requirements to be verified. The keys are standard names, and the values
+                     are dictionaries where the keys are requirement IDs and the values are booleans indicating whether
+                     the requirement is enabled.
+    :param available: A dictionary of available requirements provided by SDCcc. The keys are standard names, and the
+                      values are dictionaries where the keys are requirement IDs and the values are booleans indicating
+                      whether the requirement is enabled.
+    :raise KeyError: If a standard or requirement provided by the user is not found in the SDCcc provided requirements.
+    """
+    for standard, requirements in provided.items():
+        if standard not in available:
+            msg = f'Unsupported standard "{standard}". Supported standards are "{list(available)}"'
+            raise KeyError(msg)
+        provided_enabled = [req for req, enabled in requirements.items() if enabled]
+        available_enabled = [a for a, enabled in available[standard].items() if enabled]
+        for req in provided_enabled:
+            if req not in available_enabled:
+                msg = f'Requirement id "{standard}.{req}" not found'
+                raise KeyError(msg)
+
+
+class _BaseRunner:
+    """Runner for the SDCcc tests.
+
+    This class provides methods to manage and execute the SDCcc tests. It handles the configuration, requirements,
+    and execution of the SDCcc executable, as well as parsing the test results.
+    """
+
+    def __init__(self, test_run_dir: _common.PATH_TYPE, exe: _common.PATH_TYPE | None = None):
+        """Initialize the SdcccRunner object.
+
+        :param exe: The path to the SDCcc executable. Must be an absolute path.
+        :param test_run_dir: The path to the directory where the test run results are to be stored. Must be an absolute
+        path.
+        :raises ValueError: If the provided paths are not absolute.
+        """
+        try:
+            self.exe = (
+                pathlib.Path(exe)
+                if exe is not None
+                else _common.get_exe_path(_common.DEFAULT_STORAGE_DIRECTORY).absolute()
+            )
+        except FileNotFoundError as e:
+            msg = 'Have you downloaded SDCcc?'
+            raise FileNotFoundError(msg) from e
+        if not self.exe.is_absolute():
+            msg = f'Path to executable must be absolute but is {self.exe}'
+            raise ValueError(msg)
+        if not self.exe.is_file():
+            msg = f'No executable found under {self.exe}'
+            raise FileNotFoundError(msg)
+        self.test_run_dir = pathlib.Path(test_run_dir)
+        if not self.test_run_dir.is_absolute():
+            msg = f'Path to test run directory must be absolute but is {self.test_run_dir}'
+            raise ValueError(msg)
+        if not self.test_run_dir.is_dir():
+            msg = f'Test run directory "{self.test_run_dir}" is not a directory or does not exist'
+            raise ValueError(msg)
+
+    def get_config(self) -> dict[str, typing.Any]:
+        """Get the default configuration.
+
+        This method loads the default configuration from the SDCcc executable's directory.
+
+        :return: A dictionary containing the configuration data.
+        """
+        return tomllib.loads(self.exe.parent.joinpath('configuration').joinpath('config.toml').read_text())
+
+    def get_requirements(self) -> dict[str, dict[str, bool]]:
+        """Get the default requirements.
+
+        This method loads the default requirements from the SDCcc executable's directory.
+
+        :return: A dictionary containing the requirements data.
+        """
+        return tomllib.loads(self.exe.parent.joinpath('configuration').joinpath('test_configuration.toml').read_text())
+
+    def get_test_parameter(self) -> dict[str, typing.Any]:
+        """Get the default test parameter.
+
+        This method loads the default test parameters from the SDCcc executable's directory.
+
+        :return: A dictionary containing the test parameter data.
+        """
+        return tomllib.loads(self.exe.parent.joinpath('configuration').joinpath('test_parameter.toml').read_text())
+
+    def check_requirements(self, path: pathlib.Path) -> None:
+        """Check the requirements from the given file against the requirements provided by the SDCcc version.
+
+        This method verifies that all the requirements specified in the user's requirements file are supported by the
+        requirements provided by the SDCcc version. If any requirement is not found, a KeyError is raised.
+
+        :param path: The path to the user's requirements file.
+        :raises KeyError: If a standard or requirement provided by the user is not found in the SDCcc provided
+        requirements.
+        """
+        sdccc_provided_requirements = self.get_requirements()
+        user_provided_requirements = tomllib.loads(path.read_text())
+        check_requirements(user_provided_requirements, sdccc_provided_requirements)
+
+    def _get_result(self, file_name: str) -> TestSuite | None:
+        """Get the parsed results of the test run.
+
+        This method reads the direct and invariant test result files from the test run directory and returns them
+        as TestSuite objects.
+
+        :return: A tuple containing the parsed direct and invariant test results as TestSuite objects.
+        """
+        test_result_dir = self.test_run_dir.joinpath(file_name)
+        if not test_result_dir.exists():
+            return None
+        return TestSuite.from_file(test_result_dir)
+
+    def _prepare_command(
+        self,
+        *args: str,
+        config: pathlib.Path,
+        requirements: pathlib.Path,
+        **kwargs: _common.CMD_TYPE,
+    ) -> list[str]:
+        if not config.is_absolute():
+            msg = 'Path to config file must be absolute'
+            raise ValueError(msg)
+        if not requirements.is_absolute():
+            msg = 'Path to requirements file must be absolute'
+            raise ValueError(msg)
+        if list(self.test_run_dir.iterdir()):
+            msg = f'{self.test_run_dir} is not empty'
+            raise ValueError(msg)
+
+        kwargs['no_subdirectories'] = 'true'
+        kwargs['test_run_directory'] = self.test_run_dir
+        kwargs['config'] = config
+        kwargs['testconfig'] = requirements
+        return _common.build_command(*args, **kwargs)
+
+
+class SdcccRunner(_BaseRunner):
+    """Synchronous runner for SDCcc."""
+
+    def run(
+        self,
+        *,
+        config: _common.PATH_TYPE,
+        requirements: _common.PATH_TYPE,
+        timeout: float | None = None,
+        **kwargs: _common.CMD_TYPE,
+    ) -> tuple[int, TestSuite | None, TestSuite | None]:
+        """Run the SDCcc executable using the specified configuration and requirements.
+
+        This method executes the SDCcc executable with the provided configuration and requirements files,
+        and additional command line arguments. It logs the stdout and stderr of the process and waits for the
+        process to complete or timeout.
+        Checkout more parameter under https://github.com/draegerwerk/sdccc?tab=readme-ov-file#running-sdccc
+
+        :param config: The path to the configuration file. Must be an absolute path.
+        :param requirements: The path to the requirements file. Must be an absolute path.
+        :param timeout: The timeout in seconds for the SDCcc process. If None, wait indefinitely.
+        :param kwargs: Additional command line arguments to be passed to the SDCcc executable.
+        :return: A tuple containing the returncode of the SDCcc process, parsed direct and invariant test results as
+        TestSuite objects.
+        :raises ValueError: If the provided paths are not absolute.
+        :raises subprocess.TimeoutExpired: If the process is running longer than the timeout.
+        """
+        command = self._prepare_command(
+            str(self.exe),
+            config=pathlib.Path(config),
+            requirements=pathlib.Path(requirements),
+            **kwargs,
+        )
+        try:
+            return_code = subprocess.run(command, timeout=timeout, check=True, cwd=self.exe.parent).returncode  # noqa: S603
+        except subprocess.CalledProcessError as e:
+            return_code = e.returncode
+        return (
+            return_code,
+            self._get_result(DIRECT_TEST_RESULT_FILE_NAME),
+            self._get_result(INVARIANT_TEST_RESULT_FILE_NAME),
+        )
+
+    def get_version(self) -> str:
+        """Get the version of the SDCcc executable."""
+        # use capture_output = True to get stdout and stderr instead of check_output which only collects stdout
+        process = subprocess.run([str(self.exe), '--version'], check=True, capture_output=True, cwd=self.exe.parent)  # noqa: S603
+        return process.stdout.decode(_common.ENCODING).strip()
+
+
+class SdcccRunnerAsync(_BaseRunner):
+    """Asynchronous runner for SDCcc."""
+
+    def __init__(self, test_run_dir: _common.PATH_TYPE, exe: _common.PATH_TYPE | None = None):
+        """Initialize the SdcccRunnerAsync object.
+
+        :param exe: The path to the SDCcc executable. Must be an absolute path.
+        :param test_run_dir: The path to the directory where the test run results are to be stored. Must be an absolute
+        path.
+        :raises ValueError: If the provided paths are not absolute.
+        """
+        super().__init__(test_run_dir=test_run_dir, exe=exe)
+
+    async def run(
+        self,
+        *,
+        config: _common.PATH_TYPE,
+        requirements: _common.PATH_TYPE,
+        **kwargs: _common.CMD_TYPE,
+    ) -> tuple[int, TestSuite | None, TestSuite | None]:
+        """Run the SDCcc executable using the specified configuration and requirements.
+
+        This method executes the SDCcc executable with the provided configuration and requirements files,
+        and additional command line arguments. It logs the stdout and stderr of the process and waits for the
+        process to complete or timeout.
+        Checkout more parameter under https://github.com/draegerwerk/sdccc?tab=readme-ov-file#running-sdccc
+
+        :param config: The path to the configuration file. Must be an absolute path.
+        :param requirements: The path to the requirements file. Must be an absolute path.
+        :param kwargs: Additional command line arguments to be passed to the SDCcc executable.
+        :return: A tuple containing the returncode of the SDCcc process, parsed direct and invariant test results as
+        TestSuite objects.
+        :raises ValueError: If the provided paths are not absolute.
+        :raises TimeoutError: If the process is running longer than the timeout.
+        """
+        command = self._prepare_command(
+            str(self.exe), config=pathlib.Path(config), requirements=pathlib.Path(requirements), **kwargs
+        )
+        try:
+            return_code = (
+                await anyio.run_process(command, check=True, cwd=self.exe.parent, stdout=sys.stdout, stderr=sys.stderr)
+            ).returncode
+        except subprocess.CalledProcessError as e:
+            return_code = e.returncode
+
+        return (
+            return_code,
+            self._get_result(DIRECT_TEST_RESULT_FILE_NAME),
+            self._get_result(INVARIANT_TEST_RESULT_FILE_NAME),
+        )
+
+    async def get_version(self) -> str | None:
+        """Get the version of the SDCcc executable."""
+        result = await anyio.run_process([self.exe, '--version'], check=True, cwd=self.exe.parent)
+        return result.stdout.decode(_common.ENCODING).strip() if result.stdout is not None else None

pysdccc-0.1.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: pysdccc
+Version: 0.1.0
+Summary: Python wrapper for SDCcc test tool
+Project-URL: Homepage, https://github.com/Draegerwerk/pysdccc
+Project-URL: Bug Tracker, https://github.com/Draegerwerk/pysdccc/issues
+Project-URL: Changelog, https://github.com/Draegerwerk/pysdccc/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/Draegerwerk/pysdccc.git
+Author-email: Leon Budnick <leon.budnick@draeger.com>
+License: MIT License
+        
+        Copyright (c) 2024 Dräger
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: SDCcc,sdc,test,wrapper
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.14,>=3.11
+Requires-Dist: anyio>=4.7.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: junitparser>=3.1.2
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# pysdccc
+
+This python packages provides a convenient way to execute the [SDCcc test suite](https://github.com/Draegerwerk/sdccc/).
+
+This wrapper is only compatible with SDCcc versions later than [internal-baseline-001](https://github.com/Draegerwerk/SDCcc/releases/tag/internal-baseline-001).
+
+## Installation
+
+Download from pypi using `pip install pysdccc`. There is also an option to use this via the command line by installing `pysdccc[cli]`.
+
+### Development
+
+For this open source project the [Contributor License Agreement](Contributor_License_Agreement.md) governs all relevant activities and your contributions. By contributing to the project you agree to be bound by this Agreement and to licence your work accordingly.
+
+1. clone the repository
+2. install dependencies, e.g. with [`uv sync --dev --all-extras`](https://docs.astral.sh/uv/reference/cli/#uv-sync)
+
+## Usage
+
+### Quick start
+
+```python
+import pathlib
+import subprocess
+
+import pysdccc
+
+
+def main():
+    if not pysdccc.is_downloaded("my-specific-version"):
+        pysdccc.download("https://url/to/sdccc.zip")
+
+    runner = pysdccc.SdcccRunner(
+        pathlib.Path("/path/to/sdccc/result/directory"),
+    )
+
+    try:
+        # https://github.com/Draegerwerk/SDCcc/?tab=readme-ov-file#exit-codes
+        return_code, direct_result, invariant_result = runner.run(
+            config=pathlib.Path("/path/to/configuration/file.toml"),
+            requirements=pathlib.Path("/path/to/requirements/file.toml"),
+        )
+    except subprocess.TimeoutExpired:
+        print("Timeout occurred")
+        return
+
+    if direct_result is None or invariant_result is None:
+        print("No result file available")
+        return
+
+    for test_case in direct_result + invariant_result:
+        print(f"{test_case.name}: {test_case.is_passed}")
+```
+If you look for an async version
+
+```python
+import pathlib
+
+import pysdccc
+
+
+async def main():
+    if not await pysdccc.ais_downloaded("my-specific-version"):
+        await pysdccc.adownload("https://url/to/sdccc.zip")
+
+    runner = pysdccc.SdcccRunnerAsync(
+        pathlib.Path("/path/to/sdccc/result/directory"),
+    )
+
+    # https://github.com/Draegerwerk/SDCcc/?tab=readme-ov-file#exit-codes
+    return_code, direct_result, invariant_result = await runner.run(
+        config=pathlib.Path("/path/to/configuration/file.toml"),
+        requirements=pathlib.Path("/path/to/requirements/file.toml"),
+    )
+
+    # checkout example from above ...
+```
+
+### Download an SDCcc executable
+
+Check out `pysdccc.download` or `pysdccc.adownload`. If the command line interface of `pysdccc` is installed, the zipped source of SDCcc can be installed using this command: `pysdccc install https://url/to/sdccc.zip`
+
+### Create configuration file
+
+Configure the test consumer. Check the [test consumer configuration](https://github.com/Draegerwerk/SDCcc/?tab=readme-ov-file#test-consumer-configuration) for more information.
+
+```python
+import pathlib
+
+import toml  # has to be installed by the user
+
+import pysdccc
+
+config = {
+    'SDCcc': {
+        ...  # add all relevant config parameter
+    }
+}
+config_path = pathlib.Path('/path/to/configuration/file.toml')
+config_path.write_text(toml.dumps(config))
+
+runner = pysdccc.SdcccRunner(
+    pathlib.Path('/path/to/sdccc/result/directory'),
+)
+
+runner.run(
+    config=config_path,
+    requirements=pathlib.Path('/path/to/requirements/file.toml'),
+)
+
+# or if you have already downloaded SDCcc
+config = runner.get_config()  # load default configuration
+config['SDCcc']['Consumer']['DeviceEpr'] = "urn:uuid:12345678-1234-1234-1234-123456789012"  # e.g. change device epr
+# save and run as above
+```
+
+### Create requirements file
+
+Enable or disable specific requirements. Check the [test requirements](https://github.com/Draegerwerk/SDCcc/?tab=readme-ov-file#enabling-tests) for more information.
+
+```python
+import pathlib
+
+import toml  # has to be installed by the user
+
+import pysdccc
+
+requirements = {
+    # the standard name is the key, the requirement from the standard is the value
+    'BICEPS': {
+        ...  # add all requirements to be tested
+    }
+}
+requirements_path = pathlib.Path('/path/to/requirement/file.toml')
+requirements_path.write_text(toml.dumps(requirements))
+
+runner = pysdccc.SdcccRunner(
+    pathlib.Path('/path/to/sdccc/result/directory'),
+)
+# optionally, check whether you did not add a requirement that is not available
+runner.check_requirements(requirements_path)
+runner.run(
+    config=pathlib.Path('/path/to/configuration/file.toml'),
+    requirements=requirements_path,
+)
+
+# or, if you have already downloaded SDCcc
+requirements = runner.get_requirements()  # load default configuration
+requirements['BICEPS']['R0033'] = False  # e.g. disable biceps R0033
+# save and run as above
+```
+
+### Create test parameter configuration
+
+Some tests require individual parameters. Check the [test parameter configuration](https://github.com/Draegerwerk/SDCcc/?tab=readme-ov-file#test-parameter-configuration) for more information.
+
+```python
+import pathlib
+
+import toml  # has to be installed by the user
+
+import pysdccc
+
+testparameter_config = {
+    'TestParameter': {
+        ...
+    }
+}
+testparameter_config_path = pathlib.Path('/path/to/test_parameter/file.toml')
+testparameter_config_path.write_text(toml.dumps(testparameter_config))
+
+runner = pysdccc.SdcccRunner(
+    pathlib.Path('/path/to/sdccc/result/directory'),
+)
+runner.run(
+    config=pathlib.Path('/path/to/configuration/file.toml'),
+    requirements=pathlib.Path('/path/to/requirements/file.toml'),
+    testparam=testparameter_config_path,
+)
+
+# or, if you have already downloaded SDCcc
+testparameter_config = runner.get_test_parameter()  # load default configuration
+testparameter_config['TestParameter']['Biceps547TimeInterval'] = 10
+# save and run as above
+```
+
+### Execute SDCcc from command-line interface (cli)
+
+There exists a cli wrapper for the SDCcc executable. If `pysdccc[cli]` is installed, `sdccc` can be used to execute arbitrary SDCcc commands, e.g. `sdccc --version`. More information can be found [here](https://github.com/draegerwerk/sdccc?tab=readme-ov-file#running-sdccc).
+
+## Notices
+
+`pysdccc` is not intended for use in medical products, clinical trials, clinical studies, or in clinical routine.
+
+### ISO 9001
+
+`pysdccc` was not developed according to ISO 9001.
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)

pysdccc-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pysdccc/__init__.py,sha256=qnHztGXtWUV3taE_vaNcCOuktWyFpJNWnJh3tJmYLTs,599
+pysdccc/_cli.py,sha256=pbzr3hhc2stlSrNWybLoE6XxTEZgSN1XyeHyUF2Hq7o,4803
+pysdccc/_common.py,sha256=ujgKH6_oA1h2KZXPyShfa3o-nho_I2snmkvfcs7rLm8,2246
+pysdccc/_download.py,sha256=1PVyGcEC63mmZXdUlfg4HaPb-gz-47iB4IAdnne_GAg,4320
+pysdccc/_result_parser.py,sha256=QsRbpV4obBFrirwMHXWLm6zdoxxV_rsdhqzm5YJ13Uk,4603
+pysdccc/_runner.py,sha256=AaWtU7vj_cgfRgrGpn6SQhrvhyFDQhmPQHKaAbMF1b0,13830
+pysdccc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pysdccc-0.1.0.dist-info/METADATA,sha256=yLzQyyXJFzi8pcC3jBR2zb1__r9AuyC5zVL_JAlKKSo,8519
+pysdccc-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pysdccc-0.1.0.dist-info/entry_points.txt,sha256=1Y-7xLrgZ-44p0AnJikH9buOqLGo-1mDfORut7ZXCkU,72
+pysdccc-0.1.0.dist-info/licenses/LICENSE,sha256=W8bC5k53mY5GatF3EpFnE4bK6m-htGV_IsiveTOwKMc,1064
+pysdccc-0.1.0.dist-info/RECORD,,

pysdccc-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pysdccc-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pysdccc = pysdccc._cli:cli
+sdccc = pysdccc._cli:sdccc

pysdccc-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dräger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.