Navigation

Phoenix Logo

phoenix_title wx.lib.pubsub.core.topicmgr.TopicManager

Manages the registry of all topics and creation/deletion of topics.

Note that any method that accepts a topic name can accept it in the ‘dotted’ format such as 'a.b.c.' or in tuple format such as ('a', 'b', 'c'). Any such method will raise a ValueError if name not valid (empty, invalid characters, etc).


class_hierarchy Class Hierarchy

Inheritance diagram for class TopicManager:

method_summary Methods Summary

__init__ The optional treeConfig is an instance of TreeConfig, used to
addDefnProvider Register a topic definition provider. After this method is called, whenever a topic must be created,
checkAllTopicsHaveMDS Check that all topics that have been created for their MDS.
clearDefnProviders Remove all registered topic definition providers
delTopic Delete the named topic, including all sub-topics. Returns False if topic does not exist; True otherwise. Also unsubscribe any listeners
getNumDefnProviders Get how many topic definitions providers are registered.
getOrCreateTopic Get the Topic instance for topic of given name, creating it
getRootAllTopics Get the topic that is parent of all root (ie top-level) topics,
getTopic Get the Topic instance for the given topic name. By default, raises
getTopicsSubscribed Get the list of Topic objects that have given listener
hasTopicDefinition Determine if there is a definition avaiable for topic ‘name’. Return
isTopicInUse Determine if topic ‘name’ is in use. True if a Topic object exists
newTopic Deprecated legacy method.

api Class API


class TopicManager

Manages the registry of all topics and creation/deletion of topics.

Note that any method that accepts a topic name can accept it in the ‘dotted’ format such as 'a.b.c.' or in tuple format such as ('a', 'b', 'c'). Any such method will raise a ValueError if name not valid (empty, invalid characters, etc).


Methods


__init__(self, treeConfig=None)

The optional treeConfig is an instance of TreeConfig, used to configure the topic tree such as notification settings, etc. A default config is created if not given. This method should only be called by an instance of Publisher (see Publisher.getTopicManager()).


addDefnProvider(self, providerOrSource, format=None)

Register a topic definition provider. After this method is called, whenever a topic must be created, the first definition provider that has a definition for the required topic is used to instantiate the topic.

If providerOrSource is an instance of ITopicDefnProvider, register it as a provider of topic definitions. Otherwise, register a new instance of TopicDefnProvider(providerOrSource, format). In that case, if format is not given, it defaults to TOPIC_TREE_FROM_MODULE. Either way, returns the instance of ITopicDefnProvider registered.


checkAllTopicsHaveMDS(self)

Check that all topics that have been created for their MDS. Raise a TopicDefnError if one is found that does not have one.


clearDefnProviders(self)

Remove all registered topic definition providers


delTopic(self, name)

Delete the named topic, including all sub-topics. Returns False if topic does not exist; True otherwise. Also unsubscribe any listeners of topic and all subtopics.


getNumDefnProviders(self)

Get how many topic definitions providers are registered.


getOrCreateTopic(self, name, protoListener=None)

Get the Topic instance for topic of given name, creating it (and any of its missing parent topics) as necessary. Pubsub functions such as subscribe() use this to obtain the Topic object corresponding to a topic name.

The name can be in dotted or string format ('a.b.' or ('a','b')).

This method always attempts to return a “complete” topic, i.e. one with a Message Data Specification (MDS). So if the topic does not have an MDS, it attempts to add it. It first tries to find an MDS from a TopicDefnProvider (see addDefnProvider()). If none is available, it attempts to set it from protoListener, if it has been given. If not, the topic has no MDS.

Once a topic’s MDS has been set, it is never again changed or accessed by this method.

Examples:

# assume no topics exist
# but a topic definition provider has been added via
# pub.addTopicDefnProvider() and has definition for topics 'a' and 'a.b'

# creates topic a and a.b; both will have MDS from the defn provider:
t1 = topicMgr.getOrCreateTopic('a.b')
t2 = topicMgr.getOrCreateTopic('a.b')
assert(t1 is t2)
assert(t1.getParent().getName() == 'a')

def proto(req1, optarg1=None): pass
# creates topic c.d with MDS based on proto; creates c without an MDS
# since no proto for it, nor defn provider:
t1 = topicMgr.getOrCreateTopic('c.d', proto)

The MDS can also be defined via a call to subscribe(listener, topicName), which indirectly calls getOrCreateTopic(topicName, listener).


getRootAllTopics(self)

Get the topic that is parent of all root (ie top-level) topics, for default TopicManager instance created when this module is imported. Some notes:

  • “root of all topics” topic satisfies isAll()==True, isRoot()==False, getParent() is None;
  • all root-level topics satisfy isAll()==False, isRoot()==True, and getParent() is getDefaultTopicTreeRoot();
  • all other topics satisfy neither.

getTopic(self, name, okIfNone=False)

Get the Topic instance for the given topic name. By default, raises an TopicNameError exception if a topic with given name doesn’t exist. If okIfNone=True, returns None instead of raising an exception.


getTopicsSubscribed(self, listener)

Get the list of Topic objects that have given listener subscribed. Note: the listener can also get messages from any sub-topic of returned list.


hasTopicDefinition(self, name)

Determine if there is a definition avaiable for topic ‘name’. Return true if there is, false otherwise. Note: a topic may have a definition without being in use, and vice versa.


isTopicInUse(self, name)

Determine if topic ‘name’ is in use. True if a Topic object exists for topic name (i.e. message has already been sent for that topic, or a least one listener subscribed), false otherwise. Note: a topic may be in use but not have a definition (MDS and docstring); or a topic may have a definition, but not be in use.


newTopic(self, _name, _desc, _required=(), **_argDocs)

Deprecated legacy method. If topic _name already exists, just returns it and does nothing else. Otherwise, uses getOrCreateTopic() to create it, then sets its description (_desc) and its message data specification (_argDocs and _required). Replaced by getOrCreateTopic().