rhcn%SrSSKJr SSKrSSKJrJr SSKrSSKrSSK J r SSK r SSK J r SSKrSSKrSSKrSSKJrJr SSKJr SS KJrJr SS KJr SS KJrJr SS KJr SS KJ r SSK!J"r"J#r# SSK$J%r% SSKJ&r& SSKJ'r' SSKJ(r( SSK)J*r*J+r+J,r, SSK-J.r. SSK/J0r0J1r1J2r2 SSKJ3r3 \ Rh(a1SSK5r5SSK6J7r7 SSK8r8SSKJ9r9 SSKJ:r: SSKJ;r; \ Rx"SSS9r=\r>\r?/SQr@\'RrA\&R"S5rC/rDS H!rE\ "\E5rF\FbM\DR\E5 M# C CE\D(a)\CS!S";a \CR\R"\D5S#S$9 "S%S&\'R5rJ"S'S(\'R5rK"S)S*\ R5rM"S+S,\ R5rN"S-S.\O5rP"S/S0\Q5rR\S"5rT\S"5rU\RS;S1j5rW"S2S3\(R5rY\O"\Z"\Y"555r[S4\\S5'"S6S7\Y5r]"S8S9\R5r_\Y\]/r`\aS::XaSSKr\R"5 gg)>> import music21 >>> music21.Music21Object >>> music21.VERSION_STR '9.9.1' Alternatively, after doing a complete import, these classes are available under the module "base": >>> base.Music21Object ) annotationsN) GeneratorIterable) find_spec)overload) __version____version_info__)common) ElementSearch OffsetSpecial)opFrac)OffsetQL OffsetQLIn)defaults) Derivation)DurationDurationException) Editorial) environment) exceptions21)prebase)SitesSitesExceptionWEAKREF_ACTIVE)Style) SortTupleZeroSortTupleLowZeroSortTupleHigh)tie)IOBasemeterstream)spanner_M21Tzmusic21.base.Music21Object)bound) Music21ExceptionrMusic21ObjectExceptionElementExceptionGroups Music21ObjectElementWrapperVERSION VERSION_STRbase) matplotlibnumpywarnings)1Tzmusic21:)headerc\rSrSrSrg)r)~N__name__ __module__ __qualname____firstlineno____static_attributes__r9F/home/james-whalen/.local/lib/python3.13/site-packages/music21/base.pyr)r)~r@r)c\rSrSrSrg)r*r9Nr:r9r@rAr*r*rBr@r*c4\rSrSr%S\S'S\S'S\S'Srg ) ContextTuple stream.Streamsiteroffsetstream.enums.RecursionType recurseTyper9Nr;r<r=r>__annotations__r?r9r@rArFrFs  ++r@rFc4\rSrSr%S\S'S\S'S\S'Srg ) ContextSortTuplerHrIrrJrKrLr9NrMr9r@rArPrPs  ++r@rPcN^\rSrSrSrU4SjrSSjrU4SjrU4SjrSr U=r $) _SplitTuplea >>> st = base._SplitTuple([1, 2]) >>> st.spannerList = [expressions.Trill()] >>> st (1, 2) >>> st.spannerList [] >>> a, b = st >>> a 1 >>> b 2 >>> st.__class__ OMIT_FROM_DOCS Might have been a mistake to make an implicit return make sure that normal tuple comparisons work, but that things do not hash the same. st2 has the same (1, 2) value as st1 but no spanners >>> st2 = base._SplitTuple([1, 2]) >>> st == st2 False >>> c = set() >>> c.add(st) >>> st2 in c False >>> st3 = base._SplitTuple([1, 2]) >>> st2 == st3 True >>> st_big = base._SplitTuple([1, 3]) >>> st2 < st_big True c>>[[U] U[U55$N)superrS__new__tuple)clstupEls __class__s rArX_SplitTuple.__new__s[#.sE&MBBr@c/UlgrV spannerList)selfr[s rA__init___SplitTuple.__init__s 24r@c>[U[5(dgURUR:wag[TU]U5$)NF) isinstancerSr`rW__eq__)raotherr\s rArf_SplitTuple.__eq__s9%--   u00 0w~e$$r@cb>[TU]5n[UR5n[ X45$rV)rW__hash__idr`hash)rah1h2r\s rArj_SplitTuple.__hash__s, W     !RH~r@r_)r[t.AnyreturnNone) r;r<r=r>__doc__rXrbrfrjr? __classcell__r\s@rArSrSs#%LC5%r@rScN^\rSrSrSrSrSSjrSSjrU4SjrS Sjr Sr U=r $) r+az Groups is a list (subclass) of strings used to identify associations that an element might have. (in the future, Groups will become a set subclass) The Groups object enforces that all elements must be strings, and that the same element cannot be provided more than once. NOTE: In the future, spaces will not be allowed in group names. >>> g = Groups() >>> g.append('hello') >>> g[0] 'hello' >>> g.append('hello') # not added as already present >>> len(g) 1 >>> g ['hello'] >>> g.append(5) # type: ignore Traceback (most recent call last): music21.exceptions21.GroupException: Only strings can be used as group names, not 5 r9ch[U[5(d[R"SSU<3-5eg)Nz)Only strings can be used as group names, znot )restrrGroupExceptionravalues rA _validNameGroups._validNames<%%%--.Y26ui0@/AB B&r@cURU5 [RX5(d[RX5 ggrV)r}list __contains__appendr{s rAr Groups.appends0   -- KK $.r@cF>URU5 [TU] X5 grV)r}rW __setitem__)raiyr\s rArGroups.__setitem__s  A!r@c[U[5(dg[U5[U5:wag[[ U5[ U55H)up#UR 5UR 5:wdM) g g)a Test Group equality. In normal lists, order matters; here it does not. More like a set. >>> a = base.Groups() >>> a.append('red') >>> a.append('green') >>> a ['red', 'green'] >>> b = base.Groups() >>> b.append('green') >>> a == b False >>> b.append('reD') # case insensitive >>> a == b True >>> a == ['red', 'green'] # need both to be groups False >>> c = base.Groups() >>> c.append('black') >>> c.append('tuba') >>> a == c False FT)rer+lenzipsortedlower)rargeSelfeOthers rArf Groups.__eq__s^8%(( t9E " ve}=ME{{} .>r@)r|ryrqrr)rgobject) r;r<r=r>rs __slots__r}rrrfr?rtrus@rAr+r+s*BIB% "%%r@r+c[5nU/UR5QHHn[US5(dMURn[ U[ 5(aU4nU[U5-nMJ [ U5$)z Get equality attributes for a class. Cached. >>> base._getEqualityAttributes(base.Music21Object) frozenset({'duration'}) >>> 'location' in base._getEqualityAttributes(bar.Barline) True >>> 'pitch' in base._getEqualityAttributes(bar.Barline) False equalityAttributes)setmrohasattrrrery frozenset)rZrklasskas rA_getEqualityAttributesr6sp" " 5. / /))B"c""U #b' )  # ' ((r@c ^\rSrSr%SrSrS\S'Sr\r S\S'S r S \S '/r S \S 'SSSSS.r S\S'SgShSjjr SiSjrSjSjr\SkSj5r\R$SlSj5rSmSjrSnSS.SoSjjjrSnSpSjjrSqS jrSrS!jrSsU4S"jjr\StS#j5r\SuS$j5r\R$SvS%j5r\StS&j5r\SwS'j5r\R$SxS(j5r\SyS)j5r\R$SzS*j5r\S{S+j5r\R$S|S,j5rS}S-jr\ SS..S~S/jj5r!\ SS..SS0jj5r!SS..SS1jjr!SS2jr"SS3jr#SnSS4jjr$SS}S6jjr%SS}S7jjr&\ \'RPSS5SS8.SS9jj5r)\ \'RPSS5SS8.SS:jj5r)\'RPSS5SS8.SS;jjr)\ SSSSSS5SS<.SS=jj5r*\ SSSSSSS5SS>.SS?jj5r*SSSSSSS5SS>.SS@jjr*SAr+SnSSB.SSCjjjr,SnSSB.SSDjjjr-SEr.SSFjr/\"\.\/SGSH9r0\SySIj5r1\1R$SzSJj5r1SSSKjjr2\SSLj5r3\3R$SSMj5r3SnSNjr4SOr5SPr6\"\5\6SQSH9r7SSSRjjr8SSr9STr:SSUjr;S5SSV.SWjrSS[jr?\SS\j5r@SSS]jjrASS^jrB\SS_j5rC\SsS`j5rD\SSaj5rE\SSbj5rFSScjrGSSdjrH\"\G\HSeSH9rISfrJU=rK$)r,iWa Music21Object is the base class for all elements that can go into Streams. Notes, Clefs, TimeSignatures are all sublcasses of Music21Object. Durations and Pitches (which need to be attached to Notes, etc.) are not. All music21 objects have these pieces of information: 1. id: identification string unique to the object's container (optional). Defaults to the `id()` of the element. 2. groups: a :class:`~music21.base.Groups` object: which is a list of strings identifying internal sub-collections (voices, parts, selections) to which this element belongs 3. duration: :class:`~music21.duration.Duration` object representing the length of the object 4. activeSite: a reference to the currently active :class:`~music21.stream.Stream` or None 5. offset: a floating point or Fraction value, generally in quarter lengths, specifying the position of the object in a site. 6. priority: int representing the position of an object among all objects at the same offset. 7. sites: a :class:`~music21.base.Sites` object that stores all the Streams and Contexts that an object is in. 8. derivation: a :class:`~music21.derivation.Derivation` object, or None, that shows where the object came from. 9. style: a :class:`~music21.style.Style` object, that contains Style information automatically created if it doesn't exist, so check `.hasStyleInformation` first if that is not desired. 10. editorial: a :class:`~music21.editorial.Editorial` object Each of these may be passed in as a named keyword to any music21 object. Some of these may be intercepted by the subclassing object (e.g., duration within Note) **Equality** For historical reasons, music21 uses a different idea of object equality for Music21Objects than recommended by modern Python standards. Two Music21Objects are equal if they are the same class and same duration. Their offset, activeSite, id, and groups do not matter for equality. Since these two objects are therefore not interchangable, they do not have the same hash value. >>> obj1 = base.Music21Object(id='obj1') >>> obj2 = base.Music21Object(id='obj2') >>> obj1 == obj2 True >>> hash(obj1) == hash(obj2) False This has the stange side effect that structures that use equality to report containment (such as lists and tuples) will report differently from structures that use hash values to report containment (such as dicts and sets): >>> obj1 in [obj2] True >>> obj1 in {obj2} False Subclasses need to apply stricter criteria for equality, like Barline does here with `.location` >>> bar1 = bar.Barline('double', 'left') >>> bar2 = bar.Barline('double', 'right') >>> bar1 == bar2 False >>> bar2.location = 'left' >>> bar1 == bar2 True >>> bar1.duration.type = 'whole' # Buh? >>> bar1 == bar2 False In general, a subclass of Music21Object must match all super-class criteria for equality before they can be considered equal themselves. However, there are some exceptions. For instance, RomanNumeral objects with the same figure and key are equal even if their notes are in different octaves or have different doublings. Developers creating their own Music21Object subclasses should add a class attribute `equalityAttributes = ('one', 'two')`. (Remember that as a tuple of strings, if there is only one string, don't forget the trailing comma: `('only',)`. >>> class CarolineShawBreathMark(base.Music21Object): ... equalityAttributes = ('direction',) ... def __init__(self, direction, speed): ... super().__init__(self) ... self.direction = direction ... self.speed = speed >>> bm1 = CarolineShawBreathMark('in', 'fast') >>> bm2 = CarolineShawBreathMark('out', 'fast') >>> bm1 == bm2 False "speed" is not in the equalityAttributes so it can differ while objects are still equal. >>> bm3 = CarolineShawBreathMark('in', 'slow') >>> bm1 == bm3 True  int | floatclassSortOrderFz type[Style] _styleClass)durationtuple[str, ...]rz list[str] _DOC_ORDERzAn instance of a :class:`~music21.base.Groups` object which describes arbitrary `Groups` that this object belongs to.zka :class:`~music21.sites.Sites` object that stores references to Streams that hold this object.zmBoolean value for quickly identifying :class:`~music21.stream.Stream` objects (False by default).aQProperty which returns an number (int or otherwise) depending on the class of the Music21Object that represents a priority for an object based on its class alone -- used as a tie for stream sorting in case two objects have the same offset and priority. Lower numbers are sorted to the left of higher numbers. For instance, Clef, KeySignature, TimeSignature all come (in that order) before Note. All undefined classes have classSortOrder of 20 -- same as note.Note >>> m21o = base.Music21Object() >>> m21o.classSortOrder 20 >>> tc = clef.TrebleClef() >>> tc.classSortOrder 0 >>> ks = key.KeySignature(3) >>> ks.classSortOrder 2 New classes can define their own default classSortOrder >>> class ExampleClass(base.Music21Object): ... classSortOrder = 5 ... >>> ec1 = ExampleClass() >>> ec1.classSortOrder 5 )groupssitesisStreamrdict[str, str] _DOC_ATTRNc  4XlSUlXlSUlSUlX`lSUlX@lUbXlSUl 0Ul U=(d [5Ul U=(d [5UlUbXPlU bXR lgg)Nr)_id _activeSite _naiveOffset_activeSiteStoredOffset _derivation_style _editorial _durationclient _priority_cacher+rrr activeSiter quarterLength) rarkrrrrstyle editorialrJrkeywordss rArbMusic21Object.__init__s"$EI&, GK$-1"' *.)1  "O)+ ( %eg   !(O  $*7MM ' %r@c[R"[UR5n[ X5(dg[ U5H'n[ X[5[ X[5:wdM' g g)z; Define equality for Music21Objects. See main class docs. FT) tcasttyper\rergetattr_EQUALITY_SENTINEL_SELF_EQUALITY_SENTINEL_OTHER)rargrZattrs rArfMusic21Object.__eq__'sYffT4>>*%%%*3/D$;<u,DEF0r@c[U5S- $)z' Restore hashing, but only on id(self) )rkras rArjMusic21Object.__hash__5s$x1}r@c`URb UR$[R"U5$)a A unique identification string or int; not to be confused with Python's built-in `id()` method. However, if not set, will return Python's `id()` number. "Unique" is intended with respect to the stream hierarchy one is likely to query with :meth:`~music21.stream.Stream.getElementById`. For instance, the `.id` of a Voice should be unique in any single Measure, but the id's may reset from measure to measure across a Part. )rbuiltinsrkrs rArkMusic21Object.id;s& 88 88O{{4  r@c[U[5(a4U[R:a SnUSU3- n[R "U5 Xlg)Nz;Setting an ID that could be mistaken for a memory location zis discouraged: got )reintr#minIdNumberToConsiderMemoryLocationr3warnr)ranew_idmsgs rArkrKsD fc " "v0\0\'\OC )&2 2C MM# r@cUR[U5:waURUl[R"UR5Ulg)ab Merge all elementary, static attributes. Namely, `id` and `groups` attributes from another music21 object. Can be useful for copy-like operations. >>> m1 = base.Music21Object() >>> m2 = base.Music21Object() >>> m1.id = 'music21Object1' >>> m1.groups.append('group1') >>> m2.mergeAttributes(m1) >>> m2.id 'music21Object1' >>> 'group1' in m2.groups True N)rkcopydeepcopyr)rargs rAmergeAttributesMusic21Object.mergeAttributesSs3 88r%y hhDGmmELL1 r@ignoreAttributescd1SknUR(dURS5 UcUnOX#-n[R"XUS9n[ US05 [ US[ 55 SU;a[ 5Ul[US9nXlSUl [ USU5 UR5 U$) ai Subclassable __deepcopy__ helper so that the same attributes do not need to be called for each Music21Object subclass. ignoreAttributes is a set of attributes not to copy via the default deepcopy style. More can be passed to it. But calling functions are responsible * Changed in v9: removeFromIgnore removed; never used and this is performance critical. >r_sitesrrrrrrr __deepcopy__r) raddr defaultDeepcopysetattrrr+roriginmethod purgeOrphans)ramemordefaultIgnoreSetnew newDerivations rA_deepcopySubclassable#Music21Object._deepcopySubclassablegsN{{   *  #/ /B $$TBRSXr"Xuw' ' 'CJ##. #- ]M2  r@c$URU5$)a Helper method to copy.py's deepcopy function. Call it from there. memo=None is the default as specified in copy.py Problem: if an attribute is defined with an underscore (_priority) but is also made available through a property (e.g. priority) using dir(self) results in the copy happening twice. Thus, __dict__.keys() is used. >>> from copy import deepcopy >>> n = note.Note('A') >>> n.offset = 1.0 >>> n.groups.append('flute') >>> n.groups ['flute'] >>> idN = n.id >>> idN > 10000 # pointer True >>> b = deepcopy(n) >>> b.offset = 2.0 >>> n is b False >>> b.id != n.id True >>> n.pitch.accidental = '-' >>> b.name 'A' >>> n.offset 1.0 >>> b.offset 2.0 >>> n.groups[0] = 'bassoon' >>> ('flute' in n.groups, 'flute' in b.groups) (False, True) )r)rars rArMusic21Object.__deepcopy__sN))$//r@cNURR5nSUS'SUS'U$)Nrr)__dict__rrastates rA __getstate__Music21Object.__getstate__s- ""$#m#m r@c2[RUSU5 g)Nr)r __setattr__rs rA __setstate__Music21Object.__setstate__s4U3r@c>[US5(aUR[U5:Xa[TU] 5$URn[ [ U55nSU3$![ [4a Nf=f)z If `x.id` is not the same as `id(x)`, then that id is used instead: >>> b = base.Music21Object() >>> b._reprInternal() 'object at 0x129a903b1' >>> b.id = 'hi' >>> b._reprInternal() 'id=hi' rkid=)rrkrW _reprInternalhexr ValueError TypeError)rareprIdr\s rArMusic21Object._reprInternalsrtT""dggD&97(* * V%FVH~I&   sA A32A3cURSL$)a Returns True if there is a :class:`~music21.editorial.Editorial` object already associated with this object, False otherwise. Calling .editorial on an object will always create a new Editorial object, so even though a new Editorial object isn't too expensive to create, this property helps to prevent creating new Editorial objects more than is necessary. >>> mObj = base.Music21Object() >>> mObj.hasEditorialInformation False >>> mObj.editorial >>> mObj.hasEditorialInformation True Nrrs rAhasEditorialInformation%Music21Object.hasEditorialInformations(OOt+,r@cRURc[5UlUR$)a a :class:`~music21.editorial.Editorial` object that stores editorial information (comments, footnotes, harmonic information, ficta). Created automatically as needed: >>> n = note.Note('C4') >>> n.editorial >>> n.editorial.ficta = pitch.Accidental('sharp') >>> n.editorial.ficta >>> n.editorial }> )rrrs rArMusic21Object.editorials!* ?? "'kDOr@cXlgrVr)raeds rArr sr@cURSL$)a Returns True if there is a :class:`~music21.style.Style` object already associated with this object, False otherwise. Calling .style on an object will always create a new Style object, so even though a new Style object isn't too expensive to create, this property helps to prevent creating new Styles more than necessary. >>> mObj = base.Music21Object() >>> mObj.hasStyleInformation False >>> mObj.style >>> mObj.hasStyleInformation True Nrrs rAhasStyleInformation!Music21Object.hasStyleInformations(KK4'(r@cUR(dURnU"5UlURceUR$)a* Returns (or Creates and then Returns) the Style object associated with this object, or sets a new style object. Different classes might use different Style objects because they might have different style needs (such as text formatting or bezier positioning) Eventually will also query the groups to see if they have any styles associated with them. >>> n = note.Note() >>> st = n.style >>> st >>> st.absoluteX = 20.0 >>> st.absoluteX 20.0 >>> n.style = style.Style() >>> n.style.absoluteX is None True )rrr)ra StyleClasss rArMusic21Object.style's;0''))J$,DK{{&&&{{r@cXlgrVr)ranewStyles rArr Es r@c.URR$)a Set or Return the Duration as represented in Quarter Length, possibly as a fraction. Same as setting `.duration.quarterLength`. >>> n = note.Note() >>> n.quarterLength = 2.0 >>> n.quarterLength 2.0 >>> n.quarterLength = 1/3 >>> n.quarterLength Fraction(1, 3) rrrs rArMusic21Object.quarterLengthKs}}***r@c$XRlgrVrr{s rArr\s &+ #r@cPURc[US9UlUR$)a Return the :class:`~music21.derivation.Derivation` object for this element. Or create one if none exists: >>> n = note.Note() >>> n.derivation from None> Make a copy of n but change the pitch to D to see which is which later: >>> import copy >>> n2 = copy.deepcopy(n) >>> n2.pitch.step = 'D' Because n2 was originally a copy of n, it has a derivation set to show it. >>> n2.derivation from via '__deepcopy__'> >>> n2.derivation.origin is n True Note that (for now at least) derivation.origin is NOT a weakref: >>> del n >>> n2.derivation from via '__deepcopy__'> >>> n2.derivation.origin r)rrrs rA derivationMusic21Object.derivation`s*@    #)6D r@cXlgrV)r)rars rArrs(r@c 0Ulg)a A number of music21 attributes (especially with Chords and RomanNumerals, etc.) are expensive to compute and are therefore cached. Generally speaking objects are responsible for making sure that their own caches are up to date, but a power user might want to do something in an unusual way (such as manipulating private attributes on a Pitch object) and need to be able to clear caches. That's what this is here for. If all goes well, you'll never need to call it unless you're expanding music21's core functionality. `**keywords` is not used in Music21Object but is included for subclassing. Look at :func:`~music21.common.decorators.cacheMethod` for the other half of this utility. * New in v6: exposes previously hidden functionality. N)rrars rA clearCacheMusic21Object.clearCaches ( r@ returnSpecialcgrVr9rarIrs rAgetOffsetBySiteMusic21Object.getOffsetBySite r@cgrVr9rs rArrr r@cJUc UR$SnUn[5nSnUcURXBS9nUcMU$![an[ SU<S35UeSnAf[ anXAR ;a+USLa[RsSnA$URsSnA$URRn U cUeU n[U5U;aUeUR[U55 US-nUS:aUeSnANSnAff=f![an [ S U<S U<35U eSn A ff=f) ab If this class has been registered in a container such as a Stream, that container can be provided here, and the offset in that object can be returned. >>> n = note.Note('A-4') # a Music21Object >>> n.offset = 30 >>> n.getOffsetBySite(None) 30.0 >>> s1 = stream.Stream() >>> s1.id = 'containingStream' >>> s1.insert(20 / 3, n) >>> n.getOffsetBySite(s1) Fraction(20, 3) >>> float(n.getOffsetBySite(s1)) 6.6666... n.getOffsetBySite(None) should still return 30.0 >>> n.getOffsetBySite(None) 30.0 If the Stream does not contain the element and the element is not derived from an element that does, then a SitesException is raised: >>> s2 = stream.Stream() >>> s2.id = 'notContainingStream' >>> n.getOffsetBySite(s2) Traceback (most recent call last): music21.sites.SitesException: an entry for this object is not stored in stream Consider this use of derivations: >>> import copy >>> nCopy = copy.deepcopy(n) >>> nCopy.derivation from via '__deepcopy__'> >>> nCopy.getOffsetBySite(s1) Fraction(20, 3) nCopy can still find the offset of `n` in `s1`! This is the primary difference between element.getOffsetBySite(stream) and stream.elementOffset(element) >>> s1.elementOffset(nCopy) Traceback (most recent call last): music21.sites.SitesException: an entry for this object ... is not stored in stream If the object is stored at the end of the Stream, then the highest time is usually returned: >>> s3 = stream.Stream() >>> n3 = note.Note(type='whole') >>> s3.append(n3) >>> rb = bar.Barline() >>> s3.storeAtEnd(rb) # s3.rightBarline = rb would do the same >>> rb.getOffsetBySite(s3) 4.0 However, setting returnSpecial to True will return OffsetSpecial.AT_END >>> rb.getOffsetBySite(s3, returnSpecial=True) Even with returnSpecial normal offsets are still returned as a float or Fraction: >>> n3.getOffsetBySite(s3, returnSpecial=True) 0.0 * Changed in v7: stringReturns renamed to returnSpecial. Returns an OffsetSpecial Enum. NdrzYou were using z$ as a site, when it is not a Stream.Tr4rzan entry for this object z is not stored in stream )rr elementOffsetAttributeErrorrr( _endElementsr AT_END highestTimerrrkr) rarIra tryOrigin originMemo maxSearchaeepossiblyNoneTryOriginses rArrsOb <$$ $" A'+IJI) **9*RA)2H-&()$1UV(  $5$55(D0#0#7#77#'#3#33,0OO,B,B),4 5I)} 2NN2i=1NI 1}%! &  +D83LTHU  ssC?;C?C? C<A C<##C7C<C? C7C<C?AC72C?7C<<C?? D" DD"czUbURX5 g[U[5(a [U5nX lg)a Change the offset for a site. These are equivalent: n1.setOffsetBySite(stream1, 20) and stream1.setElementOffset(n1, 20) Which you choose to use will depend on whether you are iterating over a list of notes (etc.) or streams. >>> import music21 >>> aSite = stream.Stream() >>> aSite.id = 'aSite' >>> a = music21.Music21Object() >>> aSite.insert(0, a) >>> aSite.setElementOffset(a, 20) >>> a.setOffsetBySite(aSite, 30) >>> a.getOffsetBySite(aSite) 30.0 And if it isn't in a Stream? Raises an exception and the offset does not change. >>> b = note.Note('D') >>> b.setOffsetBySite(aSite, 40) Traceback (most recent call last): music21.exceptions21.StreamException: Cannot set the offset for element , not in Stream . >>> b.offset 0.0 Setting offset for `None` changes the "naive offset" of an object: >>> b.setOffsetBySite(None, 32) >>> b.offset 32.0 >>> b.activeSite is None True Running `setOffsetBySite` also changes the `activeSite` of the object. N)setElementOffsetrerfloatr)rarIr|s rAsetOffsetBySiteMusic21Object.setOffsetBySite(s5\    ! !$ .%%%e  % r@cURU5$![a Of=fUR5H nURULdMURs $ [SUSU35e)a For an element which may not be in site, but might be in a Stream in site (or further in streams), find the cumulative offset of the element in that site. >>> s = stream.Score(id='mainScore') >>> p = stream.Part() >>> m = stream.Measure() >>> n = note.Note() >>> m.insert(5.0, n) >>> p.insert(10.0, m) >>> s.insert(0.0, p) >>> n.getOffsetInHierarchy(s) 15.0 If no hierarchy beginning with site contains the element and the element is not derived from an element that does, then a SitesException is raised: >>> s2 = stream.Score(id='otherScore') >>> n.getOffsetInHierarchy(s2) Traceback (most recent call last): music21.sites.SitesException: Element is not in hierarchy of But if the element is derived from an element in a hierarchy then it can get the offset: >>> n2 = n.transpose('P5') >>> n2.derivation.origin is n True >>> n2.derivation.method 'transpose' >>> n2.getOffsetInHierarchy(s) 15.0 There is no corresponding `.setOffsetInHierarchy()` since it's unclear what that would mean. See also :meth:`music21.stream.iterator.RecursiveIterator.currentHierarchyOffset` for a method that is about 10x faster when running through a recursed stream. * New in v3. OMIT_FROM_DOCS Timing: 113microseconds for a search vs 1 microsecond for getOffsetBySite vs 0.4 for elementOffset. Hence the short-circuit for easy looking below. TODO: If timing permits, replace .flatten() w/ and w/o retainContainers with this routine. Currently not possible; for instance, if b = bwv66.6 %timeit b = corpus.parse('bwv66.6') -- 24.8ms %timeit b = corpus.parse('bwv66.6'); b.flatten() -- 42.9ms %timeit b = corpus.parse('bwv66.6'); b.recurse().stream() -- 83.1ms zElement z is not in hierarchy of )rr contextSitesrIrJ)rarIcss rAgetOffsetInHierarchy"Music21Object.getOffsetInHierarchy]spx ''- -    ##%Bww$yy &xv-EdVLMMs   cpURRS5n/nUb[R"U5(dU/nUHhnUcMUcUR UR 5 M(UH:nXTR R ;dMUR UR 5 Mf Mj [USS9$)a Return a list of all :class:`~music21.spanner.Spanner` objects (or Spanner subclasses) that contain this element. This method provides a way for objects to be aware of what Spanners they reside in. Note that Spanners are not Streams but specialized Music21Objects that use a Stream subclass, SpannerStorage, internally to keep track of the elements that are spanned. >>> c = note.Note('C4') >>> d = note.Note('D4') >>> slur1 = spanner.Slur(c, d) >>> c.getSpannerSites() == [slur1] True Note that not all Spanners are in the spanner module. They tend to reside in modules closer to their musical function: >>> cresc = dynamics.Crescendo(d, c) The order that Spanners are returned is by sortTuple. For spanners created the same way and in the same order, the order returned will be consistent: >>> d.getSpannerSites() == [slur1, cresc] True Optionally a class name or list of class names (as Classes or strings) can be specified and only Spanners of that class will be returned >>> dim = dynamics.Diminuendo(c, d) >>> d.getSpannerSites(dynamics.Diminuendo) == [dim] True A larger class name can be used to get all subclasses: >>> d.getSpannerSites(dynamics.DynamicWedge) == [cresc, dim] True >>> d.getSpannerSites(['Slur', 'Diminuendo']) == [slur1, dim] True Note that the order of spanners returned from this routine can vary, so changing to a set is useful for comparisons >>> set(d.getSpannerSites(['Slur', 'Diminuendo'])) == {dim, slur1} True Example: see which pairs of notes are in the same slur. >>> e = note.Note('E4') >>> slur2 = spanner.Slur(c, e) >>> for n in [c, d, e]: ... nSlurs = n.getSpannerSites(spanner.Slur) ... for nOther in [c, d, e]: ... if n is nOther: ... continue ... nOtherSlurs = nOther.getSpannerSites(spanner.Slur) ... for thisSlur in nSlurs: ... if thisSlur in nOtherSlurs: ... print(f'{n.name} shares a slur with {nOther.name}') C shares a slur with D C shares a slur with E D shares a slur with C E shares a slur with C SpannerStoragec"UR5$rV) sortTuple)xs rA/Music21Object.getSpannerSites..s !++-r@)key)rgetSitesByClassr isIterablerrclassSetr)raspannerClassListfoundpostobj spannerClasss rAgetSpannerSitesMusic21Object.getSpannerSitessN **+;<&(  '$$%566$4#5 C{' CJJ'$4L#zz':':: CJJ/%5 d 788r@Tc/nURRSS9H~nUR(dMX;dMU(a@SUR;a.SUR;aUR [ U55 M`MbMdUR [ U55 M UHUnURR U5 UR5nUcM3[ U5U:XdMDURS5 MW g)a A Music21Object may, due to deep copying or other reasons, have a site (with an offset) which no longer contains the Music21Object. These lingering sites are called orphans. This method gets rid of them. The `excludeStorageStreams` are SpannerStorage and VariantStorage. T excludeNoner<VariantStorageN) r yieldSitesrclassesrrk removeById_getActiveSite_setActiveSite)raexcludeStorageStreamsorphanssrps rArMusic21Object.purgeOrphanss&&4&8Azzzdm(( 9 0 Ar!u-!B: NN2a5)9A JJ ! !! $##%A}A!##D) r@c6URRUS9 g)zE Remove references to all locations in objects that no longer exist. ) rescanIsDeadN)rpurgeLocations)rar\s rAr]Music21Object.purgeLocations!s !!|!>> p = converter.parse('tinynotation: 3/4 C4 D E 2/4 F G A B 1/4 c') >>> p >>> p.show('t') {0.0} {0.0} {0.0} {0.0} {1.0} {2.0} {3.0} {0.0} {0.0} {1.0} {5.0} {0.0} {1.0} {7.0} {0.0} {0.0} {1.0} Let's get the last two notes of the piece, the B and high c: >>> m4 = p.measure(4) >>> c = m4.notes.first() >>> c >>> m3 = p.measure(3) >>> b = m3.notes.last() >>> b Now when we run `getContextByClass(meter.TimeSignature)` on c, we get a time signature of 1/4. >>> c.getContextByClass(meter.TimeSignature) Doing what we just did wouldn't be hard to do with other methods, though `getContextByClass` makes it easier. But the time signature context for b would be much harder to get without this method, since in order to do it, it searches backwards within the measure, finds that there's nothing there. It goes to the previous measure and searches inside that one from the end backwards until it gets the proper TimeSignature of 2/4: >>> b.getContextByClass(meter.TimeSignature) For backwards compatibility you can also pass in a string of the class name: >>> b.getContextByClass('TimeSignature') But if you use Python typing or a typing-aware IDE, then the first call (with class name) will signal that it is returning a TimeSignature object and allow for error detection, autocomplete, etc. The latter call (with string) will only know that some Music21Object was returned. The method is smart enough to stop when it gets to the beginning of the part. This is all you need to know for most uses. The rest of the docs are for advanced uses: The method searches Sites and also associated objects to find a matching class. Returns `None` if no match is found. A reference to the caller is required to find the offset of the object of the caller. The caller may be a Sites reference from a lower-level object. If so, we can access the location of that lower-level object. However, if we need a flat representation, the caller needs to be the source Stream, not its Sites reference. The `getElementMethod` is an enum value (new in v7) from :class:`~music21.common.enums.ElementSearch` that selects which Stream method is used to get elements for searching. (The historical form of supplying one of the following values as a string is also supported.) >>> from music21.common.enums import ElementSearch >>> [x for x in ElementSearch] [, , , , , , , , , , ] The "after" do forward contexts -- looking ahead. Demonstrations of these keywords: Because `b` is a `Note`, `.getContextByClass(note.Note)` will only find itself: >>> b.getContextByClass(note.Note) is b True To get the previous `Note`, use `getElementMethod=ElementSearch.BEFORE`: >>> a = b.getContextByClass(note.Note, getElementMethod=ElementSearch.BEFORE) >>> a This is similar to `.previous(note.Note)`, though that method is a bit more sophisticated: >>> b.previous(note.Note) To get the following `Note` use `getElementMethod=ElementSearch.AFTER`: >>> c = b.getContextByClass(note.Note, getElementMethod=ElementSearch.AFTER) >>> c This is similar to `.next(note.Note)`, though, again, that method is a bit more sophisticated: >>> b.next(note.Note) A Stream might contain several elements at the same offset, leading to potentially surprising results where searching by `ElementSearch.AT_OR_BEFORE` does not find an element that is technically the NEXT node but still at 0.0: >>> s = stream.Stream() >>> s.insert(0, clef.BassClef()) >>> s.next() >>> s.getContextByClass(clef.Clef) is None True >>> s.getContextByClass(clef.Clef, getElementMethod=ElementSearch.AT_OR_AFTER) This can be remedied by explicitly searching by offsets: >>> s.getContextByClass(clef.Clef, getElementMethod=ElementSearch.AT_OR_BEFORE_OFFSET) Or by not limiting the search by temporal position at all: >>> s.getContextByClass(clef.Clef, getElementMethod=ElementSearch.ALL) Notice that if searching for a `Stream` context, the element is not guaranteed to be in that Stream. This is obviously true in this case: >>> p2 = stream.Part() >>> m = stream.Measure(number=1) >>> p2.insert(0, m) >>> n = note.Note('D') >>> m.insert(2.0, n) >>> try: ... n.getContextByClass(stream.Part).elementOffset(n) ... except Music21Exception: ... print('not there') not there But it is less clear with something like this: >>> import copy >>> n2 = copy.deepcopy(n) >>> try: ... n2.getContextByClass(stream.Measure).elementOffset(n2) ... except Music21Exception: ... print('not there') not there A measure context is being found, but only through the derivation chain. >>> n2.getContextByClass(stream.Measure) To prevent this error, use the `followDerivation=False` setting >>> print(n2.getContextByClass(stream.Measure, followDerivation=False)) None Or if you want the offset of the element following the derivation chain, call `getOffsetBySite()` on the object: >>> n2.getOffsetBySite(n2.getContextByClass(stream.Measure)) 2.0 Raises `ValueError` if `getElementMethod` is not a value in `ElementSearch`. >>> n2.getContextByClass(expressions.TextExpression, getElementMethod='invalid') Traceback (most recent call last): ValueError: Invalid getElementMethod: invalid Raises `ValueError` for incompatible values `followDerivation=True` and `priorityTargetOnly=True`. * Changed in v5.7: added followDerivation=False and made everything but the class keyword only * New in v6: added priorityTargetOnly -- see contextSites for description. * New in v7: added getElementMethod `all` and `ElementSearch` enum. * Changed in v8: class-based calls return properly typed items. Putting multiple types into className (never documented) is no longer allowed. OMIT_FROM_DOCS Testing that this works: >>> import gc >>> _ = gc.collect() >>> for site, positionStart, searchType in b.contextSites( ... returnSortTuples=True, ... sortByCreationTime=False, ... followDerivation=True ... ): ... print(site, positionStart, searchType) SortTuple(atEnd=0, offset=1.0, ...) elementsFirst SortTuple(atEnd=0, offset=6.0, ...) flatten c~>T (dSOT 4nURXS9nT T;aaT [R[R4;a[R "UR S9nO[R "UR S9nT T;aURU5nOURU5nUbURnU$g)z change the site (stream) to a Tree (using caches if possible), then find the node before (or after) the positionStart and return the element there or None. flatten can be True, 'semiFlat', or False. N)flatten classListrJ) asTreer BEFORE_OFFSETAT_OR_AFTER_OFFSETrmodifyrJr getNodeBefore getNodeAfterpayload) checkSiterlinnerPositionStartrmsiteTree contextNoderuBEFORE_METHODSOFFSET_METHODSrer_s rApayloadExtractor9Music21Object.getContextByClass..payloadExtractorVs%.I1# (C(C(5(H(H(JJ)9)@)@HZHaHa)b&):)A)AI[IbIb)c&>1&445GH &334FG &%--r@c>TRUSS9nURUSS9nTT;aX#:agTT;aX#:agg![a gf=f)aV Long explanation for a short method. It is possible for a contextEl to be returned that contradicts the 'Before' or 'After' criterion due to the following: (I'll take the example of Before; After is much harder to construct, but possible). Assume that s is a Score, and tb2 = s.flatten()[1] and tb1 is the previous element (would be s.flatten()[0]) -- both are at offset 0 in s and are of the same class (so same sort order and priority) and are thus ordered entirely by insert order. in s we have the following. s.sortTuple = 0.0 <0.-20.0> # not inserted tb1.sortTuple = 0.0 <0.-31.1> tb2.sortTuple = 0.0 <0.-31.2> in s.flatten() we have: s.flatten().sortTuple = 0.0 <0.-20.0> # not inserted tb1.sortTuple = 0.0 <0.-31.3> tb2.sortTuple = 0.0 <0.-31.4> Now tb2 is declared through s.flatten()[1], so its activeSite is s.flatten(). Calling .previous() finds tb1 in s.flatten(). This is normal. tb1 calls .previous(). Search of first site finds nothing before tb1, so .getContextByClass() is ready to return None. But other sites need to be checked Search returns to s. .getContextByClass() asks is there anything before tb1's sort tuple of 0.0 <0.-31.3> (.3 is the insertIndex) in s? Yes, it's tb2 at 0.0 <0.-31.2> (because s was created before s.flatten(), the insert indices of objects in s are lower than the insert indices of objects in s.flatten() (perhaps insert indices should be eventually made global within the context of a stream, but not global overall? but that wasn't the solution here). So we go back to tb2 in s. Then in theory we should go to tb1 in s, then s, then None. This would have certain elements appear twice in a .previous() search, which is not optimal, but wouldn't be such a huge bug to make this method necessary. That'd be the only bug that would occur if we did: sf = s.flatten(), tb2 = sf[1]. But consider the exact phrasing above: tb2 = s.flatten()[1]. s.flatten() is created for an instant, it is assigned to tb2's ._activeSite via weakRef, and then tb2's sortTuple is set via this temporary stream. Suppose tb2 is from that temp s.flatten()[1]. Then tb1 = tb2.previous() which is found in s.flatten(). Suppose then that for some reason s._cache['flat'] gets cleaned up (It was a bug that s._cache was being cleaned by the positioning of notes during s_flat's setOffset, but _cache cleanups are allowed to happen at any time, so it's not a bug that it's being cleaned; assuming that it wouldn't be cleaned would be the bug) and garbage collection runs. Now we get tb1.previous() would get tb2 in s. Okay, it's redundant but not a huge deal, and tb2.previous() gets tb1. tb1's ._activeSite is still a weakref to s.flatten(). When tb1's getContextByClass() is called, it needs its .sortTuple(). This looks first at .activeSite. That is None, so it gets it from .offset which is the .offset of the last .activeSite (even if it is dead. A lot of code depends on .offset still being available if .activeSite dies, so changing that is not an option for now). So its sortTuple is 0.0 <0.-31.3>. which has a .previous() of tb2 in s, which can call previous can get tb1, etc. So with terrible timing of cache cleanups and garbage collecting, it's possible to get an infinite loop. There may be ways to set activeSite on .getContextByClass() call such that this routine is not necessary, but I could not find one that was not disruptive for normal usages. There are some possible issues that one could raise about "wellFormed". Suppose for instance, that in one stream (b) we have [tb1, tb2] and then in another stream context (a), created earlier, we have [tb0, tb1, tb2]. tb1 is set up with (b) as an activeSite. Finding nothing previous, it goes to (a) and finds tb2; it then discovers that in (a), tb2 is after tb1, so it returns None for this context. One might say, "wait a second, why isn't tb0 returned? It's going to be skipped." To this, I would answer, the original context in which .previous() or .getContextByClass() was called was (b). There is no absolute obligation to find what was previous in a different site context. It is absolutely fair game to say, "there's nothing prior to tb1". Then why even search other streams/sites? Because it's quite common to create a new site for say a single measure or .getElementsByOffset(), etc., so that when leaving this extracted section, one wants to see how that fits into a larger stream hierarchy. T)raiseExceptionOnMissF)r>r)checkContextElrv selfSortTuplecontextSortTuple AFTER_METHODSrzr_ras rA wellFormed3Music21Object.getContextByClass..wellFormedssqj  $yt T #1#;#;I\`#;#a  >1m6V!]2}7W!"    s < A A zInvalid getElementMethod: z;priorityTargetOnly and followDerivation cannot both be TrueT)returnSortTuplesr`rarb) elementsOnly elementsFirstF)rlrwNrsemiFlatrqbool)r rp AFTER_OFFSETAT_OR_BEFORE_OFFSETrqBEFORE AT_OR_BEFOREBEFORE_NOT_SELFAFTER AT_OR_AFTERAFTER_NOT_SELFrrEr7coreSelfActiveSiter)rarer_r`rarb AT_METHODSNOT_SELF_METHODSr|rrI positionStart searchType contextElrrzr{s``` @@@rArfrgDsf  ' '  & &  - -  , ,     ' '  & &  - -  ) )       & &  % %  % %  , ,  ( (    & &  % %  - -  , ,    ) )  ( (    :h h T = 09:J9KLM M "2Z[ [ z )i4==.HK/3/@/@!1-1 0A0 +D >>,T5:@MO (Z -H-H// :%$^+$ 5!* )T]] :'+;; )1AA# ,T5?@MO (Z -H-H// :%$$6!* )T]] :'+;; # [0 dI*$$**$$s$ J J& J#"J#& J65J6) callerFirstr offsetAppendr`priorityTargetrarbcgrVr9) rarrrrr`rrarbs rAr7Music21Object.contextSites r@)rrrr`rrrarbcgrVr9) rarrrr`rrrarbs rAr7r*rr@c ## SSKJn Uc [5nUcUnUR(aX;a[R "SU5n U R n [RSUSU35 U(a6U R5RS[S5S 9n [XU 5v O[U SU 5v URU 5 UcUS La URnO[RS U35 Un UR R#UUS S 9GHnX;aM [%XR&5(aM'URU5nU(aUR)U5nOUR+U5n[-UU-5nURUS9nUR n U(a[UUU 5v O[UUR0U 5v URU5 [RSU3SUR353-5 UR5UUUR0S US9Hmun nnU(aXLa O]UR0nURUS9nX;dM6U(a[U UU5v O[U UU5v URU 5 Mo U(dGM O U(Ga+U R6R95GH n[RSUSU3-5 UR5SUSS US9HnUR:U;aM[RSUS35 [UR:UR0RUSR0U-S9UR<5nU(aUv O7[UR:UR0R0UR<5v URUR:5 M GM [RS5 g![.a GMf=f7f)a" A generator that returns a list of namedtuples of sites to search for a context. Each tuple contains three elements: .site -- Stream object .offset -- the offset or position (sortTuple) of this element in that Stream .recurseType -- the way of searching that should be applied to search for a context. The recurseType values are all music21.stream.enums.RecurseType: * FLATTEN -- flatten the stream and then look from this offset backwards. * ELEMENTS_ONLY -- only search the stream's personal elements from this offset backwards * ELEMENTS_FIRST -- search this stream backwards, and then flatten and search backwards >>> c = corpus.parse('bwv66.6') >>> c.id = 'bach' >>> n = c[2][4][2] >>> n Returning sortTuples are important for distinguishing the order of multiple sites at the same offset. >>> for csTuple in n.contextSites(returnSortTuples=True): ... yClearer = (csTuple.site, csTuple.offset.shortRepr(), csTuple.recurseType) ... print(yClearer) (, '0.5 <0.20...>', ) (, '9.5 <0.20...>', ) (, '9.5 <0.20...>', ) Streams have themselves as the first element in their context sites, at position zero and classSortOrder negative infinity. This example shows the context sites for Measure 3 of the Alto part. We will get the measure object using direct access to indices to ensure that no other temporary streams are created; normally, we would do `c.parts['#Alto'].measure(3)`. >>> m = c.parts['#Alto'].getElementsByClass(stream.Measure)[3] >>> m If returnSortTuples is true then ContextSortTuples are returned, where the second element is a SortTuple: >>> for csTuple in m.contextSites(returnSortTuples=True): ... print(csTuple) ContextSortTuple(site=, offset=SortTuple(atEnd=0, offset=0.0, priority=-inf, ...), recurseType=) ContextSortTuple(...) ContextSortTuple(...) Because SortTuples are so detailed, we'll use their `shortRepr()` to see the values, removing the insertIndex because it changes from run to run: >>> for csTuple in m.contextSites(returnSortTuples=True): ... yClearer = (csTuple.site, csTuple.offset.shortRepr(), csTuple.recurseType) ... print(yClearer) (, '0.0 <-inf.-20...>', ) (, '9.0 <0.-20...>', ) (, '9.0 <0.-20...>', ) Here we make a copy of the earlier measure, and we see that its contextSites follow the derivationChain from the original measure and still find the Part and Score of the original Measure 3 (and also the original Measure 3) even though mCopy is not in any of these objects. >>> import copy >>> mCopy = copy.deepcopy(m) >>> mCopy.number = 3333 >>> for csTuple in mCopy.contextSites(): ... print(csTuple, mCopy in csTuple.site) ContextTuple(site=, offset=0.0, recurseType=) False ContextTuple(site=, offset=0.0, recurseType=) False ContextTuple(site=, offset=9.0, recurseType=) False ContextTuple(site=, offset=9.0, recurseType=) False If followDerivation were False, then the Part and Score would not be found. >>> for csTuple in mCopy.contextSites(followDerivation=False): ... print(csTuple) ContextTuple(site=, offset=0.0, recurseType=) >>> partIterator = c.parts >>> m3 = partIterator[1].measure(3) >>> for csTuple in m3.contextSites(): ... print(csTuple) ContextTuple(site=, offset=0.0, recurseType=) ContextTuple(site=, offset=9.0, recurseType=) ContextTuple(site=, offset=9.0, recurseType=) Sorting order: >>> p1 = stream.Part() >>> p1.id = 'p1' >>> m1 = stream.Measure() >>> m1.number = 1 >>> n = note.Note() >>> m1.append(n) >>> p1.append(m1) >>> for csTuple in n.contextSites(): ... print(csTuple.site) >>> p2 = stream.Part() >>> p2.id = 'p2' >>> m2 = stream.Measure() >>> m2.number = 2 >>> m2.append(n) >>> p2.append(m2) The keys could have appeared in any order, but by default we set priorityTarget to activeSite. So this is the same as omitting. >>> for y in n.contextSites(priorityTarget=n.activeSite): ... print(y[0]) We can sort sites by creationTime: >>> for csTuple in n.contextSites(sortByCreationTime=True): ... print(csTuple.site) Use `reverse` for oldest first: >>> for csTuple in n.contextSites(sortByCreationTime='reverse'): ... print(csTuple.site) Note that by default we search all sites, but you might want to only search one, for instance: >>> c = note.Note('C') >>> m1 = stream.Measure() >>> m1.append(c) >>> d = note.Note('D') >>> m2 = stream.Measure() >>> m2.append([c, d]) >>> c.activeSite = m1 >>> c.next('Note') # uses contextSites There is a particular site in which there is a Note after c, but we want to know if there is one in m1 or its hierarchy, so we can pass in activeSiteOnly to `.next()` which sets `priorityTargetOnly=True` for contextSites >>> print(c.next('Note', activeSiteOnly=True)) None * Removed in v3: priorityTarget cannot be set, in order to use `.sites.yieldSites()` * Changed in v5.5: all arguments are keyword only. * Changed in v6: added `priorityTargetOnly=False` to only search in the context of the priorityTarget. * Changed in v8: `returnSortTuple=True` returns a new ContextSortTuple rr#Nmusic21.stream.StreamzCaller first is z with offsetAppend rz-inf)rJpriorityFzsortByCreationTime T)r`rrOrnzlooking in contextSites for z with position )rrrrr`zlooking now in derivedObject, z Yielding z from derivedObject contextSitesr4z%--returning from derivedObject search)music21r$rrrr recursionType environLocal printDebugr>rrr3rPrFrrrrQrer<rr$r rrJ shortReprr7rchainrIrL)rarrrr`rrrarbr$ streamSelfrrtopLevelsiteObjstoffsetInStream newOffsetpositionInStream inStreamPos recurTypeinStreamOffsethypotheticalPosition derivedObjectderivedCsTupleoffsetAdjustedCsTuples rAr7r9sZ # <5D  K}}!1VV$;TB * 8 8 ''&{m3F|nUW#$.$8$8$:$A$A"!&v%B%M+:mTT&z3 FF$  !&8E&A!__N  # #&9:L9M$N Ozz,,@RL#@A #%99I9#> $11M&w0@-PP"7,<,C,C]SS HHW   # #.wi8#$4$>$>$@#ABC D5<4H4H'-44!%#5 5I50+y&(*H!,!3!3(8'>'>n'>'U$' (.x9MyYY*8^YOOHHX&152"!w?z !)!4!4!:!:!< ''4&':<.IJK'4&@&@$(!%()-+= 'A'?N&**d2  ++#N#33ST-=&++&--44N1J=K4L&22 -4) (33*+@+E+E+@+G+G+N+N+@+L+LNNHH^0011'? "=<  GHQ"  s:D;P>AO4CP"AP'E P4 P>PPPc## URU5nUb(Uv URU[RS9nUbM'gg7f)a@ Returns a generator that yields elements found by `.getContextByClass` and then finds the previous contexts for that element. >>> s = stream.Stream() >>> s.append(meter.TimeSignature('2/4')) >>> s.append(note.Note('C')) >>> s.append(meter.TimeSignature('3/4')) >>> n = note.Note('D') >>> s.append(n) >>> for ts in n.getAllContextsByClass(meter.TimeSignature): ... print(ts, ts.offset) 1.0 0.0 TODO: make it so that it does not skip over multiple matching classes at the same offset. with sortTuple Nr_)rfr rp)rareels rAgetAllContextsByClass#Music21Object.getAllContextsByClasssC, # #I .nH%%i-B]B]%^Bns :AA)activeSiteOnlyc[URSUS95nSnUnU(aURU[RU(+US9nSnUH=upn XhLdM [ R "SU5nU(aUSULaUSs $UnSn O U(aUS-nMX`LaU$US-nU(aMUS:Xa [S 5eg ) aI Get the next element found in the activeSite (or other Sites) of this Music21Object. The `className` can be used to specify one or more classes to match. >>> s = corpus.parse('bwv66.6') >>> m3 = s.parts[0].measure(3) >>> m4 = s.parts[0].measure(4) >>> m3 >>> m3.show('t') {0.0} {0.0} {0.5} {1.0} {2.0} {3.0} >>> m3.next() >>> nextM3 = m3.next('Measure') >>> nextM3 is m4 True Note that calling next() repeatedly gives the same object. You'll want to call next on that object. >>> m3.next('Measure') is s.parts[0].measure(4) True >>> m3.next('Measure') is s.parts[0].measure(4) True So do this instead: >>> o = m3 >>> for i in range(5): ... print(o) ... o = o.next('Measure') We can find the next element given a certain class with the `className`: >>> n = m3.next('Note') >>> n >>> n.measureNumber 3 >>> n is m3.notes.first() True >>> n.next() Notice though that when we get to the end of the set of measures, something interesting happens (maybe it shouldn't? don't count on this.): we descend into the last measure and give its elements instead. We'll leave `o` where it is (m8 now) to demonstrate what happens, and also print its Part for more information: >>> while o is not None: ... print(o, o.getContextByClass(stream.Part)) ... o = o.next() * Changed in v6: added activeSiteOnly -- see description in `.contextSites()` T)rrbrrer_rarbFrrr4zMaximum recursion!N)rr7rfr rrrr() rarerallSiteContexts maxRecurse thisElForNextnextEl callContinuesingleSiteContextunused_positionInContextunused_recurseTypes rAnextMusic21Object.nextsft00!- 1    "44#!.!=!=%3!3#1 5F!LSbO!=O.VV$;VDF&)4"7%ay($*M#'LTca ! !OJ3j6 ?"#78 8 r@cURU[RU(+US9nSnUR(a%Ub"UR 5HupVnXPLdM Sn O U(a X0La U(dU$UR nUcgUR U/SS9n U RUR55n U cUbXR;aU$gU R$)a+ Get the previous element found in the activeSite or other .sites of this Music21Object. The `className` can be used to specify one or more classes to match. >>> s = corpus.parse('bwv66.6') >>> m2 = s.parts[0].getElementsByClass(stream.Measure)[2] # pickup measure >>> m3 = s.parts[0].getElementsByClass(stream.Measure)[3] >>> m3 >>> m3prev = m3.previous() >>> m3prev >>> m3prev is m2.notes[-1] True >>> m3.previous('Measure') is m2 True We'll iterate backwards from the first note of the second measure of the Alto part. >>> o = s.parts[1].getElementsByClass(stream.Measure)[2][0] >>> while o: ... print(o) ... o = o.previous() f# minor P2: Alto: Instrument 2 * Changed in v6: added activeSiteOnly -- see description in `.contextSites()` rFNT)rmrl) rfr rrr7rrorsr>rEru) rarerprevElisInPartr8unused1unused2activeSroprevNodes rApreviousMusic21Object.previous sj'')9F9V9V=K9K;I(* ==V/(.(;(;(=$W:#H)> f(MooG^^yk5^IF++DNN,<=H$ 5E5E(E"N'''r@c[(a.URcg[R"UR5$UR$rV)rrr unwrapWeakrefrs rArTMusic21Object._getActiveSitev s; >'++D,<,<==## #r@cUbURU5nX lOSUl[(a'UcSUlg[ R "U5UlgXlg![an[SSUSU3-5UeSnAff=f)NzactiveSite cannot be set for zobject z not in the Stream )r$rrrrr wrapWeakref)rarI storedOffsetr0s rArUMusic21Object._setActiveSite s   #11$7 ,8 (,0D ( >|#' #)#5#5d#; # +" $3v%8?@ sA B'A<<Ba A reference to the most-recent object used to contain this object. In most cases, this will be a Stream or Stream sub-class. In most cases, an object's activeSite attribute is automatically set when the object is attached to a Stream. >>> n = note.Note('C#4') >>> p = stream.Part() >>> p.insert(20.0, n) >>> n.activeSite is p True >>> n.offset 20.0 >>> m = stream.Measure() >>> m.insert(10.0, n) >>> n.activeSite is m True >>> n.offset 10.0 >>> n.activeSite = p >>> n.offset 20.0 )doccURnUb8URnUcUR=(d S$URU5nU$URnU$![a, [ R S5 SUlURnU$f=f)a The offset property sets or returns the position of this object as a float or fractions.Fraction value (generally in `quarterLengths`), depending on what is representable. Offsets are measured from the start of the object's `activeSite`, that is, the most recently referenced `Stream` or `Stream` subclass such as `Part`, `Measure`, or `Voice`. It is a simpler way of calling `o.getOffsetBySite(o.activeSite, returnType='rational')`. If we put a `Note` into a `Stream`, we will see the activeSite changes. >>> import fractions >>> n1 = note.Note('D#3') >>> n1.activeSite is None True >>> m1 = stream.Measure() >>> m1.number = 4 >>> m1.insert(10.0, n1) >>> n1.offset 10.0 >>> n1.activeSite >>> n1.activeSite is m1 True The most recently referenced `Stream` becomes an object's `activeSite` and thus the place where `.offset` looks to find its number. >>> m2 = stream.Measure() >>> m2.insert(3/5, n1) >>> m2.number = 5 >>> n1.offset Fraction(3, 5) >>> n1.activeSite is m2 True Notice though that `.offset` depends on the `.activeSite` which is the most recently accessed/referenced Stream. Here we will iterate over the `elements` in `m1` and we will see that the `.offset` of `n1` now is its offset in `m1` even though we haven't done anything directly to `n1`. Simply iterating over a site is enough to change the `.activeSite` of its elements: >>> for element in m1: ... pass >>> n1.offset 10.0 The property can also set the offset for the object if no container has been set: >>> n1 = note.Note() >>> n1.id = 'hi' >>> n1.offset = 20/3 >>> n1.offset Fraction(20, 3) >>> float(n1.offset) 6.666... >>> s1 = stream.Stream() >>> s1.append(n1) >>> n1.offset 0.0 >>> s2 = stream.Stream() >>> s2.insert(30.5, n1) >>> n1.offset 30.5 After calling `getElementById` on `s1`, the returned element's `offset` will be its offset in `s1`. >>> n2 = s1.getElementById('hi') >>> n2 is n1 True >>> n2.offset 0.0 Iterating over the elements in a Stream will make its `offset` be the offset in iterated Stream. >>> for thisElement in s2: ... thisElement.offset 30.5 When in doubt, use `.getOffsetBySite(streamObj)` which is safer or streamObj.elementOffset(self) which is 3x faster. * Changed in v8: using a Duration object as an offset is not allowed. NrzENot in Stream: changing activeSite to None and returning _naiveOffset)rrrr$rrrr)raactiveSiteWeakRefros rArJMusic21Object.offset sR!,,  (J!33:s: &,,T2!!A" &''[]"&%% &sA2B  B c[U5nURbURRX5 gX lg![a UnN>f=frV)r rrr2r)rar|rJs rArJr: sJ E]F ?? & OO , ,T : &   F s = A  A cUSLa URnOUnUc URnOURUSS9nU[ R :XaSnSnO[R"[U5nSnUR(dURR(dSOSnURR[U55(a-URR [U5R"nOFURb7URR [UR5R"nOSn[%XeUR&UR(Xx5$![a U(aeURnGNEf=f)a Returns a collections.namedtuple called SortTuple(atEnd, offset, priority, classSortOrder, isNotGrace, insertIndex) which contains the six elements necessary to determine the sort order of any set of objects in a Stream. 1) atEnd = {0, 1}; Elements specified to always stay at the end of a stream (``stream.storeAtEnd``) sort after normal elements. 2) offset = float; Offset (with respect to the active site) is the next and most important parameter in determining the order of elements in a stream (the note on beat 1 has offset 0.0, while the note on beat 2 might have offset 1.0). 3) priority = int; Priority is a user-specified property (default 0) that can set the order of elements which have the same offset (for instance, two Parts both at offset 0.0). 4) classSortOrder = int or float; ClassSortOrder is the third level of comparison that gives an ordering to elements with different classes, ensuring, for instance that Clefs (classSortOrder = 0) sort before Notes (classSortOrder = 20). 5) isNotGrace = {0, 1}; 0 = grace, 1 = normal. Grace notes sort before normal notes 6) The last tie-breaker is the creation time (insertIndex) of the site object represented by the activeSite. By default, the site used will be the activeSite: >>> n = note.Note() >>> n.offset = 4.0 >>> n.priority = -3 >>> n.sortTuple() SortTuple(atEnd=0, offset=4.0, priority=-3, classSortOrder=20, isNotGrace=1, insertIndex=0) >>> st = n.sortTuple() Check that all these values are the same as above: >>> st.offset == n.offset True >>> st.priority == n.priority True An object's classSortOrder comes from the Class object itself: >>> st.classSortOrder == note.Note.classSortOrder True SortTuples have a few methods that are documented in :class:`~music21.sorting.SortTuple`. The most useful one for documenting is `.shortRepr()`. >>> st.shortRepr() '4.0 <-3.20.0>' Inserting the note into the Stream will set the insertIndex. Most implementations of music21 will use a global counter rather than an actual timer. Note that this is a last resort, but useful for things such as multiple Parts inserted in order. It changes with each run, so we can't display it here. >>> s = stream.Stream() >>> s.insert(n) >>> n.sortTuple() SortTuple(atEnd=0, offset=4.0, priority=-3, classSortOrder=20, isNotGrace=1, insertIndex=...) >>> nInsertIndex = n.sortTuple().insertIndex If we create another nearly identical note, the insertIndex will be different: >>> n2 = note.Note() >>> n2.offset = 4.0 >>> n2.priority = -3 >>> s.insert(n2) >>> n2InsertIndex = n2.sortTuple().insertIndex >>> n2InsertIndex > nInsertIndex True >>> rb = bar.Barline() >>> s.storeAtEnd(rb) >>> rb.sortTuple() SortTuple(atEnd=1, offset=0.0, priority=0, classSortOrder=-5, isNotGrace=1, insertIndex=...) Normally if there's a site specified and the element is not in the site, the offset of None will be used, but if raiseExceptionOnMiss is set to True then a SitesException will be raised: >>> aloneNote = note.Note() >>> aloneNote.offset = 30 >>> aloneStream = stream.Stream(id='aloneStream') # no insert >>> aloneNote.sortTuple(aloneStream) SortTuple(atEnd=0, offset=30.0, priority=0, classSortOrder=20, isNotGrace=1, insertIndex=0) >>> aloneNote.sortTuple(aloneStream, raiseExceptionOnMiss=True) Traceback (most recent call last): music21.sites.SitesException: an entry for this object 0x... is not stored in stream FTrrr4r)rrJr$rrr r'rrrrrisGracer hasSiteIdrksiteDictglobalSiteIndexrrr) rauseSiteruseSiteNoFalse foundOffsetrJatEnd isNotGrace insertIndexs rAr>Music21Object.sortTupleH s?X e !__N$N  !++K 0,::4t:T  -.. .FEVVHk2FE--t}}/D/DQ! ::  7 , ,**--bk:JJK __ (**--b.ABRRKK --zH H3" 0'#//  0sEE<;E<cURc[S5UlURn[R(aUceU$)z? Get and set the duration of this object as a Duration object. r)rrr TYPE_CHECKING)rad_outs rArMusic21Object.duration s: >> !%a[DN ??$ $$ r@cSnURbSURlSnURnXlXlU(aURSUS.5 gg![an[ SU35UeSnAff=f)NFTr)changedElementrz$this must be a Duration object, not )rrr informSitesr%r)ra durationObjdurationObjAlreadyExistsqlr-s rArr s#( >> %$(DNN !'+ $ **B(N!% '  JQS!TU( 6{mD  s3A A7#A22A7cURR5H&n[US5(dMURSSS9 M( g)z trigger called whenever sites need to be informed of a change in the parameters of this object. `changedInformation` is not used now, but it can be a dictionary of what has changed. subclass this to do very interesting things. coreElementsChangedFT) updateIsFlat keepIndexN)rgetrr)rachangedInformationrXs rArMusic21Object.informSites s:!Aq/00%%5D%I"r@cUR$rV)rrs rA _getPriorityMusic21Object._getPriority s ~~r@c[U[5(d [S5eURU:waXlUR SUS.5 gg)z4 value is an int. Informs all sites of the change. z!priority values must be integers.r)rrN)rerr*rrr{s rA _setPriorityMusic21Object._setPriority sF %%%"#FG G >>U ""N    N O #r@a Get and set the priority integer value. Priority specifies the order of processing from left (lowest number) to right (highest number) of objects at the same offset. For instance, if you want a key change and a clef change to happen at the same time but the key change to appear first, then set: keySigElement.priority = 1; clefElement.priority = 2 this might be a slightly counterintuitive numbering of priority, but it does mean, for instance, if you had two elements at the same offset, an allegro tempo change and an andante tempo change, then the tempo change with the higher priority number would apply to the following notes (by being processed second). Default priority is 0; thus negative priorities are encouraged to have Elements that appear before non-priority set elements. In case of tie, there are defined class sort orders defined in `music21.base.classSortOrder`. For instance, a key signature change appears before a time signature change before a note at the same offset. This produces the familiar order of materials at the start of a musical score. >>> import music21 >>> a = music21.Music21Object() >>> a.priority = 3 >>> a.priority = 'high' Traceback (most recent call last): music21.base.ElementException: priority values must be integers. c zUc [SnOURS5(aUSSnUS:XaSUS'[R"U5upEUc[ SU35eUR S5nUS nUSSn[R "U5nUc[ SU35eU"5n U R"U4UUUS .UD6$) a Write out a file of music notation (or an image, etc.) in a given format. If fp is specified as a file path then the file will be placed there. If it is not given then a temporary file will be created. If fmt is not given then the default of your Environment's 'writeFormat' will be used. For most people that is musicxml. Returns the full path to the file. Some formats, including .musicxml, create a copy of the stream, pack it into a well-formed score if necessary, and run :meth:`~music21.stream.Score.makeNotation`. To avoid this when writing .musicxml, use `makeNotation=False`, an advanced option that prioritizes speed but may not guarantee satisfactory notation. N writeFormat.r4mxlTcompressz*cannot support output in this format yet: r)fmtfp subformats)r startswithr findFormatr)splitfindSubConverterForFormatwrite) rarr rregularizedConverterFormat unused_ext formatSubsr scClass formatWriters rArMusic21Object.writeA s* ;}-C ^^C ab'C %<#'HZ 171B1B31G." % -(+UVYUZ)[\ \YYs^ m^ 223MN ?(+UVYUZ)[\ \y !!$.&@%'-7.%- . .r@c [U5$)z Return a text representation possible with line breaks. This method can be overridden by subclasses to provide alternative text representations. reprrs rA _reprTextMusic21Object._reprTextq  Dzr@c[U5$)z Return a text representation without line breaks. This method can be overridden by subclasses to provide alternative text representations. rrs rA _reprTextLineMusic21Object._reprTextLiney rr@c <Uc/[R"5(a [SnO[[SnOQUR S5(aUSSnO5[R"5(aUR S5(aSU-n[R"U5upEUc[S U35eURS5nUS nUSSn[R"U5nU"5n U R"UU4UUS .UD6$![R[ 4a SnNf=f) a Displays an object in a format provided by the fmt argument or, if not provided, the format set in the user's Environment Valid formats include (but are not limited to):: musicxml text midi lily (or lilypond) lily.png lily.pdf lily.svg braille vexflow musicxml.png N.B. score.write('lily') returns a bare lilypond file, score.show('lily') runs it through lilypond and displays it as a png. Some formats, including .musicxml, create a copy of the stream, pack it into a well-formed score if necessary, and run :meth:`~music21.stream.Score.makeNotation`. To avoid this when showing .musicxml, use `makeNotation=False`, an advanced option that prioritizes speed but may not guarantee satisfactory notation. NipythonShowFormatzipython.musicxml.png showFormatrr4midizipython.z*cannot support showing in this format yet:r)appr ) r runningInNotebookrrEnvironmentExceptionKeyErrorr r r)r rshow) rarr#rrrrr rrs rAr'Music21Object.show s+8 ;''))1&':;C#<0 ^^C ab'C  % % ' 'CNN6,B,Bs"C171B1B31G." % -(+UVYUZ)[\ \YYs^ m^ 223MNy   !;-%(,6-$, - -'$88(C10C1s C<<DD)raincludeNonStreamDerivationsc/nUnSnUS:a{US- nURnUc6USLa/[US5(aURRnUcU$UnOU$USLdUR(aUR U5 UnUS:aM{U$)a Return a list of Stream subclasses that this object is contained within or (if followDerivation is set) is derived from. This method gives access to the hierarchy that contained or created this object. >>> s = corpus.parse('bach/bwv66.6') >>> noteE = s[1][2][3] >>> noteE >>> [e for e in noteE.containerHierarchy()] [, , ] Note that derived objects also can follow the container hierarchy: >>> import copy >>> n2 = copy.deepcopy(noteE) >>> [e for e in n2.containerHierarchy()] [, , ] Unless followDerivation is False: >>> [e for e in n2.containerHierarchy(followDerivation=False)] [] if includeNonStreamDerivations is True then n2's containerHierarchy will include n even though it's not a container. It gives a good idea of how the hierarchy is being constructed. >>> [e for e in n2.containerHierarchy(includeNonStreamDerivations=True)] [, , , ] The method follows activeSites, so set the activeSite as necessary. >>> p = stream.Part(id='newPart') >>> m = stream.Measure(number=20) >>> p.insert(0, m) >>> m.insert(0, noteE) >>> noteE.activeSite >>> noteE.containerHierarchy() [, ] * Changed in v5.7: `followDerivation` and `includeNonStreamDerivations` are now keyword only rr4Tr)rrrrootDerivationrr)rarar)rHfocusendMe candidatealts rAcontainerHierarchy Music21Object.containerHierarchy s~aiAIE((I #t+|0L0L **99C{# $' K*d2i6H6H I&E)ai* r@) retainOriginaddTiesdisplayTiedAccidentalsc SSKJn SSKJn [U5nXRR :a*[ SURR S3SUS3-5eUSLaUnO[R"U5n[R"U5n[XR5(a/n Xl /n S GHbn [X{5(dM[X{5n [X{/5 [X/5 U GH"n [U S 5(a.U RXx/5nUHnU R!U5 M MC[U S 5(aU R"S :Xa[X{5nUR!U 5 MU R"S :Xa[X5nUR!U 5 M[X{5nUR!U 5 [X5nUR!U 5 M[X{5nUR!U 5 [X5nUR!U 5 GM% GMe [%XRR - 5S:aURR nURR U- nURR U- n['5nUUl['5nUUlUUlUUlU(a[XvR(UR*45(aSnUR,bhUR,R.S:XaSnOfUR,R.S:XaSnSUR,lO8UR,R.S:XaSnO[,R0"S5Ul[XR(UR*45(a[,R0"U5nUUlGOU(Ga [XuR25(a[XR25(a[5UR6UR65HunnSnUR,bhUR,R.S:XaSnOfUR,R.S:XaSnSUR,lO8UR,R.S:XaSnO[,R0"S5Ul[,R0"U5UlM U(a[XvR85(a[XR85(a[;UR<5HunnUR<UnUR>cM$UR>cM3U(d/UR>R@S:waSUR>l!MgMiSUR>l SUR>l!M URR S:a [EXx/5nO [EUS/5nU (aU Ul#U$)au Split an Element into two Elements at a provided `quarterLength` (offset) into the Element. Returns a specialized tuple (_SplitTuple) that also has a .spannerList element which is a list of spanners that were created during the split, such as by splitting a trill note into more than one trill. TODO: unite into a "split" function -- document obscure uses. >>> a = note.Note('C#5') >>> a.duration.type = 'whole' >>> a.articulations = [articulations.Staccato()] >>> a.lyric = 'hi' >>> a.expressions = [expressions.Mordent(), expressions.Trill(), expressions.Fermata()] >>> st = a.splitAtQuarterLength(3) >>> b, c = st >>> b.duration.type 'half' >>> b.duration.dots 1 >>> b.duration.quarterLength 3.0 >>> b.articulations [] >>> b.lyric 'hi' >>> b.expressions [, ] >>> c.duration.type 'quarter' >>> c.duration.dots 0 >>> c.duration.quarterLength 1.0 >>> c.articulations [] >>> c.lyric >>> c.expressions [] >>> c.getSpannerSites() [>] st is a _SplitTuple which can get the spanners from it for inserting into a Stream. >>> st.spannerList [>] Make sure that ties and accidentals remain as they should be: >>> d = note.Note('D#4') >>> d.duration.quarterLength = 3.0 >>> d.tie = tie.Tie('start') >>> e, f = d.splitAtQuarterLength(2.0) >>> e.tie, f.tie (, ) >>> e.pitch.accidental.displayStatus is None True >>> f.pitch.accidental.displayStatus False Should be the same for chords: >>> g = chord.Chord(['C4', 'E4', 'G#4']) >>> g.duration.quarterLength = 3.0 >>> g[1].tie = tie.Tie('start') >>> h, i = g.splitAtQuarterLength(2.0) >>> for j in range(3): ... (h[j].tie, i[j].tie) (, ) (, ) (, ) >>> h[2].pitch.accidental.displayStatus, i[2].pitch.accidental.displayStatus (None, False) If quarterLength == self.quarterLength then the second element will be None. >>> n = note.Note() >>> n.quarterLength = 0.5 >>> firstPart, secondPart = n.splitAtQuarterLength(0.5) >>> secondPart is None True >>> firstPart is n True (same with retainOrigin off) >>> n = note.Note() >>> n.quarterLength = 0.5 >>> firstPart, secondPart = n.splitAtQuarterLength(0.5, retainOrigin=False) >>> firstPart is n False If quarterLength > self.quarterLength then a DurationException will be raised: >>> n = note.Note() >>> n.quarterLength = 0.5 >>> first, second = n.splitAtQuarterLength(0.7) Traceback (most recent call last): music21.duration.DurationException: cannot split a duration (0.5) at this quarterLength (7/10) * Changed in v7: all but quarterLength are keyword only r)chord)notezcannot split a duration (z) zat this quarterLength ()T) expressions articulations splitClient tieAttachfirstlaststopNstartcontinuez even-tiedFr)$rr7r8r rrrrrre GeneralNotelyricsrrrr<rr=absrNote UnpitchedrrTieChordrnotesNotRest enumeratepitches accidental displayType displayStatusrSr`)rarr3r4r5r7r8r.eRemain emptyLyricsr`listTypetempthisExpressionspannersrXeList eRemainListlenEndlenStartd1d2forceEndTieTypenewTie componentremainComponentrrYremainPrs rAsplitAtQuarterLength"Music21Object.splitAtQuarterLength sl " }- ==66 6#+DMM,G,G+HK+M?!<=  4 A d#A--% g// 0 0,.K(N 8Hq##q+R(2.&*N~}==#1#=#=ql#K!)A'..q1"* ==)33w>$+A$8E!LL8+55?*1'*DK'..~>$+A$8E!LL8*1'*DK'..~> ' 4 ^4&-g&@ #**>:+'+ 98 }}}::: ;a ? MM77M,,}<==..7 Z# Z!  z!ii%@AA$Ouu 55::(&0OUUZZ6)&,O!+AEEJUUZZ:-&0O('IIt~~#>??1$ A{{33 7KK8X8X.1!''7==.I* ?"(==,!}}))W4*4#++v5*0-7 *"++z9*4%(GGG$4IM&)ggo&>#%/J, z!\\22z'<<7X7X!!)),1!//!,<<+0B0B0N1<<33{B?DG..<C:E**6;?**8-    ) )C /a\*BaY'B (BN r@cN[[U55URR:wa'[ SUSURR3-5e[ U5S:Xa [ [R"U5/5$U(d[ SUS35e/n/n[R"U5nUSSHDnURUUUS9nUupURU 5 URUR5 MF UbURU5 [ U5n XZl U $) a5 Given a list of quarter lengths, return a "SplitTuple" of Music21Object objects, copied from this Music21Object, that are partitioned and tied with the specified quarter length list durations. THe SplitTuple will also have a .spannerList which contains a list of spanner created during the split, such as by splitting a trill note into more than one trill. TODO: unite into a "split" function -- document obscure uses. >>> n = note.Note() >>> n.quarterLength = 3 >>> post = n.splitByQuarterLengths([1, 1, 1]) >>> [n.quarterLength for n in post] [1.0, 1.0, 1.0] zhcannot split by quarter length list whose sum is not equal to the quarterLength duration of the source: z, r4z*cannot split by this quarter length list: rN)r4r5) r sumrrr)rrSrrrbrextendr`) raquarterLengthListr4r5rWr`rQqlSplitrnewElstOuts rAsplitByQuarterLengths#Music21Object.splitByQuarterLengths s60 #'( )T]]-H-H H(H&'r$--*E*E)FGH   !Q & d 345 5"(<=N>> a = note.Note() >>> a.duration.clear() # remove defaults >>> a.duration.addDurationTuple(duration.durationTupleFromTypeDots('half', 0)) >>> a.duration.quarterLength 2.0 >>> a.duration.addDurationTuple(duration.durationTupleFromTypeDots('whole', 0)) >>> a.duration.quarterLength 6.0 >>> b = a.splitAtDurations() >>> b (, ) >>> b[0].pitch == b[1].pitch True >>> b[0].duration >>> b[0].duration.type 'half' >>> b[1].duration.type 'whole' >>> b[0].quarterLength, b[1].quarterLength (2.0, 4.0) >>> c = note.Note() >>> c.quarterLength = 2.5 >>> d, e = c.splitAtDurations() >>> d.duration.type 'half' >>> e.duration.type 'eighth' >>> d.tie.type 'start' >>> print(e.tie) Assume c is tied to the next note. Then the last split note should also be tied >>> c.tie = tie.Tie('start') >>> d, e = c.splitAtDurations() >>> d.tie.type 'start' >>> e.tie.type 'continue' Rests have no ties: >>> f = note.Rest() >>> f.quarterLength = 2.5 >>> g, h = f.splitAtDurations() >>> (g.duration.type, h.duration.type) ('half', 'eighth') >>> f.tie is None True >>> g.tie is None True It should work for complex notes with tuplets. (this duration occurs in Modena A, Le greygnour bien, from the ars subtilior, c. 1380; hence how I discovered this bug) >>> n = note.Note() >>> n.duration.quarterLength = 0.5 + 0.0625 # eighth + 64th >>> tup = duration.Tuplet(4, 3) >>> n.duration.appendTuplet(tup) >>> first, last = n.splitAtDurations() >>> (first.duration, last.duration) (, ) Notice that this duration could have been done w/o tuplets, so no tuplets in output: >>> (first.duration.type, first.duration.dots, first.duration.tuplets) ('16th', 1, ()) >>> (last.duration.type, last.duration.dots, last.duration.tuplets) ('128th', 1, ()) Test of one with tuplets that cannot be split: >>> n = note.Note() >>> n.duration.quarterLength = 0.5 + 0.0625 # eighth + 64th >>> tup = duration.Tuplet(3, 2, 'eighth') >>> n.duration.appendTuplet(tup) >>> (n.duration.type, n.duration.dots, n.duration.tuplets) ('complex', 0, (,)) >>> first, last = n.splitAtDurations() >>> (first.duration, last.duration) (, ) >>> (first.duration.type, first.duration.dots, first.duration.tuplets) ('eighth', 0, (,)) >>> (last.duration.type, last.duration.dots, last.duration.tuplets) ('64th', 0, (,)) TODO: unite this and other functions into a "split" function -- document obscure uses. )raggregateTupletMultiplier componentsr rrl)raatmcrh splitLists rAsplitAtDurationsMusic21Object.splitAtDurationsV scXmm557DHMMD\D\]D\qVAOOc$9:D\]../@A ^s"A*cSnURb3URR(aURRnU$UR5H'nUSnUR(dMURnM) U$)a. Return the measure number of a :class:`~music21.stream.Measure` that contains this object if the object is in a measure. Returns None if the object is not in a measure. Also note that by default Measure objects have measure number 0. If an object belongs to multiple measures (not in the same hierarchy) then it returns the measure number of the :meth:`~music21.base.Music21Object.activeSite` if that is a :class:`~music21.stream.Measure` object. Otherwise, it will use :meth:`~music21.base.Music21Object.getContextByClass` to find the number of the measure it was most recently added to. >>> m = stream.Measure() >>> m.number = 12 >>> n = note.Note() >>> m.append(n) >>> n.measureNumber 12 >>> n2 = note.Note() >>> n2.measureNumber is None True >>> m2 = stream.Measure() >>> m2.append(n2) >>> n2.measureNumber 0 The property updates if the object's surrounding measure's number changes: >>> m2.number = 11 >>> n2.measureNumber 11 The most recent measure added to is used unless activeSite is a measure: >>> m.append(n2) >>> n2.measureNumber 12 >>> n2.activeSite = m2 >>> n2.measureNumber 11 Copies can retain measure numbers until set themselves: >>> import copy >>> nCopy = copy.deepcopy(n2) >>> nCopy.measureNumber 12 >>> m3 = stream.Measure() >>> m3.number = 4 >>> m3.append(nCopy) >>> nCopy.measureNumber 4 Nr)r isMeasurenumberr7)ramNumberr8ms rA measureNumberMusic21Object.measureNumber smz ?? &4??+D+Doo,,G '')qE;;;hhG * r@cSSKJn URnUb9UR(a(UR U5nU(aXCR - nU$UR URSS9nUb)UR U5nU(aXER - nU$URnU$![a URnU$f=f)a Try to obtain the nearest Measure that contains this object, and return the offset of this object within that Measure. If a Measure is found, and that Measure has padding defined as `paddingLeft` (for pickup measures, etc.), padding will be added to the native offset gathered from the object. >>> n = note.Note() >>> n.quarterLength = 2 >>> m = stream.Measure() >>> n._getMeasureOffset() # returns zero when not assigned 0.0 >>> n.quarterLength = 0.5 >>> m = stream.Measure() >>> m.repeatAppend(n, 4) >>> [n._getMeasureOffset() for n in m.notes] [0.0, 0.5, 1.0, 1.5] >>> m.paddingLeft = 2.0 >>> [n._getMeasureOffset() for n in m.notes] [2.0, 2.5, 3.0, 3.5] >>> [n._getMeasureOffset(includeMeasurePadding=False) for n in m.notes] [0.0, 0.5, 1.0, 1.5] rr#T)r`) rr$rrwr$ paddingLeftrfMeasurerrJ)raincludeMeasurePaddingr$r offsetLocalrzs rA_getMeasureOffsetMusic21Object._getMeasureOffsets8 #//  7#4#4!//5K$222 .#&&v~~$&OA}."#//$"7K,#}}4  #kk &."&++K.s-&B##B=<B=c~SSKJn URUR[R S9nUc [ S5eU$)z used by all the _getBeat, _getBeatDuration, _getBeatStrength functions. extracted to make sure that all three of the routines use the same one. rr!rz2this object does not have a TimeSignature in Sites)rr"rf TimeSignaturer rr))rar"tss rA_getTimeSignatureForBeat&Music21Object._getTimeSignatureForBeatPsF "'+'='=   *>>(>(  :()]^ ^ r@cUR5nURURU55$![a [ S5s$f=f)a Return the beat of this object as found in the most recently positioned Measure. Beat values count from 1 and contain a floating-point designation between 0 and 1 to show proportional progress through the beat. >>> n = note.Note() >>> n.quarterLength = 0.5 >>> m = stream.Measure() >>> m.timeSignature = meter.TimeSignature('3/4') >>> m.repeatAppend(n, 6) >>> [n.beat for n in m.notes] [1.0, 1.5, 2.0, 2.5, 3.0, 3.5] Fractions are returned for positions that cannot be represented perfectly using floats: >>> m.timeSignature = meter.TimeSignature('6/8') >>> [n.beat for n in m.notes] [1.0, Fraction(4, 3), Fraction(5, 3), 2.0, Fraction(7, 3), Fraction(8, 3)] >>> s = stream.Stream() >>> s.insert(0, meter.TimeSignature('3/4')) >>> s.repeatAppend(note.Note(), 8) >>> [n.beat for n in s.notes] [1.0, 2.0, 3.0, 1.0, 2.0, 3.0, 1.0, 2.0] Notes inside flat streams can still find the original beat placement from outer streams: >>> p = stream.Part() >>> ts = meter.TimeSignature('2/4') >>> p.insert(0, ts) >>> n = note.Note('C4', type='eighth') >>> m1 = stream.Measure(number=1) >>> m1.repeatAppend(n, 4) >>> m2 = stream.Measure(number=2) >>> m2.repeatAppend(n, 4) >>> p.append([m1, m2]) >>> [n.beat for n in p.flatten().notes] [1.0, 1.5, 2.0, 2.5, 1.0, 1.5, 2.0, 2.5] Fractions print out as improper fraction strings >>> m = stream.Measure() >>> m.timeSignature = meter.TimeSignature('4/4') >>> n = note.Note() >>> n.quarterLength = 1/3 >>> m.repeatAppend(n, 12) >>> for n in m.notes[:5]: ... print(n.beat) 1.0 4/3 5/3 2.0 7/3 If there is no TimeSignature object in sites then returns the special float `nan` meaning "Not a Number": >>> isolatedNote = note.Note('E4') >>> isolatedNote.beat nan Not-a-number objects do not compare equal to themselves: >>> isolatedNote.beat == isolatedNote.beat False Instead, to test for `nan`, import the math module and use `isnan()`: >>> import math >>> math.isnan(isolatedNote.beat) True * Changed in v6.3: returns `nan` if there is no TimeSignature in sites. Previously raised an exception. nan)rgetBeatProportion$getMeasureOffsetOrMeterModulusOffsetr)r3rars rAbeatMusic21Object.beat_sLn ..0B''(O(OPT(UV V% <  /2A  A cUR5nURURU55$![a gf=f)a Return a string representation of the beat of this object as found in the most recently positioned Measure. Beat values count from 1 and contain a fractional designation to show progress through the beat. >>> n = note.Note(type='eighth') >>> m = stream.Measure() >>> m.timeSignature = meter.TimeSignature('3/4') >>> m.repeatAppend(n, 6) >>> [n.beatStr for n in m.notes] ['1', '1 1/2', '2', '2 1/2', '3', '3 1/2'] >>> m.timeSignature = meter.TimeSignature('6/8') >>> [n.beatStr for n in m.notes] ['1', '1 1/3', '1 2/3', '2', '2 1/3', '2 2/3'] >>> s = stream.Stream() >>> s.insert(0, meter.TimeSignature('3/4')) >>> s.repeatAppend(note.Note(type='quarter'), 8) >>> [n.beatStr for n in s.notes] ['1', '2', '3', '1', '2', '3', '1', '2'] If there is no TimeSignature object in sites then returns 'nan' for not a number. >>> isolatedNote = note.Note('E4') >>> isolatedNote.beatStr 'nan' * Changed in v6.3: returns 'nan' if there is no TimeSignature in sites. Previously raised an exception. r)rgetBeatProportionStrrr)rs rAbeatStrMusic21Object.beatStrsEJ ..0B**2+R+RSW+XY Y%  s /2 ??cUR5nURURU55$![a [ S5s$f=f)a Return a :class:`~music21.duration.Duration` of the beat active for this object as found in the most recently positioned Measure. If extending beyond the Measure, or in a Stream with a TimeSignature, the meter modulus value will be returned. >>> n = note.Note('C4', type='eighth') >>> n.duration >>> m = stream.Measure() >>> m.timeSignature = meter.TimeSignature('3/4') >>> m.repeatAppend(n, 6) >>> n0 = m.notes.first() >>> n0.beatDuration Notice that the beat duration is the same for all these notes and has nothing to do with the duration of the element itself >>> [n.beatDuration.quarterLength for n in m.notes] [1.0, 1.0, 1.0, 1.0, 1.0, 1.0] Changing the time signature changes the beat duration: >>> m.timeSignature = meter.TimeSignature('6/8') >>> [n.beatDuration.quarterLength for n in m.notes] [1.5, 1.5, 1.5, 1.5, 1.5, 1.5] Complex time signatures will give different note lengths: >>> s = stream.Stream() >>> s.insert(0, meter.TimeSignature('2/4+3/4')) >>> s.repeatAppend(note.Note(type='quarter'), 8) >>> [n.beatDuration.quarterLength for n in s.notes] [2.0, 2.0, 3.0, 3.0, 3.0, 2.0, 2.0, 3.0] If there is no TimeSignature object in sites then returns a duration object of Zero length. >>> isolatedNote = note.Note('E4') >>> isolatedNote.beatDuration * Changed in v6.3: returns a duration.Duration object of length 0 if there is no TimeSignature in sites. Previously raised an exception. r)rgetBeatDurationrr)rrs rA beatDurationMusic21Object.beatDurationsKf ..0B%%b&M&Md&ST T% A;  rcUR5nURU5nURUSSS9$![a [ S5s$f=f)a Return the metrical accent of this object in the most recently positioned Measure. Accent values are between zero and one, and are derived from the local TimeSignature's accent MeterSequence weights. If the offset of this object does not match a defined accent weight, a minimum accent weight will be returned. >>> n = note.Note(type='eighth') >>> m = stream.Measure() >>> m.timeSignature = meter.TimeSignature('3/4') >>> m.repeatAppend(n, 6) The first note of a measure is (generally?) always beat strength 1.0: >>> m.notes.first().beatStrength 1.0 Notes on weaker beats have lower strength: >>> [n.beatStrength for n in m.notes] [1.0, 0.25, 0.5, 0.25, 0.5, 0.25] >>> m.timeSignature = meter.TimeSignature('6/8') >>> [n.beatStrength for n in m.notes] [1.0, 0.25, 0.25, 0.5, 0.25, 0.25] Importantly, the actual numbers here have no particular meaning. You cannot "add" two beatStrengths of 0.25 and say that they have the same beat strength as one note of 0.5. Only the ordinal relations really matter. Even taking an average of beat strengths is a tiny bit methodologically suspect (though it is common in research for lack of a better method). We can also get the beatStrength for elements not in a measure, if the enclosing stream has a :class:`~music21.meter.TimeSignature`. We just assume that the time signature carries through to hypothetical following measures: >>> n = note.Note('E-3', type='quarter') >>> s = stream.Stream() >>> s.insert(0.0, meter.TimeSignature('2/2')) >>> s.repeatAppend(n, 12) >>> [n.beatStrength for n in s.notes] [1.0, 0.25, 0.5, 0.25, 1.0, 0.25, 0.5, 0.25, 1.0, 0.25, 0.5, 0.25] Changing the meter changes the output, of course, as can be seen from the fourth quarter note onward: >>> s.insert(4.0, meter.TimeSignature('3/4')) >>> [n.beatStrength for n in s.notes] [1.0, 0.25, 0.5, 0.25, 1.0, 0.5, 0.5, 1.0, 0.5, 0.5, 1.0, 0.5] The method returns correct numbers for the prevailing time signature even if no measures have been made: >>> n = note.Note('E--3', type='half') >>> s = stream.Stream() >>> s.isMeasure False >>> s.insert(0, meter.TimeSignature('2/2')) >>> s.repeatAppend(n, 16) >>> s.notes[0].beatStrength 1.0 >>> s.notes[1].beatStrength 0.5 >>> s.notes[4].beatStrength 1.0 >>> s.notes[5].beatStrength 0.5 Getting the beatStrength of an object without a time signature in its context returns the not-a-number special object 'nan': >>> n2 = note.Note(type='whole') >>> n2.beatStrength nan >>> from math import isnan >>> isnan(n2.beatStrength) True * Changed in v6.3: return 'nan' instead of raising an exception. TF)forcePositionMatchpermitMeterModulusr)rrgetAccentWeightr)r3)rar meterModuluss rA beatStrengthMusic21Object.beatStrength scr ..0BBB4HL%%l9=9>&@ @& <  s14A  A cSSKJn URRS:XagUR UR 5nUc [ S5$UR5nURUR5$)Nrtemporr) rrrrrfTempoIndicationr3getSoundingMetronomeMarkdurationToSeconds)rartimms rA _getSecondsMusic21Object._getSecondssb! == & &# -  # #E$9$9 : :<   ( ( *##DMM22r@c0SSKJn URUR5nUc [ S5eUR 5nUR U5UlURRSS9H$nXR;dMUR5 M& g)Nrrz4this object does not have a TempoIndication in SitesTrN) rrrfrr)rsecondsToDurationrrrelementsr)rar|rrrrXs rA _setSecondsMusic21Object._setSecondss{!  # #E$9$9 : :()_` `  ( ( *,,U3 D1Azz!%%'2r@a* Get or set the duration of this object in seconds, assuming that this object has a :class:`~music21.tempo.MetronomeMark` or :class:`~music21.tempo.MetricModulation` (or any :class:`~music21.tempo.TempoIndication`) in its past context. >>> s = stream.Stream() >>> for i in range(3): ... s.append(note.Note(type='quarter')) ... s.append(note.Note(type='quarter', dots=1)) >>> s.insert(0, tempo.MetronomeMark(number=60)) >>> s.insert(2, tempo.MetronomeMark(number=120)) >>> s.insert(4, tempo.MetronomeMark(number=30)) >>> [n.seconds for n in s.notes] [1.0, 1.5, 0.5, 0.75, 2.0, 3.0] Setting the number of seconds on a music21 object changes its duration: >>> lastNote = s.notes[-1] >>> lastNote.duration.fullName 'Dotted Quarter' >>> lastNote.seconds = 4.0 >>> lastNote.duration.fullName 'Half' Any object of length 0 has zero-second length: >>> tc = clef.TrebleClef() >>> tc.seconds 0.0 If an object has positive duration but no tempo indication in its context, then the special number 'nan' for "not-a-number" is returned: >>> r = note.Rest(type='whole') >>> r.seconds nan Check for 'nan' with the `math.isnan()` routine: >>> import math >>> math.isnan(r.seconds) True Setting seconds for an element without a tempo-indication in its sites raises a Music21ObjectException: >>> r.seconds = 2.0 Traceback (most recent call last): music21.base.Music21ObjectException: this object does not have a TempoIndication in Sites Note that if an object is in multiple Sites with multiple Metronome marks, the activeSite (or the hierarchy of the activeSite) determines its seconds for getting or setting: >>> r = note.Rest(type='whole') >>> m1 = stream.Measure() >>> m1.insert(0, tempo.MetronomeMark(number=60)) >>> m1.append(r) >>> r.seconds 4.0 >>> m2 = stream.Measure() >>> m2.insert(0, tempo.MetronomeMark(number=120)) >>> m2.append(r) >>> r.seconds 2.0 >>> r.activeSite = m1 >>> r.seconds 4.0 >>> r.seconds = 1.0 >>> r.duration.type 'quarter' >>> r.activeSite = m2 >>> r.seconds = 1.0 >>> r.duration.type 'half' * Changed in v6.3: return `nan` instead of raising an exception. )rrrrrrrrrrrrrrkr) NNNNNNNrN)rkzstr | int | Nonerz Groups | Nonerz Sites | NonerzDuration | Nonerstream.Stream | Nonerz Style | NonerzEditorial | NonerJrrzOffsetQLIn | None)rar&rqzt.TypeGuard[_M21T])rqr)rq int | str)rr)rgr,rqrrrV)rar&rdict[int, t.Any] | Nonerzset[str] | Nonerqr&)rar&rrrqr&)rqdict[str, t.Any])rr)rqryr)rqr)rr)rqr)r r)rqr)r|r)rqr)rzDerivation | Nonerqrr)rqrr)rIrrt.Literal[False]rqr)rIrrrrqzOffsetQL | OffsetSpecial)rIrr|r)rIrrqr)rFzIterable | Nonerqzlist[spanner.Spanner])T)F)rez type[_M21T]rqz _M21T | None)re str | NonerqzMusic21Object | None)reztype[_M21T] | str | Noner_r rqz_M21T | Music21Object | None)rzt.Literal[True]rrr`t.Literal['reverse'] | boolrqz'Generator[ContextSortTuple, None, None])rrr`rrrrqz#Generator[ContextTuple, None, None])rrr`rrrrqz6Generator[ContextTuple | ContextSortTuple, None, None])rez type[Music21Object] | str | None)rIr)FF)rz't.Literal[False] | stream.Stream | Nonerrrqr)rqr)rr)NN)rrr z"str | pathlib.Path | IOBase | Nonerqz pathlib.Path)rqrS)TF)rhz&list[int | float | fractions.Fraction]rqrS)rqz int | None)rqzfloat | fractions.Fraction)rqzmeter.TimeSignature)rqzfractions.Fraction | float)rqr3)r|rrqrr)Lr;r<r=r>rsrrNrrrrrrrbrfrjpropertyrksetterrrrrrrrrrrrrrrrr4r9rKrr]r rrfr7rrrrTrUrrJr>rrrrrrrrr'r1rbrlrtr{rrrrrrrrsecondsr?rtrus@rAr,r,Ws"eN!#NI"H$K$*77J ?<K(!I~(V%)'+%)+/26%)-1$'26/8!/8$/8#/8) /8 0 /8 # /8+/8"/8!0/8b   ! !YY2*=A+AE+$9+1>+JO+Z'0R 4.--*0))*: \\ ++ ,,! ! F)), +0    (      $        $ v v v vp3&03&)3&jGN GN GNT;?X9*7X92X9t*B= '33            '33           +8*D*D  T'T( T "Tn  !$8=   *    6   1     !$8=-2     6  +   -    " !$8=!& EI  EI 6 EIEI >EIN _<8<v9"v94v9r<@Y(!&Y(8Y(B $$<.(  J:zzx ]] ' 'BG/4QH>QH(,QH!QHh  __& J P $  HL+/-. -. )-.  -.`7-~$) Wz$ C CP$ 9=9  9vofGGR;z Z Z x((T66p` ` D 3 ({KO6 O Gr@r,r_m21ObjDefaultDefinedKeyscl^\rSrSr%SrSrS/rSS0rS\S'S S U4Sjjjr S r SS jr SS jr Sr U=r$)r-iaD An ElementWrapper is a way of containing any object that is not a :class:`~music21.base.Music21Object`, so that that object can be positioned within a :class:`~music21.stream.Stream`. The object stored within ElementWrapper is available from the :attr:`~music21.base.ElementWrapper.obj` attribute. All the attributes of the stored object (except .id and anything else that conflicts with a Music21Object attribute) are gettable and settable by querying the ElementWrapper. This feature makes it possible easily to mix Music21Objects and non-Music21Objects with similarly named attributes in the same Stream. This example inserts 10 random wave files into a music21 Stream and then reports their filename and number of audio channels (in this example, it's always 2) if they fall on a strong beat in fast 6/8 >>> import music21 >>> #_DOCS_SHOW import wave >>> import random >>> class Wave_read: #_DOCS_HIDE ... def getnchannels(self): return 2 #_DOCS_HIDE >>> s = stream.Stream() >>> s.id = 'mainStream' >>> s.append(meter.TimeSignature('fast 6/8')) >>> for i in range(10): ... #_DOCS_SHOW fileName = 'thisSound_' + str(random.randint(1, 20)) + '.wav' ... fileName = 'thisSound_' + str(1 + ((i * 100) % 19)) + '.wav' #_DOCS_HIDE ... soundFile = Wave_read() #_DOCS_HIDE # #make a more predictable "random" set. ... #_DOCS_SHOW soundFile = wave.open(fileName) ... soundFile.fileName = fileName ... el = music21.ElementWrapper(soundFile) ... s.insert(i, el) >>> for j in s.getElementsByClass(base.ElementWrapper): ... if j.beatStrength > 0.4: ... (j.offset, j.beatStrength, j.getnchannels(), j.fileName) (0.0, 1.0, 2, 'thisSound_1.wav') (3.0, 1.0, 2, 'thisSound_16.wav') (6.0, 1.0, 2, 'thisSound_12.wav') (9.0, 1.0, 2, 'thisSound_8.wav') >>> for j in s.getElementsByClass(base.ElementWrapper): ... if j.beatStrength > 0.4: ... (j.offset, j.beatStrength, j.getnchannels() + 1, j.fileName) (0.0, 1.0, 3, 'thisSound_1.wav') (3.0, 1.0, 3, 'thisSound_16.wav') (6.0, 1.0, 3, 'thisSound_12.wav') (9.0, 1.0, 3, 'thisSound_8.wav') Test representation of an ElementWrapper >>> for i, j in enumerate(s.getElementsByClass(base.ElementWrapper)): ... if i == 2: ... j.id = None ... else: ... j.id = str(i) + '_wrapper' ... if i <=2: ... print(j) Equality -------- Two ElementWrappers are equal if they would be equal as Music21Objects and they wrap objects that are equal. >>> list1 = ['a', 'b', 'c'] >>> a = base.ElementWrapper(list1) >>> a.offset = 3.0 >>> list2 = ['a', 'b', 'c'] >>> b = base.ElementWrapper(list2) >>> b.offset = 3.0 >>> a == b True >>> a is not b True Offset does not need to be equal for equality: >>> b.offset = 4.0 >>> a == b True But elements must compare equal >>> list2.append('d') >>> a == b False * Changed in v9: completely different approach to equality, unified w/ the rest of music21. )rIrIz The object this wrapper wraps. It should not be a Music21Object, since if so, you might as well put that directly into the Stream itself.rrc 2>Xl[TU]"S0UD6 g)Nr9)rIrWrb)rarIrr\s rArbElementWrapper.__init__Ys $8$r@c[UR5SSn[[UR55S:aUS- nUSS:XaUS- nURb SURSUR SU<3$S UR SU<3$) Nrz...<>rz offset=z obj=zoffset=)ryrIrrrkrJ)rashortObjs rArElementWrapper._reprInternalasM1R( s488}  "  H{c!C 88  $++eH<H HT[[Mxl; ;r@c6US:Xa[RUSU5 gXR;a[RXU5 [RUS5nU[;a Ub[ X15(a [ X1U5 g[RXU5 g)NrI)rrr__getattribute__rrr)ranamer| storedObjs rArElementWrapper.__setattr__ms 5=   tUE 2  ==   t5 1++D%8 1 1)I,, IU +   t5 1r@c~[RUS5nUc[SU<S35e[RX!5$)z This method is only called when __getattribute__() fails. Using this also avoids the potential recursion problems of subclassing __getattribute__()_ see: https://stackoverflow.com/questions/371753/python-using-getattribute-method for examples rIzCould not get attribute z in an object-less element)r,rr%r)rarrs rA __getattr__ElementWrapper.__getattr__sC"224?   #;D8C]!^_ _&&y77r@rV)rIrp)rryr|rprqrr)rryrqrp)r;r<r=r>rsrrrrNrbrrrr?rtrus@rAr-r-sN^~"J N!I~ %% <2( 8 8r@r-c\rSrSrSrSrSrg)Testiz, All other tests moved to test/test_base.py c2SSKJn U"U[55 g)Nr) testCopyAll)music21.test.commonTestrglobals)rars rAtestCopyAndDeepcopyTest.testCopyAndDeepcopys7D')$r@r9N)r;r<r=r>rsrr?r9r@rArrs %r@r__main__)rqzfrozenset[str])crs __future__rrcollections.abcrrr functoolsimportlib.utilrtypingrrunittestr3weakrefmusic21._versionrr rr music21.common.enumsr r music21.common.numberToolsr music21.common.typesrrrmusic21.derivationrmusic21.durationrrmusic21.editorialrrrr music21.sitesrrr music21.stylermusic21.sortingrrrrr fractionsior pathlibr"r$r%TypeVarr&r.r/__all__r( Environmentr_missingImportmodNameloaderrrgetMissingImportStrr)r* NamedTuplerFrPrYrSrr+rrrcacherProtoM21Objectr,dirrrNr-TestCaserrr;mainTestr9r@rArs*4#/ $:=-5)8' ??JJ?? IIg%A BE   ( 00&&v. &G w F ~g&'  J>1&44^D!+  - \::  |44 ,1<<, ,q||,8%8|YTY@!(!8 ))@S: G**S: nt.33}3G-H?H]8]]8@%8  %^ ,  z r@