3j^UdZddlmZddlZddlmZmZddlZddlm Z ddl Z ddl Z ddl m Z ddl mZddl mZej rdd l mZd Ze j&Zd ed <Gd dej,ZGdde j0ej2ZeZde_de_e j<ZGdde j0Z Gdde jBZ"ee gZ#e$dk(rddl Z e jJe"yy)zM sites.py -- Objects for keeping track of relationships among Music21Objects ) annotationsN) GeneratorMutableMapping)overload)common) exceptions21)prebasestreamTz!MutableMapping[str, t.Any | None]GLOBAL_SITE_STATE_DICTc eZdZy)SitesExceptionN)__name__ __module__ __qualname__:/DATA/.local/lib/python3.12/site-packages/music21/sites.pyrr0srrcJeZdZdZdZdZdZdZdZe eeZ dZ dZ y ) SiteRefa a single Site (stream, container, parent, reference, etc.) stored inside the Sites object. A very simple object. This site would be stored in the .sites.siteDict for, say a note.Note, if it were in st at offset 20.0 >>> st = stream.Stream() >>> st.id = 'hi' >>> s = sites.SiteRef() >>> s.classString = st.classes[0] >>> s.site = st >>> s.isDead False If you call s.site, you always get an object out, but internally, there's a .siteWeakref that stores a weakref to the site. >>> s.site >>> s.siteWeakref If you turn sites.WEAKREF_ACTIVE to False then .siteWeakref just stores another reference to the site. Bad for memory. Good for debugging pickling. OMIT_FROM_DOCS Note that the ...Stream was needed after Python 3.13. When 3.13 is the lowest version, replace ... with the actual output. ) classStringglobalSiteIndex siteIndexisDead siteWeakrefcJd|_d|_d|_d|_d|_yNF)rrrrrselfs r__init__zSiteRef.__init__ds( #rc|turyt|j}|jrd}|jd|j d|S)NzGlobal None Indexz dead site/z to ) _NoneSiteRefreprsiterrr)rsiteReprs r _reprInternalzSiteRef._reprInternalksI < & ? ;;"H..!4#7#7"8XJGGrctr tj|j}n |j}||turd|_|SNT)WEAKREF_ACTIVEr unwrapWeakrefrr#r)rrets r_getAndUnwrapSitezSiteRef._getAndUnwrapSiteus> &&t'7'78C""C ;4|3DK rcptr"tj||_d|_y||_d|_yr)r*r wrapWeakrefrr)rr%s r_setAndWrapSitezSiteRef._setAndWrapSites2 %11$7D   $D  rcVd}trR|j}|d|_nzSiteRef.__setstate__su!!..tU; d..:**K #4[A *;7$DI;>  #" "  #sAA/.A/N) rrr__doc__ __slots__r r'r-r0propertyr%r8r>rrrrr6s=!HI H  % 7D* $rrcReZdZdZdZdZd!dZdZdZdZ d"d Z d Z e d dd  d#d Z e d d dd d$dZ d d dd d$dZ d dd ddZdZdd dej"j$j&dddZdZdZdZdZdZdZdZd%dZdZdZd Zy)&Sitesa| An object, stored within a Music21Object, that stores (weak) references to a collection of objects that may be contextually relevant to this object. Most of these objects are locations (also called sites), or Streams that contain this object. All defined contexts are stored as dictionaries in a dictionary. The outermost dictionary stores objects. )siteDict_lastID _siteIndexcbtjdtfg|_d|_d|_y)Nr) collections OrderedDictr#rGrIrHrs rr zSites.__init__s.#//$ 1E0HI  rNc|j}|jD]}||j|}|jr"t}|j|_|jd}nt |j}|j |_t|_|j|_ d|_||j|<|j|_ |S)av Helper function for copy.deepcopy that in addition to copying produces a new, independent Sites object. This does not, however, deepcopy site references stored therein. All sites, however, are passed on to the new deepcopy, which means that in a deepcopy of a Stream that contains Notes, the copied Note will have the former site as a location, even though the new Note instance is not actually found in the old Stream. >>> import copy >>> class Mock(base.Music21Object): ... pass >>> aObj = Mock() >>> aContexts = sites.Sites() >>> aContexts.add(aObj) >>> bContexts = copy.deepcopy(aContexts) >>> len(aContexts.get()) == 2 True >>> len(bContexts.get()) == 2 True >>> aContexts.get() == bContexts.get() True NF) __class__rGrrr%r4rr5rrrI)rmemonewidKeyoldSitenewSitenewIdKeys r __deepcopy__zSites.__deepcopy__s<nn]]E}mmE*G~~iG"<>> class Mock(base.Music21Object): ... pass >>> aObj = Mock() >>> aContexts = sites.Sites() >>> len(aContexts) 1 >>> aContexts.add(aObj) >>> len(aContexts) 2 )lenrGrs r__len__z Sites.__len__s4==!!rch|jjD]\}}|j|usyy)aY returns True if checkSite in Sites. >>> m1 = stream.Measure(number=1) >>> m2 = stream.Measure(number=2) >>> n = note.Note() >>> m1.append(n) >>> m1 in n.sites True >>> m2 in n.sites False None is always in sites >>> None in n.sites True TF)rGitemsr%)r checkSiteunused_siteRefIdsiteRefs r __contains__zSites.__contains__ s5$*.)<)<)> % g||y(*?rc&|jdS)a Returns all non-None sites. Order is oldest first. >>> n = note.Note() >>> m = stream.Measure(number=1) >>> s = stream.Stream(id='thisStream') >>> m.insert(10, n) >>> s.insert(20, n) >>> for site in n.sites: ... print(site, n.getOffsetBySite(site)) 10.0 20.0 T) excludeNone) yieldSitesrs r__iter__zSites.__iter__7s400rc| td| | t|}d}||jvr+|j|}|jdur|jd}|||j d}|dur|j|}d|_n t }||_||_|j|_ |xjdz c_t|_ |s||j|<yy)a_ Add a reference to the `Sites` collection for this object. Automatically called on stream.insert(n), etc. `idKey` stores the id() of the obj. If `None`, then id(obj) is used. `classString` stores the class of obj. If `None` then `obj.classes[0]` is used. TODO: Tests. Including updates. NzNo timeValue in sites anymore!FTr) rr4rGrr%classesrrrIrr5r)robj timeValuerRr updateNotAdd tempSiteRefr^s raddz Sites.addIs   !AB B =S_sGE DMM !--.K""e+#((4#  ?{2++a.K 4 mmE*G"GNiG )!OO 1"3"5#*DMM% rcTtjdtfg|_d|_y)z( Clear all stored data. NrK)rLrMr#rGrHrs rclearz Sites.clears%$//$ 1E0HI  rF)sortByCreationTimepriorityTargetcyNrrrarnros rrbzSites.yieldSites r)rarnrocyrqrrrs rrbzSites.yieldSitesrsrc#Kt|jj}|dur|j|?t |}||vr0|j d|j |j||D]I}|j|}|j|r!|j0|j}|d|_ F|Kyw)a Yield references; order, based on dictionary keys, is from least recently added to most recently added. The `sortByCreationTime` option if set to True will sort objects by creation time, where most-recently assigned objects are returned first. Note that priorityTarget is searched only on id -- this could be dangerous if the target has been garbage collected and the id is reused. Unlikely since you have to pass in the priorityTarget itself, so therefore it still exists. This can be much faster than .get in the case where the sought-for site is earlier in the list. >>> class Mock(base.Music21Object): ... def __init__(self, idEl): ... self.id = idEl >>> aObj = Mock('a') >>> bObj = Mock('b') >>> cObj = Mock('c') >>> aSites = sites.Sites() >>> aSites.add(cObj) >>> aSites.add(aObj) >>> aSites.add(bObj) Returns a generator: >>> ys = aSites.yieldSites() >>> ys That's no help, so iterate over it instead: >>> for s in aSites.yieldSites(sortByCreationTime=True, excludeNone=True): ... print(s.id) b a c With priorityTarget >>> for s in aSites.yieldSites(sortByCreationTime=True, priorityTarget=cObj, ... excludeNone=True): ... print(s.id) c b a * Changed in v3: changed dramatically from previously unused version `sortByCreationTime='reverse'` is removed, since the ordered dict takes care of it and was not working. * Changed in v8: arguments are keyword only. TNr) listrGkeysreverser4insertpopindexr%r) rrarnro keyRepository priorityIdkeyr^rgs rrbzSites.yieldSitessxT]]//12  %  ! ! #  %N+J]*$$Q%2%6%6}7J7J:7V%WY!CmmC(G||#"!,,&ll;%)GNI!s BC ,C rnroract|j|||}|4||vr0|jd|j|j ||S)a Get references; order, based on dictionary keys, is from most recently added to least recently added. The `sortByCreationTime` option will sort objects by creation time, where most-recently assigned objects are returned first. Can be [False, other], [True, 1] or ['reverse', -1] If `priorityTarget` is defined, this object will be placed first in the list of objects. >>> class Mock(base.Music21Object): ... pass >>> aObj = Mock() >>> bObj = Mock() >>> cObj = Mock() >>> aSites = sites.Sites() >>> aSites.add(cObj) >>> aSites.add(aObj) >>> aSites.add(bObj) Arbitrary order, so we compare with sets: >>> set(aSites.get()) == {None, cObj, aObj, bObj} True Particular order, with None at the end. >>> aSites.get(sortByCreationTime=True) == [bObj, aObj, cObj, None] True Priority target >>> begotten = aSites.get(sortByCreationTime=True, priorityTarget=cObj, excludeNone=True) >>> begotten == [cObj, bObj, aObj] True * Changed in v5.5: keyword only. rr)rvrbryrzr{)rrnroraposts rgetz Sites.gets_VDOO7I3A0;$=>  %% Atxx >(BCD rczd}|jdD]}| t||}|cSy#t$rY$wxYw)a[ Given an attribute name, search all objects and find the first that matches this attribute name; then return a reference to this attribute. Works in reverse order, so most recent site is returned first. >>> class Mock(base.Music21Object): ... attr1 = 234 >>> aObj = Mock() >>> aObj.attr1 = 234 >>> bObj = Mock() >>> bObj.attr1 = 98 >>> aSites = sites.Sites() >>> len(aSites) 1 >>> aSites.add(aObj) >>> len(aSites) 2 >>> aSites.getAttrByName('attr1') == 234 True >>> aSites.remove(aObj) >>> aSites.add(bObj) >>> aSites.getAttrByName('attr1') == 98 True An incorrect attribute name will just give none: >>> aSites.getAttrByName('blah') is None True Nrx)rn)rbgetattrAttributeError)rattrNamerrgs r getAttrByNamezSites.getAttrByName,sRD??i?@C{ sH- A "  s . ::) callerFirstrnrogetElementMethodrPc||}|i}d}|j||d}t|t} |D]'} | r|| jvs| }nt| |s%| }n||S|D]v} | r=| jr1| j j dk(r| j|dsBt| |vsP| |t| <| j|||}|u|S|S)aK Return the most recently added reference based on className. Class name can be a string or the class name. This will recursively search the sitesDicts of objects in Site objects in the siteDict. The `callerFirst` parameters is simply used to pass a reference of the first caller; this is necessary if we are looking within a Stream for a flat offset position. If `priorityTarget` is specified, this location will be searched first. use priorityTarget=activeSite to prioritize that. The `getElementMethod` is a string that selects which Stream method is used to get elements for searching with getElementsByClass() calls. >>> import time >>> class Mock(base.Music21Object): ... pass >>> aObj = Mock() >>> bObj = Mock() >>> aSites = sites.Sites() >>> aSites.add(aObj) >>> aSites.add(bObj) We get the most recently added object first >>> aSites.getObjByClass('Mock', sortByCreationTime=True) == bObj True >>> aSites.getObjByClass(Mock, sortByCreationTime=True) == bObj True * Changed in v5.5: all arguments except className are keyword only. OMIT_FROM_DOCS TODO: not sure if memo is properly working: need a test case NTrr) forceFlat)rnr) rb isinstancer3rfisFlatsites getSiteCounthasElementOfClassr4getContextByClass) r classNamerrnrorrProbjsclassNameIsStrrgs r getObjByClasszSites.getObjByClassXsj  K <D 1) $Is3C +DC+  K C#** 99))+q000d0K #wd"!$RW ,,'9%5-7# 76 rc8|j|}|jS)a Return the object specified by an id. Used for testing and debugging. Should NOT be used in production code. >>> a = note.Note() >>> s = stream.Stream() >>> s.append(a) >>> a.sites.getById(id(s)) is s True )rGr%)rsiteIdr^s rgetByIdz Sites.getByIds--'||rcd}|jjD]#}|jdur|j|dz }%|S)a Return the number of non-dead sites, excluding the None site. This does not unwrap weakrefs for performance. >>> a = note.Note() >>> a.sites.getSiteCount() 0 >>> s = stream.Stream() >>> s.append(a) >>> a.sites.getSiteCount() 1 >>> sf = s.flatten() >>> a.sites.getSiteCount() 2 rTre)rGvaluesrr)rcountr^s rrzSites.getSiteCountsN }}++-G~~%""* QJE .  rcHt|jjS)a Return a set of all site Ids. >>> class Mock(base.Music21Object): ... pass >>> aSite = Mock() >>> dc = sites.Sites() >>> dc.add(aSite) >>> dc.getSiteIds() == {None, id(aSite)} True )setrGrwrs r getSiteIdszSites.getSiteIdss4==%%'((rc g}t|tstj|}|jj D]>}|j r|j}||k(s"|j}|j|@|S)aq 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 >>> class Mock(base.Music21Object): ... pass >>> aObj = Mock() >>> bObj = Mock() >>> cObj = stream.Stream() >>> aSites = sites.Sites() >>> aSites.add(aObj) >>> aSites.add(bObj) >>> aSites.add(cObj) >>> aSites.getSitesByClass(Mock) == [aObj, bObj] True >>> aSites.getSitesByClass('Stream') == [cObj] True ) rr3rclassToClassStrrGrrrr%append)rrfoundr^classStrobjRefs rgetSitesByClasszSites.getSitesByClassss2)S)..y9I}}++-G~~**H9$  V$ . rc||jvS)a Return True or False if this Sites object already has this site id. >>> class Mock(base.Music21Object): ... pass >>> aSite = Mock() >>> bSite = Mock() >>> dc = sites.Sites() >>> dc.add(aSite) >>> dc.hasSiteId(id(aSite)) True >>> dc.hasSiteId(id(bSite)) False Note that we use 'None' not id(None) as a key: >>> dc.hasSiteId(id(None)) False >>> dc.hasSiteId(None) True )rG)rrs r hasSiteIdzSites.hasSiteId)s,&&rc~|jjD] }|jr|jdk(s yy)z Return True if this object is found in any Spanner. This is determined by looking for a SpannerStorage Stream class as a Site. SpannerStorageTFrGrrrrr^s rhasSpannerSitezSites.hasSpannerSiteA< }}++-G~~""&66 . rc~|jjD] }|jr|jdk(s yy)z Return True if this object is found in any Variant. This is determined by looking for a VariantStorage Stream class as a Site. VariantStorageTFrrs rhasVariantSitezSites.hasVariantSiteMrrc>|r@|jD]1}||j|}|j}|d|_+d|_3g}|jD]2}||j|}|js"|j|4|D]}|j |y)a 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. >>> import gc >>> class Mock(base.Music21Object): ... pass >>> aStream = stream.Stream() >>> bStream = stream.Stream() >>> mySites = sites.Sites() >>> len(mySites) 1 >>> mySites.add(aStream) >>> mySites.add(bStream) >>> del aStream >>> numObjectsCollected = gc.collect() # make sure to garbage collect We still have 3 locations -- just because aStream is gone, doesn't make it disappear from sites >>> len(mySites) 3 >>> mySites.purgeLocations(rescanIsDead=True) >>> len(mySites) 2 NTF)rGr%rr removeById)r rescanIsDeadrRr^rgremoves rpurgeLocationszSites.purgeLocationsYsB =--.ll;%)GN%*GN']]E}mmE*G~~ e$ #E OOE "rcd|_d}| t|} |j|=y#t$r}t d|d|d}~wwxYw)a Remove the object (a context or location site) specified from Sites. Object provided can be a location site (i.e., a Stream) or a pure context (like a Temperament). N.B. -- like all .sites operations, this is an advanced tool not for standard music21 usage. Instead of: elObj.remove(streamObj) use this command, which will take care of `.sites.remove` as well as removing `elObj` from `streamObj.elements`: streamObj.remove(elObj) >>> class Mock(base.Music21Object): ... pass >>> aSite = Mock() >>> bSite = Mock() >>> cSite = Mock() >>> aSites = sites.Sites() >>> len(aSites) 1 >>> aSites.add(aSite) >>> len(aSites) 2 >>> aSites.add(bSite) >>> len(aSites) 3 >>> aSites.add(cSite) >>> len(aSites) 4 >>> aSites.remove(aSite) >>> len(aSites) 3 rKNzan entry for this object (z$) is not stored in this Sites object)rHr4rG Exceptionr)rr%res rrz Sites.removesgT   XF  f%  6=?  s & A?Ac||jk(rd|_| td |j|=y#t$rYywxYw)zU Remove a site entry by id key, which is id() of the object. rKNz*trying to remove None idKey is not allowed)rHrrGr?)rrRs rrzSites.removeByIdsK DLL DL = !MN N  e$   s 3 ??c|jD]}| t||}t|||!y#t$rY.wxYw)a Given an attribute name, search all objects and find the first that matches this attribute name; then return a reference to this attribute. >>> class Mock(base.Music21Object): ... attr1 = 234 >>> aObj = Mock() >>> bObj = Mock() >>> bObj.attr1 = 98 >>> aSites = sites.Sites() >>> aSites.add(aObj) >>> aSites.add(bObj) >>> aSites.setAttrByName('attr1', 'test') >>> aSites.getAttrByName('attr1') == 'test' True N)rrsetattrr)rrvaluergjunks r setAttrByNamezSites.setAttrByNamesM$88:C{ sH-Xu-  "  s4 AArq)NNN)razt.Literal[True]rnbool | t.Literal['reverse']returnz$Generator[stream.Stream, None, None])raboolrnrrz+Generator[stream.Stream | None, None, None])F) rrrrArBr rVrYr_rcrkrmrrbrrrenums ElementSearch AT_OR_BEFORErrrrrrrrrrrrrrrrFrFsW I 8t"".1$:+xDI"&  / (A =   (-CH"&  $ (A B   (-CH"& T $T(AT B Tp % 6p*` 33@@ sj 2 )$L'0  8#t7r$rrFceZdZdZy)Testcddlm}ddlm}ddlm}ddlm}|j }d|_|j}|j||j}|jj||j}|jj||j|jjdd|jjdt|jjd|j|j d |jjd|jjd|j|j d |j#d d d j%d} | j'j(d} | j+|j} |j-| |j.y)Nr)noter )corpus)clef"numberlyric34zbeethoven/opus18no1)xml)fileExtensionszViolin IrK)music21rr rrMeasurerNoterrrkClef assertEqualrrr3rparsegetElementByIdflattennotesrassertIsInstance TrebleClef) rrr rrmnn2cviolin1lastNote lastNoteClefs r testSiteszTest.testSitessk "" FNN  IIK  YY[  Q IIK  A //92> gs288+A+A(+K'LM $' grxx'='=h'GH $',, ! #  . $  ??$**2.11$))<  lDOOrs#5 ??;V':U:U:W7W \22 s$f'')?)?s$ly !  +F++-D F % %D N =8   =Hu   zGTr