ANTA Commands API

AntaCommand

Bases: BaseModel

Class to define a command.

Info

eAPI models are revisioned, this means that if a model is modified in a non-backwards compatible way, then its revision will be bumped up (revisions are numbers, default value is 1).

By default an eAPI request will return revision 1 of the model instance, this ensures that older management software will not suddenly stop working when a switch is upgraded. A revision applies to a particular CLI command whereas a version is global and is internally translated to a specific revision for each CLI command in the RPC.

Revision has precedence over version.

Attributes:

Name	Type	Description
command	str	Device command.
version	Literal[1, 'latest']	eAPI version - valid values are 1 or “latest”.
revision	Revision | None	eAPI revision of the command. Valid values are 1 to 99. Revision has precedence over version.
ofmt	Literal['json', 'text']	eAPI output - json or text.
output	dict[str, Any] | str | None	Output of the command. Only defined if there was no errors.
template	AntaTemplate | None	AntaTemplate object used to render this command.
errors	list[str]	If the command execution fails, eAPI returns a list of strings detailing the error(s).
params	AntaParamsBaseModel	Pydantic Model containing the variables values used to render the template.
use_cache	bool	Enable or disable caching for this AntaCommand if the AntaDevice supports it.

collected property

collected: bool

Return True if the command has been collected, False otherwise.

A command that has not been collected could have returned an error. See error property.

error property

error: bool

Return True if the command returned an error, False otherwise.

json_output property

json_output: dict[str, Any]

Get the command output as JSON.

requires_privileges property

requires_privileges: bool

Return True if the command requires privileged mode, False otherwise.

Raises:

Type	Description
RuntimeError	If the command has not been collected and has not returned an error. AntaDevice.collect() must be called before this property.

returned_known_eos_error property

returned_known_eos_error: bool

Return True if the command returned a known_eos_error on the device, False otherwise.

RuntimeError If the command has not been collected and has not returned an error. AntaDevice.collect() must be called before this property.

supported property

supported: bool

Indicates if the command is supported on the device.

Returns:

Type	Description
bool	True if the command is supported on the device hardware platform, False otherwise.

Raises:

Type	Description
RuntimeError	If the command has not been collected and has not returned an error. AntaDevice.collect() must be called before this property.

text_output property

text_output: str

Get the command output as a string.

uid property

uid: str

Generate a unique identifier for this command.

AntaTemplate

AntaTemplate(
    template: str,
    version: Literal[1, "latest"] = "latest",
    revision: Revision | None = None,
    ofmt: Literal["json", "text"] = "json",
    *,
    use_cache: bool = True
)

Class to define a command template as Python f-string.

Can render a command from parameters.

Attributes:

Name	Type	Description
template		Python f-string. Example: ‘show vlan {vlan_id}’.
version		eAPI version - valid values are 1 or “latest”.
revision		Revision of the command. Valid values are 1 to 99. Revision has precedence over version.
ofmt		eAPI output - json or text.
use_cache		Enable or disable caching for this AntaTemplate if the AntaDevice supports it.

render

render(**params: str | int | bool) -> AntaCommand

Render an AntaCommand from an AntaTemplate instance.

Keep the parameters used in the AntaTemplate instance.

Parameters:

Name	Type	Description	Default
params	str | int | bool	Dictionary of variables with string values to render the Python f-string.	{}

Returns:

Type	Description
AntaCommand	The rendered AntaCommand. This AntaCommand instance have a template attribute that references this AntaTemplate instance.

Raises:

Type	Description
AntaTemplateRenderError	If a parameter is missing to render the AntaTemplate instance.

Source code in anta/models.py

def render(self, **params: str | int | bool) -> AntaCommand:
    """Render an AntaCommand from an AntaTemplate instance.

    Keep the parameters used in the AntaTemplate instance.

    Parameters
    ----------
    params
        Dictionary of variables with string values to render the Python f-string.

    Returns
    -------
    AntaCommand
        The rendered AntaCommand.
        This AntaCommand instance have a template attribute that references this
        AntaTemplate instance.

    Raises
    ------
    AntaTemplateRenderError
        If a parameter is missing to render the AntaTemplate instance.
    """
    try:
        command = self.template.format(**params)
    except (KeyError, SyntaxError) as e:
        raise AntaTemplateRenderError(self, e.args[0]) from e
    return AntaCommand(
        command=command,
        ofmt=self.ofmt,
        version=self.version,
        revision=self.revision,
        template=self,
        params=self.params_schema(**params),
        use_cache=self.use_cache,
    )

EOS Commands Error Handling

UNSUPPORTED_PLATFORM_ERRORS

UNSUPPORTED_PLATFORM_ERRORS = [
    "not supported on this hardware platform",
    "Invalid input (at token 2: 'trident')",
]

Error messages indicating platform or hardware unsupported commands. Includes both general hardware platform errors and specific ASIC family limitations.

Running EOS commands unsupported by hardware

When catching these errors, ANTA will skip the affected test and raise a warning. The test catalog must be updated to remove execution of the affected test on unsupported devices.

EOS_BLACKLIST_CMDS

EOS_BLACKLIST_CMDS = ['^reload.*', '^conf.*', '^wr.*']

List of blacklisted EOS commands.

Disruptive commands safeguard

ANTA implements a mechanism to prevent the execution of disruptive commands such as reload, write erase or configure terminal.

KNOWN_EOS_ERRORS

KNOWN_EOS_ERRORS = [
    "BGP inactive",
    "VRF '.*' is not active",
    ".* does not support IP",
    "IS-IS (.*) is disabled because: .*",
    "No source interface .*",
    ".*controller\\snot\\sready.*",
]

List of known EOS errors.

Generic EOS Error Handling

When catching these errors, ANTA will fail the affected test and reported the error message.