scrapli 2.0.0a3__py3-none-musllinux_1_1_aarch64.whl → 2.0.0a5__py3-none-musllinux_1_1_aarch64.whl

scrapli/cli.py

@@ -1,18 +1,21 @@
 """scrapli.cli"""
 
 import importlib.resources
-from collections.abc import Callable
+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
 
@@ -31,14 +34,13 @@ from scrapli.exceptions import (
 )
 from scrapli.ffi_mapping import LibScrapliMapping
 from scrapli.ffi_types import (
-    CancelPointer,
     DriverPointer,
     IntPointer,
-    LogFuncCallback,
     OperationIdPointer,
     U64Pointer,
     ZigSlice,
     ZigU64Slice,
+    ffi_logger_wrapper,
     to_c_string,
 )
 from scrapli.helper import (
@@ -47,6 +49,7 @@ from scrapli.helper import (
     wait_for_available_operation_result_async,
 )
 from scrapli.session import Options as SessionOptions
+from scrapli.transport import BinOptions as TransportBinOptions
 from scrapli.transport import Options as TransportOptions
 
 CLI_DEFINITIONS_PATH_OVERRIDE_ENV = "SCRAPLI_DEFINITIONS_PATH"
@@ -73,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.
@@ -93,7 +140,6 @@ class Cli:
         definition_file_or_name: str,
         host: str,
         *,
-        logger_callback: Callable[[int, str], None] | None = None,
         port: int = 22,
         auth_options: AuthOptions | None = None,
         session_options: SessionOptions | None = None,
@@ -105,6 +151,7 @@ class Cli:
             logger_name += f":{logging_uid}"
 
         self.logger = getLogger(logger_name)
+        self.logger_callback = ffi_logger_wrapper(logger=self.logger)
         self._logging_uid = logging_uid
 
         self.ffi_mapping = LibScrapliMapping()
@@ -117,18 +164,13 @@ class Cli:
         # why. in this case we also just store the host since thats cheap and we need it as a string
         # in places too
         self.host = host
-        self._host = to_c_string(host)
-
-        self.logger_callback = (
-            LogFuncCallback(logger_callback) if logger_callback else LogFuncCallback(0)
-        )
-        self._logger_callback = logger_callback
+        self._host = to_c_string(s=host)
 
         self.port = port
 
         self.auth_options = auth_options or AuthOptions()
         self.session_options = session_options or SessionOptions()
-        self.transport_options = transport_options or TransportOptions()
+        self.transport_options = transport_options or TransportBinOptions()
 
         self.ptr: DriverPointer | None = None
         self.poll_fd: int = 0
@@ -264,7 +306,6 @@ class Cli:
         return Cli(
             host=self.host,
             definition_file_or_name=self.definition_file_or_name,
-            logger_callback=self._logger_callback,
             port=self.port,
             auth_options=self.auth_options,
             session_options=self.session_options,
@@ -289,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"
         )
@@ -307,7 +350,7 @@ class Cli:
             logger_callback=self.logger_callback,
             host=self._host,
             port=c_int(self.port),
-            transport_kind=c_char_p(self.transport_options.get_transport_kind()),
+            transport_kind=c_char_p(self.transport_options.transport_kind.encode(encoding="utf-8")),
         )
         if ptr == 0:  # type: ignore[comparison-overlap]
             raise AllocationException("failed to allocate cli")
@@ -319,7 +362,7 @@ class Cli:
                 ptr=self._ptr_or_exception(),
             )
         )
-        if poll_fd == 0:
+        if poll_fd <= 0:
             raise AllocationException("failed to allocate cli")
 
         self.poll_fd = poll_fd
@@ -393,9 +436,9 @@ class Cli:
 
     def _open(
         self,
+        *,
         operation_id: OperationIdPointer,
-        cancel: CancelPointer,
-    ) -> c_uint:
+    ) -> None:
         self._alloc()
 
         self.auth_options.apply(self.ffi_mapping, self._ptr_or_exception())
@@ -405,15 +448,12 @@ class Cli:
         status = self.ffi_mapping.cli_mapping.open(
             ptr=self._ptr_or_exception(),
             operation_id=operation_id,
-            cancel=cancel,
         )
         if status != 0:
             self._free()
 
             raise OpenException("failed to submit open operation")
 
-        return c_uint(operation_id.contents.value)
-
     def open(
         self,
     ) -> Result:
@@ -431,11 +471,10 @@ class Cli:
 
         """
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
-        operation_id = self._open(operation_id=operation_id, cancel=cancel)
+        self._open(operation_id=operation_id)
 
-        return self._get_result(operation_id=operation_id)
+        return self._get_result(operation_id=operation_id.contents.value)
 
     async def open_async(self) -> Result:
         """
@@ -452,24 +491,23 @@ class Cli:
 
         """
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
-        operation_id = self._open(operation_id=operation_id, cancel=cancel)
+        self._open(operation_id=operation_id)
 
-        return await self._get_result_async(operation_id=operation_id)
-
-    def _close(self) -> c_uint:
-        operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
+        return await self._get_result_async(operation_id=operation_id.contents.value)
 
+    def _close(
+        self,
+        *,
+        operation_id: OperationIdPointer,
+    ) -> None:
         status = self.ffi_mapping.cli_mapping.close(
-            ptr=self._ptr_or_exception(), operation_id=operation_id, cancel=cancel
+            ptr=self._ptr_or_exception(),
+            operation_id=operation_id,
         )
         if status != 0:
             raise CloseException("submitting close operation")
 
-        return c_uint(operation_id.contents.value)
-
     def close(
         self,
     ) -> Result:
@@ -487,9 +525,11 @@ class Cli:
             CloseException: if the operation fails
 
         """
-        operation_id = self._close()
+        operation_id = OperationIdPointer(c_uint(0))
 
-        result = self._get_result(operation_id=operation_id)
+        self._close(operation_id=operation_id)
+
+        result = self._get_result(operation_id=operation_id.contents.value)
 
         self._free()
 
@@ -512,14 +552,70 @@ class Cli:
             CloseException: if the operation fails
 
         """
-        operation_id = self._close()
+        operation_id = OperationIdPointer(c_uint(0))
+
+        self._close(operation_id=operation_id)
 
-        result = await self._get_result_async(operation_id=operation_id)
+        result = await self._get_result_async(operation_id=operation_id.contents.value)
 
         self._free()
 
         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,
@@ -658,13 +754,11 @@ class Cli:
         self,
         *,
         operation_id: OperationIdPointer,
-        cancel: CancelPointer,
         requested_mode: c_char_p,
     ) -> c_uint:
         status = self.ffi_mapping.cli_mapping.enter_mode(
             ptr=self._ptr_or_exception(),
             operation_id=operation_id,
-            cancel=cancel,
             requested_mode=requested_mode,
         )
         if status != 0:
@@ -698,12 +792,12 @@ class Cli:
         _ = operation_timeout_ns
 
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
         _requested_mode = to_c_string(requested_mode)
 
         operation_id = self._enter_mode(
-            operation_id=operation_id, cancel=cancel, requested_mode=_requested_mode
+            operation_id=operation_id,
+            requested_mode=_requested_mode,
         )
 
         return self._get_result(operation_id=operation_id)
@@ -734,12 +828,12 @@ class Cli:
         _ = operation_timeout_ns
 
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
         _requested_mode = to_c_string(requested_mode)
 
         operation_id = self._enter_mode(
-            operation_id=operation_id, cancel=cancel, requested_mode=_requested_mode
+            operation_id=operation_id,
+            requested_mode=_requested_mode,
         )
 
         return await self._get_result_async(operation_id=operation_id)
@@ -748,12 +842,10 @@ class Cli:
         self,
         *,
         operation_id: OperationIdPointer,
-        cancel: CancelPointer,
     ) -> c_uint:
         status = self.ffi_mapping.cli_mapping.get_prompt(
             ptr=self._ptr_or_exception(),
             operation_id=operation_id,
-            cancel=cancel,
         )
         if status != 0:
             raise SubmitOperationException("submitting get prompt operation failed")
@@ -784,9 +876,8 @@ class Cli:
         _ = operation_timeout_ns
 
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
-        operation_id = self._get_prompt(operation_id=operation_id, cancel=cancel)
+        operation_id = self._get_prompt(operation_id=operation_id)
 
         return self._get_result(operation_id=operation_id)
 
@@ -814,9 +905,8 @@ class Cli:
         _ = operation_timeout_ns
 
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
-        operation_id = self._get_prompt(operation_id=operation_id, cancel=cancel)
+        operation_id = self._get_prompt(operation_id=operation_id)
 
         return await self._get_result_async(operation_id=operation_id)
 
@@ -824,7 +914,6 @@ class Cli:
         self,
         *,
         operation_id: OperationIdPointer,
-        cancel: CancelPointer,
         input_: c_char_p,
         requested_mode: c_char_p,
         input_handling: c_char_p,
@@ -834,7 +923,6 @@ class Cli:
         status = self.ffi_mapping.cli_mapping.send_input(
             ptr=self._ptr_or_exception(),
             operation_id=operation_id,
-            cancel=cancel,
             input_=input_,
             requested_mode=requested_mode,
             input_handling=input_handling,
@@ -880,7 +968,6 @@ class Cli:
         _ = operation_timeout_ns
 
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
         _input = to_c_string(input_)
         _requested_mode = to_c_string(requested_mode)
@@ -888,7 +975,6 @@ class Cli:
 
         operation_id = self._send_input(
             operation_id=operation_id,
-            cancel=cancel,
             input_=_input,
             requested_mode=_requested_mode,
             input_handling=_input_handling,
@@ -932,7 +1018,6 @@ class Cli:
         _ = operation_timeout_ns
 
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
         _input = to_c_string(input_)
         _requested_mode = to_c_string(requested_mode)
@@ -940,7 +1025,6 @@ class Cli:
 
         operation_id = self._send_input(
             operation_id=operation_id,
-            cancel=cancel,
             input_=_input,
             requested_mode=_requested_mode,
             input_handling=_input_handling,
@@ -986,8 +1070,6 @@ class Cli:
         # meaning all the "inputs" combined, not individually
         _ = operation_timeout_ns
 
-        cancel = CancelPointer(c_bool(False))
-
         result: Result | None = None
 
         for input_ in inputs:
@@ -999,7 +1081,6 @@ class Cli:
 
             operation_id = self._send_input(
                 operation_id=operation_id,
-                cancel=cancel,
                 input_=_input,
                 requested_mode=_requested_mode,
                 input_handling=_input_handling,
@@ -1055,8 +1136,6 @@ class Cli:
         # meaning all the "inputs" combined, not individually
         _ = operation_timeout_ns
 
-        cancel = CancelPointer(c_bool(False))
-
         result: Result | None = None
 
         for input_ in inputs:
@@ -1068,7 +1147,6 @@ class Cli:
 
             operation_id = self._send_input(
                 operation_id=operation_id,
-                cancel=cancel,
                 input_=_input,
                 requested_mode=_requested_mode,
                 input_handling=_input_handling,
@@ -1179,7 +1257,6 @@ class Cli:
         self,
         *,
         operation_id: OperationIdPointer,
-        cancel: CancelPointer,
         input_: c_char_p,
         prompt: c_char_p,
         prompt_pattern: c_char_p,
@@ -1193,7 +1270,6 @@ class Cli:
         status = self.ffi_mapping.cli_mapping.send_prompted_input(
             ptr=self._ptr_or_exception(),
             operation_id=operation_id,
-            cancel=cancel,
             input_=input_,
             prompt=prompt,
             prompt_pattern=prompt_pattern,
@@ -1252,7 +1328,6 @@ class Cli:
         _ = operation_timeout_ns
 
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
         _input = to_c_string(input_)
         _prompt = to_c_string(prompt)
@@ -1264,7 +1339,6 @@ class Cli:
 
         operation_id = self._send_prompted_input(
             operation_id=operation_id,
-            cancel=cancel,
             input_=_input,
             prompt=_prompt,
             prompt_pattern=_prompt_pattern,
@@ -1321,7 +1395,6 @@ class Cli:
         _ = operation_timeout_ns
 
         operation_id = OperationIdPointer(c_uint(0))
-        cancel = CancelPointer(c_bool(False))
 
         _input = to_c_string(input_)
         _prompt = to_c_string(prompt)
@@ -1333,7 +1406,6 @@ class Cli:
 
         operation_id = self._send_prompted_input(
             operation_id=operation_id,
-            cancel=cancel,
             input_=_input,
             prompt=_prompt,
             prompt_pattern=_prompt_pattern,
@@ -1347,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
         """