vitro 0.8.0__py3-none-any.whl

vitro/__init__.py

@@ -0,0 +1,13 @@
+"""Automated testing of network devices."""
+
+__version__ = "2025.12.17a0"
+
+from pluggy import HookimplMarker, HookspecMarker
+
+PROJECT_NAME = "vitro"
+
+hookspec = HookspecMarker(PROJECT_NAME)
+hookimpl = HookimplMarker(PROJECT_NAME)
+
+
+__all__ = ["hookimpl", "hookspec"]

vitro/configs/__init__.py

@@ -0,0 +1,8 @@
+"""Vitro configs package."""
+
+import json
+from pathlib import Path
+
+LOGGING_CONFIG = json.loads(
+    (Path(__file__).parent / "logging.json").read_text(encoding="utf-8"),
+)

vitro/configs/logging.json

@@ -0,0 +1,40 @@
+{
+    "disable_existing_loggers": true,
+    "formatters": {
+        "pexpect": {
+            "class": "logging.Formatter",
+            "format": "%(asctime)s %(levelname)-8s- %(message)-100s  (%(name)s)"
+        },
+        "root": {
+            "class": "logging.Formatter",
+            "format": "%(asctime)s %(levelname)-8s- %(message)-100s  (%(name)s:%(funcName)s:%(lineno)d)"
+        }
+    },
+    "handlers": {
+        "pexpect": {
+            "class": "logging.StreamHandler",
+            "formatter": "pexpect",
+            "stream": "ext://sys.stderr"
+        },
+        "root": {
+            "class": "logging.StreamHandler",
+            "formatter": "root",
+            "stream": "ext://sys.stderr"
+        }
+    },
+    "loggers": {
+        "pexpect": {
+            "handlers": [
+                "pexpect"
+            ],
+            "propagate": false
+        }
+    },
+    "root": {
+        "handlers": [
+            "root"
+        ],
+        "level": "DEBUG"
+    },
+    "version": 1
+}

vitro/devices/__init__.py

@@ -0,0 +1 @@
+"""Vitro devices package."""

vitro/devices/base_devices/__init__.py

@@ -0,0 +1,5 @@
+"""Vitro base devices package."""
+
+from vitro.devices.base_devices.vitro_device import VitroDevice
+
+__all__ = ["VitroDevice"]

vitro/devices/base_devices/vitro_device.py

@@ -0,0 +1,57 @@
+"""Vitro base device template."""
+
+from argparse import Namespace
+
+from vitro.libraries.vitro_pexpect import VitroPexpect
+from vitro.type_hints import DeviceConfigType
+
+
+class VitroDevice:
+    """Vitro base device which all devices inherit from."""
+
+    def __init__(self, config: DeviceConfigType, cmdline_args: Namespace) -> None:
+        """Initialize vitro base device.
+
+        :param config: device configuration
+        :param cmdline_args: command line arguments
+        """
+        self._config: DeviceConfigType = config
+        self._cmdline_args = cmdline_args
+
+    def _extract_property_value(self, property_name: str) -> str:
+        name = self._config.get(property_name)
+        if name is None:
+            msg = f"{property_name} is not set in the configuration: {self._config=}"
+            raise RuntimeError(msg)
+        return name
+
+    @property
+    def config(self) -> DeviceConfigType:
+        """Get device configuration.
+
+        :returns: device configuration
+        """
+        return self._config
+
+    @property
+    def device_name(self) -> str:
+        """Get name of the device.
+
+        :returns: device name
+        """
+        return self._extract_property_value("name")
+
+    @property
+    def device_type(self) -> str:
+        """Get type of the device.
+
+        :returns: device type
+        """
+        return self._extract_property_value("type")
+
+    def get_interactive_consoles(self) -> dict[str, VitroPexpect]:
+        """Get interactive consoles from device.
+
+        :returns: interactive consoles of the device
+        """
+        return {}

vitro/exceptions.py

@@ -0,0 +1,98 @@
+"""Vitro exceptions for all plugins and modules used by framework."""
+
+from typing import Any
+
+
+class VitroError(Exception):
+    """Base exception all vitro exceptions inherit from."""
+
+
+class ShellPromptUndefinedError(VitroError):
+    """Raise this when shell prompt is not defined."""
+
+
+class DeviceConnectionError(VitroError):
+    """Raise this on device connection error."""
+
+
+class SSHConnectionError(DeviceConnectionError):
+    """Raise this on SSH connection failure."""
+
+
+class SCPConnectionError(DeviceConnectionError):
+    """Raise this on SCP connection failure."""
+
+
+class EnvConfigError(VitroError):
+    """Raise this on environment configuration error."""
+
+
+class DeviceRequirementError(VitroError):
+    """Raise this on device requirement error."""
+
+
+class DeviceNotFoundError(VitroError):
+    """Raise this on device is not available."""
+
+
+class FileLockTimeoutError(VitroError):
+    """Raise this on file lock timeout."""
+
+
+class ConfigurationFailureError(VitroError):
+    """Raise this on device configuration failure."""
+
+
+class DeviceBootFailureError(VitroError):
+    """Raise this on device boot failure."""
+
+
+class TR069ResponseErrorError(VitroError):
+    """Raise this on TR069 response error."""
+
+
+class TR069FaultCodeError(VitroError):
+    """Raise this on TR069 response error."""
+
+    faultdict: dict[str, Any]
+
+
+class UseCaseFailureError(VitroError):
+    """Raise this on failures in use cases."""
+
+
+class NotSupportedError(VitroError):
+    """Raise this on feature not supported."""
+
+
+class SNMPError(VitroError):
+    """Raise this on any SNMP related error."""
+
+
+class VoiceError(VitroError):
+    """Raise this on any voice related errors."""
+
+
+# TODO: maybe move to testsuite
+class TeardownError(VitroError):
+    """Raise this on any test teardown failure."""
+
+
+class ContingencyCheckError(VitroError):
+    """Raise this on any contingency check failure."""
+
+
+class WifiError(VitroError):
+    """Raise this on any wifi related errors."""
+
+
+class MulticastError(VitroError):
+    """Raise this on any multicast related errors."""
+
+
+class CodeError(VitroError):
+    """Raise this if an code assert fails.
+
+    This exception is only meant for custom assert
+    clause used inside libraries.
+    """

vitro/libraries/__init__.py

@@ -0,0 +1 @@
+"""Vitro libraries package."""

vitro/libraries/connection_factory.py

@@ -0,0 +1,78 @@
+"""Connection decider module."""
+
+from typing import Any
+
+from vitro.exceptions import EnvConfigError
+from vitro.libraries.connections.ldap_authenticated_serial import (
+    LdapAuthenticatedSerial,
+)
+from vitro.libraries.connections.local_cmd import LocalCmd
+from vitro.libraries.connections.ser2net_connection import Ser2NetConnection
+from vitro.libraries.connections.serial_connection import SerialConnection
+from vitro.libraries.connections.ssh_connection import SSHConnection
+from vitro.libraries.connections.telnet import TelnetConnection
+from vitro.libraries.vitro_pexpect import VitroPexpect
+
+
+def connection_factory(
+    connection_type: str,
+    connection_name: str,
+    **kwargs: Any,  # noqa: ANN401
+) -> VitroPexpect:
+    """Return connection of given type.
+
+    :param connection_type: type of the connection
+    :param connection_name: name of the connection
+    :param kwargs: arguments to the connection
+    :returns: VitroPexpect: connection of given type
+    :raises EnvConfigError: when given connection type is not supported
+    """
+    connection_dispatcher = {
+        "ssh_connection": SSHConnection,
+        "authenticated_ssh": SSHConnection,
+        "ldap_authenticated_serial": LdapAuthenticatedSerial,
+        "local_cmd": LocalCmd,
+        "serial": SerialConnection,
+        "ser2net": _ser2net_param_parser,
+        "telnet": _telnet_param_parser,
+    }
+    connection_obj = connection_dispatcher.get(connection_type)
+    if connection_obj is not None and callable(connection_obj):
+        if connection_type == "ssh_connection":
+            kwargs.pop("password")
+        return connection_obj(connection_name, **kwargs)
+    # Handle unsupported connection types
+    msg = f"Unsupported connection type: {connection_type}"
+    raise EnvConfigError(msg)
+
+
+def _telnet_param_parser(
+    connection_name: str,
+    **kwargs: Any,  # noqa: ANN401
+) -> TelnetConnection:
+    return TelnetConnection(
+        session_name=connection_name,
+        command="telnet",
+        save_console_logs=kwargs.pop("save_console_logs"),
+        args=[
+            kwargs["ip_addr"],
+            kwargs["port"],
+            kwargs["shell_prompt"],
+        ],
+    )
+
+
+def _ser2net_param_parser(
+    connection_name: str,
+    **kwargs: Any,  # noqa: ANN401
+) -> Ser2NetConnection:
+    return Ser2NetConnection(
+        connection_name,
+        "telnet",
+        kwargs["save_console_logs"],
+        [
+            kwargs["ip_addr"],
+            kwargs["port"],
+            kwargs["shell_prompt"],
+        ],
+    )

vitro/libraries/connections/__init__.py

@@ -0,0 +1 @@
+"""Vitro connections package."""

vitro/libraries/connections/connect_and_run.py

@@ -0,0 +1,70 @@
+"""Connect and run module."""
+
+from collections.abc import Callable
+from time import sleep
+from typing import ParamSpec, Protocol, TypeVar, runtime_checkable
+
+from vitro.exceptions import DeviceConnectionError
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+@runtime_checkable
+class RuntimeConnectable(Protocol):
+    """Runtine connectable protocol class."""
+
+    def connect_console(self) -> None:
+        """Connect to the console."""
+
+    def disconnect_console(self) -> None:
+        """Disconnect from the console."""
+
+    def is_console_connected(self) -> bool:
+        """Get status of the connection."""
+
+
+def connect_and_run(func: Callable[P, T]) -> Callable[P, T]:
+    """Connect run and disconnect to console at runtime.
+
+    Note: This is implemented only for instance methods
+
+    :param func: the decorated method
+    :return: True or False
+    :rtype: Callable[P, T]
+    """
+
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        instance = args[0]
+        exc_to_raise = None
+        if not isinstance(instance, RuntimeConnectable):
+            msg = (
+                f"Provided instance {instance} do not ,"
+                f"follows the protocol RuntimeConnectable .i.e {RuntimeConnectable}"
+            )
+            raise TypeError(msg)
+
+        if not instance.is_console_connected():
+            # Adding a retry
+            for _ in range(10):
+                try:
+                    instance.connect_console()
+                    break
+                except DeviceConnectionError:
+                    sleep(15)
+                    raise
+            else:
+                raise DeviceConnectionError
+
+        try:
+            output = func(*args, **kwargs)
+        except Exception as e:  # noqa: BLE001 pylint: disable=W0718
+            exc_to_raise = e
+        finally:
+            if instance.is_console_connected():
+                instance.disconnect_console()
+        if exc_to_raise:
+            raise exc_to_raise
+        return output
+
+    return wrapper

vitro/libraries/connections/ldap_authenticated_serial.py

@@ -0,0 +1,122 @@
+"""SSH connection module."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pexpect
+
+from vitro.exceptions import DeviceConnectionError
+from vitro.libraries.connections.ssh_connection import SSHConnection
+
+if TYPE_CHECKING:
+    from pexpect.spawnbase import _InputRePattern
+
+_CONNECTION_FAILED_STR: str = "Failed to connect to device via serial"
+_EOF_INDEX = 2
+
+
+class LdapAuthenticatedSerial(SSHConnection):
+    """Connect to a serial with ldap credentials."""
+
+    def __init__(  # noqa: PLR0913
+        self,
+        name: str,
+        ip_addr: str,
+        ldap_credentials: str,
+        shell_prompt: list[_InputRePattern],
+        port: int = 22,
+        save_console_logs: str = "",
+        **kwargs: dict[str, Any],  # ignore other arguments  # noqa: ARG002
+    ) -> None:
+        """Initialize ldap authenticated serial connection.
+
+        :param name: connection name
+        :type name: str
+        :param ip_addr: server ip address
+        :type ip_addr: str
+        :param ldap_credentials: ldap credentials
+        :type ldap_credentials: str
+        :param shell_prompt: shell prompt patterns
+        :type shell_prompt: list[str]
+        :param port: port number, defaults to 22
+        :type port: int
+        :param save_console_logs: save console logs to disk, defaults to ""
+        :type save_console_logs: str
+        :param kwargs: other keyword arguments
+        :raises ValueError: invalid LDAP credentials
+        """
+        if ";" not in ldap_credentials:
+            msg = "Invalid LDAP credentials"
+            raise ValueError(msg)
+        username, password = ldap_credentials.split(";")
+        super().__init__(
+            name,
+            ip_addr,
+            username,
+            shell_prompt,
+            port,
+            password,
+            save_console_logs,
+        )
+
+    def login_to_server(self, password: str | None = None) -> None:
+        """Login to serial server.
+
+        :param password: LDAP password
+        :type password: str
+        :raises DeviceConnectionError: failed to connect to device via serial
+        """
+        if password is None:
+            password = self._password
+        if self.expect(["Password:", pexpect.EOF, pexpect.TIMEOUT]):
+            raise DeviceConnectionError(_CONNECTION_FAILED_STR)
+        self.sendline(password)
+
+        if (
+            self.expect_exact(
+                ["OpenGear Serial Server", pexpect.TIMEOUT, pexpect.EOF],
+                timeout=10,
+            )
+            == _EOF_INDEX
+        ):
+            raise DeviceConnectionError(_CONNECTION_FAILED_STR)
+        # In case of SSH communication over different geological WAN:
+        # The SSH channel does not start to display data post connection.
+        # Instead the user needs to enter some key to refresh. e.g. ENTER
+        # This is generally due to poor connection.
+        # Providing a few input below and flushing the buffer after 5 sec.
+        self.sendline()
+        self.sendline()
+        self.expect(pexpect.TIMEOUT, timeout=5)
+
+    async def login_to_server_async(self, password: str | None = None) -> None:
+        """Login to serial server.
+
+        :param password: LDAP password
+        :type password: str
+        :raises DeviceConnectionError: failed to connect to device via serial
+        """
+        if password is None:
+            password = self._password
+        if await self.expect(["Password:", pexpect.EOF, pexpect.TIMEOUT], async_=True):
+            raise DeviceConnectionError(_CONNECTION_FAILED_STR)
+        self.sendline(password)
+
+        if (
+            await self.expect_exact(
+                ["OpenGear Serial Server", pexpect.TIMEOUT, pexpect.EOF],
+                timeout=10,
+                async_=True,
+            )
+            == _EOF_INDEX
+        ):
+            raise DeviceConnectionError(_CONNECTION_FAILED_STR)
+        # In case of SSH communication over different geological WAN:
+        # The SSH channel does not start to display data post connection.
+        # Instead the user needs to enter some key to refresh. e.g. ENTER
+        # This is generally due to poor connection.
+        # Providing a few input below and flushing the buffer after 5 sec.
+        self.sendline()
+        self.sendline()
+        await self.expect(pexpect.TIMEOUT, timeout=5, async_=True)

vitro/libraries/connections/local_cmd.py

@@ -0,0 +1,159 @@
+"""Connect to a device with a local command."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pexpect
+
+from vitro.exceptions import (
+    DeviceConnectionError,
+    ShellPromptUndefinedError,
+    VitroError,
+)
+from vitro.libraries.vitro_pexpect import VitroPexpect
+
+if TYPE_CHECKING:
+    from pexpect.spawnbase import _InputRePattern
+
+_CONNECTION_ERROR_THRESHOLD = 2
+_CONNECTION_FAILED_STR: str = "Connection failed with Local Command"
+
+
+class LocalCmd(VitroPexpect):
+    """Connect to a device with a local command."""
+
+    def __init__(  # pylint: disable=too-many-arguments  # noqa: PLR0913
+        self,  # pylint: disable=unused-argument
+        name: str,
+        conn_command: str,
+        save_console_logs: str,
+        shell_prompt: list[_InputRePattern] | None = None,
+        args: list[str] | None = None,
+        *,
+        username: str = "root",
+        password: str | None = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> None:
+        """Initialize local command connection.
+
+        :param name: connection name
+        :type name: str
+        :param conn_command: command to start the session
+        :type conn_command: str
+        :param save_console_logs: save console logs to disk
+        :type save_console_logs: str
+        :param shell_prompt: shell prompt pattern, defaults to None
+        :type shell_prompt: list[str]
+        :param args: arguments to the command, defaults to None
+        :type args: list[str], optional
+        :param username: effective user inside the local command session.
+            Defaults to ``"root"``, matching the default ``docker exec``
+            behaviour.  Set when the local command launches as a
+            non-root user (e.g. ``docker exec --user alice ...``) so
+            :meth:`sudo_sendline` knows whether escalation is required.
+        :type username: str
+        :param password: password used for sudo escalation when
+            ``username != "root"``.  Required only when the sudoers
+            policy prompts for one; may be ``None`` for NOPASSWD
+            configurations.
+        :type password: str | None
+        :param kwargs: additional keyword args
+        """
+        self._shell_prompt = shell_prompt
+        self._username = username
+        self._password = password
+        if args is None:
+            args = []
+        super().__init__(
+            name,
+            conn_command,
+            save_console_logs,
+            args,
+            **kwargs,
+        )
+
+    # pylint: disable=duplicate-code
+    def login_to_server(self, password: str | None = None) -> None:
+        """Login.
+
+        :param password: ssh password
+        :raises DeviceConnectionError: connection failed via local command
+        :raises ValueError: if shell prompt is unavailable
+        """
+        if password is not None:
+            if self.expect(
+                ["password:", pexpect.EOF, pexpect.TIMEOUT],
+            ):
+                raise DeviceConnectionError(_CONNECTION_FAILED_STR)
+            self.sendline(password)
+        # TODO: temp fix for now. To be decided if shell prompt to be used.
+        if not self._shell_prompt:
+            raise ShellPromptUndefinedError
+        if (
+            self.expect(
+                [
+                    pexpect.EOF,
+                    pexpect.TIMEOUT,
+                    *self._shell_prompt,
+                ],
+            )
+            < _CONNECTION_ERROR_THRESHOLD
+        ):
+            raise DeviceConnectionError(_CONNECTION_FAILED_STR)
+
+    def execute_command(self, command: str, timeout: int = -1) -> str:
+        """Execute a command in the local command session.
+
+        :param command: command to execute
+        :param timeout: timeout in seconds. defaults to -1
+        :returns: command output
+        :raises ValueError: if shell prompt is unavailable
+        """
+        if not self._shell_prompt:
+            raise ShellPromptUndefinedError
+        self.sendline(command)
+        self.expect_exact(command)
+        self.expect(self.linesep)
+        # TODO: is this needed? is the shell prompt of Local(Jenkins or any user)?
+        self.expect(self._shell_prompt, timeout=timeout)
+        return self.get_last_output()
+
+    def sudo_sendline(self, cmd: str) -> None:
+        """Add sudo in the sendline if username is not root.
+
+        Mirrors :meth:`SSHConnection.sudo_sendline`: when ``_username``
+        is not ``"root"``, prime sudo with ``sudo true``, supply
+        ``_password`` if sudo prompts for one, then send the command
+        prefixed with ``sudo``.  For ``_username == "root"`` the method
+        collapses to a plain :meth:`sendline` — identical to the root
+        branch of :class:`SSHConnection`.
+
+        :param cmd: command to send
+        :raises VitroError: if sudo prompts for a password but none was
+            configured on the connection.
+        :raises ShellPromptUndefinedError: if no shell prompt was
+            configured on the connection.
+        """
+        if not self._shell_prompt:
+            raise ShellPromptUndefinedError
+        if self._username != "root":
+            self.sendline("sudo true")
+            password_requested = self.expect(
+                [*self._shell_prompt, "password for .*:", "Password:"],
+            )
+            if password_requested:
+                if self._password is None:
+                    msg = (
+                        "sudo prompted for a password but none was configured "
+                        f"for LocalCmd (username={self._username!r}). "
+                        "Supply a password at construction time or use a "
+                        "NOPASSWD sudoers entry for this user."
+                    )
+                    raise VitroError(msg)
+                self.sendline(self._password)
+                self.expect(self._shell_prompt)
+            cmd = "sudo " + cmd
+        self.sendline(cmd)
+
+    # pylint: enable=duplicate-code