1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2018 by Total Control Software
License: wxWindows License
.. include:: headings.inc
.. currentmodule:: wx.lib.pubsub.core.topicmgr
.. highlight:: python
.. _wx.lib.pubsub.core.topicmgr.TopicManager:
==========================================================================================================================================
|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
=================================
.. raw:: html
<div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
<img id="toggleBlock-trigger" src="_static/images/closed.png"/>
Inheritance diagram for class <strong>TopicManager</strong>:
</div>
<div id="toggleBlock-summary" style="display:block;"></div>
<div id="toggleBlock-content" style="display:none;">
<p class="graphviz">
<center><img src="_static/images/inheritance/wx.lib.pubsub.core.topicmgr.TopicManager_inheritance.png" alt="Inheritance diagram of TopicManager" usemap="#dummy" class="inheritance"/></center>
</div>
<script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
<map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.lib.pubsub.core.topicmgr.TopicManager.html" title="wx.lib.pubsub.core.topicmgr.TopicManager" alt="" coords="5,5,296,35"/> </map>
</p>
|
|method_summary| Methods Summary
================================
================================================================================ ================================================================================
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.__init__` The optional treeConfig is an instance of TreeConfig, used to
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.addDefnProvider` Register a topic definition provider. After this method is called, whenever a topic must be created,
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.checkAllTopicsHaveMDS` Check that all topics that have been created for their MDS.
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.clearDefnProviders` Remove all registered topic definition providers
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.delTopic` Delete the named topic, including all sub-topics. Returns ``False`` if topic does not exist; ``True`` otherwise. Also unsubscribe any listeners
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getNumDefnProviders` Get how many topic definitions providers are registered.
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getOrCreateTopic` Get the Topic instance for topic of given name, creating it
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getRootAllTopics` Get the topic that is parent of all root (ie top-level) topics,
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getTopic` Get the Topic instance for the given topic name. By default, raises
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.getTopicsSubscribed` Get the list of Topic objects that have given listener
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.hasTopicDefinition` Determine if there is a definition avaiable for topic 'name'. Return
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.isTopicInUse` Determine if topic 'name' is in use. ``True`` if a Topic object exists
:meth:`~wx.lib.pubsub.core.topicmgr.TopicManager.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).
.. method:: __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()).
.. method:: 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.
.. method:: 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.
.. method:: clearDefnProviders(self)
Remove all registered topic definition providers
.. method:: 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.
.. method:: getNumDefnProviders(self)
Get how many topic definitions providers are registered.
.. method:: 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).
.. method:: 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.
.. method:: 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.
.. method:: 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.
.. method:: 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.
.. method:: 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.
.. method:: 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().
|
