Adding upstream version 0.14.0.upstream/0.14.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

3 files changed, 47 insertions, 25 deletions

diff --git a/docs/advanced_usages/as-python-lib.md b/docs/advanced_usages/as-python-lib.md
index b4ce654..f8d6734 100644
--- a/docs/advanced_usages/as-python-lib.md
+++ b/docs/advanced_usages/as-python-lib.md
@@ -72,7 +72,6 @@ if __name__ == "__main__":
         filename="inv.yml",
         username="arista",
         password="@rista123",
-        timeout=15,
     )
 
     # Run the main coroutine
@@ -129,7 +128,6 @@ if __name__ == "__main__":
         filename="inv.yml",
         username="arista",
         password="@rista123",
-        timeout=15,
     )
 
     # Create a list of commands with json output
@@ -228,7 +226,7 @@ class VerifyTransceiversManufacturers(AntaTest):
         pass
 ```
 
-The test itself does not return any value, but the result is directly availble from your AntaTest object and exposes a `anta.result_manager.models.TestResult` object with result, name of the test and optional messages:
+The test itself does not return any value, but the result is directly available from your AntaTest object and exposes a `anta.result_manager.models.TestResult` object with result, name of the test and optional messages:
 
 
 - `name` (str): Device name where the test has run.
@@ -256,7 +254,7 @@ To make it easier to get data, ANTA defines 2 different classes to manage comman
 Represent a command with following information:
 
 - Command to run
-- Ouput format expected
+- Output format expected
 - eAPI version
 - Output of the command
 
@@ -272,13 +270,13 @@ cmd2 = AntaCommand(command="show running-config diffs", ofmt="text")
 !!! tip "Command revision and version"
     * Most of EOS commands return a JSON structure according to a model (some commands may not be modeled hence the necessity to use `text` outformat sometimes.
     * The model can change across time (adding feature, ... ) and when the model is changed in a non backward-compatible way, the __revision__ number is bumped. The initial model starts with __revision__ 1.
-    * A __revision__ applies to a particular CLI command whereas a __version__ is global to an eAPI call. The __version__ is internally translated to a specific __revision__ for each CLI command in the RPC call. The currently supported __version__ vaues  are `1` and `latest`.
+    * A __revision__ applies to a particular CLI command whereas a __version__ is global to an eAPI call. The __version__ is internally translated to a specific __revision__ for each CLI command in the RPC call. The currently supported __version__ values  are `1` and `latest`.
     * A __revision takes precedence over a version__ (e.g. if a command is run with version="latest" and revision=1, the first revision of the model is returned)
-    * By default eAPI returns the first revision of each model to ensure that when upgrading, intergation with existing tools is not broken. This is done by using by default `version=1` in eAPI calls.
+    * By default, eAPI returns the first revision of each model to ensure that when upgrading, integrations with existing tools are not broken. This is done by using by default `version=1` in eAPI calls.
 
-    ANTA uses by default `version="latest"` in AntaCommand. For some commands, you may want to run them with a different revision or version.
+    By default, ANTA uses `version="latest"` in AntaCommand, but when developing tests, the revision MUST be provided when the outformat of the command is `json`. As explained earlier, this is to ensure that the eAPI always returns the same output model and that the test remains always valid from the day it was created. For some commands, you may also want to run them with a different revision or version.
 
-    For instance the `VerifyRoutingTableSize` test leverages the first revision of `show bfd peers`:
+    For instance, the `VerifyBFDPeersHealth` test leverages the first revision of `show bfd peers`:
 
     ```
     # revision 1 as later revision introduce additional nesting for type
diff --git a/docs/advanced_usages/caching.md b/docs/advanced_usages/caching.md
index cec2467..ce4a787 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 definining 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#create-an-inventory-file) file:
     ```yaml
     anta_inventory:
       hosts:
@@ -71,7 +71,7 @@ There might be scenarios where caching is not wanted. You can disable caching in
     ```
     This approach effectively disables caching for **ALL** commands sent to devices targeted by the `disable_cache` key.
 
-3. For tests developpers, caching can be disabled for a specific [`AntaCommand`](../advanced_usages/as-python-lib.md#antacommand-class) or [`AntaTemplate`](../advanced_usages/as-python-lib.md#antatemplate-class) by setting the `use_cache` attribute to `False`. That means the command output will always be collected on the device and therefore, never use caching.
+3. For tests developers, caching can be disabled for a specific [`AntaCommand`](../advanced_usages/as-python-lib.md#antacommand-class) or [`AntaTemplate`](../advanced_usages/as-python-lib.md#antatemplate-class) by setting the `use_cache` attribute to `False`. That means the command output will always be collected on the device and therefore, never use caching.
 
 ### Disable caching in a child class of `AntaDevice`
 
@@ -82,6 +82,6 @@ class AnsibleEOSDevice(AntaDevice):
   """
   Implementation of an AntaDevice using Ansible HttpApi plugin for EOS.
   """
-  def __init__(self, name: str, connection: ConnectionBase, tags: list = None) -> None:
+  def __init__(self, name: str, connection: ConnectionBase, tags: set = None) -> None:
       super().__init__(name, tags, disable_cache=True)
 ```
diff --git a/docs/advanced_usages/custom-tests.md b/docs/advanced_usages/custom-tests.md
index 87402c1..df17c1c 100644
--- a/docs/advanced_usages/custom-tests.md
+++ b/docs/advanced_usages/custom-tests.md
@@ -21,24 +21,32 @@ from anta.decorators import skip_on_platforms
 
 
 class VerifyTemperature(AntaTest):
-    """
-    This test verifies if the device temperature is within acceptable limits.
-
-    Expected Results:
-      * success: The test will pass if the device temperature is currently OK: 'temperatureOk'.
-      * failure: The test will fail if the device temperature is NOT OK.
+    """Verifies if the device temperature is within acceptable limits.
+
+    Expected Results
+    ----------------
+    * Success: The test will pass if the device temperature is currently OK: 'temperatureOk'.
+    * Failure: The test will fail if the device temperature is NOT OK.
+
+    Examples
+    --------
+    ```yaml
+    anta.tests.hardware:
+      - VerifyTemperature:
+    ```
     """
 
     name = "VerifyTemperature"
-    description = "Verifies if the device temperature is within the acceptable range."
-    categories = ["hardware"]
-    commands = [AntaCommand(command="show system environment temperature", ofmt="json")]
+    description = "Verifies the device temperature."
+    categories: ClassVar[list[str]] = ["hardware"]
+    commands: ClassVar[list[AntaCommand | AntaTemplate]] = [AntaCommand(command="show system environment temperature", revision=1)]
 
-    @skip_on_platforms(["cEOSLab", "vEOS-lab"])
+    @skip_on_platforms(["cEOSLab", "vEOS-lab", "cEOSCloudLab"])
     @AntaTest.anta_test
     def test(self) -> None:
+        """Main test function for VerifyTemperature."""
         command_output = self.instance_commands[0].json_output
-        temperature_status = command_output["systemStatus"] if "systemStatus" in command_output.keys() else ""
+        temperature_status = command_output.get("systemStatus", "")
         if temperature_status == "temperatureOk":
             self.result.is_success()
         else:
@@ -54,7 +62,7 @@ class VerifyTemperature(AntaTest):
 - `name` (`str`): Name of the test. Used during reporting.
 - `description` (`str`): A human readable description of your test.
 - `categories` (`list[str]`): A list of categories in which the test belongs.
-- `commands` (`list[Union[AntaTemplate, AntaCommand]]`): A list of command to collect from devices. This list __must__ be a list of [AntaCommand](../api/models.md#anta.models.AntaCommand) or [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances. Rendering [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances will be discussed later.
+- `commands` (`[list[AntaCommand | AntaTemplate]]`): A list of command to collect from devices. This list __must__ be a list of [AntaCommand](../api/models.md#anta.models.AntaCommand) or [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances. Rendering [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances will be discussed later.
 
 !!! info
     All these class attributes are mandatory. If any attribute is missing, a `NotImplementedError` exception will be raised during class instantiation.
@@ -127,7 +135,7 @@ The base definition of [AntaTest.Input](../api/models.md#anta.models.AntaTest.In
 ### Methods
 
 - [test(self) -> None](../api/models.md#anta.models.AntaTest.test): This is an abstract method that __must__ be implemented. It contains the test logic that can access the collected command outputs using the `instance_commands` instance attribute, access the test inputs using the `inputs` instance attribute and __must__ set the `result` instance attribute accordingly. It must be implemented using the `AntaTest.anta_test` decorator that provides logging and will collect commands before executing the `test()` method.
-- [render(self, template: AntaTemplate) -> list[AntaCommand]](../api/models.md#anta.models.AntaTest.render): This method only needs to be implemented if [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances are present in the `commands` class attribute. It will be called for every [AntaTemplate](../api/models.md#anta.models.AntaTemplate) occurence and __must__ return a list of [AntaCommand](../api/models.md#anta.models.AntaCommand) using the [AntaTemplate.render()](../api/models.md#anta.models.AntaTemplate.render) method. It can access test inputs using the `inputs` instance attribute.
+- [render(self, template: AntaTemplate) -> list[AntaCommand]](../api/models.md#anta.models.AntaTest.render): This method only needs to be implemented if [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances are present in the `commands` class attribute. It will be called for every [AntaTemplate](../api/models.md#anta.models.AntaTemplate) occurrence and __must__ return a list of [AntaCommand](../api/models.md#anta.models.AntaCommand) using the [AntaTemplate.render()](../api/models.md#anta.models.AntaTemplate.render) method. It can access test inputs using the `inputs` instance attribute.
 
 ## Test execution
 
@@ -191,8 +199,24 @@ If the user needs to provide inputs for your test, you need to define a [pydanti
 
 ```python
 class <YourTestName>(AntaTest):
+    """Verifies ...
+
+    Expected Results
+    ----------------
+    * Success: The test will pass if ...
+    * Failure: The test will fail if ...
+
+    Examples
+    --------
+    ```yaml
+    your.module.path:
+      - YourTestName:
+        field_name: example_field_value
+    ```
+    """
     ...
-    class Input(AntaTest.Input):  # pylint: disable=missing-class-docstring
+    class Input(AntaTest.Input):
+        """Inputs for my awesome test."""
         <input field name>: <input field type>
         """<input field docstring>"""
 ```