# evennia.scripts.monitorhandler

Monitors - catch changes to model fields and Attributes.

The MONITOR_HANDLER singleton from this module offers the following functionality:

- Field-monitor - track a object’s specific database field and perform

    an action whenever that field changes for whatever reason.

- Attribute-monitor tracks an object’s specific Attribute and perform

    an action whenever that Attribute changes for whatever reason.

class `evennia.scripts.monitorhandler.``MonitorHandler`

  Bases: `object`

  This is a resource singleton that allows for registering callbacks for when a field or Attribute is updated (saved).

  `__init__`()

    Initialize the handler.

  `save`()

    Store our monitors to the database. This is called by the server process.

    Since dbserialize can’t handle defaultdicts, we convert to an intermediary save format ((obj,fieldname, idstring, callback, kwargs), …)

  `restore`(server_reload=True)

    Restore our monitors after a reload. This is called by the server process.

    Parameters

      server_reload (bool, optional) – If this is False, it means the server went through a cold reboot and all non-persistent tickers must be killed.

  `at_update`(obj, fieldname)

    Called by the field/attribute as it saves.

  `add`(obj, fieldname, callback, idstring='', persistent=False, category=None, **kwargs)

    Add monitoring to a given field or Attribute. A field must be specified with the full db_* name or it will be assumed to be an Attribute (so db_key, not just key).

    Parameters

      - obj (Typeclassed Entity) – The entity on which to monitor a field or Attribute.

      - fieldname (str) – Name of field (db_*) or Attribute to monitor.

      - callback (callable) – A callable on the form **callable(**kwargs), where kwargs holds keys fieldname and obj.

      - idstring (str, optional) – An id to separate this monitor from other monitors of the same field and object.

      - persistent (bool, optional) – If False, the monitor will survive a server reload but not a cold restart. This is default.

      - category (str, optional) – This is only used if fieldname refers to an Attribute (i.e. it does not start with db_). You must specify this if you want to target an Attribute with a category.

    Keyword Arguments

      - session (Session) – If this keyword is given, the monitorhandler will correctly analyze it and remove the monitor if after a reload/reboot the session is no longer valid.

      - any (any) – Any other kwargs are passed on to the callback. Remember that all kwargs must be possible to pickle!

  `remove`(obj, fieldname, idstring='', category=None)

    Remove a monitor.

  `clear`()

    Delete all monitors.

  `all`(obj=None)

    List all monitors or all monitors of a given object.

    Parameters

      obj (Object) – The object on which to list all monitors.

    Returns

      monitors (list) – The handled monitors.