The topic hierarchy can be created on the fly by the application (default), or can be specified and documented via one or more Topic Definition Providers (TDP). TDP’s are objects that state
Pubsub can be setup to deny (via an exception) any attempt to use a topic that is not specified by a TDP. This is very useful in larger applications.
Every topic has a message arguments specification, i.e. a prescribed set of argument names that are allowed when sending a message of that topic. This is the TMAS, for topic message arguments specification. For instance, topic “sports.baseball” might have following TMAS:
but only location and playersA are required: playersB and dateTime are only used during a match (vs a practice). Then every message of topic “sports.baseball” must be given at least a location and list for playersA, and every recipient of the message must accept all four parameters (since some messages will have all four parameters). I.e.:
pub.sendMessage("sports.baseball", playersA=[], location="Montreal")
pub.sendMessage("sports.baseball", playersA=[], playersB=[], location="Montreal")
pub.sendMessage("sports.baseball", playersA=[], location="Montreal", dateTime=today() )
pub.sendMessage("sports.baseball", playersA=[], playersB=[], location="Montreal", dateTime=today() )
pub.sendMessage("sports.baseball", playersA=[]) # ERROR: required location missing
The TMAS of each topic:
A listener is a Python callable object (i.e. a function, method or instance with a __call__ method). A listener subscribes to topics that it wants to listen to. The only restrictions on listeners are:
A listener should not make any assumptions about:
Listeners that are subscribed are held by pubsub in a registry. However, Listeners are stored in this registry in such a way that when the application no longer uses the listener (reference count goes to zero), it is removed from the registry. In other words, the listener is stored in the registry by weak reference only. This prevents pubsub from artificially keeping listeners alive when the application no longer needs them.
A listener can be given the Topic object when receiving a message.
The kwargs protocol is defined as follows:
Example: assume a topic ‘someTopic’ and subtopic ‘someTopic.subTopic’:
from pubsub import pub
def listener(hi): assert msg == 123
pub.subscribe(listener, 'someTopic')
def listener2(hi, foo): assert hi == 123; assert foo = 'bar'
pub.subscribe(listener2, 'someTopic.subTopic')
pub.sendMessage('someTopic.subTopic', hi=123, foo='bar')
This protocol is defined as follows:
Example:
from pubsub import setuparg1
from pubsub import pub
def listener(msg): assert msg.data['hi'] == 123
data = dict('hi':123, ...)
pub.sendMessage('someTopic', data)