:mod:`dip.publish`
==================
.. module:: dip.publish

The :mod:`dip.publish` module implements the infrastructure for publishing
events about a :term:`model` and for subscribing to those events.


:class:`IPublication`
---------------------
.. class:: IPublication

    Base class: :class:`~dip.model.Interface`

    The IPublication interface defines the API to be implemented by a model
    that represents an event related to a published model.

    .. attribute:: event = Str()

         The event related to the model.  The following events are considered to
         be well known.
        
         'dip.events.opened'
           occurs once just after the model has been opened or created.
         'dip.events.closed'
           occurs once just before the model is closed.
         'dip.event.active'
           occurs whenever the model becomes active.
         'dip.events.inactive'
           occurs whenever the model becomes inactive.

    .. attribute:: model = Any()

        The model being published.


:class:`IPublicationManager`
----------------------------
.. class:: IPublicationManager

    Base class: :class:`~dip.model.Interface`

    The IPublicationManager interface defines the API of a publication
    manager.

    .. attribute:: publishers = List(IPublisher)

        The list of publishers.

    .. attribute:: subscribers = List(ISubscriber)

        The list of subscribers.


:class:`IPublisher`
-------------------
.. class:: IPublisher

    Base class: :class:`~dip.model.Interface`

    The IPublisher interface defines the API to be implemented by an object
    that publishes an event related to a :term:`model` to other objects that
    implement the :class:`~dip.publish.ISubscriber` interface.

    .. attribute:: publication = Instance(IPublication)

        The publication we have published.


:class:`ISubscriber`
--------------------
.. class:: ISubscriber

    Base class: :class:`~dip.model.Interface`

    The ISubscriber interface defines the API to be implemented by an
    object that subscribes to the publication of events related to a
    :term:`model` by other objects that implement the
    :class:`~dip.publish.IPublisher` interface.

    .. attribute:: subscription = Instance(IPublication)

        The publication we have subscribed to.

    .. attribute:: subscription_type = Instance(type)

        The type of model that the subscriber is interested in.  If it is
        ``None`` then publications related to all types of model will be
        subscribed to.


:class:`Publication`
--------------------
.. class:: Publication

    Base class: :class:`~dip.model.Model`

    The Publication class is the default implementation of the
    :class:`~dip.publish.IPublication` interface.