rh %SrSSKJr SSKrSSKJrJr SSKrSSKJ r SSK r SSK r SSK J r SSK Jr SSK Jr \R (aSS K Jr S r\ R&"5rS \S '"S S\R,5r"SS\ R0\R25r\"5rS\lS\l\ R<"5r"SS\ R05r "SS\ RB5r"\\ /r#\$S:XaSSK r \ RJ"\"5 gg)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\rSrSrSrg)SitesException1N)__name__ __module__ __qualname____firstlineno____static_attributes__rG/home/james-whalen/.local/lib/python3.13/site-packages/music21/sites.pyrr1srrcR\rSrSrSrSrSrSrSrSr \ "\\ 5r Sr S r S rg ) SiteRef7am 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 siteWeakrefcJSUlSUlSUlSUlSUlgNF)rrrrrselfs r__init__SiteRef.__init__es( #rcU[Lag[UR5nUR(aSnURSUR SU3$)NzGlobal None Indexz dead site/z to ) _NoneSiteRefreprsiterrr)r#siteReprs r _reprInternalSiteRef._reprInternallsI < & ? ;;"H..!4#7#7"8XJGGrc[(a![R"UR5nO URnUcU[LaSUlU$NT)WEAKREF_ACTIVEr unwrapWeakrefrr(r)r#rets r_getAndUnwrapSiteSiteRef._getAndUnwrapSitevs@ >&&t'7'78C""C ;4|3DK rcl[(a[R"U5UlOXlSUlgr!)r0r wrapWeakrefrr)r#r*s r_setAndWrapSiteSiteRef._setAndWrapSites' >%11$7D #  rclSn[(aRURnUcSUlO;[[ U55S-[[ 55-nU[ U'X l[RRU5n[(a UbXlU$![an[SU35UeSnAff=f)N_z This str screwed up everything: ) r0r*rstrid_singletonCounterr TypeErrorrSlottedObjectMixin __getstate__)r# currentSite siteIdValuete returnStates rr@SiteRef.__getstate__s >))K"#' !"[/2S83?P?R;SS :E*;7 $/ //<k5#I!#:;-Hs B B3B..B3c[RRX5 [(a2URb$URn[ Un[ U X0lggg![ a SnSUlNf=fr/) rr? __setstate__r0rr KeyErrorrr*)r#staterBrAs rrGSiteRef.__setstate__ss!!..t; >d..:**K #4[A *;7$I;>  #" "  #sAA43A4)rrrr*rrN)rrrr__doc__ __slots__r$r,r3r7propertyr*r@rGrrrrrr7s=!HI H  % 7D* $rrcp\rSrSrSrSrSrS#SjrSrSr S r S$S jr S r \ S SS .S%Sjj5r\ S S SS.S&Sjj5rS S SS.S&SjjrS SS S.SjrSrSS S\R$R&R(SS.SjrSrSrSrSrSrSrSrS'SjrSrS rS!r S"r!g)(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 _siteIndexcd[R"S[4/5UlSUlSUlg)Nr) collections OrderedDictr(rRrTrSr"s rr$Sites.__init__s.#//$ 1E0HI  rNcUR5nURHnUcMURUnUR(aM*[5nURUlURcSnO[ UR5nUR Ul[5UlURUl SUlXRRU'M URUl U$)a 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__rRrrr*r<rr=rrrT)r#memonewidKeyoldSitenewSitenewIdKeys r __deepcopy__Sites.__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 )lenrRr"s r__len__ Sites.__len__s4==!!rclURR5Hup#URULdM g g)z 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)rRitemsr*)r# checkSiteunused_siteRefIdsiteRefs r __contains__Sites.__contains__#s3$*.)<)<)> % ||y(*?rc URSS9$)aS 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) yieldSitesr"s r__iter__Sites.__iter__:s400rcUb [S5eUcUb [U5nSnX0R;a-URUnURSLaURbSnUbUcUR SnUSLaURUnSUlO [ 5nXlXGlURUl U=RS- sl[5Ul U(dXpRU'gg)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) rr<rRrr*classesrrrTrr=r)r#obj timeValuer^r updateNotAdd tempSiteRefrls radd Sites.addLs   !AB B =S_sGE MM !--.K""e+#((4#  ?{2++a.K 4 mmE*G"GNiG )!OO 1"3"5#*MM% rcV[R"S[4/5UlSUlg)z Clear all stored data. NrV)rWrXr(rRrSr"s rclear Sites.clears%$//$ 1E0HI  rF)sortByCreationTimepriorityTargetcgNrr#rprrs rrqSites.yieldSites r)rprrcgrrrs rrqrrrc## [URR55nUSLaUR5 Ub@[ U5nXT;a0UR SUR URU555 UHTnURUnURcU(dURv M6M8URnUc SUl MPUv MV g7f)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) listrRkeysreverser<insertpopindexr*r) r#rprr keyRepository priorityIdkeyrlrws rrqrsxT]]//12  %  ! ! #  %N+J*$$Q%2%6%6}7J7J:7V%WY!CmmC(G||#"!,,&#ll;%)GNI!sCCrrrpc[URUUUS95nUb5X$;a0URSURUR U555 U$)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)rrqrrr)r#rrrpposts rget Sites.gets]VDOO7I3A0;$=>  %% Atxx >(BCD rc|SnURSS9HnUcM[X15nUs $ g![a M(f=f)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 Nr)r)rqgetattrAttributeError)r#attrNamerrws r getAttrByNameSites.getAttrByName,sPD??i?@C{ s- A "  s - ;;) callerFirstrrgetElementMethodr\cUcUnUc0nSnURUUSS9n[U[5n UH3n U (aXR;aU n OM[X5(dM1U n O UbU$UHn U (aFU R(a5U R R 5S:XaU RUSS9(dMP[U 5U;dMaX[U 5'U RUUUS9nUcM U$ U$)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)rr) rq isinstancer;rvisFlatsites getSiteCounthasElementOfClassr<getContextByClass) r# classNamerrrrr\robjsclassNameIsStrrws r getObjByClassSites.getObjByClassXs#j  K <D 1)  $Is3C +D,C++  K C#** 99))+q000d0K #wd"!$RW ,,'9%5-7# 76 rc8URUnUR$)z 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 )rRr*)r#siteIdrls rgetById Sites.getByIds--'||rcSnURR5H(nURSLaMURcM#US- nM* U$)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 rTru)rRvaluesrr)r#countrls rrSites.getSiteCountsN }}++-G~~%""* QJE .  rcH[URR55$)z 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 )setrRrr"s r getSiteIdsSites.getSiteIdss4==%%'((rc(/n[U[5(d[R"U5nURR 5HFnUR (aMURnXA:XdM)URnURU5 MH U$)a 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 ) rr;rclassToClassStrrRrrrr*append)r#rfoundrlclassStrobjRefs rgetSitesByClassSites.getSitesByClassst2)S))..y9I}}++-G~~**H$  V$ . rcXR;$)aw 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 )rR)r#rs r hasSiteIdSites.hasSiteId%s,&&rcURR5H(nUR(aMURS:XdM( g g)z Return True if this object is found in any Spanner. This is determined by looking for a SpannerStorage Stream class as a Site. SpannerStorageTFrRrrrr#rls rhasSpannerSiteSites.hasSpannerSite=< }}++-G~~""&66 . rcURR5H(nUR(aMURS:XdM( g g)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 rhasVariantSiteSites.hasVariantSiteIrrclU(aFURH6nUcMURUnURnUc SUlM/SUlM8 /nURH;nUcMURUnUR(dM*URU5 M= UHnUR U5 M g)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)rRr*rr removeById)r# rescanIsDeadr^rlrwremoves rpurgeLocationsSites.purgeLocationsUsB =--.ll;%)GN%*GN']]E}mmE*G~~~ e$ #E OOE "rcSUlSnUb [U5nURU g![an[ SSUS3-5UeSnAff=f)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 rVNzan entry for this object (z$) is not stored in this Sites object)rSr<rR Exceptionr)r#r*res rr Sites.removeskT   XF  f%  +dV?@A  s ' A AA cXR:XaSUlUc [S5eURU g![a gf=f)z= Remove a site entry by id key, which is id() of the object. rVNz*trying to remove None idKey is not allowed)rSrrRrH)r#r^s rrSites.removeByIdsI LL DL = !MN N  e$   s 4 AAcUR5H nUcM[X15n[X1U5 M" g![a M2f=f)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)r#rvaluerwjunks r setAttrByNameSites.setAttrByNamesI$88:C{ s-u-  "  s6 AA)rSrTrRr)NNN)rpzt.Literal[True]r#t.Union[bool, t.Literal['reverse']]returnz$Generator[stream.Stream, None, None])rpboolrrrz+Generator[stream.Stream | None, None, None])F)"rrrrrKrLr$rbrfrmrrr{r~rrqrrrenums ElementSearch AT_OR_BEFORErrrrrrrrrrrrrrrrrPrPsW I :x"".1$7+rNS"&  / (K =   (-MR"&  $ (K B   (-MR"& T $T(KT B Tp % 6p*` 33@@ ob 2 )$L'0  8#t7r$rrPc\rSrSrSrSrg)TesticSSKJn SSKJn SSKJn SSKJn UR "5nSUlUR5nURU5 UR5nURRU5 UR5nURRU5 URURRS5S5 URRS[URRS555 URUR S 5 URRSURRS55 URUR S 5 UR#S S S S 9R%S5n U R'5R(Sn U R+UR5n UR-XR.5 g)Nr)noter )corpus)clef"numberlyric34zbeethoven/opus18no1)xml)fileExtensionszViolin IrV)music21rr rrMeasurerNoterrr{Clef assertEqualrrr;rparsegetElementByIdflattennotesrassertIsInstance TrebleClef) r#rr rrmnn2cviolin1lastNote lastNoteClefs r testSitesTest.testSitessg "" NN  IIK  YY[  Q IIK  A //92> gs288+A+A(+K'LM $' grxx'='=h'GH $',, ! #  . $  ??$**2.11$))<  lOOrs#5 ??;B:U:U:W7W \22 s$f'')?)?s$ly !  ++- F % % D =8   =Hu   z Tr