"""
Provide the Topic class.

:copyright: Copyright since 2006 by Oliver Schoenborn, all rights reserved.
:license: BSD, see LICENSE_BSD_Simple.txt for details.
"""


from weakref import ref as weakref

from .listener import (
    Listener, 
    ListenerValidator,
)

from .topicutils import (
    ALL_TOPICS, 
    stringize, 
    tupleize, 
    validateName, 
    smartDedent,
)

from .topicexc import (
    TopicDefnError, 
    TopicNameError, 
    ExcHandlerError,
)

from .publishermixin import PublisherMixin

from .topicargspec import (
    ArgsInfo, 
    ArgSpecGiven, 
    topicArgsFromCallable, 
    SenderMissingReqdMsgDataError, 
    SenderUnknownMsgDataError, 
    MessageDataSpecError,
)

from .. import py2and3


class Topic(PublisherMixin):
    """
    Represent topics in pubsub. Contains information about a topic, 
    including topic's message data specification (MDS), the list of 
    subscribed listeners, docstring for the topic. It allows Python-like 
    access to subtopics (e.g. A.B is subtopic B of topic A).
    """

    def __init__(self, treeConfig, nameTuple, description,
        msgArgsInfo, parent=None):
        """Create a topic. Should only be called by TopicManager via its
        getOrCreateTopic() method (which gets called in several places 
        in pubsub, such as sendMessage, subscribe, and newTopic).
        
        :param treeConfig: topic tree configuration settings
        :param nameTuple: topic name, in tuple format (no dots)
        :param description: "docstring" for topic
        :param ArgsInfo msgArgsInfo: object that defines MDS for topic
        :param parent: parent of topic
        
        :raises ValueError: invalid topic name
        """
        if parent is None:
            if nameTuple != (ALL_TOPICS,):
                msg = 'Only one topic, named %s, can be root of topic tree'
                raise ValueError(msg % 'pub.ALL_TOPICS')
        else:
            validateName(nameTuple)
        self.__tupleName = nameTuple

        self.__handlingUncaughtListenerExc = False
        self._treeConfig = treeConfig
        PublisherMixin.__init__(self)

        self.__validator = None
        # Registered listeners were originally kept in a Python list; however 
        # a few methods require lookup of the Listener for the given callable, 
        # which is an O(n) operation. A set() could have been more suitable but
        # there is no way of retrieving an element from a set without iterating 
        # over the set, again an O(n) operation. A dict() is ok too. Because 
        # Listener.__eq__(callable) returns true if the Listener instance wraps
        # the given callable, and because Listener.__hash__ produces the hash 
        # value of the wrapped callable, calling dict[callable] on a 
        # dict(Listener -> Listener) mapping will be O(1) in most cases: 
        # the dict will take the callables hash, find the list of Listeners that 
        # have that hash, and then iterate over that inner list to find the 
        # Listener instance which satisfies Listener == callable, and will return
        # the Listener. 
        self.__listeners = dict()

        # specification:
        self.__description  = None
        self.setDescription(description)
        self.__msgArgs = msgArgsInfo
        if msgArgsInfo.isComplete():
            self.__finalize()
        else:
            assert not self._treeConfig.raiseOnTopicUnspecified

        # now that we know the args are fine, we can link to parent
        self.__parentTopic = None
        self.__subTopics = {}
        if parent is None:
            assert self.hasMDS()
        else:
            self.__parentTopic = weakref(parent)
            assert self.__msgArgs.parentAI() is parent._getListenerSpec()
            parent.__adoptSubtopic( self )

    def setDescription(self, desc):
        """Set the 'docstring' of topic"""
        self.__description = desc

    def getDescription(self):
        """Return the 'docstring' of topic"""
        if self.__description is None:
            return None
        return smartDedent(self.__description)

    def setMsgArgSpec(self, argsDocs, required=()):
        """Specify the message data for topic messages.
        :param argsDocs: a dictionary of keyword names (message data name) and data 'docstring'; cannot be None
        :param required: a list of those keyword names, appearing in argsDocs, 
        which are required (all others are assumed optional)
            
        Can only be called if this info has not been already set at construction 
        or in a previous call. 
        :raise RuntimeError: if MDS already set at construction or previous call."""
        assert self.__parentTopic is not None # for root of tree, this method never called!
        if argsDocs is None:
            raise ValueError('Cannot set listener spec to None')

        if self.__msgArgs is None or not self.__msgArgs.isComplete():
            try:
                specGiven = ArgSpecGiven(argsDocs, required)
                self.__msgArgs = ArgsInfo(self.__tupleName, specGiven,
                    self.__parentTopic()._getListenerSpec())
            except MessageDataSpecError:
                # discard the lower part of the stack trace
                exc = py2and3.getexcobj()
                raise exc
            self.__finalize()

        else:
            raise RuntimeError('Not allowed to call this: msg spec already set!')

    def getArgs(self):
        """Returns a pair (reqdArgs, optArgs) where reqdArgs is tuple
        of names of required message arguments, optArgs is tuple
        of names for optional arguments. If topic args not specified
        yet, returns (None, None)."""
        sendable = self.__msgArgs.isComplete()
        assert sendable == self.hasMDS()
        if sendable:
            return (self.__msgArgs.allRequired ,
                    self.__msgArgs.allOptional)
        return None, None

    def getArgDescriptions(self):
        """Get a map of keyword names to docstrings: documents each MDS element. """
        return self.__msgArgs.getArgsDocs()

    def setArgDescriptions(self, **docs):
        """Set the docstring for each MDS datum."""
        self.__msgArgs.setArgsDocs(docs)

    def hasMDS(self):
        """Return true if this topic has a message data specification (MDS)."""
        return self.__validator is not None

    def filterMsgArgs(self, msgKwargs, check=False):
        """Get the MDS docstrings for each of the spedified kwargs."""
        filteredArgs = self.__msgArgs.filterArgs(msgKwargs)
        # if no check of args yet, do it now:
        if check:
            self.__msgArgs.check(filteredArgs)
        return filteredArgs

    def isAll(self):
        """Returns true if this topic is the 'all topics' topic. All root
        topics behave as though they are child of that topic. """
        return self.__tupleName == (ALL_TOPICS,)

    def isRoot(self):
        """Returns true if this is a "root" topic, false otherwise. A
        root topic is a topic whose name contains no dots and which
        has pub.ALL_TOPICS as parent."""
        parent = self.getParent()
        if parent:
            return parent.isAll()
        assert self.isAll()
        return False

    def getName(self):
        """Return dotted form of full topic name"""
        return stringize(self.__tupleName)

    def getNameTuple(self):
        """Return tuple form of full topic name"""
        return self.__tupleName

    def getNodeName(self):
        """Return the last part of the topic name (has no dots)"""
        name = self.__tupleName[-1]
        return name

    def getParent(self):
        """Get Topic object that is parent of self (i.e. self is a subtopic
        of parent). Return none if self is the "all topics" topic."""
        if self.__parentTopic is None:
            return None
        return self.__parentTopic()

    def hasSubtopic(self, name=None):
        """Return true only if name is a subtopic of self. If name not
        specified, return true only if self has at least one subtopic."""
        if name is None:
            return len(self.__subTopics) > 0

        return name in self.__subTopics

    def getSubtopic(self, relName):
        """Get the specified subtopic object. The relName can be a valid
        subtopic name, a dotted-name string, or a tuple. """
        if not relName:
            raise ValueError("getSubtopic() arg can't be empty")
        topicTuple = tupleize(relName)
        assert topicTuple

        topicObj = self
        for topicName in topicTuple:
            child = topicObj.__subTopics.get(topicName)
            if child is None:
                msg = 'Topic "%s" doesn\'t have "%s" as subtopic' % (topicObj.getName(), topicName)
                raise TopicNameError(relName, msg)
            topicObj = child

        return topicObj

    def getSubtopics(self):
        """Get a list of Topic instances that are subtopics of self."""
        return py2and3.values(self.__subTopics)

    def getNumListeners(self):
        """Return number of listeners currently subscribed to topic. This is
        different from number of listeners that will get notified since more
        general topics up the topic tree may have listeners."""
        return len(self.__listeners)

    def hasListener(self, listener):
        """Return true if listener is subscribed to this topic."""
        return listener in self.__listeners

    def hasListeners(self):
        """Return true if there are any listeners subscribed to
        this topic, false otherwise."""
        return bool(self.__listeners)

    def getListeners(self):
        """Get a copy of list of listeners subscribed to this topic. Safe to iterate over while listeners
        get un/subscribed from this topics (such as while sending a message)."""
        return py2and3.keys(self.__listeners)

    def getListenersIter(self):
        """Get an iterator over listeners subscribed to this topic. Do not use if listeners can be
        un/subscribed while iterating. """
        return py2and3.iterkeys(self.__listeners)

    def validate(self, listener):
        """Checks whether listener could be subscribed to this topic:
        if yes, just returns; if not, raises ListenerMismatchError.
        Note that method raises TopicDefnError if self not
        hasMDS()."""
        if not self.hasMDS():
            raise TopicDefnError(self.__tupleName)
        return self.__validator.validate(listener)

    def isValid(self, listener):
        """Return True only if listener could be subscribed to this topic,
        otherwise returns False. Note that method raises TopicDefnError
        if self not hasMDS()."""
        if not self.hasMDS():
            raise TopicDefnError(self.__tupleName)
        return self.__validator.isValid(listener)

    def subscribe(self, listener):
        """Subscribe listener to this topic. Returns a pair
        (pub.Listener, success). The success is true only if listener
        was not already subscribed and is now subscribed. """
        if listener in self.__listeners:
            assert self.hasMDS()
            subdLisnr, newSub = self.__listeners[listener], False

        else:
            if self.__validator is None:
                args, reqd = topicArgsFromCallable(listener)
                self.setMsgArgSpec(args, reqd)
            argsInfo = self.__validator.validate(listener)
            weakListener = Listener(
                listener, argsInfo, onDead=self.__onDeadListener)
            self.__listeners[weakListener] = weakListener
            subdLisnr, newSub = weakListener, True

        # notify of subscription
        self._treeConfig.notificationMgr.notifySubscribe(subdLisnr, self, newSub)

        return subdLisnr, newSub

    def unsubscribe(self, listener):
        """Unsubscribe the specified listener from this topic. Returns
        the pub.Listener object associated with the listener that was
        unsubscribed, or None if the specified listener was not
        subscribed to this topic.  Note that this method calls
        ``notifyUnsubscribe(listener, self)`` on all registered notification
        handlers (see pub.addNotificationHandler)."""
        unsubdLisnr = self.__listeners.pop(listener, None)
        if unsubdLisnr is None: 
            return None

        unsubdLisnr._unlinkFromTopic_()
        assert listener == unsubdLisnr.getCallable()

        # notify of unsubscription
        self._treeConfig.notificationMgr.notifyUnsubscribe(unsubdLisnr, self)

        return unsubdLisnr

    def unsubscribeAllListeners(self, filter=None):
        """Clears list of subscribed listeners. If filter is given, it must
        be a function that takes a listener and returns true if the listener
        should be unsubscribed. Returns the list of Listener for listeners 
        that were unsubscribed."""
        unsubd = []
        if filter is None:
            for listener in self.__listeners:
                listener._unlinkFromTopic_()
            unsubd = py2and3.keys(self.__listeners)
            self.__listeners = {}
        else:
            unsubd = []
            for listener in py2and3.keys(self.__listeners):
                if filter(listener):
                    unsubd.append(listener)
                    listener._unlinkFromTopic_()
                    del self.__listeners[listener]

        # send notification regarding all listeners actually unsubscribed
        notificationMgr = self._treeConfig.notificationMgr
        for unsubdLisnr in unsubd:
            notificationMgr.notifyUnsubscribe(unsubdLisnr, self)

        return unsubd

    #############################################################
    #
    # Impementation
    #
    #############################################################

    def _getListenerSpec(self):
        """Only to be called by pubsub package"""
        return self.__msgArgs

    def _publish(self, data):
        """This sends message to listeners of parent topics as well.
        If an exception is raised in a listener, the publish is
        aborted, except if there is a handler (see
        pub.setListenerExcHandler)."""
        self._treeConfig.notificationMgr.notifySend('pre', self)

        # send to ourself
        iterState = self._mix_prePublish(data)
        self.__sendMessage(data, self, iterState)

        # send up the chain
        topicObj = self.getParent()
        while topicObj is not None:
            if topicObj.hasListeners():
                iterState = self._mix_prePublish(data, topicObj, iterState)
                self.__sendMessage(data, topicObj, iterState)

            # done for this topic, continue up branch to parent towards root
            topicObj = topicObj.getParent()

        self._treeConfig.notificationMgr.notifySend('post', self)

    def __sendMessage(self, data, topicObj, iterState):
        # now send message data to each listener for current topic;
        # use list of listeners rather than iterator, so that if listeners added/removed during
        # send loop, no runtime exception:
        for listener in topicObj.getListeners():
            try:
                self._treeConfig.notificationMgr.notifySend('in', topicObj, pubListener=listener)
                self._mix_callListener(listener, data, iterState)

            except Exception:
                # if exception handling is on, handle, otherwise re-raise
                handler = self._treeConfig.listenerExcHandler
                if handler is None or self.__handlingUncaughtListenerExc:
                    raise

                # try handling the exception so we can continue the send:
                try:
                    self.__handlingUncaughtListenerExc = True
                    handler( listener.name(), topicObj )
                    self.__handlingUncaughtListenerExc = False
                except Exception:
                    exc = py2and3.getexcobj()
                    #print 'exception raised', exc
                    self.__handlingUncaughtListenerExc = False
                    raise ExcHandlerError(listener.name(), topicObj, exc)

    def __finalize(self):
        """Finalize the topic specification, which currently means
        creating the listener validator for this topic. This allows 
        calls to subscribe() to validate that listener adheres to 
        topic's message data specification (MDS)."""
        assert self.__msgArgs.isComplete()
        assert not self.hasMDS()

        # must make sure can adopt a validator
        required = self.__msgArgs.allRequired
        optional = self.__msgArgs.allOptional
        self.__validator = ListenerValidator(required, list(optional) )
        assert not self.__listeners

    def _undefineSelf_(self, topicsMap):
        """Called by topic manager when deleting a topic."""
        if self.__parentTopic is not None:
            self.__parentTopic().__abandonSubtopic(self.__tupleName[-1])
        self.__undefineBranch(topicsMap)

    def __undefineBranch(self, topicsMap):
        """Unsubscribe all our listeners, remove all subtopics from self,
        then detach from parent. Parent is not notified, because method
        assumes it has been called by parent"""
        #print 'Remove %s listeners (%s)' % (self.getName(), self.getNumListeners())
        self.unsubscribeAllListeners()
        self.__parentTopic = None

        for subName, subObj in py2and3.iteritems(self.__subTopics):
            assert isinstance(subObj, Topic)
            #print 'Unlinking %s from parent' % subObj.getName()
            subObj.__undefineBranch(topicsMap)

        self.__subTopics = {}
        del topicsMap[self.getName()]

    def __adoptSubtopic(self, topicObj):
        """Add topicObj as child topic."""
        assert topicObj.__parentTopic() is self
        attrName = topicObj.getNodeName()
        self.__subTopics[attrName] = topicObj

    def __abandonSubtopic(self, name):
        """The given subtopic becomes orphan (no parent)."""
        topicObj = self.__subTopics.pop(name)
        assert topicObj.__parentTopic() is self

    def __onDeadListener(self, weakListener):
        """One of our subscribed listeners has died, so remove it and notify"""
        pubListener = self.__listeners.pop(weakListener)
        # notify:
        self._treeConfig.notificationMgr.notifyDeadListener(pubListener, self)

    def __str__(self):
        return "%s(%s)" % (self.getName(), self.getNumListeners())