From ae57c9ceb387d66d350bb4f1999e0b6683f6b41b Mon Sep 17 00:00:00 2001 From: frmdstryr Date: Tue, 17 Nov 2026 20:22:03 +0000 Subject: [PATCH] Add notes on extended observers Documents behavior in #245 --- docs/source/basis/observation.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/source/basis/observation.rst b/docs/source/basis/observation.rst index fd6382c0..fb42064d 100644 --- a/docs/source/basis/observation.rst +++ b/docs/source/basis/observation.rst @@ -171,6 +171,31 @@ dictionary can contains additional information (note that ``'value'`` and a.s.connect(print_pair) a.s('a', 1) +Extended observers +------------------ + +Atom supports observing a member of a nested Atom object up to one level deep +using the format ``"."``. This is called an extended observer and +uses a combination of static and dynamic observers. + +.. code-block:: python + + from atom.api import Atom, Int, Typed, observe + class Point(Atom): + x = Int() + y = Int() + + class Item(Atom): + pos = Typed(Point, ()) + + @observe("pos.x") + def on_change(self, change): + print(change) + + item = Item() + item.pos.x = 1 # Invokes on_change with change event for "x" + item.pos = Point(x=2, y=0) # Does NOT invoke on_change. Add a separate "pos" argument to @observe if this is needed. + item.pos.x = 3 # Invokes on_change with change event for "x" Suppressing notifications -------------------------