[schedy] Simplified internal handling of IncludeSchedule

Author: Robert Schindler

docs/apps/schedy/CHANGELOG.md

@@ -19,6 +19,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 * Infinite retrying of value sending to an actor is no longer supported, meaning
   `send_retries: -1` is now a configuration error. Use a reasonably high value
   instead if you really need excessive retrying.
+* Simplified internal handling of `IncludeSchedule()`. If this causes problems with
+  existing configurations, please file an issue.
 
 ### Deprecated
 

docs/apps/schedy/schedules/expressions/examples.rst

@@ -224,91 +224,6 @@ weather sensors.
    readable as they grow.
 
 
-.. _schedy/schedules/expressions/examples/include-schedule/cycles:
-
-Cycles
-~~~~~~
-
-.. include:: /advanced-topic.rst.inc
-
-Schedy prevents you from creating cycles when using ``IncludeSchedule()``,
-that would lead to infinite recursion.
-
-Take this example. It's quite useless, but simple enough for demonstration
-purposes.
-
-::
-
-    schedule_snippets:
-      snippet:
-      - x: "IncludeSchedule(schedule_snippets['snippet'])"
-        name: snippet rule 1
-
-    schedule_prepend:
-    - v: 21
-      rules:
-      - x: "IncludeSchedule(schedule_snippets['snippet'])"
-
-The ``IncludeSchedule()`` returned by ``snippet rule 1`` is not
-considered, because doing so would lead to an infinite recursion. It is
-treated as if it was ``Inherit()``, what then causes value lookup to be
-continued at the next parent, resulting in ``21`` .
-
-Here's another, more useful example, inspired by my own configuration,
-which makes the benefits of this behaviour more obvious.
-
-::
-
-    schedule_snippets:
-      somebody_home:
-      - x: "Inherit() if is_on('input_boolean.awake') else Next()"
-        name: always heat when awake switch is on
-      - weekdays: 1-5
-        name: normal working days
-        rules:
-        - { start: "07:00", end: "09:00" }
-        - { start: "16:00", end: "22:00" }
-
-    schedule_prepend:
-    - v: 15
-
-    watched_entities:
-    - "input_boolean.awake"
-
-    rooms:
-      living:
-        schedule:
-        - v: 22
-          rules:
-          - x: "IncludeSchedule(schedule_snippets['somebody_home'])"
-
-      office:
-        schedule:
-        - v: 20
-          rules:
-          - x: "IncludeSchedule(schedule_snippets['somebody_home'])"
-            name: include somebody_home snippet
-            rules:
-            - { start: "06:00", end: "18:00", name: "stop at 6.00 pm" }
-
-I'm not going to describe what every single rule does. If you want to
-see the actual evaluation flow, put it into your configuration and turn
-on the debug logging.
-
-What I do want to highlight is that each room can have it's own heating
-temperature, without having to define the times redundantly. I can even
-limit the ``office`` to heat no longer than until ``18:00``, and that's
-where the magic kicks in. The ``stop at 6.00 pm`` rule inherits its result
-from its parent rule (``include somebody_home snippet``), which causes the
-``somebody_home`` snippet to be inserted and evaluated. Now, we assume
-that ``always heat when awake switch is on`` returns ``Inherit()``,
-which again causes its parent's value to be used. The nearest parent
-with a value again is ``include somebody_home snippet`` - and there we
-would get an infinite recursion. But Schedy is smart enough to notice that
-we're already inside the ``somebody_home`` snippet and just takes the next
-parent's value, which is ``20`` and exactly what we want. Problem solved.
-
-
 What to Use ``Abort()`` for
 ---------------------------
 

docs/apps/schedy/schedules/expressions/index.rst

@@ -20,7 +20,6 @@ make their later evaluation really performant.
    helpers/index
    postprocessors
    result-markers
-   sub-schedules
 
 
 Security Considerations

docs/apps/schedy/schedules/expressions/sub-schedules.rst

@@ -86,12 +86,46 @@ processed.
 * ``Break(levels=1)``, which causes lookup of one (or multiple nested)
   sub-schedule(s) to be aborted immediately. The evaluation will continue
   after the sub-schedule(s).
-* ``IncludeSchedule(schedule)``, which dynamically inserts the given
-  schedule object as a sub-schedule after the current rule.
+* ``IncludeSchedule(schedule)``, which dynamically inserts a sub-schedule rule with
+  the given ``Schedule`` object after the current rule. Especially, ``Break()`` and
+  ``Inherit()`` in included schedules do behave as if the included schedule was a
+  regular sub-schedule.
 * ``Inherit()``, which causes the value or expression of the nearest
   ancestor rule to be used as result for the current rule. See the next
   section for a more detailed explanation.
 * ``Next()``, which causes the rule to be treated as if it didn't exist
   at all. If one exists, the next rule is evaluated in this case.
 
 For all of these types, :doc:`usage examples <examples>` are provided.
+
+
+Expressions and Sub-Schedules
+-----------------------------
+
+In general, there is no difference between using plain values and advanced
+expressions in both rules with a sub-schedule attached to them (so-called
+sub-schedule rules) and the rules contained in these sub-schedules. But
+with expressions, you gain a lot more flexibility.
+
+As you know from :ref:`schedy/schedules/basics/rules-with-sub-schedules`,
+rules of sub-schedules inherit their ``v`` parameter from the nearest
+ancestor rule having it defined, should they miss an own one. Basically,
+this is true for the ``x`` parameter as well.
+
+With an expression as the ``x`` value of the rule inside a sub-schedule,
+you get the flexibility to conditionally overwrite the ancestor rule's
+value or expression. Should an expression return ``Inherit()``, the next
+ancestor rule's value or expression is used. When compared to static
+values, returning ``Inherit()`` is the equivalent of omitting the ``v``
+parameter completely, but with the benefit of deciding dynamically about
+whether to omit it or not.
+
+The whole process can be described as follows. To find the result for
+a particular rule inside a sub-schedule, the ``v``/``x`` parameters of
+the rule and it's ancestor rules are evaluated from inside to outside
+(from right to left when looking at the indentation of the YAML syntax)
+until one results in something different to ``Inherit()``.
+
+``Inherit()`` even works accross the boundaries of a schedule snippet, because Schedy
+internally converts a rule which returned ``IncludeSchedule()`` into a sub-schedule
+rule, with the included schedule attached to it.

docs/apps/schedy/schedules/expressions/writing-expressions.rst

@@ -261,10 +261,8 @@ def extend(self, rules: T.Iterable[Rule]) -> None:
 
     def includes_schedule(self, schedule: "Schedule") -> bool:
         """Checks whether the given schedule is included in this path."""
-
         if schedule is self.root_schedule:
             return True
-
         for rule in self.rules:
             if isinstance(rule, SubScheduleRule) and rule.sub_schedule is schedule:
                 return True
@@ -474,6 +472,9 @@ def log(msg: str, path: RulePath, *args: T.Any, **kwargs: T.Any) -> None:
                         result = room.eval_expr(rule.expr, expr_env)
                         expr_cache[rule.expr] = result
                         log("=> {}".format(repr(result)), path, level="DEBUG")
+                        # Unwrap a result with markers
+                        if isinstance(result, expression.types.Mark):
+                            result = result.unwrap(markers)
                     else:
                         log(
                             "=> {}  [cache-hit]".format(repr(result)),
@@ -490,29 +491,23 @@ def log(msg: str, path: RulePath, *args: T.Any, **kwargs: T.Any) -> None:
                     result = rule.value
                     log("=> {}".format(repr(result)), path, level="DEBUG")
 
-                # Unwrap a result with markers
-                if isinstance(result, expression.types.Mark):
-                    result = result.unwrap(markers)
-
                 if isinstance(
                     result, expression.types.IncludeSchedule
                 ) and path.includes_schedule(result.schedule):
-                    # Prevent reusing IncludeSchedule results that would
-                    # lead to a cycle. This happens when a rule of an
-                    # included schedule returns Inherit() and the search
-                    # then reaches the IncludeSchedule within the parent.
-                    log(
-                        "==   skipping in favour of the parent to prevent " "a cycle",
-                        path,
-                        level="DEBUG",
+                    room.log(
+                        "IncludeSchedule() created a cycle, which would lead to "
+                        "infinite recursion in rule {}.".format(path),
+                        level="ERROR",
                     )
                     result = None
-                elif result is None or isinstance(result, expression.types.Inherit):
-                    log("==   skipping in favour of the parent", path, level="DEBUG")
-                    result = None
-                else:
                     break
 
+                if result is None or isinstance(result, expression.types.Inherit):
+                    log("==   skipping in favour of parent", path, level="DEBUG")
+                    result = None
+                    continue
+                break
+
             if result is None:
                 room.log(
                     "No expression/value definition found, skipping {}.".format(path),
@@ -535,7 +530,8 @@ def log(msg: str, path: RulePath, *args: T.Any, **kwargs: T.Any) -> None:
                 ):
                     del paths[path_idx]
             elif isinstance(result, expression.types.IncludeSchedule):
-                # Replace the current rule with a dynamic SubScheduleRule
+                # Replace current rule with temporary SubScheduleRule to enable
+                # proper handling of Inherit() and Break()
                 _path = path.copy()
                 _path.pop()
                 _path.append(SubScheduleRule(result.schedule))