py_branches 1.2.1__py3-none-any.whl

py_branches/__init__.py

@@ -0,0 +1,9 @@
+from . import alternating
+from . import blackboard
+from . import cooldown
+from . import counter
+from . import latch
+from . import pause
+from . import random
+from . import retry
+from . import timeout

py_branches/alternating.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+import py_trees
+import random
+from typing import List
+from typing import Tuple
+
+
+class ActivateBehavior(py_trees.decorators.Decorator):
+    '''
+    Enables activation of a behavior from an external source as long as it has a handle to 
+    this decorator.
+
+    Args:
+        child(Behavior): The child behavior that is being activated or not activated.
+        name(str): Name of this behavior
+        activate(bool): Whether or not to start this behavior activated or not.
+    '''
+    def __init__(self, child: py_trees.behaviour.Behaviour,
+                       name: str,
+                       activate: bool,
+                       success_if_skip:bool=False):
+        super(ActivateBehavior, self).__init__(name=name, child=child)
+        self._activate = activate
+        self._success_if_skip = success_if_skip
+
+    @property
+    def activate(self):
+        return self._activate
+    
+    @activate.setter
+    def activate(self, activate: bool):
+        self._activate = activate
+
+    def tick(self):
+        if not self._activate:
+            if self._success_if_skip:
+                self.stop(py_trees.common.Status.SUCCESS)
+            else:
+                self.stop(py_trees.common.Status.FAILURE)
+            yield self
+        else:
+            for node in super().tick():
+                yield node
+
+    def update(self) -> py_trees.common.Status:
+        return self.decorated.status
+
+class _RunAlternatingHelper(py_trees.behaviour.Behaviour):
+    def __init__(self, name: str, activatable_behaviors: List[ActivateBehavior], counts: List[int]):
+        self._counts = counts
+        self._current_behavior_idx = 0
+        self._current_behavior_num_consecutive_runs = 0
+        self._activatable_behaviors = activatable_behaviors
+        self._activatable_behaviors[0].activate = True
+
+        super().__init__(name)
+
+    def initialise(self) -> None:
+        if self._current_behavior_num_consecutive_runs >= self._counts[self._current_behavior_idx]:
+            self._activatable_behaviors[self._current_behavior_idx].activate = False
+            self._current_behavior_idx = (self._current_behavior_idx + 1) % len(self._counts)
+            self._activatable_behaviors[self._current_behavior_idx].activate = True
+            self._current_behavior_num_consecutive_runs = 0
+
+        self._current_behavior_num_consecutive_runs += 1
+
+    def update(self) -> py_trees.common.Status:
+        return py_trees.common.Status.FAILURE
+
+def run_alternating(name: str, behaviors: List[py_trees.behaviour.Behaviour], counts: List[int]):
+    '''
+    Args:
+        name(str): Name of the behavior
+        behaviors(List[Behaviors]): List of all the behaviors to run alternating.
+        count(List[int]): A list of how many times the corresponding behavior ought to be ran.
+
+            Example:
+                A if behaviors is [behavior_a, behavior_b, behavior_c] and count is [3,2,4] then
+                behavior_a will run 3 times in a row, behavior_b will run 2 times in a row, and
+                behavior_c will run 4 times in a row before repeating.
+    '''
+    if 0 in counts:
+        raise ValueError(f'counts({counts}) can not have 0 in the list.')
+    if len(counts) != len(behaviors):
+        raise ValueError('len(counts) != len(behaviors), two lists must be of same length.')
+
+    alternating_behaviors = []
+    for idx, behavior in enumerate(behaviors):
+        activate_decorator = ActivateBehavior(behavior, f'activate_{behavior.name}', False)
+        alternating_behaviors.append(activate_decorator)
+    run_alternating_helper = _RunAlternatingHelper(f'{name}_helper', alternating_behaviors, counts)
+
+    children = []
+    children.append(run_alternating_helper)
+    children += alternating_behaviors
+
+    run_alternating_selector = py_trees.composites.Selector(name, False, children)
+    return run_alternating_selector
+
+class RunEveryRange(py_trees.decorators.Decorator):
+    '''
+    Enables the activation of child every for a range of calls within
+
+    Args:
+        child(Behavior): The child behavior that is being activated or not activated.
+        name(str): Name of this behavior.
+        max_range(int): Maximum number of runs before the iterations resets to 1.
+        run_range(Tuple[int, int]): Determines which range of iterations that the child
+            will execute for. Range is inclusive.
+
+    Example:
+        E: Executes that cycle.
+        S: Skips that cycle.
+        if max_range and run_range is:
+            6 and (4,6) the the child will run on the 4th, 5th, and 6th cycle.
+                S, S, S, E, E, E, S, S, S, E, E, E, S, S, S, ...
+            6 and (2,4) then the child will run on the 2nd, 3rd, and 4th cycle.
+                S, E, E, E, S, S, S, E, E, E, S, S, S, E, E, ...
+    '''
+    def __init__(self, child: py_trees.behaviour.Behaviour,
+                       name: str,
+                       max_range: int,
+                       run_range: Tuple[int, int],
+                       success_if_skip: bool = False):
+        if run_range[0] > run_range[1]:
+            raise ValueError('run_range must be a tuple with (smaller_number, bigger_number)')
+        if run_range[0] < 1:
+            raise ValueError('Lower run range must be greater or equal to 1')
+        if run_range[1] > max_range:
+            raise ValueError(f'Upper run range must be lower or equal to {max_range}')
+
+        super(RunEveryRange, self).__init__(name=name, child=child)
+        self._max_range = max_range
+        self._run_range = run_range
+        self._success_if_skip = success_if_skip
+        self._iteration = 1
+
+    def tick(self):
+        if self._run_range[0] <= self._iteration <= self._run_range[1]:
+            for node in super().tick():
+                yield node
+        else:
+            if self._success_if_skip:
+                self.stop(py_trees.common.Status.SUCCESS)
+            else:
+                self.stop(py_trees.common.Status.FAILURE)
+            yield self
+
+    def terminate(self, new_status: py_trees.common.Status) -> None:
+        self._iteration += 1
+        if self._iteration > self._max_range:
+            self._iteration = 1
+
+    def update(self) -> py_trees.common.Status:
+        return self.decorated.status
+
+class RunEveryX(py_trees.decorators.Decorator):
+    '''
+    Enables the activation of child every X calls. X can falls within a range
+    and gets recalculated every success.
+
+    Args:
+        child(Behavior): The child behavior that is being activated or not activated.
+        name(str): Name of this behavior
+        every_x_range(Tuple[int, int]): Run the child ever however many cycles. Number of
+        cycles is within a range. Range is inclusive.
+
+    Example:
+        E: Executes that cycle.
+        S: Skips that cycle.
+        if every_x_range is:
+            (1,1) then the child behavior will run every cycle.
+                E, E, E, E, E, E, E, E, E, E, E, E, E, E, E, ...
+            (5,5) then the child behavior will run every 5th cycle.
+                S, S, S, S, E, S, S, S, S, E, S, S, S, S, E, ...
+            (1,5) then the child behavior will run randomly between every
+            cycle or every 5th cycle. Changes every times it child gets executed.
+                S, S, E, S, S, S, S, E, E, S, S, S, E, S, S, ...
+                The execute cycle above goes:
+                    3: S, S, E
+                    5: S, S, S, S, E
+                    1: E
+                    4: S, S, S, E
+    '''
+    def __init__(self, child: py_trees.behaviour.Behaviour,
+                       name: str,
+                       every_x_range: Tuple[int, int],
+                       success_if_skip:bool=False):
+        if every_x_range[0] > every_x_range[1]:
+            raise ValueError('every_x_range must be a tuple with (smaller_number, bigger_number)')
+        if every_x_range[0] < 1:
+            raise ValueError('Can not have range be lower than 1.')
+
+        super(RunEveryX, self).__init__(name=name, child=child)
+        self._every_x_range = every_x_range
+        self._cycles_remaining = random.randint(*self._every_x_range)-1
+        self._success_if_skip = success_if_skip
+
+    def initialise(self):
+        self._cycles_remaining = random.randint(*self._every_x_range)-1
+
+    def tick(self):
+        if self._cycles_remaining > 0:
+            self._cycles_remaining -= 1
+            if self._success_if_skip:
+                self.stop(py_trees.common.Status.SUCCESS)
+            else:
+                self.stop(py_trees.common.Status.FAILURE)
+            yield self
+        else:
+            for node in super().tick():
+                yield node
+
+    def update(self):
+        return self.decorated.status

py_branches/blackboard.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+from typing import Any
+from typing import Optional
+import py_trees
+
+
+def _get_and_check(bb: py_trees.blackboard.Client, var: str, types: Optional[list], logger):
+    try:
+        value = bb.get(var)
+    except KeyError:
+        logger.warning(f'Tried to access blackboard variable {var} but it does not exist.')
+        return None
+    if value is None:
+        logger.warning(f'Tried to access blackboard variable {var} but it does not exist.')
+        return None
+    if types is not None and type(value) not in types:
+        logger.warning(f'Tried to access blackboard variable {var} ' +
+            f'of type {type(value)}, variable must be one of {types}.')
+        return None
+    return value
+
+class IncrementBlackboardVariable(py_trees.behaviour.Behaviour):
+    def __init__(self, name: str, variable_name: str, increment_by: float=1.0):
+        super(IncrementBlackboardVariable, self).__init__(name)
+        self._variable_name = variable_name
+        self._increment_by = increment_by
+        self._return_sucess = False
+        self._blackboard = py_trees.blackboard.Client()
+        self._blackboard.register_key(key=variable_name, access=py_trees.common.Access.WRITE)
+
+    def initialise(self):
+        self._return_sucess = False
+        current_value = _get_and_check(self._blackboard, self._variable_name, [int, float], self.logger)
+        if current_value is None:
+            self.logger.warning(
+                f'Failed to increment blackboard variable {self._variable_name}: value missing or invalid.'
+            )
+            return
+        self._blackboard.set(self._variable_name, current_value+self._increment_by)
+        self._return_sucess = True
+
+    def update(self):
+        if self._return_sucess:
+            return py_trees.common.Status.SUCCESS
+        else:
+            return py_trees.common.Status.FAILURE
+
+class IncrementBlackboardVariableIfCondition(py_trees.decorators.Decorator):
+    def __init__(self, child, name: str, variable_name: str, condition: py_trees.common.Status, increment_by: float=1.0):
+        super(IncrementBlackboardVariableIfCondition, self).__init__(name=name, child=child)
+        self._variable_name = variable_name
+        self._condition = condition
+        self._increment_by = increment_by
+        self._blackboard = py_trees.blackboard.Client()
+        self._blackboard.register_key(key=variable_name, access=py_trees.common.Access.WRITE)
+
+    def update(self):
+        if self.decorated.status == self._condition:
+            current_value = _get_and_check(self._blackboard, self._variable_name, [int, float], self.logger)
+            if current_value is not None:
+                self._blackboard.set(self._variable_name, current_value+self._increment_by, overwrite=True)
+
+        return self.decorated.status
+
+class SetBlackboardVariableIfCondition(py_trees.decorators.Decorator):
+    def __init__(self, child, name: str, variable_name: str, condition: py_trees.common.Status, set_to: Any):
+        super(SetBlackboardVariableIfCondition, self).__init__(name=name, child=child)
+        self._variable_name = variable_name
+        self._condition = condition
+        self._set_to = set_to
+        self._blackboard = py_trees.blackboard.Client()
+        self._blackboard.register_key(key=variable_name, access=py_trees.common.Access.WRITE)
+
+    def update(self):
+        if self.decorated.status == self._condition:
+            self._blackboard.set(self._variable_name, self._set_to, overwrite=True)
+
+        return self.decorated.status
+
+class RunIfBlackboardVariableEquals(py_trees.decorators.Decorator):
+    def __init__(self, child, name: str, variable_name: str, equals: Any, success_if_skip: bool=True):
+        super(RunIfBlackboardVariableEquals, self).__init__(name=name, child=child)
+        self._variable_name = variable_name
+        self._equals = equals
+        self._blackboard = py_trees.blackboard.Client()
+        self._blackboard.register_key(key=variable_name, access=py_trees.common.Access.READ)
+        self._run_child = False
+        self._ret_status_on_failure = py_trees.common.Status.SUCCESS if success_if_skip else py_trees.common.Status.FAILURE
+
+    def tick(self):
+        # Re-evaluate the condition on each fresh entry; preserve it while child is RUNNING.
+        if self.status != py_trees.common.Status.RUNNING:
+            current_value = _get_and_check(self._blackboard, self._variable_name, None, self.logger)
+            self._run_child = current_value == self._equals
+
+        if self._run_child:
+            for node in py_trees.decorators.Decorator.tick(self):
+                yield node
+        else:
+            for node in py_trees.behaviour.Behaviour.tick(self):
+                yield node
+
+    def update(self):
+        if self._run_child:
+            if self.decorated.status != py_trees.common.Status.RUNNING:
+                self._run_child = False
+            return self.decorated.status
+        else:
+            self._run_child = False
+            return self._ret_status_on_failure

py_branches/cooldown.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+import time
+import py_trees
+
+
+class Cooldown(py_trees.decorators.Decorator):
+    '''
+    Prevents a child from running again until a cooldown period has elapsed
+    after its last completion.
+
+    The child runs normally on the first tick.  Once it completes (SUCCESS or
+    FAILURE), a cooldown timer starts.  During the cooldown, the child is not
+    ticked and this decorator returns FAILURE (or SUCCESS if
+    success_if_cooling=True).  After the cooldown expires the child may run
+    again.
+
+    A child that stays RUNNING is never subject to the cooldown — the timer
+    only starts once the child actually finishes.
+
+    Args:
+        child (Behaviour): The child behavior to rate-limit.
+        name (str): Name of this decorator.
+        duration (float): Cooldown period in seconds after each completion.
+        success_if_cooling (bool): Return SUCCESS instead of FAILURE while
+            cooling down.  Default False.
+
+    Example:
+        child = py_trees.behaviours.Success(name="Expensive")
+        # Run child freely, but enforce a 5-second gap between executions.
+        cooled = Cooldown(child, name="Cooldown", duration=5.0)
+    '''
+    def __init__(self, child: py_trees.behaviour.Behaviour,
+                       name: str,
+                       duration: float,
+                       success_if_cooling: bool = False):
+        if duration <= 0.0:
+            raise ValueError(f'duration({duration}) must be positive.')
+        super(Cooldown, self).__init__(name=name, child=child)
+        self._duration = duration
+        self._success_if_cooling = success_if_cooling
+        self._cooling = False
+        self._cool_start = None
+
+    def tick(self):
+        if self._cooling:
+            elapsed = time.time() - self._cool_start
+            if elapsed < self._duration:
+                if self._success_if_cooling:
+                    self.stop(py_trees.common.Status.SUCCESS)
+                else:
+                    self.stop(py_trees.common.Status.FAILURE)
+                yield self
+                return
+            else:
+                self._cooling = False
+
+        for node in super().tick():
+            yield node
+
+    def update(self) -> py_trees.common.Status:
+        status = self.decorated.status
+        if status != py_trees.common.Status.RUNNING:
+            self._cooling = True
+            self._cool_start = time.time()
+        return status

py_branches/counter.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+import py_trees
+
+
+class Counter(py_trees.decorators.Decorator):
+    '''
+    Runs a child behavior exactly num_runs times (total completions), then
+    permanently returns completion_status without ever running the child again.
+
+    A "completion" is any tick where the child returns SUCCESS or FAILURE.
+    RUNNING ticks do not count — the counter waits for the child to finish each
+    run before counting it.
+
+    The run count and done flag persist across tree re-entries (i.e. they are
+    NOT reset by initialise()).  This makes Counter suitable for one-time
+    initialization sequences.  To reset and re-count, call reset() explicitly.
+
+    Args:
+        child (Behaviour): The child behavior to count.
+        name (str): Name of this decorator.
+        num_runs (int): Total number of child completions to allow.
+        completion_status (Status): Status returned permanently once num_runs
+            completions have occurred.  Default SUCCESS.
+
+    Example:
+        child = InitializationBehavior(name="Init")
+        # Run Init exactly once; after it completes, always return SUCCESS.
+        counted = Counter(child, name="RunOnce", num_runs=1)
+
+        child = CalibrateStep(name="Calibrate")
+        # Run calibration exactly 3 times, then always return SUCCESS.
+        counted = Counter(child, name="Calibrate3x", num_runs=3)
+    '''
+    def __init__(self, child: py_trees.behaviour.Behaviour,
+                       name: str,
+                       num_runs: int,
+                       completion_status: py_trees.common.Status = py_trees.common.Status.SUCCESS):
+        if num_runs < 1:
+            raise ValueError(f'num_runs({num_runs}) must be greater than 0.')
+        super(Counter, self).__init__(name=name, child=child)
+        self._num_runs = num_runs
+        self._completion_status = completion_status
+        self._runs_completed = 0
+        self._done = False
+
+    def reset(self) -> None:
+        '''Reset the run count so the child will be run num_runs times again.'''
+        self._runs_completed = 0
+        self._done = False
+
+    def tick(self):
+        if self._done:
+            self.stop(self._completion_status)
+            yield self
+        else:
+            for node in super().tick():
+                yield node
+
+    def update(self) -> py_trees.common.Status:
+        status = self.decorated.status
+        if status == py_trees.common.Status.RUNNING:
+            return py_trees.common.Status.RUNNING
+
+        # Child completed this tick (SUCCESS or FAILURE).
+        self._runs_completed += 1
+        if self._runs_completed >= self._num_runs:
+            self._done = True
+            self.decorated.stop(py_trees.common.Status.INVALID)
+            return self._completion_status
+
+        # More runs remain — reset child so it re-runs next tick.
+        self.decorated.stop(py_trees.common.Status.INVALID)
+        return py_trees.common.Status.RUNNING

py_branches/latch.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+import py_trees
+
+
+class Latch(py_trees.decorators.Decorator):
+    '''
+    Once the child returns SUCCESS, latches to SUCCESS and stops re-running
+    the child until reset() is called.
+
+    - While unlatched: child is ticked normally and its status is passed through.
+    - On first SUCCESS from child: latch engages.
+    - While latched: child is NOT ticked; this decorator returns SUCCESS.
+    - On reset(): latch disengages and the child will run again on the next tick.
+
+    The latch state persists across tree re-entries (i.e. it is NOT cleared by
+    initialise()).  To get a fresh latch, call reset() explicitly.
+
+    Args:
+        child (Behaviour): The child behavior to latch.
+        name (str): Name of this decorator.
+
+    Example:
+        child = ExpensiveSetupBehavior(name="Setup")
+        # Run setup once; once it succeeds, always return SUCCESS without
+        # re-running it.
+        latched = Latch(child, name="Latch")
+
+        # Later, to trigger a re-run:
+        latched.reset()
+    '''
+    def __init__(self, child: py_trees.behaviour.Behaviour,
+                       name: str):
+        super(Latch, self).__init__(name=name, child=child)
+        self._latched = False
+
+    def reset(self) -> None:
+        '''Disengage the latch so the child will run again on the next tick.'''
+        self._latched = False
+
+    def tick(self):
+        if self._latched:
+            self.stop(py_trees.common.Status.SUCCESS)
+            yield self
+        else:
+            for node in super().tick():
+                yield node
+
+    def update(self) -> py_trees.common.Status:
+        if self.decorated.status == py_trees.common.Status.SUCCESS:
+            self._latched = True
+        return self.decorated.status

py_branches/pause.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+import logging
+import time
+import py_trees
+import datetime
+import random
+import yaml
+import os
+from typing import Dict
+from typing import List
+
+
+HOUR2SEC = 3600
+MIN2SEC = 60
+
+
+class PauseUniform(py_trees.behaviour.Behaviour):
+    def __init__(self, name: str, low: float, high: float):
+        super(PauseUniform, self).__init__(name=name)
+        self._high = high
+        self._low = low
+
+    def initialise(self):
+        self._pause_t = random.uniform(self._low, self._high)
+        self._start_t = time.time()
+
+    def update(self):
+        t_elapse = time.time() - self._start_t
+        if t_elapse < self._pause_t:
+            return py_trees.common.Status.RUNNING
+        else:
+            return py_trees.common.Status.SUCCESS
+
+def load_schedule_file(schedule_filepath: str):
+    if not os.path.isfile(schedule_filepath):
+        raise FileNotFoundError(f'schedule_filepath: {schedule_filepath} is not a valid file')
+    
+    with open(schedule_filepath, 'r') as schedule_file:
+        schedule_raw = yaml.safe_load(schedule_file)
+
+    schedule = []
+    for schedule_element_raw in schedule_raw:
+        start_pause_time = datetime.datetime.strptime(schedule_element_raw['start_pause_time'], '%H:%M:%S').time()
+        stop_pause_time = datetime.datetime.strptime(schedule_element_raw['stop_pause_time'], '%H:%M:%S').time()
+        variance_time = datetime.datetime.strptime(schedule_element_raw['variance'], '%H:%M:%S').time()
+        schedule.append({'start_pause_time': start_pause_time,
+                         'stop_pause_time': stop_pause_time,
+                         'variance_time': variance_time,
+                         'start_plus_variance_time': add_variance_to_datetime_time(start_pause_time, variance_time),
+                         'stop_plus_variance_time': add_variance_to_datetime_time(stop_pause_time, variance_time)})
+    return schedule
+
+class CheckPauseSchedule(py_trees.behaviour.Behaviour):
+    def __init__(self, name: str, schedule):
+        self._schedule = schedule
+        self._last_schedule_idx = None
+        super(CheckPauseSchedule, self).__init__(name=name)
+
+    def update(self):
+        now_time = datetime.datetime.now().time()
+        matched_schedule_idx = None
+        for idx, schedule_element in enumerate(self._schedule):
+            start = schedule_element['start_plus_variance_time']
+            stop = schedule_element['stop_plus_variance_time']
+            if (start < stop and start < now_time < stop) or \
+               (start > stop and (now_time > start or now_time < stop)):
+                matched_schedule_idx = idx
+                break
+
+        # Re-arm once we've left all windows.
+        if matched_schedule_idx is None:
+            self._last_schedule_idx = None
+            return py_trees.common.Status.FAILURE
+
+        # Prevent repeated SUCCESS ticks while remaining in the same window.
+        if matched_schedule_idx == self._last_schedule_idx:
+            return py_trees.common.Status.FAILURE
+
+        self._last_schedule_idx = matched_schedule_idx
+        return py_trees.common.Status.SUCCESS
+
+def datetime_time_to_sec(t: datetime.time):
+    sec = t.hour*HOUR2SEC+t.minute*MIN2SEC+t.second
+    return sec
+
+def add_variance_to_datetime_time(t: datetime.time, variance_time: datetime.time) -> datetime.time:
+    variance_sec = datetime_time_to_sec(variance_time)
+    variance_timedelta = datetime.timedelta(seconds=random.uniform(0.0, variance_sec))
+    time_to_datetime = datetime.datetime.combine(datetime.date.today(), t)
+    time_with_variance = (time_to_datetime + variance_timedelta).time()
+    return time_with_variance
+
+class PauseSchedule(py_trees.behaviour.Behaviour):
+    def __init__(self, name: str, schedule: List[Dict[str, datetime.time]]):
+        self._schedule = schedule
+        super(PauseSchedule, self).__init__(name=name)
+
+    def initialise(self):
+        super().initialise()
+        self._t_wait = None
+        self._t_start = time.time()
+        now_time = datetime.datetime.now().time()
+        for schedule_element in self._schedule:
+            start = schedule_element['start_plus_variance_time']
+            stop = schedule_element['stop_plus_variance_time']
+            variance = schedule_element['variance_time']
+            if (start < stop and start < now_time < stop) or \
+               (start > stop and (now_time > start or now_time < stop)):
+                if now_time < stop:
+                    self._t_wait = datetime_time_to_sec(stop) - \
+                                   datetime_time_to_sec(now_time)
+                else:
+                    self._t_wait = datetime_time_to_sec(datetime.time(23, 59, 59)) + 1 - \
+                                   datetime_time_to_sec(now_time) + \
+                                   datetime_time_to_sec(stop)
+                self._t_start = time.time()
+                logging.info(f'Wait has been scheduled for  {self._t_wait:.3f} sec')
+                schedule_element['start_plus_variance_time'] = \
+                    add_variance_to_datetime_time(schedule_element['start_pause_time'], variance)
+                schedule_element['stop_plus_variance_time'] = \
+                    add_variance_to_datetime_time(schedule_element['stop_pause_time'], variance)
+                logging.info(f'new start_plus_variance_time: {schedule_element["start_plus_variance_time"]}')
+                logging.info(f'new stop_plus_variance_time: {schedule_element["stop_plus_variance_time"]}')
+                break
+
+    def update(self):
+        if self._t_wait is None:
+            return py_trees.common.Status.SUCCESS
+
+        t_elapse = time.time() - self._t_start
+        if t_elapse < self._t_wait:
+            return py_trees.common.Status.RUNNING
+        else:
+            return py_trees.common.Status.SUCCESS

py_branches/random.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+
+import py_trees
+import random
+import logging
+import time
+from typing import List
+
+
+class RandomRun(py_trees.decorators.Decorator):
+    '''
+    Random chance of running the child of this decorator.
+    '''
+    def __init__(self, child, name, probability: float, success_if_skip: bool = False):
+        if not (0 <= probability <= 1.0):
+            raise ValueError(f'Probability == {probability} but needs to be in range [0, 1.0]')
+        super(RandomRun, self).__init__(name=name, child=child)
+        self._probability = probability
+        self._run = None  # rolled on first tick; terminate() handles all subsequent rolls
+        self._success_if_skip = success_if_skip
+
+    def tick(self):
+        if self._run is None:
+            self._run = random.random() <= self._probability
+        if not self._run:
+            for node in py_trees.behaviour.Behaviour.tick(self):
+                yield node
+        else:
+            for node in super().tick():
+                yield node
+
+    def update(self):
+        if self._run:
+            return self.decorated.status
+        else:
+            if self._success_if_skip:
+                return py_trees.common.Status.SUCCESS
+            else:
+                return py_trees.common.Status.FAILURE
+
+    def terminate(self, new_status: py_trees.common.Status) -> None:
+        self._run = random.random() <= self._probability
+
+class RandomDelay(py_trees.decorators.Decorator):
+    '''
+    Waits a random duration before running the child on each fresh entry.
+
+    On every fresh entry (i.e. when the decorator was not already RUNNING),
+    a delay is sampled uniformly from [low, high] seconds.  The decorator
+    stays RUNNING without ticking the child until the delay has elapsed, then
+    passes through to the child normally.
+
+    The delay is re-sampled on every new entry, so repeated executions each
+    get independent jitter.  This is useful for desynchronising multiple
+    agents that share the same tree structure.
+
+    Args:
+        child (Behaviour): The child behavior to delay.
+        name (str): Name of this decorator.
+        low (float): Minimum delay in seconds (>= 0).
+        high (float): Maximum delay in seconds (>= low).
+
+    Example:
+        child = py_trees.behaviours.Success(name="Action")
+        # Pause 0.5–2.0 seconds before running the child each time.
+        delayed = RandomDelay(child, name="RandomDelay", low=0.5, high=2.0)
+    '''
+    def __init__(self, child: py_trees.behaviour.Behaviour,
+                       name: str,
+                       low: float,
+                       high: float):
+        if low < 0.0:
+            raise ValueError(f'low({low}) must be >= 0.')
+        if low > high:
+            raise ValueError(f'low({low}) must be <= high({high}).')
+        super(RandomDelay, self).__init__(name=name, child=child)
+        self._low = low
+        self._high = high
+        self._delay = 0.0
+        self._start_time = None
+        self._waiting = False
+
+    def tick(self):
+        # Fresh entry: sample a new delay and start the timer.
+        if self.status != py_trees.common.Status.RUNNING:
+            self._delay = random.uniform(self._low, self._high)
+            self._start_time = time.time()
+            self._waiting = True
+
+        if self._waiting:
+            if time.time() - self._start_time < self._delay:
+                self.status = py_trees.common.Status.RUNNING
+                yield self
+                return
+            self._waiting = False
+
+        for node in super().tick():
+            yield node
+
+    def update(self) -> py_trees.common.Status:
+        return self.decorated.status
+
+
+def random_selector(name, behaviors: List[py_trees.behaviour.Behaviour], probabilities: List[float]):
+    if abs(sum(probabilities) - 1.0) >= 1e-9:
+        raise ValueError(f'sum(probabilities) must add up to 1.0, got {sum(probabilities)}')
+    if len(probabilities) != len(behaviors):
+        raise ValueError('len(probabilities) != len(behaviors), two lists must be of same length.')
+
+    children = []
+    new_probabilities = []
+    cumulative_prob = 0.0
+    for behavior, raw_prob in zip(behaviors, probabilities):
+        new_prob = raw_prob/(1.0-cumulative_prob)
+        if new_prob >= 1.0:
+            children.append(behavior)
+            break
+
+        new_probabilities.append(new_prob)
+        decorated_behavior_name = f'random_run_{behavior.name}'
+        decorated_behavior = RandomRun(name=decorated_behavior_name,
+                                       child=behavior,
+                                       probability=new_prob)
+        children.append(decorated_behavior)
+
+        cumulative_prob += raw_prob
+
+    logging.debug(f'behaviors->new_probabilities: {[b.name for b in behaviors]}->{new_probabilities}')
+
+    selector = py_trees.composites.Selector(name, False, children)
+    return selector

py_branches/retry.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+import time
+import py_trees
+
+
+class Retry(py_trees.decorators.Decorator):
+    '''
+    Retries a child behavior on FAILURE up to max_attempts times.
+
+    Returns SUCCESS if the child ever succeeds, FAILURE once all attempts
+    are exhausted.  Stays RUNNING between attempts (and during optional
+    delay between retries).
+
+    Args:
+        child (Behaviour): The child behavior to retry.
+        name (str): Name of this decorator.
+        max_attempts (int): Maximum number of times to attempt the child.
+        delay (float): Seconds to wait between retry attempts. Default 0.0.
+
+    Example:
+        child = py_trees.behaviours.Failure(name="Flaky")
+        # Try up to 3 times; fails permanently after 3 failures.
+        retry = Retry(child, name="Retry", max_attempts=3)
+
+        child = py_trees.behaviours.Failure(name="Flaky")
+        # Try up to 3 times with 1 second between each attempt.
+        retry = Retry(child, name="RetryWithDelay", max_attempts=3, delay=1.0)
+    '''
+    def __init__(self, child: py_trees.behaviour.Behaviour,
+                       name: str,
+                       max_attempts: int,
+                       delay: float = 0.0):
+        if max_attempts < 1:
+            raise ValueError(f'max_attempts({max_attempts}) must be greater than 0.')
+        if delay < 0.0:
+            raise ValueError(f'delay({delay}) must be non-negative.')
+        super(Retry, self).__init__(name=name, child=child)
+        self._max_attempts = max_attempts
+        self._delay = delay
+        self._attempts = 0
+        self._waiting = False
+        self._wait_start = None
+
+    def initialise(self) -> None:
+        self._attempts = 0
+        self._waiting = False
+        self._wait_start = None
+
+    def tick(self):
+        if self._waiting:
+            elapsed = time.time() - self._wait_start
+            if elapsed < self._delay:
+                self.status = py_trees.common.Status.RUNNING
+                yield self
+                return
+            else:
+                self._waiting = False
+                self.decorated.stop(py_trees.common.Status.INVALID)
+        for node in super().tick():
+            yield node
+
+    def update(self) -> py_trees.common.Status:
+        if self.decorated.status == py_trees.common.Status.SUCCESS:
+            return py_trees.common.Status.SUCCESS
+        elif self.decorated.status == py_trees.common.Status.RUNNING:
+            return py_trees.common.Status.RUNNING
+        else:  # FAILURE
+            self._attempts += 1
+            if self._attempts < self._max_attempts:
+                if self._delay > 0.0:
+                    self._waiting = True
+                    self._wait_start = time.time()
+                else:
+                    self.decorated.stop(py_trees.common.Status.INVALID)
+                return py_trees.common.Status.RUNNING
+            else:
+                return py_trees.common.Status.FAILURE

py_branches/timeout.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+import time
+import py_trees
+
+
+class Timeout(py_trees.decorators.Decorator):
+    '''
+    Fails a child behavior if it stays RUNNING beyond the specified duration.
+
+    - If the child returns SUCCESS or FAILURE before the timeout, that
+      status is passed through unchanged.
+    - If the child is still RUNNING when the timeout expires, the child is
+      stopped and FAILURE is returned.
+
+    Args:
+        child (Behaviour): The child behavior to wrap with a timeout.
+        name (str): Name of this decorator.
+        duration (float): Maximum seconds the child may remain RUNNING.
+
+    Example:
+        child = LongRunningBehavior(name="Slow")
+        # Fail if child does not complete within 5 seconds.
+        guarded = Timeout(child, name="Timeout", duration=5.0)
+    '''
+    def __init__(self, child: py_trees.behaviour.Behaviour,
+                       name: str,
+                       duration: float):
+        if duration <= 0.0:
+            raise ValueError(f'duration({duration}) must be positive.')
+        super(Timeout, self).__init__(name=name, child=child)
+        self._duration = duration
+        self._start_time = None
+
+    def initialise(self) -> None:
+        self._start_time = time.time()
+
+    def update(self) -> py_trees.common.Status:
+        if self.decorated.status != py_trees.common.Status.RUNNING:
+            return self.decorated.status
+
+        elapsed = time.time() - self._start_time
+        if elapsed >= self._duration:
+            self.decorated.stop(py_trees.common.Status.INVALID)
+            return py_trees.common.Status.FAILURE
+        return py_trees.common.Status.RUNNING

py_branches-1.2.1.dist-info/LICENSE

@@ -0,0 +1,31 @@
+# Software License Agreement (BSD License)
+#
+# Copyright (c) 2024 Shunong Wu
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+#    * Redistributions of source code must retain the above copyright
+#        notice, this list of conditions and the following disclaimer.
+#    * Redistributions in binary form must reproduce the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer in the documentation and/or other materials provided
+#        with the distribution.
+#    * Neither the name of the copyright holder nor the names of its
+#        contributors may be used to endorse or promote products derived
+#        from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.

py_branches-1.2.1.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.1
+Name: py_branches
+Version: 1.2.1
+Summary: Useful behaviors built on top of the py_trees library.
+Home-page: https://github.com/snwu1996/py_branches
+License: BSD
+Author: Shunong Wu
+Author-email: shunongwu@gmail.com
+Requires-Python: >=3.8
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: py-trees
+Requires-Dist: pyyaml
+Project-URL: Repository, https://github.com/snwu1996/py_branches
+Description-Content-Type: text/markdown
+
+# py_branches
+
+`py_branches` provides higher-level functionality designed to sit on top of the [py_trees](https://py-trees.readthedocs.io/) library. It extends py_trees with reusable behaviors and decorators for common patterns such as alternating execution, probabilistic selection, blackboard-driven conditionals, and time-based pausing.
+
+## Installation
+
+**From PyPI:**
+```bash
+pip install py_branches
+```
+
+**From source (editable):**
+```bash
+git clone https://github.com/snwu1996/py_branches.git
+cd py_branches
+pip install -e .
+```
+
+## Modules
+
+| Module | Description |
+|---|---|
+| `alternating` | Cycle through behaviors in fixed patterns or run a child every N ticks |
+| `blackboard` | Read/write/gate behaviors based on py_trees blackboard variables |
+| `pause` | Time-based pauses — uniform random duration or YAML-defined schedules |
+| `random` | Probabilistic behavior execution and weighted random selectors |
+
+## Basic Usage
+
+### Alternating — cycle through behaviors
+
+```python
+import py_trees
+from py_branches.alternating import run_alternating
+
+a = py_trees.behaviours.Success(name="A")
+b = py_trees.behaviours.Success(name="B")
+c = py_trees.behaviours.Success(name="C")
+
+# Run A for 3 ticks, then B for 2 ticks, then C for 4 ticks, then repeat
+root = run_alternating("Alternating", [a, b, c], [3, 2, 4])
+```
+
+### Alternating — run a child every N ticks
+
+```python
+from py_branches.alternating import RunEveryX, RunEveryRange
+
+child = py_trees.behaviours.Success(name="Child")
+
+# Run child every 5th tick
+every_5 = RunEveryX(child, name="Every5", every_x_range=(5, 5))
+
+# Run child only on iterations 4–6 out of every 10
+windowed = RunEveryRange(child, name="Window", max_range=10, run_range=(4, 6))
+```
+
+### Blackboard — conditional execution and variable management
+
+```python
+import py_trees
+from py_branches.blackboard import (
+    IncrementBlackboardVariable,
+    RunIfBlackboardVariableEquals,
+    SetBlackboardVariableIfCondition,
+)
+
+# Set up blackboard
+py_trees.blackboard.Blackboard.enable_activity_stream()
+client = py_trees.blackboard.Client(name="setup")
+client.register_key("counter", access=py_trees.common.Access.WRITE)
+client.counter = 0
+
+# Increment a blackboard counter each tick
+increment = IncrementBlackboardVariable(
+    name="Increment", variable_name="counter", increment_by=1
+)
+
+# Only run a child behavior when counter == 5
+child = py_trees.behaviours.Success(name="AtFive")
+gate = RunIfBlackboardVariableEquals(
+    child, name="RunAt5", variable_name="counter", equals=5
+)
+```
+
+### Pause — random duration pause
+
+```python
+from py_branches.pause import PauseUniform
+
+# Pause for a random duration between 1.0 and 3.0 seconds
+pause = PauseUniform(name="RandomPause", low=1.0, high=3.0)
+```
+
+### Pause — schedule-based pause
+
+```python
+from py_branches.pause import load_schedule_file, CheckPauseSchedule, PauseSchedule
+
+schedule = load_schedule_file("configs/schedules/example_schedule.yaml")
+
+# Returns SUCCESS when the current time falls inside a scheduled window
+check = CheckPauseSchedule(name="CheckSchedule", schedule=schedule)
+
+# Pauses until the current scheduled window ends
+pause = PauseSchedule(name="PauseSchedule", schedule=schedule)
+```
+
+### Random — probabilistic execution
+
+```python
+import py_trees
+from py_branches.random import RandomRun, random_selector
+
+child = py_trees.behaviours.Success(name="Child")
+
+# Execute child with 70% probability; return FAILURE otherwise
+maybe = RandomRun(child, name="Maybe", probability=0.7)
+
+# Weighted random selector: a=20%, b=30%, c=50%
+a = py_trees.behaviours.Success(name="A")
+b = py_trees.behaviours.Success(name="B")
+c = py_trees.behaviours.Success(name="C")
+selector = random_selector("WeightedSel", [a, b, c], [0.2, 0.3, 0.5])
+```
+
+## Running Tests
+
+```bash
+pytest tests/
+```
+
+## Documentation
+
+Detailed documentation for each module is in the [`docs/`](docs/) folder:
+
+- [alternating.md](docs/alternating.md) — Alternating and periodic execution
+- [blackboard.md](docs/blackboard.md) — Blackboard-driven behaviors
+- [pause.md](docs/pause.md) — Time-based pausing and schedules
+- [random.md](docs/random.md) — Probabilistic execution
+
+## License
+
+BSD License. See [LICENSE](LICENSE) for details.
+

py_branches-1.2.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+py_branches/__init__.py,sha256=f9w3Ws8Mp0lFK2bzr7EqGpxAfLLTQZ11htZSXUm7C5s,199
+py_branches/alternating.py,sha256=E9myfYWO3ObYQHEvb9IP7JwhUvlaPCQnPcAT3wMQVtQ,8666
+py_branches/blackboard.py,sha256=Kc_7EQmmz4VPpPGdJ-KhlIGY_Z2z3iLmrjZKSXHJqLY,5032
+py_branches/cooldown.py,sha256=gpN_UAfYXd9h4K6IM_zkWqWzlyy5KqYweCxUuvFuiX8,2423
+py_branches/counter.py,sha256=zI0umT3ZS8Qd68e9SetrXwhPCeQTFlJQSWgadOp_GHo,2934
+py_branches/latch.py,sha256=mKpBucyzO7YI-h5tsLXG6dsaozBKuRjWgkR4vLRaqFw,1754
+py_branches/pause.py,sha256=a3FLDw6spmDHFpFny19QMJqmzjrX150-EqBT6htw9SQ,5801
+py_branches/random.py,sha256=CivVLpzfYGMPWT04SdQz8p9um8OAXz6KRk7hLAU6uJE,4874
+py_branches/retry.py,sha256=PRUlIAKHSwItuTL4fZM8UEaFCzDV_DGWJvIggwwe1JY,2923
+py_branches/timeout.py,sha256=O1ih80zPbN4yMEzftzrQ2JaPCMuyShnhUUv1icKVMXY,1647
+py_branches-1.2.1.dist-info/LICENSE,sha256=6_acK5mJZz0h1RKJeUWRAgI-X-z8Swz3d3TjFwu4SQw,1624
+py_branches-1.2.1.dist-info/METADATA,sha256=qVG5wEB4javTVwnC8VUbQTvRwzqrNZepbmW9jPiaJIM,5286
+py_branches-1.2.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+py_branches-1.2.1.dist-info/RECORD,,

py_branches-1.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any