rhtPSrSSKJr SSKrSSKJr SSKrSSKrSSK J r SSK J r SSK Jr SSKJrJrJr SS KJr SS KJr SS KJrJr SS KJrJr \R8(aSS KJr "SS\ 5r"SS\R@5r!\"S:XaSSKr\RF"\!5 gg)a the Stream Core Mixin handles the core attributes of streams that should be thought of almost as private values and not used except by advanced programmers who need the highest speed in programming. Nothing here promises to be stable. The music21 team can make any changes here for efficiency reasons while being considered backwards compatible so long as the public methods that call these methods remain stable. All functions here will eventually begin with `.core`. ) annotationsN)Fraction) Music21Object) OffsetSpecial)opFrac)OffsetQLOffsetQLSpecial M21ObjType)spanner)tree)StreamExceptionImmutableStreamException)StreamIteratorRecursiveIterator)StreamcJ^\rSrSrSrSU4SjjrSSS.SSjjrSS.S S jjrSSS .S!S jjrSSS SS .S"Sjjr SSS.S#Sjjr Sr SS.Sjr S$Sjr \S5rSS S.SjrSrSS SSS.SjrSSSS S.S%SjjrSrU=r$)& StreamCore-z Core aspects of a Stream's behavior. Any of these can change at any time. Users are encouraged only to create stream.Stream objects. c l>[TU]"S0UD6 0Ul/Ul/UlSUlSUlg)NT)super__init__ _offsetDict _elements _endElementsisSortedisFlat)selfkeywords __class__s M/home/james-whalen/.local/lib/python3.13/site-packages/music21/stream/core.pyrStreamCore.__init__2s@ $8$ NP/124  FT) ignoreSort setActiveSitecSnU(d}URSLanURnXa:aSnOZXa:XaUUR(dSnOAURSR5nUR5R US9nXx:aSnUR U[ U5SUS9 URRU5 URRU5 U$)a N.B. -- a "core" method, not to be used by general users. Run .insert() instead. A faster way of inserting elements that performs no checks, just insertion. Only be used in contexts that we know we have a proper, single Music21Object. Best for usage when taking objects in a known Stream and creating a new Stream When using this method, the caller is responsible for calling Stream.coreElementsChanged after all operations are completed. Do not mix coreInsert with coreAppend operations. Returns boolean if the Stream (assuming it was sorted before) is still guaranteed to be sorted. (False doesn't mean that it's not sorted, just that we can't guarantee it.) If you don't care and plan to sort the stream later, then use `ignoreSort=True`. FT)offset addElementr%) r highestTimer sortTuplemodifycoreSetElementOffsetfloatsitesaddappend) rr(elementr$r% storeSortedhthighestSortTuple thisSortTuples r! coreInsertStreamCore.coreInsertHs<  }}$%%;"&K\>>&* +/>>"+=+G+G+I((/(9(9(;(B(B&(B(Q +;*.K !!  &M' "  $ g&r#)r%c&URnURXSS9 URRU5 U(aUR U5 UR R U5 URX1RR-5 g)aB N.B. -- a "core" method, not to be used by general users. Run .append() instead. Low level appending; like `coreInsert` does not error check, determine elements changed, or similar operations. When using this method, the caller is responsible for calling Stream.coreElementsChanged after all operations are completed. Tr*N) r+r.r0r1coreSelfActiveSiterr2_setHighestTimeduration quarterLength)rr3r%r5s r! coreAppendStreamCore.coreAppendsv"   !!'$!? $   # #G , g& R"2"2"@"@@Ar#r)c,[U5n[ U5nU(d!XPR ;a[SUSUS35eX!4UR U'U(aUR U5 gg![a U[;a[SU<SU35eNf=f)aN Sets the Offset for an element, very quickly. Caller is responsible for calling :meth:`~music21.stream.core.coreElementsChanged` afterward. >>> s = stream.Stream() >>> s.id = 'Stream1' >>> n = note.Note('B-4') >>> s.insert(10, n) >>> n.offset 10.0 >>> s.coreSetElementOffset(n, 20.0) >>> n.offset 20.0 >>> n.getOffsetBySite(s) 20.0 zCannot set offset to z for z"Cannot set the offset for element z, not in Stream .N)r TypeErrorrr idrr<)rr3r(r*r%idEls r!r.StreamCore.coreSetElementOffsets6 XF^F '{d*:*::!4WI=MdVSTUW W"(!2   # #G ,  X]*%(=fZuWI&VWW+ Xs A**&BBN) updateIsFlat clearIsSortedmemo keepIndexc[USS5(d [S5eUc/n[U5U;agUR[U55 URbWURR nUS;a;[ R"SURR5nUR5 URHnURUS9 M U(aSUl U(a4SUl URHnUR(dMSUl O UR (aSSn U(aS UR ;aUR S n UR5 U(aU bXR S 'gggg) a- NB -- a "core" stream method that is not necessary for most users. This method is called automatically any time the elements in the Stream are changed. However, it may be called manually in case sites or other advanced features of an element have been modified. It was previously a private method and for most users should still be treated as such. The various arguments permit optimizing the clearing of cached data in situations when completely dropping all cached data is excessive. >>> a = stream.Stream() >>> a.isFlat True Here we manipulate the private `._elements` storage (which generally shouldn't be done) using coreAppend and thus need to call `.coreElementsChanged` directly. >>> a.coreAppend(stream.Stream()) >>> a.isFlat # this is wrong. True >>> a.coreElementsChanged() >>> a.isFlat False _mutableTzBcoreElementsChanged should not be triggered on an immutable streamN)flatsemiflatzmusic21.stream.Stream)rJFindex)getattrrrEr2 _derivationmethodtcastorigin clearCacher0coreElementsChangedrrrisStream_cache) rrHrIrJrKsdmrV livingSitee indexCaches r!rXStreamCore.coreElementsChangedsTFtZ..*T  <D d8t   BtH    '""))C**23&&9P9=9I9I9P9P3R!!# **J  * * * 5% !DM DK^^:::"'DK $ ;;JW 3![[1  OO Z3'1 G$4y r#)recursedeepc SSKJn U(a[R"U5nO[R"U5nXRlU(a1U(a*[ XTR5(aURUSS9 U$)a[ *This is a Core method that most users will not need to use.* Make a copy of this stream with the proper derivation set. >>> s = stream.Stream() >>> n = note.Note() >>> s.append(n) >>> s2 = s.coreCopyAsDerivation('exampleCopy') >>> s2.derivation.method 'exampleCopy' >>> s2.derivation.origin is s True >>> s2[0].derivation.method 'exampleCopy' r)streamT)r`) music21rccopydeepcopy derivationrS isinstancersetDerivationMethod)r methodNamer`rarcposts r!coreCopyAsDerivationStreamCore.coreCopyAsDerivation2sZ( # ==&D99T?D!+ t 4 ? ?  $ $Z $ > r#cURHn[U5U:XdMUs $ URHn[U5U:XdMUs $ g)a NB -- a "core" stream method that is not necessary for most users. Low-level tool to get an element based only on the object id. This is not the same as getElementById, which refers to the id attribute which may be manually set and not unique. However, some implementations of python will reuse object locations, sometimes quickly, so don't keep these around. Used by spanner and variant. >>> s = stream.Stream() >>> n1 = note.Note('g') >>> n2 = note.Note('g#') >>> s.append(n1) >>> s.coreGetElementByMemoryLocation(id(n1)) is n1 True >>> s.coreGetElementByMemoryLocation(id(n2)) is None True >>> b = bar.Barline() >>> s.storeAtEnd(b) >>> s.coreGetElementByMemoryLocation(id(b)) is b True N)rrEr)robjIdr]s r!coreGetElementByMemoryLocation)StreamCore.coreGetElementByMemoryLocationRsI:A!u~ ""A!u~#r#)checkRedundancyc XLa [S5e[U[5(d6[U[5(a [S5e[SU<S3S-S-5eU(a[ U5nX0R ;aiUR UR4H@nUH7nXQLdM [SU<S[ U5S 3S U<S[ U5S 3-5e MB UR U UR5 g ) a Before adding an element, this method performs important checks on that element. Used by: - :meth:`~music21.stream.Stream.insert` - :meth:`~music21.stream.Stream.append` - :meth:`~music21.stream.Stream.storeAtEnd` - `Stream.__init__()` Returns None or raises a StreamException >>> s = stream.Stream() >>> s.coreGuardBeforeAddElement(s) Traceback (most recent call last): music21.exceptions21.StreamException: this Stream cannot be contained within itself >>> s.append(s.iter()) Traceback (most recent call last): music21.exceptions21.StreamException: cannot insert StreamIterator into a Stream Iterate over it instead (User's Guide chs. 6 and 26) >>> s.insert(4, 3.14159) Traceback (most recent call last): music21.exceptions21.StreamException: The object you tried to add to the Stream, 3.14159, is not a Music21Object. Use an ElementWrapper object if this is what you intend. z-this Stream cannot be contained within itselfz_cannot insert StreamIterator into a Stream Iterate over it instead (User's Guide chs. 6 and 26)z+The object you tried to add to the Stream, z, z6is not a Music21Object. Use an ElementWrapper object zif this is what you intend.z the object (z, id()= z!is already found in this Stream ()N) r rhrrrErrrpurgeLocations)rr3rr idElement search_place eInStreams r!coreGuardBeforeAddElement$StreamCore.coreGuardBeforeAddElementxs> ?!"QR R'=11'>22%KLL"=g[KJK/01 1 7 I,,,&*^^T5F5F$GL%1 $/"1".wkG Q O$EdXWUWX\U]T^^_"`!a#&2%H$$Y/  r#cURU[RSS9 URR U5 U(aUR U5 UR RU5 g)z NB -- this is a "core" method. General users should use .storeAtEnd() instead. Core method for adding end elements. To be called by other methods. Tr;N)r.rAT_ENDr0r1r<rr2)rr3r%s r!coreStoreAtEndStreamCore.coreStoreAtEndsV !!'=+?+?D!Q $   # #G ,   )r#cSUR;dURScKUR[R4SS9n[R"[ U55URS'URS$)zJ A low-level object for Spanner management. This is a read-only property. spannerBundleF) classFilterrestoreActiveSites)rZr`r Spanner SpannerBundlelist)rspannerss r!rStreamCore.spannerBundlesd $++ -_1M1U||0BW\|]H+2+@+@h+PDKK ({{?++r#flatten classListc[[U=(d S5U45nS[U5-nX@R;dURUc-[R R UUUS9nXPRU'URU$)a Convert stream to a :class:`~music21.tree.trees.TimespanTree` instance, a highly optimized data structure for searching through elements and offsets. >>> score = tree.makeExampleScore() >>> scoreTree = score.asTimespans() >>> print(scoreTree) > > > > > > > > > > > > > > > > > > > > > r timespanTreer)hashtuplestrrZr fromStream asTimespans)rrrhashedAttributescacheKeyhashedTimespanTrees r!rStreamCore.asTimespanss> yB!7 AB!C(8$99 ;; &$++h*?*G!%!>> score = tree.makeExampleScore() >>> scoreTree = score.asTree(flatten=True) >>> scoreTree to 8.0) > r elementTreer) rT TYPE_CHECKINGrhrrrrrZr rasTree)rrrrrrrhashedElementTrees r!rStreamCore.asTrees ??dF++ ++yB!7")".".!01!3'7#88 ;; &$++h*?*G $ 6 6t?FAJDPDP !7!R  %6KK !{{8$$r#)r`requireAllPresentinsertconstrainingSpannerBundlecURnUSLaUR5nOUR5n/n[U5HsnUR 5H\n X;aM X;aMUbX;aMU(a)Sn U R 5H n X;dM Sn O U SLaMKUR U 5 M^ Mu USLaU$U(a*UHn URSU 5 M URSS9 g)a find all spanners that are referenced by elements in the (recursed if recurse=True) stream and either inserts them in the Stream (if insert is True) or returns them if insert is False. If requireAllPresent is True (default) then only those spanners whose complete spanned elements are in the Stream are returned. Because spanners are stored weakly in .sites this is only guaranteed to find the spanners in cases where the spanner is in another stream that is still active. Here's a little helper function since we'll make the same Stream several times, with two slurred notes, but without the slur itself. Python's garbage collection will get rid of the slur if we do not prevent it >>> preventGarbageCollection = [] >>> def getStream(): ... s = stream.Stream() ... n = note.Note('C') ... m = note.Note('D') ... sl = spanner.Slur(n, m) ... preventGarbageCollection.append(sl) ... s.append([n, m]) ... return s Okay now we have a Stream with two slurred notes, but without the slur. `coreGatherMissingSpanners()` will put it in at the beginning. >>> s = getStream() >>> s.show('text') {0.0} {1.0} >>> s.coreGatherMissingSpanners() >>> s.show('text') {0.0} {0.0} > {1.0} Now, the same Stream, but insert is False, so it will return a list of Spanners that should be inserted, rather than inserting them. >>> s = getStream() >>> spList = s.coreGatherMissingSpanners(insert=False) >>> spList [>] >>> s.show('text') {0.0} {1.0} Now we'll remove the second note so not all elements of the Slur are present. This, by default, will not insert the Slur: >>> s = getStream() >>> s.remove(s[-1]) >>> s.show('text') {0.0} >>> s.coreGatherMissingSpanners() >>> s.show('text') {0.0} But with `requireAllPresent=False`, the spanner appears! >>> s.coreGatherMissingSpanners(requireAllPresent=False) >>> s.show('text') {0.0} {0.0} > With `recurse=False`, then spanners are not gathered inside the inner stream: >>> part = stream.Part() >>> s = getStream() >>> part.insert(0, s) >>> part.coreGatherMissingSpanners(recurse=False) >>> part.show('text') {0.0} {0.0} {1.0} But the default acts with recursion: >>> part.coreGatherMissingSpanners() >>> part.show('text') {0.0} {0.0} {1.0} {0.0} > Spanners already in the stream are not put there again: >>> s = getStream() >>> sl = s.notes.first().getSpannerSites()[0] >>> sl > >>> s.insert(0, sl) >>> s.coreGatherMissingSpanners() >>> s.show('text') {0.0} {0.0} > {1.0} Also does not happen with recursion. >>> part = stream.Part() >>> s = getStream() >>> sl = s.notes.first().getSpannerSites()[0] >>> s.insert(0, sl) >>> part.insert(0, s) >>> part.coreGatherMissingSpanners() >>> part.show('text') {0.0} {0.0} {0.0} > {1.0} If `constrainingSpannerBundle` is set then only spanners also present in that spannerBundle are added. This can be useful, for instance, in restoring spanners from an excerpt that might already have spanners removed. In Jacob Tyler Walls's brilliant phrasing, it prevents regrowing zombie spanners that you thought you had killed. Here we will constrain only to spanners also present in another Stream: >>> s = getStream() >>> s2 = stream.Stream() >>> s.coreGatherMissingSpanners(constrainingSpannerBundle=s2.spannerBundle) >>> s.show('text') {0.0} {1.0} Now with the same constraint, but we will put the Slur into the other stream. >>> sl = s.notes.first().getSpannerSites()[0] >>> s2.insert(0, sl) >>> s.coreGatherMissingSpanners(constrainingSpannerBundle=s2.spannerBundle) >>> s.show('text') {0.0} {0.0} > {1.0} TNFr)rH) rr`iterrgetSpannerSitesgetSpannedElementsr2r8rX) rr`rrrsbsIter collectListrspallFoundspannedElements r!coreGatherMissingSpanners$StreamCore.coreGatherMissingSpannerssn   d?LLNEIIKE u+B((*8$,8R=`$#H*,*?*?*A)6',H!+B 5( ""2&+$ U?  !2&"  $ $% $ 8r#)rrrrr)returnNone)r(rr3rrbool)r3rrr)r3rr(z&int | float | Fraction | OffsetSpecialrr) rHrrIrrJzlist[int] | NonerKrrr)rr rjrrr )T) r`rrrrrrzspanner.SpannerBundle | Nonerzlist[spanner.Spanner] | None)__name__ __module__ __qualname____firstlineno____doc__rr8r@r.rXrlrprzr~propertyrrr<rr__static_attributes__ __classcell__)r s@r!rr-s6 === =F BB  BL (-(-1(- (-Z""# ]2]2 ]2  ]2  ]2 ]2D&*"&),,6@#LEI?!B* ,,&*T&%P!&EX]%<"&@D xx x  x $> x $xxr#rc\rSrSrSrg)TestirN)rrrrrrr#r!rrsr#r__main__)$r __future__rre fractionsrtypingrTunittest music21.basermusic21.common.enumsrmusic21.common.numberToolsrmusic21.common.typesrr r rdr r music21.exceptions21r rmusic21.stream.iteratorrrrmusic21.streamrrTestCaserrmainTestrr#r!rs # &.-FFJE??%j j j 8    z Tr#