From c5033b6d226665d9767ea2104785bddab211b7e1 Mon Sep 17 00:00:00 2001 From: gmuloc Date: Tue, 10 Sep 2024 11:44:31 +0200 Subject: [PATCH] Doc: Fix documentation --- anta/catalog.py | 20 +++---- anta/device.py | 60 +++++++++---------- anta/inventory/__init__.py | 56 ++++++++--------- anta/models.py | 22 +++---- anta/reporter/__init__.py | 44 +++++++------- anta/result_manager/__init__.py | 12 ++-- anta/result_manager/models.py | 26 ++++---- anta/runner.py | 40 ++++++------- anta/tests/logging.py | 6 +- anta/tests/routing/bgp.py | 30 +++++----- anta/tests/routing/ospf.py | 12 ++-- docs/advanced_usages/as-python-lib.md | 8 +-- docs/advanced_usages/caching.md | 2 +- docs/api/device.md | 14 ++--- docs/api/models.md | 7 +-- docs/api/result_manager.md | 2 - docs/api/result_manager_models.md | 2 - docs/cli/debug.md | 2 +- docs/cli/nrfu.md | 2 +- docs/getting-started.md | 2 +- .../{anta_test.html => anta_test.html.jinja} | 10 ++-- .../material/{class.html => class.html.jinja} | 4 +- .../{docstring.html => docstring.html.jinja} | 0 mkdocs.yml | 4 +- pyproject.toml | 18 +++--- 25 files changed, 197 insertions(+), 208 deletions(-) rename docs/templates/python/material/{anta_test.html => anta_test.html.jinja} (96%) rename docs/templates/python/material/{class.html => class.html.jinja} (91%) rename docs/templates/python/material/{docstring.html => docstring.html.jinja} (100%) diff --git a/anta/catalog.py b/anta/catalog.py index 30bd34066..34f67f701 100644 --- a/anta/catalog.py +++ b/anta/catalog.py @@ -265,8 +265,8 @@ def __init__( Parameters ---------- - tests: A list of AntaTestDefinition instances. - filename: The path from which the catalog is loaded. + tests: A list of AntaTestDefinition instances. + filename: The path from which the catalog is loaded. """ self._tests: list[AntaTestDefinition] = [] @@ -312,8 +312,8 @@ def parse(filename: str | Path, file_format: Literal["yaml", "json"] = "yaml") - Parameters ---------- - filename: Path to test catalog YAML or JSON fil - file_format: Format of the file, either 'yaml' or 'json' + filename: Path to test catalog YAML or JSON fil + file_format: Format of the file, either 'yaml' or 'json' """ if file_format not in ["yaml", "json"]: @@ -341,8 +341,8 @@ def from_dict(data: RawCatalogInput, filename: str | Path | None = None) -> Anta Parameters ---------- - data: Python dictionary used to instantiate the AntaCatalog instance - filename: value to be set as AntaCatalog instance attribute + data: Python dictionary used to instantiate the AntaCatalog instance + filename: value to be set as AntaCatalog instance attribute """ tests: list[AntaTestDefinition] = [] @@ -375,7 +375,7 @@ def from_list(data: ListAntaTestTuples) -> AntaCatalog: Parameters ---------- - data: Python list used to instantiate the AntaCatalog instance + data: Python list used to instantiate the AntaCatalog instance """ tests: list[AntaTestDefinition] = [] @@ -391,7 +391,7 @@ def merge(self, catalog: AntaCatalog) -> AntaCatalog: Parameters ---------- - catalog: AntaCatalog instance to merge to this instance. + catalog: AntaCatalog instance to merge to this instance. Returns ------- @@ -443,8 +443,8 @@ def get_tests_by_tags(self, tags: set[str], *, strict: bool = False) -> set[Anta Parameters ---------- - tags: The tags to filter tests by. If empty, return all tests without tags. - strict: If True, returns only tests that contain all specified tags (intersection). + tags: The tags to filter tests by. If empty, return all tests without tags. + strict: If True, returns only tests that contain all specified tags (intersection). If False, returns tests that contain any of the specified tags (union). Returns diff --git a/anta/device.py b/anta/device.py index 087f3b57b..5a30de9f2 100644 --- a/anta/device.py +++ b/anta/device.py @@ -57,9 +57,9 @@ def __init__(self, name: str, tags: set[str] | None = None, *, disable_cache: bo Parameters ---------- - name: Device name. - tags: Tags for this device. - disable_cache: Disable caching for all commands for this device. + name: Device name. + tags: Tags for this device. + disable_cache: Disable caching for all commands for this device. """ self.name: str = name @@ -132,8 +132,8 @@ async def _collect(self, command: AntaCommand, *, collection_id: str | None = No Parameters ---------- - command: The command to collect. - collection_id: An identifier used to build the eAPI request ID. + command: The command to collect. + collection_id: An identifier used to build the eAPI request ID. """ async def collect(self, command: AntaCommand, *, collection_id: str | None = None) -> None: @@ -149,8 +149,8 @@ async def collect(self, command: AntaCommand, *, collection_id: str | None = Non Parameters ---------- - command: The command to collect. - collection_id: An identifier used to build the eAPI request ID. + command: The command to collect. + collection_id: An identifier used to build the eAPI request ID. """ # Need to ignore pylint no-member as Cache is a proxy class and pylint is not smart enough # https://github.com/pylint-dev/pylint/issues/7258 @@ -172,8 +172,8 @@ async def collect_commands(self, commands: list[AntaCommand], *, collection_id: Parameters ---------- - commands: The commands to collect. - collection_id: An identifier used to build the eAPI request ID. + commands: The commands to collect. + collection_id: An identifier used to build the eAPI request ID. """ await asyncio.gather(*(self.collect(command=command, collection_id=collection_id) for command in commands)) @@ -194,9 +194,9 @@ async def copy(self, sources: list[Path], destination: Path, direction: Literal[ Parameters ---------- - sources: List of files to copy to or from the device. - destination: Local or remote destination when copying the files. Can be a folder. - direction: Defines if this coroutine copies files to or from the device. + sources: List of files to copy to or from the device. + destination: Local or remote destination when copying the files. Can be a folder. + direction: Defines if this coroutine copies files to or from the device. """ _ = (sources, destination, direction) @@ -239,19 +239,19 @@ def __init__( Parameters ---------- - host: Device FQDN or IP. - username: Username to connect to eAPI and SSH. - password: Password to connect to eAPI and SSH. - name: Device name. - enable: Collect commands using privileged mode. - enable_password: Password used to gain privileged access on EOS. - port: eAPI port. Defaults to 80 is proto is 'http' or 443 if proto is 'https'. - ssh_port: SSH port. - tags: Tags for this device. - timeout: Timeout value in seconds for outgoing API calls. - insecure: Disable SSH Host Key validation. - proto: eAPI protocol. Value can be 'http' or 'https'. - disable_cache: Disable caching for all commands for this device. + host: Device FQDN or IP. + username: Username to connect to eAPI and SSH. + password: Password to connect to eAPI and SSH. + name: Device name. + enable: Collect commands using privileged mode. + enable_password: Password used to gain privileged access on EOS. + port: eAPI port. Defaults to 80 is proto is 'http' or 443 if proto is 'https'. + ssh_port: SSH port. + tags: Tags for this device. + timeout: Timeout value in seconds for outgoing API calls. + insecure: Disable SSH Host Key validation. + proto: eAPI protocol. Value can be 'http' or 'https'. + disable_cache: Disable caching for all commands for this device. """ if host is None: @@ -315,8 +315,8 @@ async def _collect(self, command: AntaCommand, *, collection_id: str | None = No Parameters ---------- - command: The command to collect. - collection_id: An identifier used to build the eAPI request ID. + command: The command to collect. + collection_id: An identifier used to build the eAPI request ID. """ commands: list[dict[str, str | int]] = [] if self.enable and self._enable_password is not None: @@ -407,9 +407,9 @@ async def copy(self, sources: list[Path], destination: Path, direction: Literal[ Parameters ---------- - sources: List of files to copy to or from the device. - destination: Local or remote destination when copying the files. Can be a folder. - direction: Defines if this coroutine copies files to or from the device. + sources: List of files to copy to or from the device. + destination: Local or remote destination when copying the files. Can be a folder. + direction: Defines if this coroutine copies files to or from the device. """ async with asyncssh.connect( diff --git a/anta/inventory/__init__.py b/anta/inventory/__init__.py index 46609676a..4aa4f6655 100644 --- a/anta/inventory/__init__.py +++ b/anta/inventory/__init__.py @@ -46,8 +46,8 @@ def _update_disable_cache(kwargs: dict[str, Any], *, inventory_disable_cache: bo Parameters ---------- - inventory_disable_cache: The value of disable_cache in the inventory - kwargs: The kwargs to instantiate the device + inventory_disable_cache: The value of disable_cache in the inventory + kwargs: The kwargs to instantiate the device """ updated_kwargs = kwargs.copy() @@ -64,9 +64,9 @@ def _parse_hosts( Parameters ---------- - inventory_input: AntaInventoryInput used to parse the devices - inventory: AntaInventory to add the parsed devices to - **kwargs: Additional keyword arguments to pass to the device constructor + inventory_input: AntaInventoryInput used to parse the devices + inventory: AntaInventory to add the parsed devices to + **kwargs: Additional keyword arguments to pass to the device constructor """ if inventory_input.hosts is None: @@ -93,13 +93,13 @@ def _parse_networks( Parameters ---------- - inventory_input: AntaInventoryInput used to parse the devices - inventory: AntaInventory to add the parsed devices to - **kwargs: Additional keyword arguments to pass to the device constructor + inventory_input: AntaInventoryInput used to parse the devices + inventory: AntaInventory to add the parsed devices to + **kwargs: Additional keyword arguments to pass to the device constructor Raises ------ - InventoryIncorrectSchemaError: Inventory file is not following AntaInventory Schema. + InventoryIncorrectSchemaError: Inventory file is not following AntaInventory Schema. """ if inventory_input.networks is None: @@ -126,13 +126,13 @@ def _parse_ranges( Parameters ---------- - inventory_input: AntaInventoryInput used to parse the devices - inventory: AntaInventory to add the parsed devices to - **kwargs: Additional keyword arguments to pass to the device constructor + inventory_input: AntaInventoryInput used to parse the devices + inventory: AntaInventory to add the parsed devices to + **kwargs: Additional keyword arguments to pass to the device constructor Raises ------ - InventoryIncorrectSchemaError: Inventory file is not following AntaInventory Schema. + InventoryIncorrectSchemaError: Inventory file is not following AntaInventory Schema. """ if inventory_input.ranges is None: @@ -177,19 +177,19 @@ def parse( Parameters ---------- - filename: Path to device inventory YAML file. - username: Username to use to connect to devices. - password: Password to use to connect to devices. - enable_password: Enable password to use if required. - timeout: Timeout value in seconds for outgoing API calls. - enable: Whether or not the commands need to be run in enable mode towards the devices. - insecure: Disable SSH Host Key validation. - disable_cache: Disable cache globally. + filename: Path to device inventory YAML file. + username: Username to use to connect to devices. + password: Password to use to connect to devices. + enable_password: Enable password to use if required. + timeout: Timeout value in seconds for outgoing API calls. + enable: Whether or not the commands need to be run in enable mode towards the devices. + insecure: Disable SSH Host Key validation. + disable_cache: Disable cache globally. Raises ------ - InventoryRootKeyError: Root key of inventory is missing. - InventoryIncorrectSchemaError: Inventory file is not following AntaInventory Schema. + InventoryRootKeyError: Root key of inventory is missing. + InventoryIncorrectSchemaError: Inventory file is not following AntaInventory Schema. """ inventory = AntaInventory() @@ -256,13 +256,13 @@ def get_inventory(self, *, established_only: bool = False, tags: set[str] | None Parameters ---------- - established_only: Whether or not to include only established devices. - tags: Tags to filter devices. - devices: Names to filter devices. + established_only: Whether or not to include only established devices. + tags: Tags to filter devices. + devices: Names to filter devices. Returns ------- - An inventory with filtered AntaDevice objects. + An inventory with filtered AntaDevice objects. """ def _filter_devices(device: AntaDevice) -> bool: @@ -295,7 +295,7 @@ def add_device(self, device: AntaDevice) -> None: Parameters ---------- - device: Device object to be added + device: Device object to be added """ self[device.name] = device diff --git a/anta/models.py b/anta/models.py index e2cf49857..ea44205b8 100644 --- a/anta/models.py +++ b/anta/models.py @@ -97,7 +97,7 @@ def render(self, **params: str | int | bool) -> AntaCommand: Parameters ---------- - params: dictionary of variables with string values to render the Python f-string + params: dictionary of variables with string values to render the Python f-string Returns ------- @@ -247,8 +247,8 @@ def __init__(self, template: AntaTemplate, key: str) -> None: Parameters ---------- - template: The AntaTemplate instance that failed to render - key: Key that has not been provided to render the template + template: The AntaTemplate instance that failed to render + key: Key that has not been provided to render the template """ self.template = template @@ -383,10 +383,10 @@ def __init__( Parameters ---------- - device: AntaDevice instance on which the test will be run - inputs: dictionary of attributes used to instantiate the AntaTest.Input instance - eos_data: Populate outputs of the test commands instead of collecting from devices. - This list must have the same length and order than the `instance_commands` instance attribute. + device: AntaDevice instance on which the test will be run + inputs: dictionary of attributes used to instantiate the AntaTest.Input instance + eos_data: Populate outputs of the test commands instead of collecting from devices. + This list must have the same length and order than the `instance_commands` instance attribute. """ self.logger: logging.Logger = logging.getLogger(f"{self.module}.{self.__class__.__name__}") self.device: AntaDevice = device @@ -558,10 +558,10 @@ async def wrapper( Parameters ---------- - self: The test instance. - eos_data: Populate outputs of the test commands instead of collecting from devices. - This list must have the same length and order than the `instance_commands` instance attribute. - kwargs: Any keyword argument to pass to the test. + self: The test instance. + eos_data: Populate outputs of the test commands instead of collecting from devices. + This list must have the same length and order than the `instance_commands` instance attribute. + kwargs: Any keyword argument to pass to the test. Returns ------- diff --git a/anta/reporter/__init__.py b/anta/reporter/__init__.py index 7c911f243..84fe388cc 100644 --- a/anta/reporter/__init__.py +++ b/anta/reporter/__init__.py @@ -46,12 +46,12 @@ def _split_list_to_txt_list(self, usr_list: list[str], delimiter: str | None = N Parameters ---------- - usr_list (list[str]): List of string to concatenate - delimiter (str, optional): A delimiter to use to start string. Defaults to None. + usr_list (list[str]): List of string to concatenate + delimiter (str, optional): A delimiter to use to start string. Defaults to None. Returns ------- - str: Multi-lines string + str: Multi-lines string """ if delimiter is not None: @@ -65,12 +65,12 @@ def _build_headers(self, headers: list[str], table: Table) -> Table: Parameters ---------- - headers: List of headers. - table: A rich Table instance. + headers: List of headers. + table: A rich Table instance. Returns ------- - A rich `Table` instance with headers. + A rich `Table` instance with headers. """ for idx, header in enumerate(headers): @@ -85,7 +85,7 @@ def _color_result(self, status: TestStatus) -> str: Parameters ---------- - status (TestStatus): status value to color. + status (TestStatus): status value to color. Returns ------- @@ -102,12 +102,12 @@ def report_all(self, manager: ResultManager, title: str = "All tests results") - Parameters ---------- - manager: A ResultManager instance. - title: Title for the report. Defaults to 'All tests results'. + manager: A ResultManager instance. + title: Title for the report. Defaults to 'All tests results'. Returns ------- - A fully populated rich `Table` + A fully populated rich `Table` """ table = Table(title=title, show_lines=True) @@ -136,13 +136,13 @@ def report_summary_tests( Parameters ---------- - manager: A ResultManager instance. - tests: List of test names to include. None to select all tests. - title: Title of the report. + manager: A ResultManager instance. + tests: List of test names to include. None to select all tests. + title: Title of the report. Returns ------- - A fully populated rich `Table`. + A fully populated rich `Table`. """ table = Table(title=title, show_lines=True) headers = [ @@ -184,13 +184,13 @@ def report_summary_devices( Parameters ---------- - manager: A ResultManager instance. - devices: List of device names to include. None to select all devices. - title: Title of the report. + manager: A ResultManager instance. + devices: List of device names to include. None to select all devices. + title: Title of the report. Returns ------- - A fully populated rich `Table`. + A fully populated rich `Table`. """ table = Table(title=title, show_lines=True) headers = [ @@ -252,13 +252,13 @@ def render(self, data: list[dict[str, Any]], *, trim_blocks: bool = True, lstrip Parameters ---------- - data: List of results from ResultManager.results - trim_blocks: enable trim_blocks for J2 rendering. - lstrip_blocks: enable lstrip_blocks for J2 rendering. + data: List of results from ResultManager.results + trim_blocks: enable trim_blocks for J2 rendering. + lstrip_blocks: enable lstrip_blocks for J2 rendering. Returns ------- - Rendered template + Rendered template """ with self.template_path.open(encoding="utf-8") as file_: diff --git a/anta/result_manager/__init__.py b/anta/result_manager/__init__.py index 4278c0da3..906a71aa5 100644 --- a/anta/result_manager/__init__.py +++ b/anta/result_manager/__init__.py @@ -121,7 +121,7 @@ def add(self, result: TestResult) -> None: Parameters ---------- - result: TestResult to add to the ResultManager instance. + result: TestResult to add to the ResultManager instance. """ def _update_status(test_status: TestStatus) -> None: @@ -147,11 +147,11 @@ def filter(self, hide: set[TestStatus]) -> ResultManager: Parameters ---------- - hide: set of TestStatus literals to select tests to hide based on their status. + hide: set of TestStatus literals to select tests to hide based on their status. Returns ------- - A filtered `ResultManager`. + A filtered `ResultManager`. """ manager = ResultManager() manager.results = [test for test in self._result_entries if test.result not in hide] @@ -162,11 +162,11 @@ def filter_by_tests(self, tests: set[str]) -> ResultManager: Parameters ---------- - tests: Set of test names to filter the results. + tests: Set of test names to filter the results. Returns ------- - A filtered `ResultManager`. + A filtered `ResultManager`. """ manager = ResultManager() manager.results = [result for result in self._result_entries if result.test in tests] @@ -177,7 +177,7 @@ def filter_by_devices(self, devices: set[str]) -> ResultManager: Parameters ---------- - devices: Set of device names to filter the results. + devices: Set of device names to filter the results. Returns ------- diff --git a/anta/result_manager/models.py b/anta/result_manager/models.py index e1171c88a..832a84073 100644 --- a/anta/result_manager/models.py +++ b/anta/result_manager/models.py @@ -15,13 +15,13 @@ class TestResult(BaseModel): Attributes ---------- - name: Device name where the test has run. - test: Test name runs on the device. - categories: List of categories the TestResult belongs to, by default the AntaTest categories. - description: TestResult description, by default the AntaTest description. - result: Result of the test. Can be one of "unset", "success", "failure", "error" or "skipped". - messages: Message to report after the test if any. - custom_field: Custom field to store a string for flexibility in integrating with ANTA + name: Device name where the test has run. + test: Test name runs on the device. + categories: List of categories the TestResult belongs to, by default the AntaTest categories. + description: TestResult description, by default the AntaTest description. + result: Result of the test. Can be one of "unset", "success", "failure", "error" or "skipped". + messages: Message to report after the test if any. + custom_field: Custom field to store a string for flexibility in integrating with ANTA """ @@ -38,7 +38,7 @@ def is_success(self, message: str | None = None) -> None: Parameters ---------- - message: Optional message related to the test + message: Optional message related to the test """ self._set_status("success", message) @@ -48,7 +48,7 @@ def is_failure(self, message: str | None = None) -> None: Parameters ---------- - message: Optional message related to the test + message: Optional message related to the test """ self._set_status("failure", message) @@ -58,7 +58,7 @@ def is_skipped(self, message: str | None = None) -> None: Parameters ---------- - message: Optional message related to the test + message: Optional message related to the test """ self._set_status("skipped", message) @@ -68,7 +68,7 @@ def is_error(self, message: str | None = None) -> None: Parameters ---------- - message: Optional message related to the test + message: Optional message related to the test """ self._set_status("error", message) @@ -78,8 +78,8 @@ def _set_status(self, status: TestStatus, message: str | None = None) -> None: Parameters ---------- - status: status of the test - message: optional message + status: status of the test + message: optional message """ self.result = status diff --git a/anta/runner.py b/anta/runner.py index df4c70cc4..5fe988ce8 100644 --- a/anta/runner.py +++ b/anta/runner.py @@ -61,7 +61,7 @@ def log_cache_statistics(devices: list[AntaDevice]) -> None: Parameters ---------- - devices: List of devices in the inventory. + devices: List of devices in the inventory. """ for device in devices: if device.cache_statistics is not None: @@ -80,13 +80,13 @@ async def setup_inventory(inventory: AntaInventory, tags: set[str] | None, devic Parameters ---------- - inventory: AntaInventory object that includes the device(s). - tags: Tags to filter devices from the inventory. - devices: Devices on which to run tests. None means all devices. + inventory: AntaInventory object that includes the device(s). + tags: Tags to filter devices from the inventory. + devices: Devices on which to run tests. None means all devices. Returns ------- - AntaInventory | None: The filtered inventory or None if there are no devices to run tests on. + AntaInventory | None: The filtered inventory or None if there are no devices to run tests on. """ if len(inventory) == 0: logger.info("The inventory is empty, exiting") @@ -118,14 +118,14 @@ def prepare_tests( Parameters ---------- - inventory: AntaInventory object that includes the device(s). - catalog: AntaCatalog object that includes the list of tests. - tests: Tests to run against devices. None means all tests. - tags: Tags to filter devices from the inventory. + inventory: AntaInventory object that includes the device(s). + catalog: AntaCatalog object that includes the list of tests. + tests: Tests to run against devices. None means all tests. + tags: Tags to filter devices from the inventory. Returns ------- - A mapping of devices to the tests to run or None if there are no tests to run. + A mapping of devices to the tests to run or None if there are no tests to run. """ # Build indexes for the catalog. If `tests` is set, filter the indexes based on these tests catalog.build_indexes(filtered_tests=tests) @@ -162,11 +162,11 @@ def get_coroutines(selected_tests: defaultdict[AntaDevice, set[AntaTestDefinitio Parameters ---------- - selected_tests: A mapping of devices to the tests to run. The selected tests are generated by the `prepare_tests` function. + selected_tests: A mapping of devices to the tests to run. The selected tests are generated by the `prepare_tests` function. Returns ------- - The list of coroutines to run. + The list of coroutines to run. """ coros = [] for device, test_definitions in selected_tests.items(): @@ -207,14 +207,14 @@ async def main( # noqa: PLR0913 Parameters ---------- - manager: ResultManager object to populate with the test results. - inventory: AntaInventory object that includes the device(s). - catalog: AntaCatalog object that includes the list of tests. - devices: Devices on which to run tests. None means all devices. These may come from the `--device / -d` CLI option in NRFU. - tests: Tests to run against devices. None means all tests. These may come from the `--test / -t` CLI option in NRFU. - tags: Tags to filter devices from the inventory. These may come from the `--tags` CLI option in NRFU. - established_only: Include only established device(s). - dry_run: Build the list of coroutine to run and stop before test execution. + manager: ResultManager object to populate with the test results. + inventory: AntaInventory object that includes the device(s). + catalog: AntaCatalog object that includes the list of tests. + devices: Devices on which to run tests. None means all devices. These may come from the `--device / -d` CLI option in NRFU. + tests: Tests to run against devices. None means all tests. These may come from the `--test / -t` CLI option in NRFU. + tags: Tags to filter devices from the inventory. These may come from the `--tags` CLI option in NRFU. + established_only: Include only established device(s). + dry_run: Build the list of coroutine to run and stop before test execution. """ # Adjust the maximum number of open file descriptors for the ANTA process limits = adjust_rlimit_nofile() diff --git a/anta/tests/logging.py b/anta/tests/logging.py index b520fc1e1..4d0d56a87 100644 --- a/anta/tests/logging.py +++ b/anta/tests/logging.py @@ -27,12 +27,12 @@ def _get_logging_states(logger: logging.Logger, command_output: str) -> str: Parameters ---------- - logger: The logger object. - command_output: The `show logging` output. + logger: The logger object. + command_output: The `show logging` output. Returns ------- - str: The operational logging states. + str: The operational logging states. """ log_states = command_output.partition("\n\nExternal configuration:")[0] diff --git a/anta/tests/routing/bgp.py b/anta/tests/routing/bgp.py index 6a7002356..a392538a9 100644 --- a/anta/tests/routing/bgp.py +++ b/anta/tests/routing/bgp.py @@ -26,13 +26,13 @@ def _add_bgp_failures(failures: dict[tuple[str, str | None], dict[str, Any]], af Parameters ---------- - failures: The dictionary to which the failure will be added. - afi: The address family identifier. - vrf: The VRF name. - safi: The subsequent address family identifier. - issue: A description of the issue. Can be of any type. + failures: The dictionary to which the failure will be added. + afi: The address family identifier. + vrf: The VRF name. + safi: The subsequent address family identifier. + issue: A description of the issue. Can be of any type. - Example: + Example ------- The `failures` dictionary will have the following structure: { @@ -65,17 +65,17 @@ def _check_peer_issues(peer_data: dict[str, Any] | None) -> dict[str, Any]: Parameters ---------- - peer_data: The BGP peer data dictionary nested in the `show bgp summary` command. + peer_data: The BGP peer data dictionary nested in the `show bgp summary` command. Returns ------- - dict: Dictionary with keys indicating issues or an empty dictionary if no issues. + dict: Dictionary with keys indicating issues or an empty dictionary if no issues. Raises ------ ValueError: If any of the required keys ("peerState", "inMsgQueue", "outMsgQueue") are missing in `peer_data`, i.e. invalid BGP peer data. - Example: + Example ------- {"peerNotFound": True} {"peerState": "Idle", "inMsgQueue": 2, "outMsgQueue": 0} @@ -106,15 +106,15 @@ def _add_bgp_routes_failure( Parameters ---------- - bgp_routes: The list of expected routes. - bgp_output: The BGP output from the device. - peer: The IP address of the BGP peer. - vrf: The name of the VRF for which the routes need to be verified. - route_type: The type of BGP routes. Defaults to 'advertised_routes'. + bgp_routes: The list of expected routes. + bgp_output: The BGP output from the device. + peer: The IP address of the BGP peer. + vrf: The name of the VRF for which the routes need to be verified. + route_type: The type of BGP routes. Defaults to 'advertised_routes'. Returns ------- - dict[str, dict[str, dict[str, dict[str, list[str]]]]]: A dictionary containing the missing routes and invalid or inactive routes. + dict[str, dict[str, dict[str, dict[str, list[str]]]]]: A dictionary containing the missing routes and invalid or inactive routes. """ # Prepare the failure routes dictionary diff --git a/anta/tests/routing/ospf.py b/anta/tests/routing/ospf.py index 342ada2f4..cb325d6bd 100644 --- a/anta/tests/routing/ospf.py +++ b/anta/tests/routing/ospf.py @@ -20,11 +20,11 @@ def _count_ospf_neighbor(ospf_neighbor_json: dict[str, Any]) -> int: Parameters ---------- - ospf_neighbor_json: The JSON output of the `show ip ospf neighbor` command. + ospf_neighbor_json: The JSON output of the `show ip ospf neighbor` command. Returns ------- - int: The number of OSPF neighbors. + int: The number of OSPF neighbors. """ count = 0 @@ -39,11 +39,11 @@ def _get_not_full_ospf_neighbors(ospf_neighbor_json: dict[str, Any]) -> list[dic Parameters ---------- - ospf_neighbor_json: The JSON output of the `show ip ospf neighbor` command. + ospf_neighbor_json: The JSON output of the `show ip ospf neighbor` command. Returns ------- - list[dict[str, Any]]: A list of OSPF neighbors whose adjacency state is not `full`. + list[dict[str, Any]]: A list of OSPF neighbors whose adjacency state is not `full`. """ return [ @@ -65,11 +65,11 @@ def _get_ospf_max_lsa_info(ospf_process_json: dict[str, Any]) -> list[dict[str, Parameters ---------- - ospf_process_json: OSPF process information in JSON format. + ospf_process_json: OSPF process information in JSON format. Returns ------- - list[dict[str, Any]]: A list of dictionaries containing OSPF LSAs information. + list[dict[str, Any]]: A list of dictionaries containing OSPF LSAs information. """ return [ diff --git a/docs/advanced_usages/as-python-lib.md b/docs/advanced_usages/as-python-lib.md index f8d67348b..08bb818c1 100644 --- a/docs/advanced_usages/as-python-lib.md +++ b/docs/advanced_usages/as-python-lib.md @@ -11,11 +11,11 @@ ANTA is a Python library that can be used in user applications. This section des ## [AntaDevice](../api/device.md#anta.device.AntaDevice) Abstract Class -A device is represented in ANTA as a instance of a subclass of the [AntaDevice](../api/device.md### ::: anta.device.AntaDevice) abstract class. +A device is represented in ANTA as a instance of a subclass of the [AntaDevice](../api/device.md#anta.device.AntaDevice) abstract class. There are few abstract methods that needs to be implemented by child classes: - The [collect()](../api/device.md#anta.device.AntaDevice.collect) coroutine is in charge of collecting outputs of [AntaCommand](../api/models.md#anta.models.AntaCommand) instances. -- The [refresh()](../api/device.md#anta.device.AntaDevice.refresh) coroutine is in charge of updating attributes of the [AntaDevice](../api/device.md### ::: anta.device.AntaDevice) instance. These attributes are used by [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) to filter out unreachable devices or by [AntaTest](../api/models.md#anta.models.AntaTest) to skip devices based on their hardware models. +- The [refresh()](../api/device.md#anta.device.AntaDevice.refresh) coroutine is in charge of updating attributes of the [AntaDevice](../api/device.md#anta.device.AntaDevice) instance. These attributes are used by [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) to filter out unreachable devices or by [AntaTest](../api/models.md#anta.models.AntaTest) to skip devices based on their hardware models. The [copy()](../api/device.md#anta.device.AntaDevice.copy) coroutine is used to copy files to and from the device. It does not need to be implemented if tests are not using it. @@ -24,7 +24,7 @@ The [copy()](../api/device.md#anta.device.AntaDevice.copy) coroutine is used to The [AsyncEOSDevice](../api/device.md#anta.device.AsyncEOSDevice) class is an implementation of [AntaDevice](../api/device.md#anta.device.AntaDevice) for Arista EOS. It uses the [aio-eapi](https://github.com/jeremyschulman/aio-eapi) eAPI client and the [AsyncSSH](https://github.com/ronf/asyncssh) library. -- The [collect()](../api/device.md#anta.device.AsyncEOSDevice.collect) coroutine collects [AntaCommand](../api/models.md#anta.models.AntaCommand) outputs using eAPI. +- The [_collect()](../api/device.md#anta.device.AsyncEOSDevice._collect) coroutine collects [AntaCommand](../api/models.md#anta.models.AntaCommand) outputs using eAPI. - The [refresh()](../api/device.md#anta.device.AsyncEOSDevice.refresh) coroutine tries to open a TCP connection on the eAPI port and update the `is_online` attribute accordingly. If the TCP connection succeeds, it sends a `show version` command to gather the hardware model of the device and updates the `established` and `hw_model` attributes. - The [copy()](../api/device.md#anta.device.AsyncEOSDevice.copy) coroutine copies files to and from the device using the SCP protocol. @@ -35,7 +35,7 @@ The [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) class is a [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) provides methods to interact with the ANTA inventory: -- The [add_device()](../api/inventory.md#anta.inventory.AntaInventory.add_device) method adds an [AntaDevice](../api/device.md### ::: anta.device.AntaDevice) instance to the inventory. Adding an entry to [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) with a key different from the device name is not allowed. +- The [add_device()](../api/inventory.md#anta.inventory.AntaInventory.add_device) method adds an [AntaDevice](../api/device.md#anta.device.AntaDevice) instance to the inventory. Adding an entry to [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) with a key different from the device name is not allowed. - The [get_inventory()](../api/inventory.md#anta.inventory.AntaInventory.get_inventory) returns a new [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) instance with filtered out devices based on the method inputs. - The [connect_inventory()](../api/inventory.md#anta.inventory.AntaInventory.connect_inventory) coroutine will execute the [refresh()](../api/device.md#anta.device.AntaDevice.refresh) coroutines of all the devices in the inventory. - The [parse()](../api/inventory.md#anta.inventory.AntaInventory.parse) static method creates an [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) instance from a YAML file and returns it. The devices are [AsyncEOSDevice](../api/device.md#anta.device.AsyncEOSDevice) instances. diff --git a/docs/advanced_usages/caching.md b/docs/advanced_usages/caching.md index ce4a7877c..7de310de7 100644 --- a/docs/advanced_usages/caching.md +++ b/docs/advanced_usages/caching.md @@ -47,7 +47,7 @@ There might be scenarios where caching is not wanted. You can disable caching in ```bash anta --disable-cache --username arista --password arista nrfu table ``` -2. Caching can be disabled per device, network or range by setting the `disable_cache` key to `True` when defining the ANTA [Inventory](../usage-inventory-catalog.md#create-an-inventory-file) file: +2. Caching can be disabled per device, network or range by setting the `disable_cache` key to `True` when defining the ANTA [Inventory](../usage-inventory-catalog.md#device-inventory) file: ```yaml anta_inventory: hosts: diff --git a/docs/api/device.md b/docs/api/device.md index 03cff192e..9401f59af 100644 --- a/docs/api/device.md +++ b/docs/api/device.md @@ -6,20 +6,18 @@ # AntaDevice base class -## UML representation - ![](../imgs/uml/anta.device.AntaDevice.jpeg) -### ::: anta.device.AntaDevice +## ::: anta.device.AntaDevice options: - filters: ["!^_[^_]", "!__(eq|rich_repr)__"] + filters: ["!^_[^_]", "!__(eq|rich_repr)__", "_collect"] # Async EOS device class -## UML representation - ![](../imgs/uml/anta.device.AsyncEOSDevice.jpeg) -### ::: anta.device.AsyncEOSDevice + + +## ::: anta.device.AsyncEOSDevice options: - filters: ["!^_[^_]", "!__(eq|rich_repr)__"] + filters: ["!^_[^_]", "!__(eq|rich_repr)__", "_collect"] diff --git a/docs/api/models.md b/docs/api/models.md index b0c1e916f..3175fce54 100644 --- a/docs/api/models.md +++ b/docs/api/models.md @@ -6,8 +6,6 @@ # Test definition -## UML Diagram - ![](../imgs/uml/anta.models.AntaTest.jpeg) ### ::: anta.models.AntaTest @@ -16,9 +14,8 @@ # Command definition -## UML Diagram - ![](../imgs/uml/anta.models.AntaCommand.jpeg) + ### ::: anta.models.AntaCommand !!! warning @@ -30,8 +27,6 @@ # Template definition -## UML Diagram - ![](../imgs/uml/anta.models.AntaTemplate.jpeg) ### ::: anta.models.AntaTemplate diff --git a/docs/api/result_manager.md b/docs/api/result_manager.md index 72e05aaf4..dca0a19dd 100644 --- a/docs/api/result_manager.md +++ b/docs/api/result_manager.md @@ -6,8 +6,6 @@ # Result Manager definition -## UML Diagram - ![](../imgs/uml/anta.result_manager.ResultManager.jpeg) ### ::: anta.result_manager.ResultManager diff --git a/docs/api/result_manager_models.md b/docs/api/result_manager_models.md index 096bd036b..d0ccc7983 100644 --- a/docs/api/result_manager_models.md +++ b/docs/api/result_manager_models.md @@ -6,8 +6,6 @@ # Test Result model -## UML Diagram - ![](../imgs/uml/anta.result_manager.models.TestResult.jpeg) ### ::: anta.result_manager.models.TestResult diff --git a/docs/cli/debug.md b/docs/cli/debug.md index db5f4961d..d290fe118 100644 --- a/docs/cli/debug.md +++ b/docs/cli/debug.md @@ -14,7 +14,7 @@ The ANTA CLI includes a set of debugging tools, making it easier to build and te These tools are especially helpful in building the tests, as they give a visual access to the output received from the eAPI. They also facilitate the extraction of output content for use in unit tests, as described in our [contribution guide](../contribution.md). !!! warning - The `debug` tools require a device from your inventory. Thus, you MUST use a valid [ANTA Inventory](../usage-inventory-catalog.md#create-an-inventory-file). + The `debug` tools require a device from your inventory. Thus, you MUST use a valid [ANTA Inventory](../usage-inventory-catalog.md#device-inventory). ## Executing an EOS command diff --git a/docs/cli/nrfu.md b/docs/cli/nrfu.md index afed25949..26935c2b7 100644 --- a/docs/cli/nrfu.md +++ b/docs/cli/nrfu.md @@ -205,7 +205,7 @@ The template `./custom_template.j2` is a simple Jinja2 template: {% endfor %} ``` -The Jinja2 template has access to all `TestResult` elements and their values, as described in this [documentation](../api/result_manager_models.md#testresult-entry). +The Jinja2 template has access to all `TestResult` elements and their values, as described in this [documentation](../api/result_manager_models.md#anta.result_manager.models.TestResult). You can also save the report result to a file using the `--output` option: diff --git a/docs/getting-started.md b/docs/getting-started.md index 39b270ce1..c166ebe78 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -72,7 +72,7 @@ anta_inventory: tags: ['fabric', 'leaf'] ``` -> You can read more details about how to build your inventory [here](usage-inventory-catalog.md#create-an-inventory-file) +> You can read more details about how to build your inventory [here](usage-inventory-catalog.md#device-inventory) ## Test Catalog diff --git a/docs/templates/python/material/anta_test.html b/docs/templates/python/material/anta_test.html.jinja similarity index 96% rename from docs/templates/python/material/anta_test.html rename to docs/templates/python/material/anta_test.html.jinja index ade0ba691..a40d86a24 100644 --- a/docs/templates/python/material/anta_test.html +++ b/docs/templates/python/material/anta_test.html.jinja @@ -31,7 +31,7 @@ {% endif %} {% with heading_level = heading_level + extra_level %} {% for attribute in attributes|order_members(config.members_order, members_list) %} - {% if members_list is not none or attribute.is_public(check_name=False) %} + {% if members_list is not none or attribute.is_public %} {% include attribute|get_template with context %} {% endif %} {% endfor %} @@ -60,7 +60,7 @@ {% include "attributes_table.html" with context %} {% set obj = old_obj %} {% else %} - {% if members_list is not none or class.is_public(check_name=False) %} + {% if members_list is not none or class.is_public %} {% include class|get_template with context %} {% endif %} {% endif %} @@ -82,7 +82,7 @@ {% with heading_level = heading_level + extra_level %} {% for function in functions|order_members(config.members_order, members_list) %} {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %} - {% if members_list is not none or function.is_public(check_name=False) %} + {% if members_list is not none or function.is_public %} {% include function|get_template with context %} {% endif %} {% endif %} @@ -104,7 +104,7 @@ {% endif %} {% with heading_level = heading_level + extra_level %} {% for module in modules|order_members(config.members_order.alphabetical, members_list) %} - {% if members_list is not none or module.is_public(check_name=False) %} + {% if members_list is not none or module.is_public %} {% include module|get_template with context %} {% endif %} {% endfor %} @@ -129,7 +129,7 @@ {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %} - {% if members_list is not none or child.is_public(check_name=False) %} + {% if members_list is not none or child.is_public %} {% if child.is_attribute %} {% with attribute = child %} {% include attribute|get_template with context %} diff --git a/docs/templates/python/material/class.html b/docs/templates/python/material/class.html.jinja similarity index 91% rename from docs/templates/python/material/class.html rename to docs/templates/python/material/class.html.jinja index 940103b4f..1c1173ce4 100644 --- a/docs/templates/python/material/class.html +++ b/docs/templates/python/material/class.html.jinja @@ -1,4 +1,4 @@ -{% extends "_base/class.html" %} +{% extends "_base/class.html.jinja" %} {% set anta_test = namespace(found=false) %} {% for base in class.bases %} {% set basestr = base | string %} @@ -10,7 +10,7 @@ {% if anta_test.found %} {% set root = False %} {% set heading_level = heading_level + 1 %} - {% include "anta_test.html" with context %} + {% include "anta_test.html.jinja" with context %} {# render source after children - TODO make add flag to respect disabling it.. though do we want to disable?#}
Source code in diff --git a/docs/templates/python/material/docstring.html b/docs/templates/python/material/docstring.html.jinja similarity index 100% rename from docs/templates/python/material/docstring.html rename to docs/templates/python/material/docstring.html.jinja diff --git a/mkdocs.yml b/mkdocs.yml index 291fb2bda..e206ba218 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -153,7 +153,7 @@ markdown_extensions: separator: "-" # permalink: "#" permalink: true - # baselevel: 3 + baselevel: 2 - pymdownx.highlight - pymdownx.snippets: base_path: @@ -193,7 +193,7 @@ nav: - Configuration: api/tests.configuration.md - Connectivity: api/tests.connectivity.md - Field Notices: api/tests.field_notices.md - - Flow Tracking: api/test.flow_tracking.md + - Flow Tracking: api/tests.flow_tracking.md - GreenT: api/tests.greent.md - Hardware: api/tests.hardware.md - Interfaces: api/tests.interfaces.md diff --git a/pyproject.toml b/pyproject.toml index 2f19a44fc..e1f4a303d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -80,18 +80,18 @@ dev = [ "yamllint>=1.32.0", ] doc = [ - "fontawesome_markdown", - "griffe >=0.46,<2.0.0", + "fontawesome_markdown>=0.2.6", + "griffe >=1.2.0", "mike==2.1.3", - "mkdocs-autorefs>=0.4.1", + "mkdocs>=1.6.1", + "mkdocs-autorefs>=1.2.0", "mkdocs-bootswatch>=1.1", - "mkdocs-git-revision-date-localized-plugin>=1.1.0", + "mkdocs-git-revision-date-localized-plugin>=1.2.8", "mkdocs-git-revision-date-plugin>=0.3.2", - "mkdocs-material-extensions>=1.0.3", - "mkdocs-material>=8.3.9", - "mkdocs>=1.3.1", - "mkdocstrings[python]>=0.20.0", - "mkdocs-glightbox>=0.4.0" + "mkdocs-glightbox>=0.4.0", + "mkdocs-material-extensions>=1.3.1", + "mkdocs-material>=9.5.34", + "mkdocstrings[python]>=0.26.0" ] [project.urls]