arista/aio-eapi
1
0
Fork 0
Code Issues Activity

Adding upstream version 0.6.3.

Browse source 
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
Daniel Baumann 2025-02-05 10:27:41 +01:00
parent 4a6dd5e474
commit 341025cc97
Signed by: daniel
GPG key ID: FBB4F0E80A80222F
11 changed files with 1078 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

3
aioeapi/__init__.py Normal file
View file

@ -0,0 +1,3 @@
from .device import Device
from .errors import EapiCommandError
from .config_session import SessionConfig

56
aioeapi/aio_portcheck.py Normal file
View file

@ -0,0 +1,56 @@
# -----------------------------------------------------------------------------
# System Imports
# -----------------------------------------------------------------------------
from typing import Optional
import socket
import asyncio
# -----------------------------------------------------------------------------
# Public Imports
# -----------------------------------------------------------------------------
from httpx import URL
# -----------------------------------------------------------------------------
# Exports
# -----------------------------------------------------------------------------
__all__ = ["port_check_url"]
# -----------------------------------------------------------------------------
#
# CODE BEGINS
#
# -----------------------------------------------------------------------------
async def port_check_url(url: URL, timeout: Optional[int] = 5) -> bool:
"""
This function attempts to open the port designated by the URL given the
timeout in seconds. If the port is avaialble then return True; False
otherwise.
Parameters
----------
url:
The URL that provides the target system
timeout: optional, default is 5 seonds
Time to await for the port to open in seconds
"""
port = url.port or socket.getservbyname(url.scheme)
try:
wr: asyncio.StreamWriter
_, wr = await asyncio.wait_for(
asyncio.open_connection(host=url.host, port=port), timeout=timeout
)
# MUST close if opened!
wr.close()
return True
except Exception: # noqa
return False

259
aioeapi/config_session.py Normal file
View file

@ -0,0 +1,259 @@
# -----------------------------------------------------------------------------
# System Imports
# -----------------------------------------------------------------------------
import re
from typing import Optional, TYPE_CHECKING, Union, List
if TYPE_CHECKING:
from .device import Device
# -----------------------------------------------------------------------------
# Exports
# -----------------------------------------------------------------------------
__all__ = ["SessionConfig"]
# -----------------------------------------------------------------------------
#
# CODE BEGINS
#
# -----------------------------------------------------------------------------
class SessionConfig:
"""
The SessionConfig instance is used to send configuration to a device using
the EOS session mechanism. This is the preferred way of managing
configuraiton changes.
Notes
-----
This class definition is used by the parent Device class definition as
defined by `config_session`. A Caller can use the SessionConfig directly
as well, but it is not required.
"""
CLI_CFG_FACTORY_RESET = "rollback clean-config"
def __init__(self, device: "Device", name: str):
"""
Creates a new instance of the session config instance bound
to the given device instance, and using the session `name`.
Parameters
----------
device:
The associated device instance
name:
The name of the config session
"""
self._device = device
self._cli = device.cli
self._name = name
self._cli_config_session = f"configure session {self.name}"
# -------------------------------------------------------------------------
# properties for read-only attributes
# -------------------------------------------------------------------------
@property
def name(self) -> str:
"""returns read-only session name attribute"""
return self._name
@property
def device(self) -> "Device":
"""returns read-only device instance attribute"""
return self._device
# -------------------------------------------------------------------------
# Public Methods
# -------------------------------------------------------------------------
async def status_all(self) -> dict:
"""
Get the status of the session config by running the command:
# show configuration sessions detail
Returns
-------
dict object of native EOS eAPI response; see `status` method for
details.
"""
return await self._cli("show configuration sessions detail")
async def status(self) -> Union[dict, None]:
"""
Get the status of the session config by running the command:
# show configuration sessions detail
And returning only the status dictionary for this session. If you want
all sessions, then use the `status_all` method.
Returns
-------
Dict instance of the session status. If the session does not exist,
then this method will return None.
The native eAPI results from JSON output, see exmaple:
Examples
--------
all results:
{
"maxSavedSessions": 1,
"maxOpenSessions": 5,
"sessions": {
"jeremy1": {
"instances": {},
"state": "pending",
"commitUser": "",
"description": ""
},
"ansible_167510439362": {
"instances": {},
"state": "completed",
"commitUser": "joe.bob",
"description": "",
"completedTime": 1675104396.4500246
}
}
}
if the session name was 'jeremy1', then this method would return
{
"instances": {},
"state": "pending",
"commitUser": "",
"description": ""
}
"""
res = await self.status_all()
return res["sessions"].get(self.name)
async def push(
self, content: Union[List[str], str], replace: Optional[bool] = False
):
"""
Sends the configuration content to the device. If `replace` is true,
then the command "rollback clean-config" is issued before sendig the
configuration content.
Parameters
----------
content: Union[List[str], str]
The text configuration CLI commands, as a list of strings, that
will be sent to the device. If the parameter is a string, and not
a list, then split the string across linebreaks. In either case
any empty lines will be discarded before they are send to the
device.
replace: bool
When True, the content will replace the existing configuration
on the device.
"""
# if given s string, we need to break it up into individual command
# lines.
if isinstance(content, str):
content = content.splitlines()
# prepare the initial set of command to enter the config session and
# rollback clean if the `replace` argument is True.
commands = [self._cli_config_session]
if replace:
commands.append(self.CLI_CFG_FACTORY_RESET)
# add the Caller's commands, filtering out any blank lines. any command
# lines (!) are still included.
commands.extend(filter(None, content))
await self._cli(commands=commands)
async def commit(self, timer: Optional[str] = None):
"""
Commits the session config using the commands
# configure session <name>
# commit
If the timer is specified, format is "hh:mm:ss", then a commit timer is
started. A second commit action must be made to confirm the config
session before the timer expires; otherwise the config-session is
automatically aborted.
"""
command = f"{self._cli_config_session} commit"
if timer:
command += f" timer {timer}"
await self._cli(command)
async def abort(self):
"""
Aborts the configuration session using the command:
# configure session <name> abort
"""
await self._cli(f"{self._cli_config_session} abort")
async def diff(self) -> str:
"""
Returns the "diff" of the session config relative to the running config, using
the command:
# show session-config named <name> diffs
Returns
-------
Returns a string in diff-patch format.
References
----------
* https://www.gnu.org/software/diffutils/manual/diffutils.txt
"""
return await self._cli(
f"show session-config named {self.name} diffs", ofmt="text"
)
async def load_scp_file(self, filename: str, replace: Optional[bool] = False):
"""
This function is used to load the configuration from <filename> into
the session configuration. If the replace parameter is True then the
file contents will replace the existing session config (load-replace).
Parameters
----------
filename:
The name of the configuration file. The caller is required to
specify the filesystem, for exmaple, the
filename="flash:thisfile.cfg"
replace:
When True, the contents of the file will completely replace the
session config for a load-replace behavior.
Raises
-------
If there are any issues with loading the configuration file then a
RuntimeError is raised with the error messages content.
"""
commands = [self._cli_config_session]
if replace:
commands.append(self.CLI_CFG_FACTORY_RESET)
commands.append(f"copy {filename} session-config")
res = await self._cli(commands=commands)
checks_re = re.compile(r"error|abort|invalid", flags=re.I)
messages = res[-1]["messages"]
if any(map(checks_re.search, messages)):
raise RuntimeError("".join(messages))
async def write(self):
"""
Saves the running config to the startup config by issuing the command
"write" to the device.
"""
await self._cli("write")

283
aioeapi/device.py Normal file
View file

@ -0,0 +1,283 @@
# -----------------------------------------------------------------------------
# System Imports
# -----------------------------------------------------------------------------
from typing import Optional, List, Union, Dict, AnyStr
from socket import getservbyname
# -----------------------------------------------------------------------------
# Public Imports
# -----------------------------------------------------------------------------
import httpx
# -----------------------------------------------------------------------------
# Private Imports
# -----------------------------------------------------------------------------
from .aio_portcheck import port_check_url
from .errors import EapiCommandError
from .config_session import SessionConfig
# -----------------------------------------------------------------------------
# Exports
# -----------------------------------------------------------------------------
__all__ = ["Device"]
# -----------------------------------------------------------------------------
#
# CODE BEGINS
#
# -----------------------------------------------------------------------------
class Device(httpx.AsyncClient):
"""
The Device class represents the async JSON-RPC client that communicates with
an Arista EOS device. This class inherits directly from the
httpx.AsyncClient, so any initialization options can be passed directly.
"""
auth = None
EAPI_OFMT_OPTIONS = ("json", "text")
EAPI_DEFAULT_OFMT = "json"
def __init__(
self,
host: Optional[str] = None,
username: Optional[str] = None,
password: Optional[str] = None,
proto: Optional[str] = "https",
port=None,
**kwargs,
):
"""
Initializes the Device class. As a subclass to httpx.AsyncClient, the
Caller can provide any of those initializers. Specific paramertes for
Device class are all optional and described below.
Parameters
----------
host: Optional[str]
The EOS target device, either hostname (DNS) or ipaddress.
username: Optional[str]
The login user-name; requires the password parameter.
password: Optional[str]
The login password; requires the username parameter.
proto: Optional[str]
The protocol, http or https, to communicate eAPI with the device.
port: Optional[Union[str,int]]
If not provided, the proto value is used to look up the associated
port (http=80, https=443). If provided, overrides the port used to
communite with the device.
Other Parameters
----------------
base_url: str
If provided, the complete URL to the device eAPI endpoint.
auth:
If provided, used as the httpx authorization initializer value. If
not provided, then username+password is assumed by the Caller and
used to create a BasicAuth instance.
"""
self.port = port or getservbyname(proto)
self.host = host
kwargs.setdefault("base_url", httpx.URL(f"{proto}://{self.host}:{self.port}"))
kwargs.setdefault("verify", False)
if username and password:
self.auth = httpx.BasicAuth(username, password)
kwargs.setdefault("auth", self.auth)
super(Device, self).__init__(**kwargs)
self.headers["Content-Type"] = "application/json-rpc"
async def check_connection(self) -> bool:
"""
This function checks the target device to ensure that the eAPI port is
open and accepting connections. It is recommended that a Caller checks
the connection before involing cli commands, but this step is not
required.
Returns
-------
True when the device eAPI is accessible, False otherwise.
"""
return await port_check_url(self.base_url)
async def cli(
self,
command: Optional[AnyStr] = None,
commands: Optional[List[AnyStr]] = None,
ofmt: Optional[str] = None,
suppress_error: Optional[bool] = False,
version: Optional[Union[int, str]] = "latest",
**kwargs,
):
"""
Execute one or more CLI commands.
Parameters
----------
command: str
A single command to execute; results in a single output response
commands: List[str]
A list of commands to execute; results in a list of output responses
ofmt: str
Either 'json' or 'text'; indicates the output fromat for the CLI commands.
suppress_error: Optional[bool] = False
When not False, then if the execution of the command would-have
raised an EapiCommandError, rather than raising this exception this
routine will return the value None.
For example, if the following command had raised
EapiCommandError, now response would be set to None instead.
response = dev.cli(..., suppress_error=True)
version: Optional[int | string]
By default the eAPI will use "version 1" for all API object models.
This driver will, by default, always set version to "latest" so
that the behavior matches the CLI of the device. The caller can
override the "latest" behavior by explicity setting the version.
Other Parameters
----------------
autoComplete: Optional[bool] = False
Enabled/disables the command auto-compelete feature of the EAPI. Per the
documentation:
Allows users to use shorthand commands in eAPI calls. With this
parameter included a user can send 'sh ver' via eAPI to get the
output of 'show version'.
expandAliases: Optional[bool] = False
Enables/disables the command use of User defined alias. Per the
documentation:
Allowed users to provide the expandAliases parameter to eAPI
calls. This allows users to use aliased commands via the API.
For example if an alias is configured as 'sv' for 'show version'
then an API call with sv and the expandAliases parameter will
return the output of show version.
Returns
-------
One or List of output respones, per the description above.
"""
if not any((command, commands)):
raise RuntimeError("Required 'command' or 'commands'")
jsonrpc = self.jsoncrpc_command(
commands=[command] if command else commands,
ofmt=ofmt,
version=version,
**kwargs,
)
try:
res = await self.jsonrpc_exec(jsonrpc)
return res[0] if command else res
except EapiCommandError as eapi_error:
if suppress_error:
return None
raise eapi_error
def jsoncrpc_command(self, commands, ofmt, version, **kwargs) -> dict:
"""Used to create the JSON-RPC command dictionary object"""
cmd = {
"jsonrpc": "2.0",
"method": "runCmds",
"params": {
"version": version,
"cmds": commands,
"format": ofmt or self.EAPI_DEFAULT_OFMT,
},
"id": str(kwargs.get("req_id") or id(self)),
}
if "autoComplete" in kwargs:
cmd["params"]["autoComplete"] = kwargs["autoComplete"]
if "expandAliases" in kwargs:
cmd["params"]["expandAliases"] = kwargs["expandAliases"]
return cmd
async def jsonrpc_exec(self, jsonrpc: dict) -> List[Union[Dict, AnyStr]]:
"""
Execute the JSON-RPC dictionary object.
Parameters
----------
jsonrpc: dict
The JSON-RPC as created by the `meth`:jsonrpc_command().
Raises
------
EapiCommandError
In the event that a command resulted in an error response.
Returns
-------
The list of command results; either dict or text depending on the
JSON-RPC format pameter.
"""
res = await self.post("/command-api", json=jsonrpc)
res.raise_for_status()
body = res.json()
commands = jsonrpc["params"]["cmds"]
ofmt = jsonrpc["params"]["format"]
get_output = (lambda _r: _r["output"]) if ofmt == "text" else (lambda _r: _r)
# if there are no errors then return the list of command results.
if (err_data := body.get("error")) is None:
return [get_output(cmd_res) for cmd_res in body["result"]]
# ---------------------------------------------------------------------
# if we are here, then there were some command errors. Raise a
# EapiCommandError exception with args (commands that failed, passed,
# not-executed).
# ---------------------------------------------------------------------
cmd_data = err_data["data"]
len_data = len(cmd_data)
err_at = len_data - 1
err_msg = err_data["message"]
raise EapiCommandError(
passed=[
get_output(cmd_data[cmd_i])
for cmd_i, cmd in enumerate(commands[:err_at])
],
failed=commands[err_at],
errmsg=err_msg,
not_exec=commands[err_at + 1 :],
)
def config_session(self, name: str) -> SessionConfig:
"""
Factory method that returns a SessionConfig instance bound to this
device with the given session name.
Parameters
----------
name:
The config-session name
"""
return SessionConfig(self, name)

30
aioeapi/errors.py Normal file
View file

@ -0,0 +1,30 @@
import httpx
class EapiCommandError(RuntimeError):
"""
Exception class for EAPI command errors
Attributes
----------
failed: str - the failed command
errmsg: str - a description of the failure reason
passed: List[dict] - a list of command results of the commands that passed
not_exec: List[str] - a list of commands that were not executed
"""
def __init__(self, failed: str, errmsg: str, passed, not_exec):
"""Initializer for the EapiCommandError exception"""
self.failed = failed
self.errmsg = errmsg
self.passed = passed
self.not_exec = not_exec
super(EapiCommandError, self).__init__()
def __str__(self):
"""returns the error message associated with the exception"""
return self.errmsg
# alias for exception during sending-receiving
EapiTransportError = httpx.HTTPStatusError