# Observers

`gtkmvc.observer.``observes`(*args)

  Decorate a method in an `Observer` subclass as a notification. Takes one to many property names as strings. If any of them changes in a model we observe, the method is called. The name of the property will be passed to the method.

  The type of notification is inferred from the number of arguments. Valid signature are:

      def value_notify(self, model, name, old, new)
      def before_notify(self, model, name, instance, method_name, args, kwargs)
      def after_notify(self, model, name, instance, method_name, res, args, kwargs)
      def signal_notify(self, model, name, arg)

  New in version 1.99.0.

  Deprecated since version 1.99.1: Use `Observer.observe()` instead, which offers more features.

class `gtkmvc.observer.``Observer`(model=None, spurious=False)

  Note

  Most methods in this class are used internally by the framework. Do not override them in subclasses.

  model is passed to `observe_model()` if given.

  spurious indicates interest to be notified even when the value hasn’t changed, like for:

      model.prop = model.prop

  New in version 1.2.0: Before that observers had to filter out spurious notifications themselves, as if the default was True. With `Signal` support this is no longer necessary.

  `get_custom_observing_methods`(prop_name)

    An alias for `get_observing_methods()`.

    Deprecated since version 1.99.1.

  `accepts_spurious_change`()

    Returns True if this observer is interested in receiving spurious value changes. This is queried by the model when notifying a value change.

  `get_observing_method_kwargs`(prop_name, method)

    Returns the keyword arguments which were specified when declaring a notification method, either statically of synamically with `Observer.observe()`.

    method a callable that was registered with `observes()`.

    Return type: | dict

  `get_observing_methods`(prop_name)

    Return a possibly empty set of callables registered with `observe()` for prop_name.

    New in version 1.99.1: Replaces `get_custom_observing_methods()`.

  `is_observing_method`(prop_name, method)

    Returns True if the given method was previously added as an observing method, either dynamically or via decorator.

  classmethod `observe`(*f, **k)

    Mark a method as recieving notifications. Comes in two flavours:

    `observe`(name, **types)

      A decorator living in the class. Can be applied more than once to the same method, provided the names differ.

      name is the property we want to be notified about as a string.

      types are boolean values denoting the types of notifications desired. At least one of the following has to be passed as True: assign, before, after, signal.

      Excess keyword arguments are passed to the method as part of the info dictionary.

    `observe`(callable, name, **types)

      An instance method to define notifications at runtime. Works as above.

      callable is the method to send notifications to. The effect will be as if this had been decorated.

    In all cases the notification method must take exactly three arguments: the model object, the name of the property that changed, and an `NTInfo` object describing the change.

    Warning

    Due to limitation in the dynamic registration (in version 1.99.1), declarations of dynamic notifications must occur before registering self as an observer of the models whose properties the notifications are supposed to be observing. A hack for this limitation, is to first relieve any interesting model before dynamically register the notifications, and then re-observe those models.

    New in version 1.99.1.

  `observe_model`(model)

    Starts observing the given model

  `relieve_model`(model)

    Stops observing the given model

  `remove_observing_method`(prop_names, method)

    Remove dynamic notifications.

    method a callable that was registered with `observe()`.

    prop_names a sequence of strings. This need not correspond to any one add call.

    Note

    This can revert the effects of a decorator at runtime. Don’t.

class `gtkmvc.observer.``NTInfo`(_type, *args, **kwargs)

  Bases: `dict`

  A container for information attached to a notification. This class is a dictionary-like object used:

  1. As class when defining notification methods in observers, as it contains the flags identifying the notification types.
  2. As class instance as parameter when a notification methods is called in observers.

  Notification Type Flags

  Notification methods are declared either statically or dynamically through `Observer.observe()`. In both cases the type of the notification is defined by setting to True some flags. Flags can be set in any combination for multi-type notification methods. Flags are:

  assign
    For notifications issued when OPs are assigned.
  before
    For notifications called before a modifying method is called.
  after
    For notifications called after a modifying method is called.
  signal
    For notifications called when a signal is emitted.

  Instance content

  Instances of class NTInfo will be received as the last argument (info) of any notification method:

      def notification_method(self, model, name, info)

  NTInfo is a dictionary (with some particular behaviour added) containing some information which is independent on the notification type, and some other information wich depends on the notification type.

  Common to all types

  For all notification types, NTInfo contains:

  model
    the model containing the observable property triggering the notification. model is also passed as first argument of the notification method.
  prop_name
    the name of the observable property triggering the notification. name is also passed as second argument of the notification method.

  Furthermore, any keyword argument not listed here is copied without modification into info.

  There are further information depending on the specific notification type:

  For Assign-type

  assign
    flag set to True
  old
    the value that the observable property had before being changed.
  new
    the new value that the observable property has been changed to.

  For Before method call type

  before
    flag set to True
  instance
    the object instance which the method that is being called belongs to.
  method_name
    the name of the method that is being called.
  args
    tuple of the arguments of the method that is being called.
  kwargs
    dictionary of the keyword arguments of the method that is being called.

  For After method call type

  after
    flag set to True
  instance
    the object instance which the method that has been called belongs to.
  method_name
    the name of the method that has been called.
  args
    tuple of the arguments of the method that has been called.
  kwargs
    dictionary of the keyword arguments of the method that has been called.
  result
    the value returned by the method which has been called.

  For Signal-type

  signal
    flag set to True
  arg
    the argument which was optionally specified when invoking emit() on the signal observable property.

  Information access

  The information carried by a NTInfo instance passed to a notification method can be retrieved using the instance as a dictionary, or accessing directly to the information as an attribute of the instance. For example:

      # This is a multi-type notification
      @Observer.observe("op1", assign=True, hello="Ciao")
      @Observer.observe("op2", after=True, before=True)
      def notify_me(self, model, name, info):
          assert info["model"] == model # access as dict key
          assert info.prop_name == name # access as attribute

          if "assign" in info:
             assert info.old == info["old"]
             assert "hello" in info and "ciao" == info.hello
             print "Assign from", info.old, "to", info.new
          else:
             assert "before" in info or "after" in info
             assert "hello" not in info
             print "Method name=", info.method_name
             if "after" in info: print "Method returned", info.result
             pass

          return

  As already told, the type carried by a NTInfo instance can be accessed through boolean flags assign, before, after and signal. Furthermore, any other information specified at declaration time (keyword argument ‘hello’ in the previous example) will be accessible in the corresponding notification method.

  New in version 1.99.1.

  `__getattr__`(name)

    All dictionary keys are also available as attributes.