scrapli 2.0.0a4__py3-none-macosx_11_0_arm64.whl → 2.0.0a5__py3-none-macosx_11_0_arm64.whl

scrapli/__init__.py

@@ -2,19 +2,18 @@
 
 from scrapli.auth import LookupKeyValue
 from scrapli.auth import Options as AuthOptions
-from scrapli.cli import Cli
+from scrapli.cli import Cli, ReadCallback
 from scrapli.netconf import Netconf
 from scrapli.netconf import Options as NetconfOptions
 from scrapli.session import Options as SessionOptions
 from scrapli.transport import BinOptions as TransportBinOptions
-from scrapli.transport import Options as TransportOptions
 from scrapli.transport import Ssh2Options as TransportSsh2Options
 from scrapli.transport import TelnetOptions as TransportTelnetOptions
 from scrapli.transport import TestOptions as TransportTestOptions
 
-__version__ = "2.0.0-alpha.4"
-__calendar_version__ = "2025.6.7"
-__definitions_version__ = "471f12e"
+__version__ = "2.0.0-alpha.5"
+__calendar_version__ = "2025.7.12"
+__definitions_version__ = "c38ec6d"
 
 __all__ = (
     "AuthOptions",
@@ -22,9 +21,9 @@ __all__ = (
     "LookupKeyValue",
     "Netconf",
     "NetconfOptions",
+    "ReadCallback",
     "SessionOptions",
     "TransportBinOptions",
-    "TransportOptions",
     "TransportSsh2Options",
     "TransportTelnetOptions",
     "TransportTestOptions",

scrapli/auth.py

@@ -63,8 +63,8 @@ class Options:
         lookups: a list of key/values that can be "looked up" from a connection -- used in
             conjunction with platform definition templating like `__lookup::enable` where "enable"
             is the key to "lookup" in the list of lookup key/values.
-        in_session_auth_bypass: whether to bypass attempting in session authentication -- only
-             applicable to "bin" and "telnet" transports.
+        force_in_session_auth: unconditionally force the in session auth process.
+        bypass_in_session_auth: skip in session auth even if transport (telnet/bin) expect it.
         username_pattern: the regex pattern to use to look for a username prompt
         password_pattern: the regex pattern to use to look for a password prompt
         private_key_passphrase_pattern: the regex pattern to use to look for a passphrase prompt
@@ -82,7 +82,8 @@ class Options:
     private_key_path: str | None = None
     private_key_passphrase: str | None = None
     lookups: list[LookupKeyValue] | None = None
-    in_session_auth_bypass: bool | None = None
+    force_in_session_auth: bool | None = None
+    bypass_in_session_auth: bool | None = None
     username_pattern: str | None = None
     password_pattern: str | None = None
     private_key_passphrase_pattern: str | None = None
@@ -154,10 +155,15 @@ class Options:
                 if status != 0:
                     raise OptionsException("failed to set auth lookup key/value")
 
-        if self.in_session_auth_bypass is not None:
-            status = ffi_mapping.options_mapping.auth.set_in_session_auth_bypass(ptr)
+        if self.force_in_session_auth is not None:
+            status = ffi_mapping.options_mapping.auth.set_force_in_session_auth(ptr)
             if status != 0:
-                raise OptionsException("failed to set session in session auth bypass")
+                raise OptionsException("failed to set force in session auth")
+
+        if self.bypass_in_session_auth is not None:
+            status = ffi_mapping.options_mapping.auth.set_bypass_in_session_auth(ptr)
+            if status != 0:
+                raise OptionsException("failed to set bypass in session auth")
 
         if self.username_pattern is not None:
             self._username_pattern = to_c_string(self.username_pattern)
@@ -209,7 +215,8 @@ class Options:
             f"private_key_path={self.private_key_path!r} "
             f"private_key_passphrase={self.private_key_passphrase!r} "
             f"lookups={self.lookups!r}) "
-            f"in_session_auth_bypass={self.in_session_auth_bypass!r}) "
+            f"force_in_session_auth={self.force_in_session_auth!r}) "
+            f"bypass_in_session_auth={self.bypass_in_session_auth!r}) "
             f"username_pattern={self.username_pattern!r}) "
             f"password_pattern={self.password_pattern!r}) "
             f"private_key_passphrase_pattern={self.private_key_passphrase_pattern!r}) "

scrapli/cli.py

@@ -1,17 +1,21 @@
 """scrapli.cli"""
 
 import importlib.resources
+from collections.abc import Awaitable, Callable
 from ctypes import (
     c_bool,
     c_char_p,
     c_int,
     c_uint,
     c_uint64,
+    pointer,
 )
+from dataclasses import dataclass
 from enum import Enum
 from logging import getLogger
 from os import environ
 from pathlib import Path
+from time import time_ns
 from types import TracebackType
 from typing import Any
 
@@ -72,6 +76,50 @@ class InputHandling(str, Enum):
     IGNORE = "ignore"
 
 
+@dataclass
+class ReadCallback:
+    """
+    ReadCallback represents a callback and how it should be executed in a read_with_callbacks op.
+
+    Args:
+        name: friendly name for the callback
+        contains: string that when contained in the buf being processed indicates this callback
+            should be executed
+        contains_pattern: string representing a pcre2 pattern that, if found in the buf being
+            processed indicates this callback should be executed -- note: ignored if contains is set
+        not_contains: a string that if found in the buf being processed nullifies the containment
+            check
+        once: bool indicating if this is an "only once" callback or if it can be executed multiple
+            times
+        completes: bool indicated if, after execution, this callback should "complete" (end) the
+            read_with_callbacks operation
+        callback: the callback func to execute
+
+    Returns:
+        None
+
+    Raises:
+        N/A
+
+    """
+
+    name: str
+    contains: str = ""
+    contains_pattern: str = ""
+    not_contains: str = ""
+    once: bool = False
+    completes: bool = False
+    callback: Callable[["Cli"], None] | None = None
+    callback_async: Callable[["Cli"], Awaitable[None]] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.contains and not self.contains_pattern:
+            raise OperationException("one of 'contains' or 'contains_pattern' must be set")
+
+        if self.callback is None and self.callback_async is None:
+            raise OperationException("one of 'callback' or 'callback_async' must be set")
+
+
 class Cli:
     """
     Cli represents a cli connection object.
@@ -282,6 +330,8 @@ class Cli:
             with open(definition_file_or_name, "rb") as f:
                 self.definition_string = f.read()
 
+            return
+
         raise OptionsException(
             f"definition platform name or filename '{definition_file_or_name}' not found"
         )
@@ -512,6 +562,60 @@ class Cli:
 
         return result
 
+    def write(self, input_: str) -> None:
+        """
+        Write the given input.
+
+        Args:
+            input_: the input to write
+
+        Returns:
+            Result: a Result object representing the operation
+
+        Raises:
+            NotOpenedException: if the ptr to the cli object is None (via _ptr_or_exception)
+            SubmitOperationException: if the operation fails
+
+        """
+        _input = to_c_string(s=input_)
+
+        status = self.ffi_mapping.session_mapping.write(
+            ptr=self._ptr_or_exception(),
+            input_=_input,
+            redacted=c_bool(False),
+        )
+        if status != 0:
+            raise SubmitOperationException("executing write and return operation failed")
+
+        _ = _input
+
+    def write_and_return(self, input_: str) -> None:
+        """
+        Write the given input then send a return character.
+
+        Args:
+            input_: the input to write
+
+        Returns:
+            Result: a Result object representing the operation
+
+        Raises:
+            NotOpenedException: if the ptr to the cli object is None (via _ptr_or_exception)
+            SubmitOperationException: if the operation fails
+
+        """
+        _input = to_c_string(s=input_)
+
+        status = self.ffi_mapping.session_mapping.write_and_return(
+            ptr=self._ptr_or_exception(),
+            input_=_input,
+            redacted=c_bool(False),
+        )
+        if status != 0:
+            raise SubmitOperationException("executing write and return operation failed")
+
+        _ = _input
+
     def _get_result(
         self,
         operation_id: c_uint,
@@ -1315,6 +1419,202 @@ class Cli:
 
         return await self._get_result_async(operation_id=operation_id)
 
+    @handle_operation_timeout
+    def read_with_callbacks(
+        self,
+        callbacks: list[ReadCallback],
+        *,
+        initial_input: str = "",
+        operation_timeout_ns: int | None = None,
+    ) -> Result:
+        """
+        Read from the device and react to the output with some callback.
+
+        Args:
+            callbacks: a list of callbacks to process when reading from the session
+            initial_input: an initial input to send
+            operation_timeout_ns: operation timeout in ns for this operation
+
+        Returns:
+            Result: a Result object representing the operation
+
+        Raises:
+            NotOpenedException: if the ptr to the cli object is None (via _ptr_or_exception)
+            SubmitOperationException: if the operation fails
+
+        """
+        # only used in the decorator
+        _ = operation_timeout_ns
+
+        start_time = time_ns()
+
+        if initial_input:
+            self.write_and_return(input_=initial_input)
+
+        pos = 0
+
+        result = ""
+        result_raw = b""
+
+        executed_callbacks = set()
+
+        while True:
+            operation_id = OperationIdPointer(c_uint(0))
+
+            status = self.ffi_mapping.cli_mapping.read_any(
+                ptr=self._ptr_or_exception(),
+                operation_id=operation_id,
+            )
+            if status != 0:
+                raise SubmitOperationException("submitting read any operation failed")
+
+            intermediate_result = self._get_result(operation_id=operation_id.contents.value)
+
+            result += intermediate_result.result
+            result_raw += intermediate_result.result_raw
+
+            for callback in callbacks:
+                if callback.name in executed_callbacks and callback.once:
+                    continue
+
+                execute = pointer(c_bool(False))
+
+                status = self.ffi_mapping.cli_mapping.read_callback_should_execute(
+                    buf=to_c_string(result[pos:]),
+                    name=to_c_string(callback.name),
+                    contains=to_c_string(callback.contains),
+                    contains_pattern=to_c_string(callback.contains_pattern),
+                    not_contains=to_c_string(callback.not_contains),
+                    execute=execute,
+                )
+                if status != 0:
+                    raise OperationException("failed checking if callback should execute")
+
+                if execute.contents.value is False:
+                    continue
+
+                executed_callbacks.add(callback.name)
+
+                pos = len(result)
+
+                if callback.callback is None:
+                    raise OperationException("callback is None, cannot proceed")
+                else:
+                    callback.callback(self)
+
+                if callback.completes is True:
+                    return Result(
+                        inputs=initial_input,
+                        host=self.host,
+                        port=self.port,
+                        start_time=start_time,
+                        splits=[time_ns()],
+                        results_raw=result_raw,
+                        results=result,
+                        results_failed_indicator="",
+                        textfsm_platform=self.ntc_templates_platform,
+                        genie_platform=self.genie_platform,
+                    )
+
+    @handle_operation_timeout_async
+    async def read_with_callbacks_async(
+        self,
+        callbacks: list[ReadCallback],
+        *,
+        initial_input: str = "",
+        operation_timeout_ns: int | None = None,
+    ) -> Result:
+        """
+        Read from the device and react to the output with some callback.
+
+        Args:
+            callbacks: a list of callbacks to process when reading from the session
+            initial_input: an initial input to send
+            operation_timeout_ns: operation timeout in ns for this operation
+
+        Returns:
+            Result: a Result object representing the operation
+
+        Raises:
+            NotOpenedException: if the ptr to the cli object is None (via _ptr_or_exception)
+            SubmitOperationException: if the operation fails
+
+        """
+        # only used in the decorator
+        _ = operation_timeout_ns
+
+        start_time = time_ns()
+
+        if initial_input:
+            self.write_and_return(input_=initial_input)
+
+        pos = 0
+
+        result = ""
+        result_raw = b""
+
+        executed_callbacks = set()
+
+        while True:
+            operation_id = OperationIdPointer(c_uint(0))
+
+            status = self.ffi_mapping.cli_mapping.read_any(
+                ptr=self._ptr_or_exception(),
+                operation_id=operation_id,
+            )
+            if status != 0:
+                raise SubmitOperationException("submitting read any operation failed")
+
+            intermediate_result = await self._get_result_async(
+                operation_id=operation_id.contents.value
+            )
+
+            result += intermediate_result.result
+            result_raw += intermediate_result.result_raw
+
+            for callback in callbacks:
+                if callback.name in executed_callbacks and callback.once:
+                    continue
+
+                execute = pointer(c_bool(False))
+
+                status = self.ffi_mapping.cli_mapping.read_callback_should_execute(
+                    buf=to_c_string(result[pos:]),
+                    name=to_c_string(callback.name),
+                    contains=to_c_string(callback.contains),
+                    contains_pattern=to_c_string(callback.contains_pattern),
+                    not_contains=to_c_string(callback.not_contains),
+                    execute=execute,
+                )
+                if status != 0:
+                    raise OperationException("failed checking if callback should execute")
+
+                if execute.contents.value is False:
+                    continue
+
+                executed_callbacks.add(callback.name)
+
+                pos = len(result)
+
+                if callback.callback is None:
+                    raise OperationException("callback is None, cannot proceed")
+                else:
+                    callback.callback(self)
+
+                if callback.completes is True:
+                    return Result(
+                        inputs=initial_input,
+                        host=self.host,
+                        port=self.port,
+                        start_time=start_time,
+                        splits=[time_ns()],
+                        results_raw=result_raw,
+                        results=result,
+                        results_failed_indicator="",
+                        textfsm_platform=self.ntc_templates_platform,
+                        genie_platform=self.genie_platform,
+                    )
+
     @staticmethod
     def ___getwide___() -> None:  # pragma: no cover
         """

scrapli/cli_parse.py

@@ -93,7 +93,7 @@ def textfsm_parse(
             originating textfsm.parser.TextFSMError exception.
 
     """
-    import textfsm
+    import textfsm  # noqa: PLC0415
 
     if isinstance(template, str):
         if template.startswith("http://") or template.startswith("https://"):

scrapli/cli_result.py

@@ -4,6 +4,7 @@ from typing import Any, TextIO
 
 from scrapli.cli_parse import genie_parse, textfsm_get_template, textfsm_parse
 from scrapli.exceptions import ParsingException
+from scrapli.helper import bulid_result_preview, unix_nano_timestmap_to_iso
 
 OPERATION_DELIMITER = "__libscrapli__"
 
@@ -48,6 +49,30 @@ class Result:
         self.textfsm_platform = textfsm_platform
         self.genie_platform = genie_platform
 
+    def __str__(self) -> str:
+        """
+        Magic str method for Result class
+
+        Args:
+            N/A
+
+        Returns:
+            str: str for class object
+
+        Raises:
+            N/A
+
+        """
+        return (
+            "<-----\n"
+            f"\tInput(s)         : {self.inputs}\n"
+            f"\tStart Time       : {unix_nano_timestmap_to_iso(timestamp=self.start_time)}\n"
+            f"\tEnd Time         : {unix_nano_timestmap_to_iso(timestamp=self.end_time)}\n"
+            f"\tElapsed Time (s) : {self.elapsed_time_seconds:.2f}s\n"
+            f"\tResult           : {bulid_result_preview(result=self.result)}\n"
+            "----->"
+        )
+
     def extend(self, result: "Result") -> None:
         """
         Extends this Result object with another Result object.
@@ -141,6 +166,23 @@ class Result:
         """
         return "\n".join(self.results)
 
+    @property
+    def result_raw(self) -> bytes:
+        """
+        Returns the results (raw) joined on newline chars. Note this does *not* include inputs sent.
+
+        Args:
+            N/A
+
+        Returns:
+            bytes: joined results
+
+        Raises:
+            N/A
+
+        """
+        return b"\n".join(self.results_raw)
+
     def textfsm_parse(
         self,
         index: int = 0,

scrapli/definitions/aethra_atosnt.yaml

@@ -0,0 +1,9 @@
+---
+prompt_pattern: '^[a-z0-9.\-_@]{1,64}>>'
+default_mode: 'exec'
+modes:
+  - name: 'exec'
+    prompt_pattern: '^[a-z0-9.\-_@]{1,64}>>'
+on_close_instructions:
+  - write:
+      input: '\x04'

scrapli/definitions/alcatel_aos.yaml

@@ -0,0 +1,9 @@
+---
+prompt_pattern: '^[a-zA-Z0-9.\-_@\/:]{1,63}[>|#]\s*'
+default_mode: 'exec'
+modes:
+  - name: 'exec'
+    prompt_pattern: '^[a-zA-Z0-9.\-_@\/:]{1,63}[>|#]\s*'
+on_close_instructions:
+  - write:
+      input: 'exit'

scrapli/definitions/arista_eos.yaml

@@ -62,3 +62,4 @@ on_close_instructions:
       requested_mode: 'privileged_exec'
   - write:
       input: 'exit'
+ntc_templates_platform: 'arista_eos'

scrapli/definitions/aruba_aoscx.yaml

@@ -0,0 +1,33 @@
+---
+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'
+    prompt_pattern: '^[\w.\-@/:]{1,63}\(config[\w.\-@/:]{0,32}\)#\s?$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_input:
+              input: 'exit'
+failure_indicators:
+  - '% Command incomplete.'
+  - 'Invalid input:'
+  - 'doesn''t exist'
+on_open_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - send_input:
+      input: 'no page'
+on_close_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - write:
+      input: 'exit'
+ntc_templates_platform: 'aruba_aoscx'

scrapli/definitions/cisco_aireos.yaml

@@ -0,0 +1,31 @@
+---
+prompt_pattern: '^.*[>#$]\s?+$'
+default_mode: 'exec'
+modes:
+  - name: 'exec'
+    prompt_pattern: '^\([\w. -]{1,31}\) >$'
+    accessible_modes:
+      - name: 'configuration'
+        instructions:
+          - send_input:
+              input: 'config'
+  - name: 'configuration'
+    prompt_pattern: '^\([\w. -]{1,31}\) config>$'
+    accessible_modes:
+      - name: 'exec'
+        instructions:
+          - send_input:
+              input: 'exit'
+failure_indicators:
+  - 'Incorrect Usage. Use the ''?'' or <TAB> key to list commands.'
+  - 'Incorrect input!'
+on_open_instructions:
+  - send_input:
+      input: 'config paging disable'
+on_close_instructions:
+  - enter_mode:
+      requested_mode: 'exec'
+  - write:
+      input: 'logout'
+force_in_session_auth: true
+ntc_templates_platform: 'cisco_wlc_ssh'

scrapli/definitions/cisco_asa.yaml

@@ -0,0 +1,48 @@
+---
+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_pattern: '^(P|p)assword:\s?$'
+              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: 'configuration'
+    prompt_pattern: '^[\w\./-]{1,63}\([\w-]{0,32}\)#\s?$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_input:
+              input: 'exit'
+failure_indicators:
+  - '% Ambiguous command'
+  - '% Incomplete command'
+  - '% Invalid input detected'
+  - '% Unknown command'
+on_open_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - send_input:
+      input: 'terminal pager 0'
+on_close_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - write:
+      input: 'logout'
+ntc_templates_platform: 'cisco_asa'
+genie_platform: 'asa'

scrapli/definitions/cisco_cbs.yaml

@@ -0,0 +1,50 @@
+---
+prompt_pattern: '^.*[>#$]\s?+$'
+default_mode: 'privileged_exec'
+modes:
+  - name: 'exec'
+    prompt_pattern: '^[a-zA-Z0-9-.]{1,58}>$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_prompted_input:
+              input: 'enable'
+              prompt_exact: '^(?:enable\s){0,1}Password:\s?$'
+              response: '__lookup::enable'
+  - name: 'privileged_exec'
+    prompt_pattern: '^[a-zA-Z0-9-.]{1,58}#$'
+    accessible_modes:
+      - name: 'exec'
+        instructions:
+          - send_input:
+              input: 'disable'
+      - name: 'configuration'
+        instructions:
+          - send_input:
+              input: 'configure terminal'
+  - name: 'configuration'
+    prompt_pattern: '^[a-zA-Z0-9-.]{1,58}\([\w.\-@/:+]{1,32}\)#$'
+    accessible_modes:
+      - name: 'privileged_exec'
+        instructions:
+          - send_input:
+              input: 'end'
+failure_indicators:
+  - '% Incomplete command'
+  - '% Unrecognized command'
+  - '% missing mandatory parameter'
+  - '% bad parameter value'
+  - '% Ambiguous command'
+on_open_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - send_input:
+      input: 'terminal datadump'
+  - send_input:
+      input: 'terminal width 0'
+on_close_instructions:
+  - enter_mode:
+      requested_mode: 'privileged_exec'
+  - write:
+      input: 'exit'
+ntc_templates_platform: 'cisco_s300'