def element(self):
     '''
     defined so a TimespanTree can be used like an PitchedTimespan
     
     TODO: Look at subclassing or at least deriving from a common base...
     '''
     return common.unwrapWeakref(self._source)

    def getComponents(self, spanner):
        """Given a spanner defined in this Spanners, return a list of associated components. 

        Components, while stored as weakrefs, are unwrapped.

        >>> from music21 import *
        >>> class TestMock(object): pass
        >>> tm1 = TestMock()
        >>> n1 = note.Note('c2')
        >>> n2 = note.Note('g3')
        >>> sp1 = Spanners()
        >>> sp1.add(tm1, [n1, n2])
        >>> sp1.getComponents(tm1) == [n1, n2]
        True
        """
        idSpanner = id(spanner)
        if idSpanner not in self.keys():
            raise SpannersException(
                "cannot return comoponents from an object not defined in spanners: %s" % repr(spanner)
            )

        post = []
        # get all objects, unwrap
        # second index is list of components
        for wr in self._storage[idSpanner][1]:
            post.append(common.unwrapWeakref(wr))
        return post

    def getSpanner(self, component):
        """Given a component, return a list of all spanner objects that bundle that component.

        >>> from music21 import *
        >>> class TestMock(object): pass
        >>> tm1 = TestMock()
        >>> n1 = note.Note('c2')
        >>> n2 = note.Note('g3')
        >>> sp1 = Spanners()
        >>> sp1.add(tm1, [n1, n2])
        >>> sp1.getSpanner(n2) == [tm1]
        True
        """
        idComponent = id(component)
        # find all keys
        spannerKeys = []
        for key in self.keys():
            # look at all component ids
            for idKnown in self._idRef[key]:
                if idKnown == idComponent:
                    spannerKeys.append(key)
                    break
        # unwrap spanner for found keys
        post = []
        for key in spannerKeys:
            # first index is spanner object
            post.append(common.unwrapWeakref(self._storage[key][0]))

        return post

 def client(self):
     c = common.unwrapWeakref(self._client)
     if c is None and self._clientId is not None:
         self._clientId = None
         self._client = None
         self._origin = None
         self._originId = None
     return c

    def testWeakref(self):
        from music21 import note

        n = note.Note()
        idStored = id(n)
        wn = common.wrapWeakref(n)
        n2 = common.unwrapWeakref(n)
        self.assertEqual(id(n), id(n2))

 def _getParent(self):
     if self._parent is None:
         return None
     post = common.unwrapWeakref(self._parent)
     if post is None:
         # set attribute for speed
         self._parent = None
     return post

    def client(self):
        '''
        The client stores a reference to the Plot that
        makes reference to this axis.

        (Like all music21 clients, It is normally stored internally as a weakref,
        so no need for garbage collecting)
        '''
        return common.unwrapWeakref(self._client)

    def purgeLocations(self, rescanIsDead=False):
        '''
        Clean all locations that refer to objects that no longer exist.

        The `removeOrphanedSites` option removes sites that may have been the
        result of deepcopy: the element has the site, but the site does not
        have the element. This results b/c Sites are shallow-copied, and then
        elements are re-added.

        >>> class Mock(base.Music21Object):
        ...     pass
        ...
        >>> aSite = Mock()
        >>> cSite = Mock()
        >>> aLocations = sites.Sites()
        >>> aLocations.add(aSite, 0)
        >>> aLocations.add(cSite) # a context
        >>> del aSite
        >>> len(aLocations)
        2

        >>> aLocations.purgeLocations(rescanIsDead=True)
        >>> len(aLocations)
        1
        '''
        # first, check if any sites are dead, and cache the results
        if rescanIsDead:
            for idKey in self._locationKeys:
                if idKey is None:
                    continue
                siteRef = self.siteDict[idKey]
                #if siteRef.isDead:
                #    continue  # already marked -- do it again, in case it is reused
                if WEAKREF_ACTIVE:
                    obj = common.unwrapWeakref(
                        siteRef.site)
                else:
                    obj = siteRef.site
                if obj is None: # if None, it no longer exists
                    siteRef.isDead = True
                else:
                    siteRef.isDead = False
        # use previously set isDead entry, so as not to
        # unwrap all references
        remove = []
        for idKey in self._locationKeys:
            if idKey is None:
                continue
            siteRef = self.siteDict[idKey]
            if siteRef.isDead:
                remove.append(idKey)
                
        for idKey in remove:
            # this call changes the ._locationKeys list, and thus must be
            # out side _locationKeys loop
            self.removeById(idKey)

 def _getAndUnwrapSite(self):
     if WEAKREF_ACTIVE:
         ret = common.unwrapWeakref(self.siteWeakref)
     else:
         ret = self.siteWeakref
         
     if ret is None and self is not _NoneSiteRef:
         self.isDead = True
         
     return ret

 def client(self):
     '''
     Get or set the client, which must be a note.NotRest subclass. The
     client is wrapped in a weak reference.
     '''
     if self._client is None:
         return None
     post = common.unwrapWeakref(self._client)
     if post is None:
         # set attribute for speed
         self._client = None
     return post

    def getSites(self, idExclude=None, excludeNone=False):
        """
        Get all Site objects in .siteDict that are locations. 
        Note that this unwraps all sites from weakrefs and is thus an expensive operation.

        ::
        
            >>> import music21
            >>> class Mock(music21.Music21Object):
            ...     pass
            ...
            >>> aObj = Mock()
            >>> bObj = Mock()
            >>> aSites = music21.Sites()
            >>> aSites.add(aObj, 234)
            >>> aSites.add(bObj, 3000)
            >>> len(aSites._locationKeys) == 2
            True

        ::

            >>> len(aSites.getSites()) == 2
            True

        """
        #         if idExclude is None:
        #             idExclude = [] # else, assume a list
        # use pre-collected keys
        post = []
        for idKey in self._locationKeys:
            if idExclude is not None:
                if idKey in idExclude:
                    continue
            try:
                objRef = self.siteDict[idKey].site
            except KeyError:
                raise SitesException("no such site: %s" % idKey)
            # skip dead references
            if self.siteDict[idKey].isDead:
                continue
            if idKey is None:
                if not excludeNone:
                    post.append(None)  # keep None as site
            elif not WEAKREF_ACTIVE:  # leave None alone
                post.append(objRef)
            else:
                obj = common.unwrapWeakref(objRef)
                if obj is None:
                    self.siteDict[idKey].isDead = True
                    continue
                post.append(obj)
        return post

    def unwrapWeakref(self):
        '''Unwrap any and all weakrefs stored.

        >>> from music21 import *  
        >>> s1 = stream.Stream()
        >>> s2 = stream.Stream()
        >>> d1 = derivation.Derivation(s1) # sets container
        >>> d1.setAncestor(s2)
        >>> common.isWeakref(d1._container)
        True
        >>> d1.unwrapWeakref()
        >>> common.isWeakref(d1._container)
        False
        '''
        #environLocal.pd(['derivation pre unwrap: self._container', self._container])
        post = common.unwrapWeakref(self._container)
        self._container = post

    def getSitesByClass(self, className):
        """
        Return a list of unwrapped site from siteDict.site [SiteRef.site] (generally a Stream) 
        that matches the provided class.

        Input can be either a Class object or a string

            >>> import music21
            >>> from music21 import stream
            >>> class Mock(music21.Music21Object):
            ...     pass
            ...
            >>> aObj = Mock()
            >>> bObj = Mock()
            >>> cObj = stream.Stream()
            >>> aSites = music21.Sites()
            >>> aSites.add(aObj, 234)
            >>> aSites.add(bObj, 3000)
            >>> aSites.add(cObj, 200)
            >>> aSites.getSitesByClass(Mock) == [aObj, bObj]
            True

        ::

            >>> aSites.getSitesByClass('Stream') == [cObj]
            True

        """
        found = []
        if not isinstance(className, str):
            className = common.classToClassStr(className)

        for idKey in self._locationKeys:
            siteRef = self.siteDict[idKey]
            if siteRef.isDead:
                continue
            classStr = siteRef.classString
            if classStr == className:
                objRef = siteRef.site
                if not WEAKREF_ACTIVE:  # leave None alone
                    obj = objRef
                else:
                    obj = common.unwrapWeakref(objRef)
                found.append(obj)
        return found

 def affectTokenAfterParse(self, m21Obj):
     '''
     called to modify the tokenObj after parsing
     
     tokenObj may be None if another
     state has deleted it.
     '''
     self.affectedTokens.append(m21Obj)
     if self.autoExpires is not False:
         if len(self.affectedTokens) == self.autoExpires:
             self.end()
             p = common.unwrapWeakref(self.parent)
             for i in range(len(p.activeStates)):
                 backCount = -1 * (i+1)
                 if p.activeStates[backCount] is self:
                     p.activeStates.pop(backCount)
                     break
     return m21Obj

    def corpus(self):
        r'''
        The `corpus.corpora.Corpus` object associated with the metadata
        bundle's name.

        >>> from music21 import metadata
        >>> coreBundle = corpus.corpora.CoreCorpus().metadataBundle
        >>> coreBundle
        <music21.metadata.bundles.MetadataBundle 'core': {150... entries}>
        >>> coreBundle.corpus
        <music21.corpus.corpora.CoreCorpus>
        '''
        if self._corpus is not None:
            cObj = common.unwrapWeakref(self._corpus)
            if cObj is not None:
                return cObj
            
        if self.name is None:
            return None
        
        from music21.corpus import manager
        return manager.fromName(self.name)

 def _getParent(self):
     return common.unwrapWeakref(self._parent)

 def _getAndUnwrapSite(self):
     # should set isDead?
     return common.unwrapWeakref(self.siteWeakref)

 def client(self):
     return common.unwrapWeakref(self._client)

 def __getstate__(self):
     self._client = common.unwrapWeakref(self._client)
     return SlottedObject.__getstate__(self)

 def _getSpineCollection(self):
     return common.unwrapWeakref(self._spineCollection)