zepben.ewb 1.0.0__py3-none-any.whl

zepben/ewb/services/network/tracing/traversal/context_value_computer.py

@@ -0,0 +1,63 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+__all__ = ['ContextValueComputer']
+
+from abc import abstractmethod
+from typing import TypeVar, Generic
+
+from zepben.ewb.services.network.tracing.traversal.step_context import StepContext
+
+T = TypeVar('T')
+U = TypeVar('U')
+
+
+class ContextValueComputer(Generic[T]):
+    """
+    Interface representing a context value computer used to compute and store values in a `StepContext`.
+    Implementations compute initial and subsequent context values during traversal steps.
+
+    `T` The type of items being traversed.
+    """
+
+    def __init__(self, key: str):
+        self.key = key  # A unique key identifying the context value computed by this computer.
+
+    @abstractmethod
+    def compute_initial_value(self, item: T):
+        """
+        Computes the initial context value for the given starting item.
+
+        :param item: The starting item for which to compute the initial context value.
+        :return: The initial context value associated with the starting item.
+        """
+        raise NotImplemented
+
+    @abstractmethod
+    def compute_next_value(self, next_item: T, current_item: T, current_value):
+        """
+        Computes the next context value based on the current item, next item, and the current context value.
+
+        :param next_item: The next item in the traversal.
+        :param current_item: The current item of the traversal.
+        :param current_value: The current context value associated with the current item.
+        :return: The updated context value for the next item.
+        """
+        raise NotImplemented
+
+    def get_context_value(self, context: StepContext):
+        """
+        Gets the computed value from the context cast to type [U].
+        """
+        return context.get_value(self.key)
+
+    def is_standalone_computer(self):
+        return not isinstance(self, (StepAction, StopCondition, QueueCondition))
+
+
+# these imports are here to stop circular imports
+from zepben.ewb.services.network.tracing.traversal.stop_condition import StopCondition
+from zepben.ewb.services.network.tracing.traversal.step_action import StepAction
+from zepben.ewb.services.network.tracing.traversal.queue_condition import QueueCondition

zepben/ewb/services/network/tracing/traversal/debug_logging.py

@@ -0,0 +1,124 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+__all__ = ['DebugLoggingWrapper']
+
+import copy
+import functools
+from logging import Logger
+from types import FunctionType
+from typing import TypeVar, Union, Type, List, Tuple, Dict
+
+from zepben.ewb.services.network.tracing.traversal.queue_condition import QueueCondition
+from zepben.ewb.services.network.tracing.traversal.step_action import StepAction
+from zepben.ewb.services.network.tracing.traversal.stop_condition import StopCondition
+
+T = TypeVar('T')
+
+Wrappable = Union[StepAction[T], QueueCondition[T], StopCondition[T]]
+
+DebugLoggingDataParam = List[Tuple[Union[Tuple[str, str], str], str]]
+
+# class_to_wrap:
+#       - attr_name: 'attr_name=(log_msg)'
+#       - (attr_name, log_name): 'log_name=(log_msg)'
+_data: Dict[Type[Wrappable], DebugLoggingDataParam] = {
+    StepAction: [(('apply', 'stepped_on'), ' [item={args[0]}, context={args[1]}]')],
+    StopCondition: [('should_stop', '={result} [item={args[0]}, context={args[1]}]')],
+    QueueCondition: [
+        ('should_queue', '={result} [next_item={args[0]}, next_context={args[1]}, current_item={args[2]}, current_context={args[3]}]'),
+        ('should_queue_start_item', '={result} [item={args[0]}]'),
+    ],
+}
+
+
+class DebugLoggingWrapper:
+
+    def __init__(self, description: str, logger: Logger):
+        self.description: str = description
+        self._logger: Logger = logger
+        self._wrapped = {
+            StepAction: 0,
+            StopCondition: 0,
+            QueueCondition: 0
+        }
+
+    def wrap(self, obj: Wrappable):
+        """
+        Return a new object with debug logging wrappers applied to supported methods of the object.
+
+        Supported methods by object class::
+
+            - :meth:`StepAction.action`
+            - :meth:`StopCondition.should_stop`
+            - :class:`QueueCondition`
+              - :meth:`should_queue`
+              - :meth:`should_queue_start_item`
+
+        :param obj: Instantiated object representing a condition or action in a :class:`zepben.ewb.Traversal`.
+        :return: new copy of the object passed in for fluent use.
+
+        :raises AttributeError: If wrapping the passed in object type is not supported.
+        """
+
+        # Create a shallow copy of the object as early as possible to avoid accidentally modifying the original.
+        w_obj = copy.copy(obj)
+
+        def _get_logger_index(_clazz: Type[Wrappable]) -> int:
+            """
+            This is just a very lazy way of auto counting the number of objects wrapped
+            based on their basic classification without requiring any information in the
+            object aside from what it inherits from.
+
+            """
+
+            self._wrapped[clazz] += 1
+            return self._wrapped[clazz]
+
+        def _wrap_attr(_index: int, _attr: str, _msg: str) -> None:
+            """
+            Replaces the specified attr with a wrapper around the same attr to inject
+            logging.
+
+            :param _attr: Method/Function name.
+            :raises AttributeError: if ``wrappable`` is already wrapped
+            """
+
+            if isinstance(_attr, tuple):
+                _attr_name, _log_attr_name = _attr
+            else:
+                _attr_name = _log_attr_name = _attr
+
+            to_wrap = getattr(w_obj, _attr_name)
+
+            setattr(w_obj, _attr_name, self._log_method_call(to_wrap, f'{self.description}: {_log_attr_name}({_index})' + _msg))
+
+        for clazz in (StepAction, StopCondition, QueueCondition):
+            if isinstance(w_obj, clazz):
+                index = _get_logger_index(clazz)
+                for attr, msg in _data.get(clazz):
+                    _wrap_attr(index, attr, msg)
+                return w_obj
+        else:
+            raise NotImplementedError(f'{type(self).__name__} does not support wrapping {obj}')
+
+    def _log_method_call(self, func: FunctionType, log_string: str):
+        """
+        returns ``func`` wrapped with call to ``self._logger`` using ``log_string`` as the format
+
+        :param func: any callable
+        :param log_string: Log message format string to output when ``attr`` is called, args/kwargs
+         passed to the function are passed to :code:`str.format()`, as well as is ``result`` which is the
+         result of the function itself
+        """
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            result = func(*args, **kwargs)
+            msg = f"{self._logger.name}: {log_string.format(result=result, args=args, kwargs=kwargs)}"
+            self._logger.debug(msg)
+            return result
+
+        return wrapper

zepben/ewb/services/network/tracing/traversal/queue.py

@@ -0,0 +1,112 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ["TraversalQueue"]
+
+from abc import abstractmethod, ABCMeta
+from collections import deque
+from typing import TypeVar, Iterable, Generic, Deque, TYPE_CHECKING, Union
+
+T = TypeVar('T')
+U = TypeVar('U')
+
+
+class FIFODeque(deque):
+    def pop(self):
+        return self.popleft()
+
+    def peek(self) -> T:
+        return self[-1]
+
+
+class LIFODeque(deque):
+    def peek(self) -> T:
+        return self[0]
+
+
+class TraversalQueue(Generic[T], metaclass=ABCMeta):
+    """
+    Basic queue object, implementing some methods to align it with the kotlin sdk syntax,
+    """
+    @abstractmethod
+    def __len__(self):
+        """:return: the length of the queue"""
+
+    @classmethod
+    def breadth_first(cls) -> TraversalQueue[T]:
+        """ Creates a new instance backed by a breadth first (FIFO) queue. """
+        return BasicQueue(FIFODeque())
+
+    @classmethod
+    def depth_first(cls) -> TraversalQueue[T]:
+        """ Creates a new instance backed by a depth first (LIFO) queue. """
+        return BasicQueue(LIFODeque())
+
+    @abstractmethod
+    def has_next(self) -> bool:
+        """:return: True if the queue has more items."""
+
+    @abstractmethod
+    def pop(self):
+        """:return: The next item in the queue"""
+
+    @abstractmethod
+    def append(self, item: T) -> bool:
+        """
+        Adds an item to the queue
+
+        :param item: The item to be added to the queue
+
+        :return: True if the item was added
+        """
+
+    @abstractmethod
+    def extend(self, items: Iterable[T]):
+        """
+        Adds the items to the queue
+
+        :param items: The items to be added to the queue
+        """
+
+    @abstractmethod
+    def peek(self) -> T:
+        """:return: The next item on the queue without removing it"""
+
+    @abstractmethod
+    def clear(self):
+        """Clears the queue"""
+
+
+class BasicQueue(TraversalQueue, Generic[T]):
+
+    def __init__(self, queue: Union[FIFODeque, LIFODeque]):
+        self.queue = queue
+
+    def __iter__(self):
+        return self.queue.__iter__()
+
+    def __len__(self):
+        return len(self.queue)
+
+    def has_next(self) -> bool:
+        return len(self.queue) > 0
+
+    def pop(self):
+        return self.queue.pop()
+
+    def append(self, item: T) -> bool:
+        self.queue.append(item)
+        return True
+
+    def extend(self, items: Iterable[T]) -> None:
+        self.queue.extend(items)
+
+    def peek(self) -> T:
+        return self.queue.peek()
+
+    def clear(self):
+        self.queue.clear()

zepben/ewb/services/network/tracing/traversal/queue_condition.py

@@ -0,0 +1,75 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+from __future__ import annotations
+
+__all__ = ['QueueCondition', 'QueueConditionWithContextValue', 'ShouldQueue', 'ShouldQueueStartItem']
+
+from abc import abstractmethod
+from typing import TypeVar, Generic, Callable
+
+from zepben.ewb.services.network.tracing.traversal.step_context import StepContext
+from zepben.ewb.services.network.tracing.traversal.traversal_condition import TraversalCondition
+
+T = TypeVar('T')
+U = TypeVar('U')
+
+ShouldQueue = Callable[[T, StepContext, T, StepContext], bool]
+ShouldQueueStartItem = Callable[[T], bool]
+
+
+class QueueCondition(Generic[T], TraversalCondition[T]):
+    """
+    Functional interface representing a condition that determines whether a traversal should queue a next item.
+
+    `T` The type of items being traversed.
+    """
+
+    def __init__(self, condition):
+        self.should_queue = condition
+
+    def should_queue(self, next_item: T, next_context: StepContext, current_item: T, current_context: StepContext) -> bool:
+        """
+        Determines whether the `next_item` should be queued for traversal.
+
+        `next_item` The next item to be potentially queued.
+        `next_context` The context associated with the `next_iItem`.
+        `current_item` The current item being processed in the traversal.
+        `current_context` The context associated with the `current_item`.
+        Returns `True` if the `next_tem` should be queued; `False` otherwise.
+        """
+
+        raise NotImplemented
+
+    @staticmethod
+    def should_queue_start_item(item: T) -> bool:
+        """
+        Determines whether a traversal start_item should be queued when running a `Traversal`.
+
+        :param item: The item to be potentially queued.
+        :eturn: `True` if the `item` should be queued; `False` otherwise. Defaults to `True`.
+        """
+
+        return True
+
+
+from zepben.ewb.services.network.tracing.traversal.context_value_computer import ContextValueComputer
+
+
+class QueueConditionWithContextValue(QueueCondition[T], ContextValueComputer[T], Generic[T, U]):
+    """
+    Interface representing a queue condition that requires a value stored in the `StepContext` to determine if an item should be queued.
+
+    `T` The type of items being traversed.
+    `U` The type of the context value computed and used in the condition.
+    """
+
+    @abstractmethod
+    def compute_initial_value(self, item: T):
+        raise NotImplemented
+
+    @abstractmethod
+    def compute_next_value(self, next_item: T, current_item: T, current_value):
+        raise NotImplemented

zepben/ewb/services/network/tracing/traversal/step_action.py

@@ -0,0 +1,83 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+__all__ = ['StepAction', 'StepActionWithContextValue', 'StepActionFunc']
+
+from abc import abstractmethod
+from typing import TypeVar, Generic, Callable, final
+
+from zepben.ewb.services.network.tracing.traversal.context_value_computer import ContextValueComputer
+from zepben.ewb.services.network.tracing.traversal.step_context import StepContext
+
+T = TypeVar('T')
+U = TypeVar('U')
+
+StepActionFunc = Callable[[T, StepContext], None]
+
+
+class StepAction(Generic[T]):
+    """
+    Functional interface representing an action to be performed at each step of a traversal.
+    This allows for custom operations to be executed on each item during traversal.
+
+    `T` The type of items being traversed.
+    """
+
+    def __init__(self, _func: StepActionFunc = None):
+        self._func = _func or self._apply
+
+    def __init_subclass__(cls):
+        """
+        Due to ``apply`` needing to call ``self._func`` to allow the method wrapping used in
+        ``Traversal.if_stopping()`` and ``Traversal.if_not_stopping()`` we **DO NOT** allow this
+        method to be overridden directly.
+
+        :raises Exception: If ``cls.apply`` is overridden
+        """
+        if 'apply' in cls.__dict__.keys():
+            raise Exception(f"method 'apply' should not be directly overridden, override '_apply' instead.")
+        super().__init_subclass__()
+
+    @final
+    def apply(self, item: T, context: StepContext):
+        """
+        Applies the action to the specified ``item``.
+
+        :param item: The current item in the traversal.
+        :param context: The context associated with the current traversal step.
+        """
+
+        return self._func(item, context)
+
+    @abstractmethod
+    def _apply(self, item: T, context: StepContext):
+        """
+        Override this method instead of ``self.apply`` directly
+
+        :param item: The current item in the traversal.
+        :param context: The context associated with the current traversal step.
+        """
+        raise NotImplementedError()
+
+
+class StepActionWithContextValue(StepAction[T], ContextValueComputer[T]):
+    """
+    Interface representing a step action that utilises a value stored in the :class:`StepContext`.
+
+    `T` The type of items being traversed.
+    `U` The type of the context value computed and used in the action.
+    """
+
+    def __init__(self, key: str, _func: StepActionFunc = None):
+        StepAction.__init__(self, _func)
+        ContextValueComputer.__init__(self, key)
+
+    @abstractmethod
+    def compute_initial_value(self, item: T):
+        raise NotImplementedError()
+
+    @abstractmethod
+    def compute_next_value(self, next_item: T, current_item: T, current_value):
+        raise NotImplementedError()

zepben/ewb/services/network/tracing/traversal/step_context.py

@@ -0,0 +1,59 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+__all__ = ['StepContext']
+
+from typing import TypeVar, Generic
+
+T = TypeVar('T')
+
+
+class StepContext(Generic[T]):
+    """
+    Represents the context of a traversal step, holding information about the traversal state and the ability to store arbitrary values with the context.
+    This context is passed to conditions and actions during a traversal to provide additional information about each step.
+    
+    Any `ContextValueComputer` registered with the traversal will put the computed value into this context with the given `ContextValueComputer.key` which can
+    be retrieved by using `get_value`.
+
+    :var is_start_item: Indicates whether the current item is a starting item of the traversal.
+    :var is_branch_start_item: Indicates whether the current item is the start of a new branch in a branching traversal.
+    :var step_number: The number of steps taken in the traversal so far for this traversal path.
+    :var branch_depth: The depth of the current branch in a branching traversal.
+    :var is_stopping: Indicates whether the traversal is stopping at the current item due to a stop condition.
+    """
+
+    def __init__(self, is_start_item: bool, is_branch_start_item: bool, step_number: int = 0, branch_depth: int = 0, values: dict = None):
+        self.is_start_item = is_start_item
+        self.is_branch_start_item = is_branch_start_item
+        self.step_number = step_number
+        self.branch_depth = branch_depth
+        self._values = values or dict()
+
+        self.is_stopping: bool = False
+        self.is_actionable_item: bool = False
+
+    def set_value(self, key: str, value):
+        """
+        Sets a context value associated with the specified key.
+
+        `key` The key identifying the context value.
+        `value` The value to associate with the key.
+        """
+
+        self._values[key] = value
+
+    def get_value(self, key: str) -> T:
+        """
+        Retrieves a context value associated with the specified key.
+
+        `key` The key identifying the context value.
+        @return The context value associated with the key, or `None` if not found.
+        """
+
+        return self._values.get(key)
+
+    def __str__(self) -> str:
+        return f"StepContext({', '.join('{}={}'.format(*i) for i in vars(self).items())})"

zepben/ewb/services/network/tracing/traversal/stop_condition.py

@@ -0,0 +1,57 @@
+#  Copyright 2025 Zeppelin Bend Pty Ltd
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+__all__ = ['StopCondition', 'StopConditionWithContextValue', 'ShouldStop']
+
+from abc import abstractmethod
+from typing import TypeVar, Generic, Callable
+
+from zepben.ewb.services.network.tracing.traversal.context_value_computer import ContextValueComputer
+from zepben.ewb.services.network.tracing.traversal.step_context import StepContext
+from zepben.ewb.services.network.tracing.traversal.traversal_condition import TraversalCondition
+
+T = TypeVar('T')
+U = TypeVar('U')
+
+ShouldStop = Callable[[T, StepContext], bool]
+
+
+class StopCondition(Generic[T], TraversalCondition[T]):
+    """
+    Functional interface representing a condition that determines whether the traversal should stop at a given item.
+
+    `T` The type of items being traversed.
+    """
+
+    def __init__(self, stop_function: ShouldStop = None):
+        if stop_function is not None:
+            self.should_stop = stop_function
+
+    def should_stop(self, item: T, context: StepContext) -> bool:
+        """
+        Determines whether the traversal should stop at the specified item.
+
+        :param item: The current item being processed in the traversal.
+        :param context: The context associated with the current traversal step.
+
+        :return: `True` if the traversal should stop at this item; `False` otherwise.
+        """
+
+
+class StopConditionWithContextValue(StopCondition[T], ContextValueComputer[T]):
+    """
+    Interface representing a stop condition that requires a value stored in the StepContext to determine if an item should be queued.
+
+    `T` The type of items being traversed.
+    `U` The type of the context value computed and used in the condition.
+    """
+
+    @abstractmethod
+    def compute_initial_value(self, item: T):
+        raise NotImplemented
+
+    @abstractmethod
+    def compute_next_value(self, next_item: T, current_item: T, current_value):
+        raise NotImplemented