Utils module

Provides utility functions and classes that are not required for using pubsub but are likely to be very useful.

copyright:Copyright since 2006 by Oliver Schoenborn, all rights reserved.
license:BSD, see LICENSE_BSD_Simple.txt for details.
pubsub.utils.printTreeDocs(rootTopic=None, topicMgr=None, **kwargs)[source]

Print out the topic tree to a file (or file-like object like a StringIO), starting at rootTopic. If root topic should be root of whole tree, get it from pub.getDefaultTopicTreeRoot(). The treeVisitor is an instance of pub.TopicTreeTraverser.

Printing the tree docs would normally involve this:

from pubsub import pub
from pubsub.utils.topictreeprinter import TopicTreePrinter
traverser = pub.TopicTreeTraverser( TopicTreePrinter(**kwargs) )
traverser.traverse( pub.getDefaultTopicTreeRoot() )

With printTreeDocs, it looks like this:

from pubsub import pub
from pubsub.utils import printTreeDocs
printTreeDocs()

The kwargs are the same as for TopicTreePrinter constructor: extra(None), width(70), indentStep(4), bulletTopic, bulletTopicItem, bulletTopicArg, fileObj(stdout). If fileObj not given, stdout is used.

pubsub.utils.useNotifyByPubsubMessage(publisher: pubsub.core.publisher.Publisher = None, all: bool = True, **kwargs)[source]

Will cause all of pubsub’s notifications of pubsub “actions” (such as new topic created, message sent, listener subscribed, etc) to be sent out as messages. Topic will be ‘pubsub’ subtopics, such as ‘pubsub.newTopic’, ‘pubsub.delTopic’, ‘pubsub.sendMessage’, etc.

The ‘all’ and kwargs args are the same as pubsub’s setNotificationFlags(), except that ‘all’ defaults to True.

The publisher is rarely needed:

  • The publisher must be specfied if pubsub is not installed on the system search path (ie from pubsub import … would fail or import wrong pubsub – such as if pubsub is within wxPython’s wx.lib package). Then pbuModule is the pub module to use:

    from wx.lib.pubsub import pub
    from wx.lib.pubsub.utils import notification
    notification.useNotifyByPubsubMessage()
    
pubsub.utils.useNotifyByWriteFile(fileObj: TextIO = None, prefix: str = None, publisher: pubsub.core.publisher.Publisher = None, all: bool = True, **kwargs)[source]

Will cause all pubsub notifications of pubsub “actions” (such as new topic created, message sent, listener died etc) to be written to specified file (or stdout if none given). The fileObj need only provide a ‘write(string)’ method.

The first two arguments are the same as those of NotifyByWriteFile constructor. The ‘all’ and kwargs arguments are those of pubsub’s setNotificationFlags(), except that ‘all’ defaults to True. See useNotifyByPubsubMessage() for an explanation of pubModule (typically only if pubsub inside wxPython’s wx.lib)

class pubsub.utils.IgnoreNotificationsMixin[source]

Bases: pubsub.core.notificationmgr.INotificationHandler

Derive your Notifications handler from this class if your handler just wants to be notified of one or two types of pubsub events. Then just override the desired methods. The rest of the notifications will automatically be ignored.

notifyDeadListener(pubListener: pubsub.core.listener.Listener, topicObj: pubsub.core.topicobj.Topic)[source]

Called when a listener has been garbage collected. :param pubListener: the pubsub.core.Listener that wraps GC’d listener. :param topicObj: the pubsub.core.Topic object it was subscribed to.

notifyDelTopic(topicName: str)[source]

Called whenever a topic is removed from topic tree. :param topicName: name of topic removed.

notifyNewTopic(topicObj: pubsub.core.topicobj.Topic, description: str, required: List[str], argsDocs: Mapping[str, str])[source]

Called whenever a new topic is added to the topic tree.

Parameters:
  • topicObj – the Topic object for the message.
  • description – docstring for the topic.
  • required – list of message data names (keys in argsDocs) that are required.
  • argsDocs – dictionary of all message data names, with the corresponding docstring.
notifySend(stage: str, topicObj: pubsub.core.topicobj.Topic, pubListener: pubsub.core.listener.Listener = None)[source]

Called multiple times during a sendMessage: once before message sending has started (pre), once for each listener about to be sent the message, and once after all listeners have received the message (post).

Parameters:
  • stage – ‘pre’, ‘post’, or ‘loop’.
  • topicObj – the Topic object for the message.
  • pubListener – None for pre and post stages; for loop, the listener that is about to be sent the message.
notifySubscribe(pubListener: pubsub.core.listener.Listener, topicObj: pubsub.core.topicobj.Topic, newSub: bool)[source]

Called when a listener is subscribed to a topic. :param pubListener: the pubsub.core.Listener that wraps subscribed listener. :param topicObj: the pubsub.core.Topic object subscribed to. :param newSub: false if pubListener was already subscribed.

notifyUnsubscribe(pubListener: pubsub.core.listener.Listener, topicObj: pubsub.core.topicobj.Topic)[source]

Called when a listener is unsubscribed from given topic. :param pubListener: the pubsub.core.Listener that wraps unsubscribed listener. :param topicObj: the pubsub.core.Topic object unsubscribed from.

class pubsub.utils.ExcPublisher(topicMgr: pubsub.core.topicmgr.TopicManager = None)[source]

Bases: pubsub.core.listener.IListenerExcHandler

Example exception handler that simply publishes the exception traceback. The messages will have topic name given by topicUncaughtExc.

init(topicMgr: pubsub.core.topicmgr.TopicManager)[source]

Must be called only after pubsub has been imported since this handler creates a pubsub topic.