parameters: (self, name, protoListener=None)
return_statement: return self.__createTopic(nameTuple, desc, parent = parentObj, specGiven = specGiven)
docstring: 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).
docstring_summary: 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).
docstring_tokens: 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 ) .
function: def 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).
          """
          obj = self.getTopic(name, okIfNone=True)
          if obj:
              # if object is not sendable but a proto listener was given,
              # update its specification so that it is sendable
              if (protoListener is not None) and not obj.hasMDS():
                  allArgsDocs, required = topicArgsFromCallable(protoListener)
                  obj.setMsgArgSpec(allArgsDocs, required)
              return obj
  
          # create missing parents
          nameTuple = tupleize(name)
          parentObj = self.__createParentTopics(nameTuple)
  
          # now the final topic object, args from listener if provided
          desc, specGiven = self.__defnProvider.getDefn(nameTuple)
          # POLICY: protoListener is used only if no definition available
          if specGiven is None:
              if protoListener is None:
                  desc = 'UNDOCUMENTED: created without spec'
              else:
                  allArgsDocs, required = topicArgsFromCallable(protoListener)
                  specGiven = ArgSpecGiven(allArgsDocs, required)
                  desc = 'UNDOCUMENTED: created from protoListener "%s" in module %s' % getID(protoListener)
  
          return self.__createTopic(nameTuple, desc, parent = parentObj, specGiven = specGiven)
function_tokens: def getOrCreateTopic ( self , name , protoListener = None ) : obj = self . getTopic ( name , okIfNone = True ) if obj : # if object is not sendable but a proto listener was given, # update its specification so that it is sendable if ( protoListener is not None ) and not obj . hasMDS ( ) : allArgsDocs , required = topicArgsFromCallable ( protoListener ) obj . setMsgArgSpec ( allArgsDocs , required ) return obj # create missing parents nameTuple = tupleize ( name ) parentObj = self . __createParentTopics ( nameTuple ) # now the final topic object, args from listener if provided desc , specGiven = self . __defnProvider . getDefn ( nameTuple ) # POLICY: protoListener is used only if no definition available if specGiven is None : if protoListener is None : desc = 'UNDOCUMENTED: created without spec' else : allArgsDocs , required = topicArgsFromCallable ( protoListener ) specGiven = ArgSpecGiven ( allArgsDocs , required ) desc = 'UNDOCUMENTED: created from protoListener "%s" in module %s' % getID ( protoListener ) return self . __createTopic ( nameTuple , desc , parent = parentObj , specGiven = specGiven )