ANTA Result API

ResultManager

ResultManager()

Manager of ANTA Results.

The status of the class is initialized to “unset”

Then when adding a test with a status that is NOT ‘error’ the following table shows the updated status:

Current Status	Added test Status	Updated Status
unset	Any	Any
skipped	unset, skipped	skipped
skipped	success	success
skipped	failure	failure
success	unset, skipped, success	success
success	failure	failure
failure	unset, skipped success, failure	failure

If the status of the added test is error, the status is untouched and the error_status attribute is set to True.

Attributes:

Name	Type	Description
results	list[TestResult]
dump	list[dict[str, Any]]
status	AntaTestStatus	Status rerpesenting all the results.
error_status	bool	Will be True if a test returned an error.
results_by_status	dict[AntaTestStatus, list[TestResult]]
dump	list[dict[str, Any]]
json	str
device_stats	dict[str, DeviceStats]
category_stats	dict[str, CategoryStats]
test_stats	dict[str, TestStats]

category_stats property

category_stats: dict[str, CategoryStats]

Get the category statistics.

device_stats property

device_stats: dict[str, DeviceStats]

Get the device statistics.

dump property

dump: list[dict[str, Any]]

Get a list of dictionary of the results.

json property

json: str

Get a JSON representation of the results.

results property writable

results: list[TestResult]

Get the list of TestResult.

results_by_status cached property

results_by_status: dict[AntaTestStatus, list[TestResult]]

A cached property that returns the results grouped by status.

sorted_category_stats property

sorted_category_stats: dict[str, CategoryStats]

A property that returns the category_stats dictionary sorted by key name.

test_stats property

test_stats: dict[str, TestStats]

Get the test statistics.

add

add(result: TestResult) -> None

Add a result to the ResultManager instance.

The result is added to the internal list of results and the overall status of the ResultManager instance is updated based on the added test status.

Parameters:

Name	Type	Description	Default
result	TestResult	TestResult to add to the ResultManager instance.	required

Source code in anta/result_manager/__init__.py

def add(self, result: TestResult) -> None:
    """Add a result to the ResultManager instance.

    The result is added to the internal list of results and the overall status
    of the ResultManager instance is updated based on the added test status.

    Parameters
    ----------
    result
        TestResult to add to the ResultManager instance.
    """
    self._result_entries.append(result)
    self._update_status(result.result)
    self._stats_in_sync = False

    # Every time a new result is added, we need to clear the cached property
    self.__dict__.pop("results_by_status", None)

filter

filter(hide: set[AntaTestStatus]) -> ResultManager

Get a filtered ResultManager based on test status.

Parameters:

Name	Type	Description	Default
hide	set[AntaTestStatus]	Set of AntaTestStatus enum members to select tests to hide based on their status.	required

Returns:

Type	Description
ResultManager	A filtered ResultManager.

Source code in anta/result_manager/__init__.py

def filter(self, hide: set[AntaTestStatus]) -> ResultManager:
    """Get a filtered ResultManager based on test status.

    Parameters
    ----------
    hide
        Set of AntaTestStatus enum members to select tests to hide based on their status.

    Returns
    -------
    ResultManager
        A filtered `ResultManager`.
    """
    possible_statuses = set(AntaTestStatus)
    manager = ResultManager()
    manager.results = self.get_results(possible_statuses - hide)
    return manager

filter_by_devices deprecated

filter_by_devices(devices: set[str]) -> ResultManager

Deprecated

This method is deprecated. This will be removed in ANTA v2.0.0.

Get a filtered ResultManager that only contains specific devices.

Parameters:

Name	Type	Description	Default
devices	set[str]	Set of device names to filter the results.	required

Returns:

Type	Description
ResultManager	A filtered ResultManager.

Source code in anta/result_manager/__init__.py

@deprecated("This method is deprecated. This will be removed in ANTA v2.0.0.", category=DeprecationWarning)
def filter_by_devices(self, devices: set[str]) -> ResultManager:
    """Get a filtered ResultManager that only contains specific devices.

    Parameters
    ----------
    devices
        Set of device names to filter the results.

    Returns
    -------
    ResultManager
        A filtered `ResultManager`.
    """
    manager = ResultManager()
    manager.results = [result for result in self._result_entries if result.name in devices]
    return manager

filter_by_tests deprecated

filter_by_tests(tests: set[str]) -> ResultManager

Deprecated

This method is deprecated. This will be removed in ANTA v2.0.0.

Get a filtered ResultManager that only contains specific tests.

Parameters:

Name	Type	Description	Default
tests	set[str]	Set of test names to filter the results.	required

Returns:

Type	Description
ResultManager	A filtered ResultManager.

Source code in anta/result_manager/__init__.py

@deprecated("This method is deprecated. This will be removed in ANTA v2.0.0.", category=DeprecationWarning)
def filter_by_tests(self, tests: set[str]) -> ResultManager:
    """Get a filtered ResultManager that only contains specific tests.

    Parameters
    ----------
    tests
        Set of test names to filter the results.

    Returns
    -------
    ResultManager
        A filtered `ResultManager`.
    """
    manager = ResultManager()
    manager.results = [result for result in self._result_entries if result.test in tests]
    return manager

get_devices deprecated

get_devices() -> set[str]

Deprecated

This method is deprecated. This will be removed in ANTA v2.0.0.

Get the set of all the device names.

Returns:

Type	Description
set[str]	Set of device names.

Source code in anta/result_manager/__init__.py

@deprecated("This method is deprecated. This will be removed in ANTA v2.0.0.", category=DeprecationWarning)
def get_devices(self) -> set[str]:
    """Get the set of all the device names.

    Returns
    -------
    set[str]
        Set of device names.
    """
    return {str(result.name) for result in self._result_entries}

get_results

get_results(
    status: set[AntaTestStatus] | None = None,
    sort_by: list[str] | None = None,
) -> list[TestResult]

Get the results, optionally filtered by status and sorted by TestResult fields.

If no status is provided, all results are returned.

Parameters:

Name	Type	Description	Default
status	set[AntaTestStatus] | None	Optional set of AntaTestStatus enum members to filter the results.	None
sort_by	list[str] | None	Optional list of TestResult fields to sort the results.	None

Returns:

Type	Description
list[TestResult]	List of results.

Source code in anta/result_manager/__init__.py

def get_results(self, status: set[AntaTestStatus] | None = None, sort_by: list[str] | None = None) -> list[TestResult]:
    """Get the results, optionally filtered by status and sorted by TestResult fields.

    If no status is provided, all results are returned.

    Parameters
    ----------
    status
        Optional set of AntaTestStatus enum members to filter the results.
    sort_by
        Optional list of TestResult fields to sort the results.

    Returns
    -------
    list[TestResult]
        List of results.
    """
    # Return all results if no status is provided, otherwise return results for multiple statuses
    results = self._result_entries if status is None else list(chain.from_iterable(self.results_by_status.get(status, []) for status in status))

    if sort_by:
        accepted_fields = TestResult.model_fields.keys()
        if not set(sort_by).issubset(set(accepted_fields)):
            msg = f"Invalid sort_by fields: {sort_by}. Accepted fields are: {list(accepted_fields)}"
            raise ValueError(msg)
        results = sorted(results, key=lambda result: [getattr(result, field) for field in sort_by])

    return results

get_status

get_status(*, ignore_error: bool = False) -> str

Return the current status including error_status if ignore_error is False.

Source code in anta/result_manager/__init__.py

def get_status(self, *, ignore_error: bool = False) -> str:
    """Return the current status including error_status if ignore_error is False."""
    return "error" if self.error_status and not ignore_error else self.status

get_tests deprecated

get_tests() -> set[str]

Deprecated

This method is deprecated. This will be removed in ANTA v2.0.0.

Get the set of all the test names.

Returns:

Type	Description
set[str]	Set of test names.

Source code in anta/result_manager/__init__.py

@deprecated("This method is deprecated. This will be removed in ANTA v2.0.0.", category=DeprecationWarning)
def get_tests(self) -> set[str]:
    """Get the set of all the test names.

    Returns
    -------
    set[str]
        Set of test names.
    """
    return {str(result.test) for result in self._result_entries}

get_total_results

get_total_results(
    status: set[AntaTestStatus] | None = None,
) -> int

Get the total number of results, optionally filtered by status.

If no status is provided, the total number of results is returned.

Parameters:

Name	Type	Description	Default
status	set[AntaTestStatus] | None	Optional set of AntaTestStatus enum members to filter the results.	None

Returns:

Type	Description
int	Total number of results.

Source code in anta/result_manager/__init__.py

def get_total_results(self, status: set[AntaTestStatus] | None = None) -> int:
    """Get the total number of results, optionally filtered by status.

    If no status is provided, the total number of results is returned.

    Parameters
    ----------
    status
        Optional set of AntaTestStatus enum members to filter the results.

    Returns
    -------
    int
        Total number of results.
    """
    if status is None:
        # Return the total number of results
        return sum(len(results) for results in self.results_by_status.values())

    # Return the total number of results for multiple statuses
    return sum(len(self.results_by_status.get(status, [])) for status in status)

reset

reset() -> None

Create or reset the attributes of the ResultManager instance.

Source code in anta/result_manager/__init__.py

def reset(self) -> None:
    """Create or reset the attributes of the ResultManager instance."""
    self._result_entries: list[TestResult] = []
    self.status: AntaTestStatus = AntaTestStatus.UNSET
    self.error_status = False

    # Initialize the statistics attributes
    self._reset_stats()

sort

sort(sort_by: list[str]) -> ResultManager

Sort the ResultManager results based on TestResult fields.

Parameters:

Name	Type	Description	Default
sort_by	list[str]	List of TestResult fields to sort the results.	required

Source code in anta/result_manager/__init__.py

def sort(self, sort_by: list[str]) -> ResultManager:
    """Sort the ResultManager results based on TestResult fields.

    Parameters
    ----------
    sort_by
        List of TestResult fields to sort the results.
    """
    accepted_fields = TestResult.model_fields.keys()
    if not set(sort_by).issubset(set(accepted_fields)):
        msg = f"Invalid sort_by fields: {sort_by}. Accepted fields are: {list(accepted_fields)}"
        raise ValueError(msg)
    self._result_entries.sort(key=lambda result: [getattr(result, field) for field in sort_by])
    return self

TestResult

Bases: BaseModel

Describe the result of a test from a single device.

Attributes:

Name	Type	Description
name	str	Name of the device where the test was run.
test	str	Name of the test run on the device.
categories	list[str]	List of categories the TestResult belongs to. Defaults to the AntaTest categories.
description	str	Description of the TestResult. Defaults to the AntaTest description.
result	AntaTestStatus	Result of the test. Must be one of the AntaTestStatus Enum values: unset, success, failure, error or skipped.
messages	list[str]	Messages to report after the test, if any.
custom_field	str | None	Custom field to store a string for flexibility in integrating with ANTA.

is_error

is_error(message: str | None = None) -> None

Set status to error.

Parameters:

Name	Type	Description	Default
message	str | None	Optional message related to the test.	None

Source code in anta/result_manager/models.py

def is_error(self, message: str | None = None) -> None:
    """Set status to error.

    Parameters
    ----------
    message
        Optional message related to the test.

    """
    self._set_status(AntaTestStatus.ERROR, message)

is_failure

is_failure(message: str | None = None) -> None

Set status to failure.

Parameters:

Name	Type	Description	Default
message	str | None	Optional message related to the test.	None

Source code in anta/result_manager/models.py

def is_failure(self, message: str | None = None) -> None:
    """Set status to failure.

    Parameters
    ----------
    message
        Optional message related to the test.

    """
    self._set_status(AntaTestStatus.FAILURE, message)

is_skipped

is_skipped(message: str | None = None) -> None

Set status to skipped.

Parameters:

Name	Type	Description	Default
message	str | None	Optional message related to the test.	None

Source code in anta/result_manager/models.py

def is_skipped(self, message: str | None = None) -> None:
    """Set status to skipped.

    Parameters
    ----------
    message
        Optional message related to the test.

    """
    self._set_status(AntaTestStatus.SKIPPED, message)

is_success

is_success(message: str | None = None) -> None

Set status to success.

Parameters:

Name	Type	Description	Default
message	str | None	Optional message related to the test.	None

Source code in anta/result_manager/models.py

def is_success(self, message: str | None = None) -> None:
    """Set status to success.

    Parameters
    ----------
    message
        Optional message related to the test.

    """
    self._set_status(AntaTestStatus.SUCCESS, message)