scrapli 2.0.0a2__py3-none-musllinux_1_1_aarch64.whl

scrapli/cli_decorators.py

@@ -0,0 +1,148 @@
+"""scrapli.cli_decorators"""
+
+from collections.abc import Awaitable, Callable
+from ctypes import c_uint64
+from functools import update_wrapper
+from typing import TYPE_CHECKING, Concatenate, ParamSpec
+
+from scrapli.cli_result import Result
+from scrapli.exceptions import OptionsException
+
+if TYPE_CHECKING:
+    from scrapli.cli import Cli
+
+P = ParamSpec("P")
+
+
+def handle_operation_timeout(
+    wrapped: Callable[Concatenate["Cli", P], Result],
+) -> Callable[Concatenate["Cli", P], Result]:
+    """
+    Wraps a Cli operation and sets the timeout value for the duration of the operation.
+
+    Args:
+        wrapped: the operation function
+
+    Returns:
+        callable: the wrapper function
+
+    Raises:
+        N/A
+
+    """
+
+    def wrapper(inst: "Cli", /, *args: P.args, **kwargs: P.kwargs) -> Result:
+        """
+        The operation timeout wrapper.
+
+        Args:
+            inst: the Cli instance
+            args: the arguments to pass to the wrapped function
+            kwargs: the keyword arguments to pass to the wrapped function
+
+        Returns:
+            Result: the result of the wrapped function
+
+        Raises:
+            OptionsException: if the operation timeout failed to set
+
+        """
+        operation_timeout_ns = kwargs.get("operation_timeout_ns")
+        if operation_timeout_ns is None:
+            return wrapped(inst, *args, **kwargs)
+
+        if operation_timeout_ns == inst.session_options.operation_timeout_ns:
+            return wrapped(inst, *args, **kwargs)
+
+        if not isinstance(operation_timeout_ns, int):
+            # ignore an invalid type for the timeout
+            return wrapped(inst, *args, **kwargs)
+
+        status = inst.ffi_mapping.options_mapping.session.set_operation_timeout_ns(
+            inst._ptr_or_exception(),
+            c_uint64(operation_timeout_ns),
+        )
+        if status != 0:
+            raise OptionsException("failed to set session operation timeout")
+
+        res = wrapped(inst, *args, **kwargs)
+
+        status = inst.ffi_mapping.options_mapping.session.set_operation_timeout_ns(
+            inst._ptr_or_exception(),
+            c_uint64(operation_timeout_ns),
+        )
+        if status != 0:
+            raise OptionsException("failed to set session operation timeout")
+
+        return res
+
+    update_wrapper(wrapper=wrapper, wrapped=wrapped)
+
+    return wrapper
+
+
+def handle_operation_timeout_async(
+    wrapped: Callable[Concatenate["Cli", P], Awaitable[Result]],
+) -> Callable[Concatenate["Cli", P], Awaitable[Result]]:
+    """
+    Wraps a Cli operation and sets the timeout value for the duration of the operation.
+
+    Args:
+        wrapped: the operation function
+
+    Returns:
+        callable: the wrapper function
+
+    Raises:
+        N/A
+
+    """
+
+    async def wrapper(inst: "Cli", /, *args: P.args, **kwargs: P.kwargs) -> Result:
+        """
+        The operation timeout wrapper.
+
+        Args:
+            inst: the Cli instance
+            args: the arguments to pass to the wrapped function
+            kwargs: the keyword arguments to pass to the wrapped function
+
+        Returns:
+            Result: the result of the wrapped function
+
+        Raises:
+            OptionsException: if the operation timeout failed to set
+
+        """
+        operation_timeout_ns = kwargs.get("operation_timeout_ns")
+        if operation_timeout_ns is None:
+            return await wrapped(inst, *args, **kwargs)
+
+        if operation_timeout_ns == inst.session_options.operation_timeout_ns:
+            return await wrapped(inst, *args, **kwargs)
+
+        if not isinstance(operation_timeout_ns, int):
+            # ignore an invalid type for the timeout
+            return await wrapped(inst, *args, **kwargs)
+
+        status = inst.ffi_mapping.options_mapping.session.set_operation_timeout_ns(
+            inst._ptr_or_exception(),
+            c_uint64(operation_timeout_ns),
+        )
+        if status != 0:
+            raise OptionsException("failed to set session operation timeout")
+
+        res = await wrapped(inst, *args, **kwargs)
+
+        status = inst.ffi_mapping.options_mapping.session.set_operation_timeout_ns(
+            inst._ptr_or_exception(),
+            c_uint64(operation_timeout_ns),
+        )
+        if status != 0:
+            raise OptionsException("failed to set session operation timeout")
+
+        return res
+
+    update_wrapper(wrapper=wrapper, wrapped=wrapped)
+
+    return wrapper

scrapli/cli_parse.py

@@ -0,0 +1,161 @@
+"""cli_parse"""
+
+import urllib.request
+from importlib import import_module, resources
+from io import BytesIO, TextIOWrapper
+from logging import getLogger
+from typing import Any, TextIO
+
+from scrapli.exceptions import ParsingException
+
+logger = getLogger(__name__)
+
+
+def textfsm_get_template(platform: str, command: str) -> TextIO | None:
+    """
+    Find correct TextFSM template based on platform and command executed
+
+    Args:
+        platform: ntc-templates device type; i.e. cisco_ios, arista_eos, etc.
+        command: string of command that was executed (to find appropriate template)
+
+    Returns:
+        None or TextIO of opened template
+
+    Raises:
+        N/A
+
+    """
+    try:
+        import_module(name=".templates", package="ntc_templates")
+        cli_table_obj = getattr(import_module(name=".clitable", package="textfsm"), "CliTable")
+    except ModuleNotFoundError as exc:
+        raise ParsingException("optional extra 'textfsm' not found") from exc
+
+    template_dir = f"{resources.files('ntc_templates')}/templates"
+
+    cli_table = cli_table_obj("index", template_dir)
+    template_index = cli_table.index.GetRowMatch({"Platform": platform, "Command": command})
+
+    if not template_index:
+        logger.warning(
+            f"No match in ntc_templates index for platform `{platform}` and command `{command}`"
+        )
+        return None
+
+    template_name = cli_table.index.index[template_index]["Template"]
+
+    return open(f"{template_dir}/{template_name}", encoding="utf-8")
+
+
+def _textfsm_to_dict(
+    structured_output: list[Any] | dict[str, Any], header: list[str]
+) -> list[Any] | dict[str, Any]:
+    """
+    Create list of dicts from textfsm output and header
+
+    Args:
+        structured_output: parsed textfsm output
+        header: list of strings representing column headers for textfsm output
+
+    Returns:
+        output: structured data
+
+    Raises:
+        N/A
+
+    """
+    logger.debug("converting textfsm output to dictionary representation")
+
+    header_lower = [h.lower() for h in header]
+    structured_output = [dict(zip(header_lower, row)) for row in structured_output]
+
+    return structured_output
+
+
+def textfsm_parse(
+    template: str | TextIO, output: str, to_dict: bool = True
+) -> list[Any] | dict[str, Any]:
+    """
+    Parse output with TextFSM and ntc-templates, try to return structured output
+
+    Args:
+        template: TextIO or string of URL or filesystem path to template to use to parse data
+        output: unstructured output from device to parse
+        to_dict: convert textfsm output from list of lists to list of dicts -- basically create dict
+            from header and row data so it is easier to read/parse the output
+
+    Returns:
+        output: structured data
+
+    Raises:
+        ScrapliException: If raise_err is set and a textfsm parsing error occurs, raises from the
+            originating textfsm.parser.TextFSMError exception.
+
+    """
+    import textfsm
+
+    if isinstance(template, str):
+        if template.startswith("http://") or template.startswith("https://"):
+            with urllib.request.urlopen(template) as response:
+                re_table = textfsm.TextFSM(
+                    TextIOWrapper(
+                        BytesIO(response.read()),
+                        encoding=response.headers.get_content_charset(),
+                    )
+                )
+        else:
+            re_table = textfsm.TextFSM(open(template, mode="rb"))
+    else:
+        re_table = textfsm.TextFSM(template)
+
+    try:
+        structured_output: list[Any] | dict[str, Any] = re_table.ParseText(output)
+
+        if to_dict:
+            structured_output = _textfsm_to_dict(
+                structured_output=structured_output, header=re_table.header
+            )
+
+        return structured_output
+    except textfsm.parser.TextFSMError as exc:
+        raise ParsingException("failed parsing output with 'textfsm'") from exc
+
+    return []
+
+
+def genie_parse(platform: str, command: str, output: str) -> list[Any] | dict[str, Any]:
+    """
+    Parse output with Cisco genie parsers, try to return structured output
+
+    Args:
+        platform: genie device type; i.e. iosxe, iosxr, etc.
+        command: string of command that was executed (to find appropriate parser)
+        output: unstructured output from device to parse
+
+    Returns:
+        output: structured data
+
+    Raises:
+        N/A
+
+    """
+    try:
+        device = getattr(import_module(name=".conf.base", package="genie"), "Device")
+        get_parser = getattr(
+            import_module(name=".libs.parser.utils", package="genie"), "get_parser"
+        )
+    except ModuleNotFoundError as exc:
+        raise ParsingException("optional extra 'genie' not found") from exc
+
+    genie_device = device("scrapli_device", custom={"abstraction": {"order": ["os"]}}, os=platform)
+
+    try:
+        get_parser(command, genie_device)
+        genie_parsed_result = genie_device.parse(command, output=output)
+        if isinstance(genie_parsed_result, list | dict):
+            return genie_parsed_result
+    except Exception as exc:
+        raise ParsingException("failed parsing output with 'genie'") from exc
+
+    return []

scrapli/cli_result.py

@@ -0,0 +1,197 @@
+"""scrapli.result"""
+
+from typing import Any, TextIO
+
+from scrapli.cli_parse import genie_parse, textfsm_get_template, textfsm_parse
+from scrapli.exceptions import ParsingException
+
+OPERATION_DELIMITER = "__libscrapli__"
+
+
+class Result:
+    """
+    Result represents a set of results from some Cli operation(s).
+
+    Args:
+        N/A
+
+    Returns:
+        None
+
+    Raises:
+        N/A
+
+    """
+
+    def __init__(  # noqa: PLR0913
+        self,
+        *,
+        host: str,
+        port: int,
+        inputs: str,
+        start_time: int,
+        splits: list[int],
+        results_raw: bytes,
+        results: str,
+        results_failed_indicator: str,
+        textfsm_platform: str,
+        genie_platform: str,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.inputs = inputs.split(OPERATION_DELIMITER)
+        self.start_time = start_time
+        self.splits = splits
+        self.results_raw = results_raw.split(OPERATION_DELIMITER.encode())
+        self.results = results.split(OPERATION_DELIMITER)
+        self.results_failed_indicator = results_failed_indicator
+        self.textfsm_platform = textfsm_platform
+        self.genie_platform = genie_platform
+
+    def extend(self, result: "Result") -> None:
+        """
+        Extends this Result object with another Result object.
+
+        Args:
+            result: the result object with which to extend this result object
+
+        Returns:
+            N/A
+
+        Raises:
+            N/A
+
+        """
+        self.inputs.extend(result.inputs)
+        self.results_raw.extend(result.results_raw)
+        self.results.extend(result.results)
+        self.splits.extend(result.splits)
+
+    @property
+    def failed(self) -> bool:
+        """
+        Returns True if any failed indicators were seen, otherwise False.
+
+        Args:
+            N/A
+
+        Returns:
+            bool: True for failed, otherwise False
+
+        Raises:
+            N/A
+
+        """
+        return bool(self.results_failed_indicator)
+
+    @property
+    def end_time(self) -> int:
+        """
+        Returns the end time of the operations in unix nano.
+
+        Args:
+            N/A
+
+        Returns:
+            int: end time in unix nano
+
+        Raises:
+            N/A
+
+        """
+        if not self.splits:
+            # if we had no splits it was a "noop" type op (like enter mode when
+            # you are already in the requested mode), so we'll lie and say it
+            # was a 1ns op time
+            return self.start_time + 1
+
+        return self.splits[-1]
+
+    @property
+    def elapsed_time_seconds(self) -> float:
+        """
+        Returns the number of seconds the operation took.
+
+        Args:
+            N/A
+
+        Returns:
+            float: duration in seconds
+
+        Raises:
+            N/A
+
+        """
+        return (self.end_time - self.start_time) / 1_000_000_000
+
+    @property
+    def result(self) -> str:
+        """
+        Returns the results joined on newline chars. Note this does *not* include inputs sent.
+
+        Args:
+            N/A
+
+        Returns:
+            str: joined results
+
+        Raises:
+            N/A
+
+        """
+        return "\n".join(self.results)
+
+    def textfsm_parse(
+        self,
+        index: int = 0,
+        template: str | TextIO | None = None,
+        to_dict: bool = True,
+    ) -> list[Any] | dict[str, Any]:
+        """
+        Parse results with textfsm, always return structured data
+
+        Returns an empty list if parsing fails!
+
+        Args:
+            index: the index of the result to parse, assumes first/zeroith if not provided
+            template: string path to textfsm template or opened textfsm template file
+            to_dict: convert textfsm output from list of lists to list of dicts -- basically create
+                dict from header and row data so it is easier to read/parse the output
+
+        Returns:
+            structured_result: empty list or parsed data from textfsm
+
+        Raises:
+            N/A
+
+        """
+        if template is None:
+            template = textfsm_get_template(
+                platform=self.textfsm_platform, command=self.inputs[index]
+            )
+
+        if template is None:
+            raise ParsingException("no template provided or available for input")
+
+        return textfsm_parse(template=template, output=self.result, to_dict=to_dict)
+
+    def genie_parse(
+        self,
+        index: int = 0,
+    ) -> dict[str, Any] | list[Any]:
+        """
+        Parse results with genie, always return structured data
+
+        Returns an empty list if parsing fails!
+
+        Args:
+            index: the index of the result to parse, assumes first/zeroith if not provided
+
+        Returns:
+            structured_result: empty list or parsed data from genie
+
+        Raises:
+            N/A
+
+        """
+        return genie_parse(self.genie_platform, self.inputs[index], self.results[index])

scrapli/definitions/__init__.py

@@ -0,0 +1 @@
+"""scrapli.definitions"""

scrapli/definitions/arista_eos.yaml

@@ -0,0 +1,64 @@
+---
+prompt_pattern: '^[^<\r\n]{1,}[>#$]\s?$'
+default_mode: 'privileged_exec'
+modes:
+  - name: 'exec'
+    prompt_pattern: '^[\w.\-@()/: ]{1,63}>\s?$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_prompted_input:
+              input: 'enable'
+              prompt_exact: 'Password:'
+              response: '__lookup::enable'
+  - name: 'privileged_exec'
+    prompt_pattern: '^[\w.\-@()/: ]{1,63}#\s?$'
+    prompt_excludes:
+      - '(config'
+    accessible_modes:
+      - name: 'exec'
+        instructions:
+          - send_input:
+              input: 'disable'
+      - name: 'configuration'
+        instructions:
+          - send_input:
+              input: 'configure terminal'
+      - name: 'bash'
+        instructions:
+          - send_input:
+              input: 'bash'
+  - name: 'configuration'
+    prompt_pattern: '^[\w.\-@()/: ]{1,63}\(config[\w.\-@/:+]{0,63}\)#\s?$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_input:
+              input: 'end'
+  - name: 'bash'
+    prompt_pattern: '^\[[\w.\-@()\/: ]{1,63}~\]\$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_input:
+              input: 'exit'
+failure_indicators:
+  - '% Ambiguous command'
+  - '% Error'
+  - '% Incomplete command'
+  - '% Invalid input'
+  - '% Cannot commit'
+  - '% Unavailable command'
+  - '% Duplicate sequence number'
+on_open_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - send_input:
+      input: 'term width 32767'
+  - send_input:
+      input: 'term len 0'
+on_close_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - write:
+      input: 'exit'

scrapli/definitions/cisco_iosxe.yaml

@@ -0,0 +1,63 @@
+---
+prompt_pattern: '^.*[>#$]\s?+$'
+default_mode: 'privileged_exec'
+modes:
+  - name: 'exec'
+    prompt_pattern: '^[\w.\-@/:]{1,63}>\s?+$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_prompted_input:
+              input: 'enable'
+              prompt_exact: 'Password:'
+              response: '__lookup::enable'
+  - name: 'privileged_exec'
+    prompt_pattern: '^[\w.\-@/:]{1,63}#\s?+$'
+    accessible_modes:
+      - name: 'exec'
+        instructions:
+          - send_input:
+              input: 'disable'
+      - name: 'configuration'
+        instructions:
+          - send_input:
+              input: 'configure terminal'
+      - name: 'tclsh'
+        instructions:
+          - send_input:
+              input: 'tclsh'
+  - name: 'configuration'
+    prompt_pattern: '^[\w.\-@/:]{1,63}\([\w.\-@/:+]{0,32}\)#\s?+$'
+    prompt_excludes:
+      - 'tcl)'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_input:
+              input: 'end'
+  - name: 'tclsh'
+    prompt_pattern: '^([\w.\-@/+>:]+\(tcl\)[>#]|\+>)\s?+$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_input:
+              input: 'tclquit'
+failure_indicators:
+  - '% Ambiguous command'
+  - '% Incomplete command'
+  - '% Invalid input detected'
+  - '% Unknown command'
+on_open_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - send_input:
+      input: 'term width 512'
+  - send_input:
+      input: 'term len 0'
+on_close_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - write:
+      input: 'exit'
+ntc_templates_platform: 'cisco_iosxe'
+genie_platform: 'iosxe'

scrapli/definitions/cisco_iosxr.yaml

@@ -0,0 +1,47 @@
+---
+prompt_pattern: '^.*[>#$]\s?+$'
+default_mode: 'privileged_exec'
+modes:
+  - name: 'privileged_exec'
+    prompt_pattern: '^[\w.\-@/:]{1,63}#\s?$'
+    accessible_modes:
+      - name: 'configuration'
+        instructions:
+          - send_input:
+              input: 'configure terminal'
+      - name: 'configuration_exclusive'
+        instructions:
+          - send_input:
+              input: 'configure exclusive'
+  - name: 'configuration'
+    prompt_pattern: '^[\w.\-@/:]{1,63}\(config[\w.\-@/:]{0,32}\)#\s?$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_input:
+              input: 'end'
+  - name: 'configuration_exclusive'
+    prompt_pattern: '^[\w.\-@/:]{1,63}\(config[\w.\-@/:]{0,32}\)#\s?$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_input:
+              input: 'end'
+failure_indicators:
+  - '% Ambiguous command'
+  - '% Incomplete command'
+  - '% Invalid input detected'
+on_open_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - send_input:
+      input: 'term width 512'
+  - send_input:
+      input: 'term len 0'
+on_close_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - write:
+      input: 'exit'
+ntc_templates_platform: 'cisco_iosxe'
+genie_platform: 'iosxe'