
    rh                      % S r SSKJr  SSKrSSKrSSKJr  SSKrSSKJ	r	  SSKJ
r
  SSKJr  SSKJr  SS	KJr  SS
KJr  SSKJr  SSKJr  SSKJr  SSKJr  SSKJr  SSKJr  SSKJr  \R0                  (       a?  SSKJrJr  SSKJrJr  SSKJr  SSKJ r   SSKJ!r!  SSKJ"r"  SSK#J$r$  \RJ                  " SSS9r&\RN                  " S5      r(Sr)Sr*S r+ " S  S!\RX                  5      r- " S" S#\RX                  5      r. " S$ S%\RX                  5      r/\R`                  S&   r1/ S&Qr2S'\3S('    " S) S*\Rh                  \Rj                  5      r6 " S+ S,\	Rn                  5      r8 " S- S\85      r9 " S. S/\95      r: " S0 S1\95      r; " S2 S3\85      r< " S4 S5\Rz                  5      r> " S6 S7\Rz                  5      r?\:\<\;\9\8\6/r@\AS8:X  a  SSKr\R                  " \?5        gg)9z
Classes and functions for creating Notes, Rests, and Lyrics.

The :class:`~music21.pitch.Pitch` object is stored within,
and used to configure, :class:`~music21.note.Note` objects.
    )annotationsN)overload)base)beam)common)Duration)environment)exceptions21)expressions)interval)Pitch)prebase)styletie)volume)IterableSequence)StepName
OffsetQLIn)articulations)chord
instrument)
percussion)Style_NotRestTypeNotRest)boundnote)z
arrow downzarrow upzback slashedz
circle dotzcircle-xcircledclustercrossdiamonddofazfa upzinverted trianglelazleft triangleminonenormalotherre	rectangleslashslashedsosquaretitrianglex)doubledownnoStemr)   unspecifiedupc                 l   [        5        V s/ s H4  o R                  S5      (       a  M  U R                  S5      (       a  M2  U PM6     nn UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S	5        UR                  S
5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        UR                  S5        U$ s  sn f )N__Testtr   unittestr   environLocalcopy
_DOC_ORDERr   r   r   r   r   r	   r
   r   r   r   r   r   r   SyllabicChoices)globals
startswithremove)nouts     F/home/james-whalen/.local/lib/python3.13/site-packages/music21/note.py__dir__rI   \   s5   i
Wi||D'91!,,vBV1iC
WJJsOJJ}JJzJJzJJ~JJvJJ|JJzJJwJJvJJvJJxJJ}JJ~JJ}JJzJJyJJwJJuJJxJJ !J3 Xs   F1F1F1c                      \ rS rSrSrg)LyricExceptiony    N__name__
__module____qualname____firstlineno____static_attributes__rM       rH   rK   rK   y       rT   rK   c                      \ rS rSrSrg)NoteException}   rM   NrN   rM   rT   rH   rW   rW   }   rU   rT   rW   c                      \ rS rSrSrg)NotRestException   rM   NrN   rM   rT   rH   rZ   rZ      rU   rT   rZ   )Nbeginsingleendmiddle	compositezlist[SyllabicChoices]SYLLABIC_CHOICESc                    ^  \ rS rSrSr\R                  rSr  SSSSS.         SU 4S jjjjr	S r
\SS	 j5       r\SS
 j5       r\R                  SS j5       r\SS j5       r\R                  SS j5       r\SS j5       r\R                  SS j5       r\SS j5       r\R                  SS j5       r\S S j5       r\R                  S!S j5       rS"S#S jjrSrU =r$ )$Lyric   a  
An object representing a single Lyric as part of a note's .lyrics property.

The note.lyric property is a simple way of specifying a single lyric, but
Lyric objects are needed for working with multiple lyrics.

>>> l = note.Lyric(text='hello')
>>> l
<music21.note.Lyric number=1 syllabic=single text='hello'>

Music21 processes leading and following hyphens intelligently by default.

>>> l2 = note.Lyric(text='hel-')
>>> l2
<music21.note.Lyric number=1 syllabic=begin text='hel'>

If `applyRaw` is set to True then hyphens will be treated as actual text,
and the `syllabic` will be set to "single".

>>> l3 = note.Lyric(number=3, text='hel-', applyRaw=True)
>>> l3
<music21.note.Lyric number=3 syllabic=single text='hel-'>

Lyrics have four properties: text, number, identifier, syllabic (single,
begin, middle, end, or (not in musicxml) composite)

>>> l3.text
'hel-'

>>> l3.number
3

>>> l3.syllabic
'single'

Note musicXML only supports one 'identifier' attribute which is called
'number' but which can be a number or a descriptive identifier like
'part2verse1.' To preserve lyric ordering, music21 stores a number and a
descriptive identifier separately. The descriptive identifier is by default
the same as the number, but in cases where a string identifier is present,
it will be different.

Both music21 and musicxml support multiple `Lyric` objects in the same stanza,
for instance, if there is an elision on a note then multiple lyrics with
different syllabics can appear on a single note.  In music21 these are supported
by setting .components into a list of `Lyric` object.  For instance in
the madrigal "Il bianco e dolce cigno", the "co" and "e" of "bianco e"
are elided into a single lyric:

>>> bianco = note.Lyric()
>>> co = note.Lyric('co', syllabic='end')
>>> e = note.Lyric('e', syllabic='single')
>>> bianco.components = [co, e]
>>> bianco.isComposite
True
>>> bianco.text
'co e'
>>> bianco.syllabic
'composite'
>>> e.elisionBefore = '_'
>>> bianco.text
'co_e'

>>> [component.syllabic for component in bianco.components]
['end', 'single']

Custom elision elements for composite components will be supported later.

* New in v6.7: composite components, elisionBefore
* Changed in v8: lyric text can be an empty string, but not None.
)_identifier_number	_syllabic_text
componentselisionBeforeFN)applyRawsyllabic
identifierc                  > [         TU ]  5         S U l        SU l        SU l        S U l        S U l        SU l        U(       a  U R                  X5        Ub  X@l	        X l
        XPl        g )N     )super__init__re   rf   rh   rg   ri   rj   setTextAndSyllabicrl   numberrm   )selftextru   rk   rl   rm   keywords	__class__s          rH   rs   Lyric.__init__   sh     	%)
*.,0  ##D3 $M %rT   c                   SnU R                   b  USU R                    S3-  nU R                  b  USU R                  < S3-  nU R                  b  USU R                   S3-  nU R                  (       a  USU R                  < S3-  nU$ )Nrp   znumber=rq   zidentifier=z	syllabic=ztext=)ru   re   rm   rl   rw   )rv   rG   s     rH   _reprInternalLyric._reprInternal  s    ;;"WT[[M++C'[ 3155C==$Yt}}oQ//C99U499-q))C
rT   c                ,    [        U R                  5      $ )zf
Returns True if this Lyric has composite elements,
for instance, is multiple lyrics placed together.
)boolri   rv   s    rH   isCompositeLyric.isComposite  s     DOO$$rT   c                v   U R                   (       d  U R                  $ [        R                  (       a&  [	        U R
                  [        5      (       d   S5       eU R
                  S   R                  nUc  SnU R
                  SS  H/  nUR                  b  UR                  OSnXR                  U-   -  nM1     U$ )a  
Gets or sets the text of the lyric.  For composite lyrics, set
the text of individual components instead of setting the text here.

>>> l = note.Lyric()
>>> l.text
''
>>> l.text = 'hi'
>>> l.text
'hi'

Setting the text of a composite lyric wipes out the components:

>>> bianco = note.Lyric()
>>> co = note.Lyric('co', syllabic='end')
>>> e = note.Lyric('e', syllabic='single')
>>> bianco.components = [co, e]
>>> bianco.isComposite
True
>>> bianco.text
'co e'
>>> bianco.text = 'co_e'
>>> bianco.isComposite
False
z=Programming error: isComposite implies that components existsr   Nrp   ro   )	r   rh   r=   TYPE_CHECKING
isinstanceri   r   rw   rj   )rv   text_out	componentcomponentTexts       rH   rw   
Lyric.text  s    6 ::!$//8<< TST<q)..H!__QR0	2;..2L	RT33mCC 1 OrT   c                @    U R                   (       a  S U l        Xl        g N)r   ri   rh   )rv   newTexts     rH   rw   r   ?  s    "DO
rT   c                >    U R                   (       a  gU R                  $ )a  
Returns or sets the syllabic property of a lyric.

>>> fragment = note.Lyric('frag', syllabic='begin')
>>> fragment.syllabic
'begin'
>>> fragment.rawText
'frag-'
>>> fragment.syllabic = 'end'
>>> fragment.rawText
'-frag'

Illegal values raise a LyricException

>>> fragment.syllabic = 'slide'
Traceback (most recent call last):
music21.note.LyricException: Syllabic value 'slide' is not in
    note.SYLLABIC_CHOICES, namely:
    [None, 'begin', 'single', 'end', 'middle', 'composite']
r`   )r   rg   r   s    rH   rl   Lyric.syllabicE  s    , >>!rT   c                X    U[         ;  a  [        SU< S3S[          3-   5      eXl        g )NzSyllabic value z is not in znote.SYLLABIC_CHOICES, namely: )ra   rK   rg   )rv   newSyllabics     rH   rl   r   a  s=    .. !+<34D3EFG  %rT   c                L    U R                   c  U R                  $ U R                   $ )a  
By default, this is the same as self.number. However, if there is a
descriptive identifier like 'part2verse1', it is stored here and
will be different from self.number. When converting to musicXML,
this property will be stored in the lyric 'number' attribute which
can store a number or a descriptive identifier but not both.

>>> l = note.Lyric()
>>> l.number = 12
>>> l.identifier
12

>>> l.identifier = 'Rainbow'
>>> l.identifier
'Rainbow'

Default value is the same as default for number, that is, 1:

>>> note.Lyric().identifier
1
)re   rf   r   s    rH   rm   Lyric.identifierj  s&    . #<<###rT   c                    Xl         g r   )re   rv   values     rH   rm   r     s     rT   c                   U R                   nU R                  (       d2  U R                  nUS:X  a  US-   $ US:X  a  SU-   S-   $ US:X  a  SU-   $ U$ [        R                  (       a&  [        U R                  [        5      (       d   S5       eU R                  S   R                  nU R                  S   R                  nUS;   a  SU-   nUS	;   a  US-  nU$ )
a`  
returns the text of the syllable with '-' etc.

>>> l = note.Lyric('hel-')
>>> l.text
'hel'
>>> l.rawText
'hel-'

>>> l = note.Lyric('lo', syllabic='end')
>>> l.rawText
'-lo'

>>> l = note.Lyric('-ti-')
>>> l.rawText
'-ti-'

>>> l = note.Lyric('bye')
>>> l.rawText
'bye'

Composite lyrics take their endings from the first and last components:

>>> composite = note.Lyric()
>>> co = note.Lyric('co', syllabic='end')
>>> e = note.Lyric('e', syllabic='single')
>>> e.elisionBefore = '_'
>>> composite.components = [co, e]
>>> composite.rawText
'-co_e'
>>> e.syllabic = 'middle'
>>> composite.rawText
'-co_e-'
r\   -r_   r^   z>Programming error: isComposite should assert components existsr   )r_   r^   )r\   r_   )rw   r   rl   r=   r   r   ri   r   )rv   rw   rl   firstSyllabiclastSyllabics        rH   rawTextLyric.rawText  s    H yy}}H7"cz!X%TzC''U"Tz!!$//8<< UTU< OOA.77M??2.77L 11Tz22KrT   c                $    U R                  USS9  g )NT)rk   )rt   )rv   	rawTextIns     rH   r   r     s    	D9rT   c                    U R                   $ )aB  
This stores the number of the lyric (which determines the order
lyrics appear in the score if there are multiple lyrics). Unlike
the musicXML lyric number attribute, this value must always be a
number; lyric order is always stored in this form. Descriptive
identifiers like 'part2verse1' which can be found in the musicXML
lyric number attribute should be stored in self.identifier.

Default is 1

>>> l = note.Lyric('Hi')
>>> l.number
1

>>> l.number = 5
>>> l.number
5
>>> l.number = None
Traceback (most recent call last):
music21.note.LyricException: Number best be number
)rf   r   s    rH   ru   Lyric.number  s    . ||rT   c                \    [         R                  " U5      (       d  [        S5      eXl        g )NzNumber best be number)r   isIntrK   rf   r   s     rH   ru   r     s"    ||E"" !899rT   c                   [        U[        5      (       d  [        U5      nUSL a>  UR                  S5      (       a(  UR                  S5      (       d  USS U l        SU l        gUSL a>  UR                  S5      (       d(  UR                  S5      (       a  USS U l        SU l        gUSL a>  UR                  S5      (       a(  UR                  S5      (       a  USS U l        SU l        gXl        U R
                  b  U(       d  S	U l        gg)
a|  
Given a setting for rawText and applyRaw,
sets the syllabic type for a lyric based on the rawText.  Useful for
parsing raw text from, say, an OMR score.  Or just to quickly set text
and syllabic.

>>> l = note.Lyric()
>>> l.setTextAndSyllabic('hel-')
>>> l.text
'hel'
>>> l.syllabic
'begin'
>>> l.setTextAndSyllabic('-lo')
>>> l.text
'lo'
>>> l.syllabic
'end'
>>> l.setTextAndSyllabic('the')
>>> l.text
'the'
>>> l.syllabic
'single'

If applyRaw is True then this will assume you actually want hyphens
in the text, and if syllabic is None, sets it to 'single'

>>> l = note.Lyric()
>>> l.setTextAndSyllabic('hel-', applyRaw=True)
>>> l.text
'hel-'
>>> l.syllabic
'single'

If applyRaw is True, other syllabic settings except None are retained

>>> l.syllabic = 'begin'
>>> l.setTextAndSyllabic('-lo', applyRaw=True)
>>> l.text
'-lo'
>>> l.syllabic
'begin'

This method wipes out components.
Fr   ro   Nr^   r   r\   r_   r]   )r   strrD   endswithrw   rl   )rv   r   rk   s      rH   rt   Lyric.setTextAndSyllabic  s    ^ '3'''lG u!3!3C!8!8AQAQRUAVAVDI!DMw'9'9#'>'>7CSCSTWCXCXDI#DM7#5#5c#:#:w?O?OPS?T?T"DI$DMI}}$H ( -5rT   )
re   rf   rg   rh   ri   rj   rm   ru   rl   rw   )rp   ro   )
rw   r   ru   intrk   r   rl   rB   rm   
str | Nonereturnr   r   r   )r   r   )r   rB   )r   rB   )r   z	str | int)r   r   )r   r   )r   r   )r   r   r   None)F)r   r   rk   r   r   r   )rO   rP   rQ   rR   __doc__r   TextStylePlacement_styleClass	__slots__rs   r|   propertyr   rw   setterrl   rm   r   ru   rt   rS   __classcell__ry   s   @rH   rc   rc      sq   FN **KI   % #(-1(,%%%  	%
 +% &% %<
 % % & &P 
[[ 
 " "6 __% % $ $6 ! ! 8 8v ^^: :  0 ]] ?) ?)rT   rc   c                    ^  \ rS rSr% SrSrSrSr\R                  r
S\S'   SrS\S'   S	S
/rSSSSS.rS\S'   SSS.   S'U 4S jjjrU 4S jrU 4S jr\S(S j5       r\R(                  S)S j5       r\S*S j5       r\R(                  S+S j5       r S,SSS. S-S jjjrS.SSS.S jjr\S/S j5       r\S0S  j5       r\R(                  S1S! j5       rSS".S# jrSSS$.S% jrS&rU =r$ )2GeneralNotei/  a7  
A GeneralNote object is the base class object
for the :class:`~music21.note.Note`,
:class:`~music21.note.Rest`, :class:`~music21.chord.Chord`,
and related objects.

Keywords can be passed to
a GeneralNote which are then passed to the
underlying :class:`~music21.duration.Duration`.
These keywords might be listed like
type='16th', dots=2 etc. to create a
double-dotted sixteenth note.

In almost every circumstance, you should
create note.Note() or note.Rest() or chord.Chord()
objects directly, and not use this underlying
structure.

>>> gn = note.GeneralNote(type='16th', dots=2)
>>> gn.quarterLength
0.4375

**Equality**

GeneralNote objects are equal if they pass superclass tests (e.g., their durations are equal),
and they have the same articulation and expression classes (in any order),
and their ties are equal.
Fztype[style.Style]r   r   tuple[str, ...]equalityAttributesdurationquarterLengthz=Boolean read-only value describing if this object is a Chord.z/A list of :class:`~music21.note.Lyric` objects.za list of expressions (such
            as :class:`~music21.expressions.Fermata`, etc.)
            that are stored on this Note.zya list of articulations such
            as :class:`~music21.articulations.Staccato`, etc.) that are stored on this Note.)isChordlyricsr   r   dict[str, str]	_DOC_ATTRN)r   lyricc               f  > Uci  U(       a  SU;  a  SU;  a  [        S5      nOL[        S0 UD6nSU;   a  US	 SU;   a  US	 UR                  S:X  a  UR                  5       (       d  SUl        OUn[        TU ]  " SSU0UD6  / U l        / U l        / U l        Ub  U R                  U5        S U l	        g )Ntyper   g      ?r   r   rM   )
r   r   currentComponentsrr   rs   r   r   r   addLyric_tie)rv   r   r   rx   tempDurationry   s        rH   rs   GeneralNote.__init___  s     h 6?RZ;Z'}'3(3"h. 1X% ( !..!3 , > > @ @14L.#L;,;(;#%9;?AMM%  #'	rT   c                N  > [         TU ]  U5      (       d  gS H  n[        X5       Vs/ s H  n[        U5      PM     nn[        X5       Vs/ s H  n[        U5      PM     nn[	        U5      [	        U5      :w  a    g[        U5      [        U5      :w  d  M    g   gs  snf s  snf )NF)r   r   T)rr   __eq__getattrr   lenset)rv   r+   searchr4   my_art_express_classesother_art_express_classesry   s         rH   r   GeneralNote.__eq__  s    w~e$$ 5F7>t7L%M7L!d1g7L"%M:A%:P(Q:PQa:P%(Q)*c2K.LL)*c2K.LL 5  &N(Qs   BB"c                    > [         TU ]  5       $ r   )rr   __hash__)rv   ry   s    rH   r   GeneralNote.__hash__  s    w!!rT   c                    U R                   $ )z
Return and set a :class:`~music21.note.Tie` object, or None.

>>> n = note.Note()
>>> n.tie is None
True
>>> n.tie = tie.Tie('start')
r   r   s    rH   r   GeneralNote.tie  s     yyrT   c                    Xl         g r   r   r   s     rH   r   r     s    	rT   c                    U R                   (       d  gU R                    Vs/ s H  oR                  PM     nnSR                  U Vs/ s H	  o3c  M  UPM     sn5      $ s  snf s  snf )a  
The lyric property can
be used to get and set a lyric for this
Note, Chord, or Rest. This is a simplified version of the more general
:meth:`~music21.note.GeneralNote.addLyric` method.

>>> a = note.Note('A4')
>>> a.lyrics
[]
>>> a.lyric = 'hel-'
>>> a.lyric
'hel'
>>> a.lyrics
[<music21.note.Lyric number=1 syllabic=begin text='hel'>]

Eliminate Lyrics by setting a.lyric to None

>>> a.lyric = None
>>> a.lyric
>>> a.lyrics
[]

Set multiple lyrics with \n separated text:

>>> a.lyric = '1. Hi\n2. Bye'
>>> a.lyric
'1. Hi\n2. Bye'
>>> a.lyrics
[<music21.note.Lyric number=1 syllabic=single text='1. Hi'>,
 <music21.note.Lyric number=2 syllabic=single text='2. Bye'>]


You can also set a lyric with a lyric object directly:

>>> b = note.Note('B5')
>>> ly = note.Lyric('bon-')
>>> b.lyric = ly
>>> b.lyrics
[<music21.note.Lyric number=1 syllabic=begin text='bon'>]
>>> b.lyric
'bon'

* Changed in v6.7: added setting to a Lyric object.  Removed undocumented
  setting to False instead of setting to None
N
)r   rw   join)rv   lyallTexttextStrs       rH   r   GeneralNote.lyric  sO    ^ {{%)[[1[r77[1yyPg'PQQ 2Ps   AA#A#c                P   / U l         Uc  g [        U[        5      (       a  U R                   R                  U5        g [        U[        5      (       d  [	        U5      nUR                  S5      n[        U5       H*  u  p4U R                   R                  [        XCS-   S95        M,     g )Nr   ro   )ru   )r   r   rc   appendr   split	enumerate)rv   r   valuesivs        rH   r   r     s    =eU##KKu%%%%JET"f%DAKKuQ1u56 &rT   )rk   lyricIdentifierc          	     r   [        U[        5      (       d  [        U5      nUc<  [        U R                  5      S-   nU R                  R	                  [        XX4S95        gSnU R                   H  nUR                  U:X  d  M  Xl        Sn  O   USL a$  U R                  R	                  [        XX4S95        gg)a  
Adds a lyric, or an additional lyric, to a Note, Chord, or Rest's lyric list.
If `lyricNumber` is not None, a specific line of lyric text can be set.
The lyricIdentifier can also be set.

>>> n1 = note.Note()
>>> n1.addLyric('hello')
>>> n1.lyrics[0].text
'hello'
>>> n1.lyrics[0].number
1

An added option gives the lyric number, not the list position

>>> n1.addLyric('bye', 3)
>>> n1.lyrics[1].text
'bye'
>>> n1.lyrics[1].number
3
>>> for lyr in n1.lyrics:
...     print(lyr.text)
hello
bye

Replace an existing lyric by specifying the same number:

>>> n1.addLyric('ciao', 3)
>>> n1.lyrics[1].text
'ciao'
>>> n1.lyrics[1].number
3

Giving a lyric with a hyphen at either end will set whether it
is part of a multisyllable word:

>>> n1.addLyric('good-')
>>> n1.lyrics[2].text
'good'
>>> n1.lyrics[2].syllabic
'begin'

This feature can be overridden by specifying the keyword only argument "applyRaw=True":

>>> n1.addLyric('-5', applyRaw=True)
>>> n1.lyrics[3].text
'-5'
>>> n1.lyrics[3].syllabic
'single'
Nro   rk   rm   FT)r   r   r   r   r   rc   ru   rw   )rv   rw   lyricNumberrk   r   	maxLyrics
foundLyric	thisLyrics           rH   r   GeneralNote.addLyric  s    n $$$t9DDKK(1,IKKuT.6 T U J![[	##{2%)N!%J	 )
 U"""52:$X Y #rT   r   c          
         [        U[        5      (       d  [        U5      nU R                  US  H  nU=R                  S-  sl        M     U R                  R	                  U[        XS-   X4S95        g)aJ  
Inserts a lyric into the Note, Chord, or Rest's lyric list in front of
the index specified (0 by default), using index + 1 as the inserted lyric's
line number. shifts line numbers of all following lyrics in list

>>> n1 = note.Note()
>>> n1.addLyric('second')
>>> n1.lyrics
[<music21.note.Lyric number=1 syllabic=single text='second'>]
>>> n1.insertLyric('first', 0)
>>> n1.lyrics
[<music21.note.Lyric number=1 syllabic=single text='first'>,
 <music21.note.Lyric number=2 syllabic=single text='second'>]

OMIT_FROM_DOCS

test inserting in the middle.

>>> n1.insertLyric('newSecond', 1)
>>> n1.lyrics
[<music21.note.Lyric number=1 syllabic=single text='first'>,
 <music21.note.Lyric number=2 syllabic=single text='newSecond'>,
 <music21.note.Lyric number=3 syllabic=single text='second'>]

Test number as lyric:

>>> n1.insertLyric(0, 3)
>>> n1.lyrics
[<music21.note.Lyric number=1 syllabic=single text='first'>,
 <music21.note.Lyric number=2 syllabic=single text='newSecond'>,
 <music21.note.Lyric number=3 syllabic=single text='second'>,
 <music21.note.Lyric number=4 syllabic=single text='0'>]
Nro   r   )r   r   r   ru   insertrc   )rv   rw   indexrk   rm   r   s         rH   insertLyricGeneralNote.insertLyric;  sd    D $$$t9D[[(ELLAL )5%qy19#R 	SrT   c                     U R                   S   $ )Nr   )classesr   s    rH   fullNameGeneralNote.fullNameg  s    ||ArT   c                    g)zh
Returns an empty tuple.  (Useful for iterating over GeneralNotes since they
include Notes and Chords.)
rM   rM   r   s    rH   pitchesGeneralNote.pitchesk  s     rT   c                    g r   rM   )rv   _values     rH   r   r   s  s    rT   inPlacec                   US:  d  [        S5      eU(       a  U nO[        R                  " U 5      nUR                  R	                  U5      Ul        U(       d  U$ g)a  
Given a scalar greater than zero, return a Note with a scaled Duration.
If `inPlace` is True, this is done in-place and the method returns None.
If `inPlace` is False [default], this returns a modified deepcopy.

* Changed in v5: inPlace is now False.

>>> n = note.Note('g#')
>>> n.quarterLength = 3
>>> n.augmentOrDiminish(2, inPlace=True)
>>> n.quarterLength
6.0

>>> c = chord.Chord(['g#', 'a#', 'd'])
>>> c.quarterLength = 2
>>> c.augmentOrDiminish(0.25, inPlace=True)
>>> c.quarterLength
0.5

>>> n = note.Note('g#')
>>> n.augmentOrDiminish(-1)
Traceback (most recent call last):
music21.note.NoteException: scalar must be greater than zero

>>> n = note.Note()
>>> n.quarterLength = 3
>>> n2 = n.augmentOrDiminish(1/3, inPlace=False)
>>> n2.quarterLength
1.0
>>> n.quarterLength
3.0
r   z scalar must be greater than zeroN)rW   r@   deepcopyr   augmentOrDiminish)rv   scalarr   posts       rH   r   GeneralNote.augmentOrDiminishy  sQ    B z BCCD==&D 77?KrT   )appoggiaturar   c                   USL a  [         R                  " U 5      nOU nUR                  R                  US9Ul        USL a  U$ g)az  
Return a grace version of this GeneralNote

>>> n = note.Note('G4', quarterLength=2)
>>> n.duration.quarterLength
2.0
>>> n.duration.isGrace
False
>>> n.duration
<music21.duration.Duration 2.0>
>>> n.duration.type
'half'
>>> n.duration.components
(DurationTuple(type='half', dots=0, quarterLength=2.0),)

>>> ng = n.getGrace()
>>> ng.duration.quarterLength
0.0
>>> ng.duration.isGrace
True
>>> ng.duration
<music21.duration.GraceDuration unlinked type:half quarterLength:0.0>
>>> ng.duration.type
'half'
>>> ng.duration.components
(DurationTuple(type='half', dots=0, quarterLength=0.0),)

Appoggiaturas are still a work in progress.

* Changed in v6: corrected spelling of `appoggiatura` keyword.

>>> ng2 = n.getGrace(appoggiatura=True)
>>> ng2.duration
<music21.duration.AppoggiaturaDuration unlinked type:half quarterLength:0.0>
>>> ng2.duration.slash
False

Set inPlace to True to change the duration element on the Note.  This can have
negative consequences if the Note is in a stream.

>>> r = note.Rest(quarterLength=0.5)
>>> r.getGrace(inPlace=True)
>>> r.duration
<music21.duration.GraceDuration unlinked type:eighth quarterLength:0.0>
F)r  N)r@   r   r   getGraceDuration)rv   r  r   es       rH   getGraceGeneralNote.getGrace  sK    \ ed#AAZZ00l0K
eH rT   )r   r   r   r   )r   zDuration | Noner   zNone | str | Lyric)r   tie.Tie | None)r   r	  )r   r   )r   zstr | Lyric | Noner   r   r   )r   r   )r   r   r   ztuple[Pitch, ...])r   Iterable[Pitch]r   r   )rO   rP   rQ   rR   r   isNoteisRestr   r   	NoteStyler   __annotations__r   rA   r   rs   r   r   r   r   r   r   r   r   r   r   r   r  rS   r   r   s   @rH   r   r   /  s   8 FFG%*__K"4*22 o.J SC-`!I~  ,0)-#'(#' '#' #'J(" 	 	 	ZZ  2R 2Rh \\7 7& "FY  !%FY
 +/FYP'SUt 'SX     ^^ 
 49 /d (-e 6 6rT   r   c                  |  ^  \ rS rSr% SrSS0rS\S'   SrS\S	'   S
S
S.   S%U 4S jjjr S&S
S.     S'U 4S jjjjr	S&S jr
\S(S j5       r\R                  S)S j5       r\S(S j5       r\R                  S 5       r\S*S j5       r\R                  S+S j5       r\S,S j5       r\R                  S-S j5       rS,S jr S&   S.S jjrS/S0S jjr\S1S j5       r\R                  S0S j5       r\S2S j5       r\R                  S3S j5       r\SS .   S4S! jj5       r\    S5S" j5       rSS .   S6S# jjrS$rU =r$ )7r   i  ah  
Parent class for Note-like objects that are not rests; that is to say
they have a stem, can be tied, and volume is important.
Basically, that's a :class:`Note` or :class:`~music21.chord.Chord`
(or their subclasses such as :class:`~music21.harmony.ChordSymbol`), or
:class:`Unpitched` object.

NotRest elements are generally not created on their own.  It is a class
that exists to store common functionality used by Note, Unpitched, and Chord objects.

>>> nr = note.NotRest(storedInstrument=instrument.Ocarina())
>>> nr.stemDirection = 'up'

* Changed in v9: beams is keyword only.  Added storedInstrument keyword.
beamszx
            A :class:`~music21.beam.Beams` object that contains
            information about the beaming of this note.r   r   )noteheadnoteheadFillnoteheadParenthesisr  r   r   N)r  storedInstrumentc                  > [         TU ]  " S0 UD6  SU l        S U l        SU l        SU l        S U l        Ub  Xl        O[        R                  " 5       U l        X l
        S U l        g )Nr*   Fr8   rM   )rr   rs   	_notehead_noteheadFill_noteheadParenthesis_stemDirection_volumer  r   Beams_storedInstrument_chordAttached)rv   r  r  rx   ry   s       rH   rs   NotRest.__init__  sa    
 	$8$&(,*/!#0+/JDJ=M48rT   ignoreAttributesc                  > [         TU ]  US1S9n[        R                  (       a  [        R                  " [
        U5      nU R                  5       (       a  X3R                  l        U$ )Nr  r   )	rr   _deepcopySubclassabler=   r   castr   hasVolumeInformationr   client)rv   memor!  newry   s       rH   r#  NotRest._deepcopySubclassable  sT     g+DDTCU+V??&&s+C
 $$&& #JJ
rT   c                     U R                  US9$ )a,  
As NotRest objects have a Volume, objects, and Volume objects
store refs to the client object, need to specialize deepcopy handling

>>> import copy
>>> n = note.NotRest()
>>> n.volume = volume.Volume(velocity=50)
>>> m = copy.deepcopy(n)
>>> m.volume.client is m
True
>>> n.volume.client is n
True
)r'  )r#  )rv   r'  s     rH   __deepcopy__NotRest.__deepcopy__(  s     ))t)44rT   c                    U R                   $ )aA  
Get or set the stem direction of this NotRest object.
Valid stem direction names are found in note.stemDirectionNames (see below).

>>> note.stemDirectionNames
('double', 'down', 'noStem', 'none', 'unspecified', 'up')
>>> n = note.Note()

By default, a Note's stemDirection is 'unspecified'
meaning that it is unknown:

>>> n.stemDirection
'unspecified'

>>> n.stemDirection = 'noStem'
>>> n.stemDirection
'noStem'

The alias 'none' (the string) is the same as 'noStem'

>>> n.stemDirection = 'none'
>>> n.stemDirection
'noStem'

>>> n.stemDirection = 'junk'
Traceback (most recent call last):
music21.note.NotRestException: not a valid stem direction name: junk

Stem direction can be set explicitly to None to remove
any prior stem information, same as 'unspecified':

>>> n.stemDirection = None
>>> n.stemDirection
'unspecified'
)r  r   s    rH   stemDirectionNotRest.stemDirection:  s    J """rT   c                ^    Uc  SnO!US:X  a  SnOU[         ;  a  [        SU 35      eXl        g )Nr8   r)   r7   z!not a valid stem direction name: )stemDirectionNamesrZ   r  )rv   	directions     rH   r.  r/  a  s<    %I&  I00"%Fyk#RSS'rT   c                    U R                   $ )a  
Get or set the notehead type of this NotRest object.
Valid notehead type names are found in note.noteheadTypeNames (see below):


>>> note.noteheadTypeNames
('arrow down', 'arrow up', 'back slashed', 'circle dot', 'circle-x', 'circled', 'cluster',
 'cross', 'diamond', 'do', 'fa', 'fa up', 'inverted triangle', 'la', 'left triangle',
 'mi', 'none', 'normal', 'other', 're', 'rectangle', 'slash', 'slashed', 'so',
 'square', 'ti', 'triangle', 'x')
>>> n = note.Note()
>>> n.notehead = 'diamond'
>>> n.notehead
'diamond'

>>> n.notehead = 'junk'
Traceback (most recent call last):
music21.note.NotRestException: not a valid notehead type name: 'junk'
)r  r   s    rH   r  NotRest.noteheadk  s    * ~~rT   c                T    US;   a  S nOU[         ;  a  [        SU< 35      eXl        g )N)r)   Nrp   z not a valid notehead type name: )noteheadTypeNamesrZ   r  r   s     rH   r  r4    s1    &&E++"%EeY#OPPrT   c                    U R                   $ )a  
Get or set the note head fill status of this NotRest. Valid note head fill values are
True, False, or None (meaning default).  "yes" and "no" are converted to True
and False.

>>> n = note.Note()
>>> n.noteheadFill = 'no'
>>> n.noteheadFill
False
>>> n.noteheadFill = 'filled'
>>> n.noteheadFill
True

>>> n.noteheadFill = 'jelly'
Traceback (most recent call last):
music21.note.NotRestException: not a valid notehead fill value: 'jelly'
)r  r   s    rH   r  NotRest.noteheadFill  s    & !!!rT   c                d    US;   a  S nO!US;   a  SnOUS;   a  SnO[        SU< 35      eX l        g )N)r)   Ndefault)TfilledyesT)F	notfillednoFz!not a valid notehead fill value: )rZ   r  rv   r   	boolValues      rH   r  r8    sG     --I--I00I"%Fui#PQQ&rT   c                    U R                   $ )a  
Get or set the note head parentheses for this Note/Unpitched/Chord object.

>>> n = note.Note()
>>> n.noteheadParenthesis
False
>>> n.noteheadParenthesis = True
>>> n.noteheadParenthesis
True

'yes' or 1 equate to True; 'no' or 0 to False

>>> n.noteheadParenthesis = 'no'
>>> n.noteheadParenthesis
False

Anything else raises an exception:

>>> n.noteheadParenthesis = 'blah'
Traceback (most recent call last):
music21.note.NotRestException: notehead parentheses must be True or False, not 'blah'
)r  r   s    rH   r  NotRest.noteheadParenthesis  s    0 (((rT   c                R    US;   a  SnOUS;   a  SnO[        SU< 35      eX l        g )N)Tr<  ro   T)Fr>  r   Fz0notehead parentheses must be True or False, not )rZ   r  r?  s      rH   r  rB    s;     $$I&&I"%UV[U^#_``$-!rT   c                     U R                   c  gg)a4  
Returns bool whether volume was set -- saving some time for advanced
users (such as MusicXML exporters) that only want to look at the volume
if it is already there.

>>> n = note.Note()
>>> n.hasVolumeInformation()
False
>>> n.volume
 <music21.volume.Volume realized=0.71>
>>> n.hasVolumeInformation()
True
FT)r  r   s    rH   r%  NotRest.hasVolumeInformation  s     <<rT   c                    U R                   c6  Uc  [        R                  " U S9U l         O[        R                  " US9U l         U R                   n[        R                  (       a  Uc   eU$ )N)r&  )r  r   Volumer=   r   )rv   forceClient
volume_outs      rH   
_getVolumeNotRest._getVolume  sV    
 <<"%}}D9%}}K@\\
??)))rT   Tc                   Uc  S U l         g [        U[        R                  5      (       a7  U(       a)  UR                  b  [
        R                  " U5      nXl        Xl         g [        R                  " U5      (       a?  U(       a8  U R                  5       nUS:  a  [        U5      Ul        g [        U5      Ul        g [        SU 35      e)Nro   z"this must be a Volume object, not )r  r   r   rG  r&  r@   r   r   isNumrJ  floatvelocityScalarr   velocity	TypeError)rv   r   	setClientvols       rH   
_setVolumeNotRest._setVolume  s     =DLv}}--<<+ MM%0E# L\\%  Y //#Cqy%*5\""5z @HIIrT   c                "    U R                  5       $ )aP  
Get and set the :class:`~music21.volume.Volume` object of this object.
Volume objects are created on demand.

>>> n1 = note.Note()
>>> n1.volume.velocity = 120
>>> n2 = note.Note()
>>> n2.volume = 80  # can directly set a velocity value
>>> s = stream.Stream()
>>> s.append([n1, n2])
>>> [n.volume.velocity for n in s.notes]
[120, 80]
)rJ  r   s    rH   r   NotRest.volume  s       rT   c                &    U R                  U5        g r   )rT  r   s     rH   r   rW    s    rT   c                    U R                   $ )a  
Get or set the :class:`~music21.instrument.Instrument` that
should be used to play this note, overriding whatever
Instrument object may be active in the Stream. (See
:meth:`getInstrument` for a means of retrieving `storedInstrument`
if available before falling back to a context search to find
the active instrument.)

>>> snare = note.Unpitched()
>>> snare.storedInstrument = instrument.SnareDrum()
>>> snare.storedInstrument
<music21.instrument.SnareDrum 'Snare Drum'>
>>> snare
<music21.note.Unpitched 'Snare Drum'>
)r  r   s    rH   r  NotRest.storedInstrument#  s    " %%%rT   c                    Ub8  [        US5      (       a  SUR                  ;  a  [        S[        U5       35      eXl        g )NclassSetzmusic21.instrument.InstrumentzExpected Instrument; got )hasattrr\  rQ  r   r  )rv   newValues     rH   r  rZ  6  sA      :667x?P?PP7X7GHII!)rT   )returnDefaultc                   g r   rM   rv   r_  s     rH   getInstrumentNotRest.getInstrument>      
 	rT   c                   g r   rM   ra  s     rH   rb  rc  E  rd  rT   c                   SSK Jn  U R                  b  U R                  $ U R                  UR                  SS9nU(       a  Uc  UR                  " 5       $ Uc  g[
        R                  " UR                  U5      $ )a  
Retrieves the `.storedInstrument` on this `NotRest` instance, if any.
If one is not found, executes a context search (without following
derivations) to find the closest (i.e., active) instrument in the
stream hierarchy.

Returns a default instrument if no instrument is found in the context
and `returnDefault` is True (default).

>>> n = note.Note()
>>> m = stream.Measure([n])
>>> n.getInstrument(returnDefault=False) is None
True
>>> dulcimer = instrument.Dulcimer()
>>> m.insert(0, dulcimer)
>>> n.getInstrument() is dulcimer
True

Overridden `.storedInstrument` is privileged:

>>> picc = instrument.Piccolo()
>>> n.storedInstrument = picc
>>> n.getInstrument() is picc
True

Instruments in containing streams ARE found:

>>> n.storedInstrument = None
>>> m.remove(dulcimer)
>>> p = stream.Part([m])
>>> p.insert(0, dulcimer)
>>> n.getInstrument() is dulcimer
True

But not if the instrument is only found in a derived stream:

>>> derived = p.stripTies()
>>> p.remove(dulcimer)
>>> derived.getInstruments().first()
<music21.instrument.Dulcimer 'Dulcimer'>
>>> n.getInstrument(returnDefault=False) is None
True

Electing to return a default generic `Instrument`:

>>> n.getInstrument(returnDefault=True)
<music21.instrument.Instrument ''>
r   r   NF)followDerivation)music21r   r  getContextByClass
Instrumentr=   r$  )rv   r_  r   instrument_or_nones       rH   rb  rc  L  sz    h 	'  ,(((!33!!E 4 ;/7((**'vvj++-?@@rT   )r  r  r  r  r  r  r  r  )r  zbeam.Beams | Noner  instrument.Instrument | Noner   )rv   r   r'  zdict[int, t.Any] | Noner!  zset[str] | Noner   r   r   )r2  z
None | str)r   zbool | None)r   zbool | None | strr   )r   zbool | str | int)rH  zNotRest | Noner   volume.Volume)T)r   z"None | volume.Volume | int | float)r   rm  )r   rl  )r^  rl  )r_  zt.Literal[True]r   zinstrument.Instrument)r_  zt.Literal[False]r   rl  )r_  r   r   rl  )rO   rP   rQ   rR   r   r   r  r   rs   r#  r+  r   r.  r   r  r  r  r%  rJ  rT  r   r  r   rb  rS   r   r   s   @rH   r   r     s>   & 	 ;!I~ +  +/@D9'9 $>9 9. =A AE$9 1> JV 5$ $# $#L ( (  , __  " "( 
' 
' ) )2 .  .( 04 ,%$J. ! !  ]]  & &$ * *  8<%4 1  %5 6  -1=A%)=A 6=A =ArT   c                    ^  \ rS rSr% SrSrSrS\S'   / SQrSS	S
S.r	S\S'    S'SSS.     S(U 4S jjjjr
S rS rS rS rS rS'S)S jjr\S*S j5       r\R&                  S+S j5       r\S*S j5       r\R&                  S+S j5       r\S,S j5       r\R&                  S-S j5       r\S.S j5       r\R&                  S/S j5       r\S0S j5       r\R&                  S1S  j5       rS!S".S# jr\S*S$ j5       rS% rS&rU =r$ )2Notei  a  
One of the most important music21 classes, a Note
stores a single note (that is, not a rest or an unpitched element)
that can be represented by one or more notational units -- so
for instance a C quarter-note and a D# eighth-tied-to-32nd are both
a single Note object.

A Note knows both its total duration and how to express itself as a set of
tied notes of different lengths. For instance, a note of 2.5 quarters in
length could be half tied to eighth or dotted quarter tied to quarter.

The first argument to the Note is the pitch name (with or without
octave, see the introduction to :class:`music21.pitch.Pitch`).
Further arguments can be specified as keywords (such as type, dots, etc.)
and are passed to the underlying :class:`music21.duration.Duration` element.

>>> n = note.Note()
>>> n
<music21.note.Note C>
>>> n.pitch
<music21.pitch.Pitch C4>

>>> n = note.Note('B-')
>>> n.name
'B-'
>>> n.octave is None
True
>>> n.pitch.implicitOctave
4

>>> n = note.Note(name='D#')
>>> n.name
'D#'
>>> n = note.Note(nameWithOctave='D#5')
>>> n.nameWithOctave
'D#5'

Other ways of instantiating a Pitch object, such as by MIDI number or pitch class
are also possible:

>>> note.Note(64).nameWithOctave
'E4'

All keyword args that are valid for Duration or Pitch objects
are valid (as well as those for superclasses, NotRest, GeneralNote,
Music21Object):

>>> n = note.Note(step='C', accidental='sharp', octave=2, id='csharp', type='eighth', dots=2)
>>> n.nameWithOctave
'C#2'
>>> n.duration
<music21.duration.Duration 0.875>

**Equality and ordering**

Two notes are equal if they pass all the equality tests for NotRest and their
pitches are equal.

Attributes that might change based on the wider context
of a note (such as offset) are not compared. This test does not look at lyrics in
establishing equality.  (It may in the future.)

>>> note.Note('C4') == note.Note('C4')
True

Enharmonics are not equal:

>>> note.Note('D#4') == note.Note('E-4')
False

>>> note.Note('C4', type='half') == note.Note('C4', type='quarter')
False

Notes, like pitches, also have an ordering based on their pitches.

>>> highE = note.Note('E5')
>>> lowF = note.Note('F2')
>>> otherHighE = note.Note('E5')

>>> highE > lowF
True
>>> highE < lowF
False
>>> highE >= otherHighE
True
>>> highE <= otherHighE
True

Notice you cannot compare Notes w/ ints or anything that does not have a
`.pitch` attribute.

>>> highE < 50
Traceback (most recent call last):
TypeError: '<' not supported between instances of 'Note' and 'int'

Note also that two objects can be >= and <= without being equal, because
only pitch-height is being compared in <, <=, >, >= but duration and other
elements are compared in equality.

>>> otherHighE.duration.type = 'whole'

Now otherHighE is != highE

>>> highE == otherHighE
False

But it is both >= and <= it:

>>> highE >= otherHighE
True
>>> highE <= otherHighE
True

(The pigeonhole principle police have a bounty out on my head for this.)
Tpitchr   r   )r   r   nameWithOctavezABoolean read-only value describing if this Note is a Note (True).zBBoolean read-only value describing if this Note is a Rest (False).zA :class:`~music21.pitch.Pitch` object containing all the
                information about the note's pitch.  Many `.pitch` properties and
                methods are also made `Note` properties also)r  r  rq  r   r   N)namerr  c                  > [         TU ]  " S0 UD6  U   Ub.  [        U[        5      (       a  Xl        O2[        U40 UD6U l        O Ub  UnO	U(       d  Sn[        U40 UD6U l        X R                  l        g )NC4rM   )rr   rs   r   r   rq  _client)rv   rq  rs  rr  rx   ry   s        rH   rs   Note.__init__  sq     	$8$%''"
"55H5
)%t0x0DJ "

rT   c                    U R                   $ r   )rs  r   s    rH   r|   Note._reprInternal+  s    yyrT   c                b     U R                   UR                   :  $ ! [         a	    [        s $ f = fr   rq  AttributeErrorNotImplementedrv   r+   s     rH   __lt__Note.__lt__/  /    	"::++ 	"!!	"    ..c                b     U R                   UR                   :  $ ! [         a	    [        s $ f = fr   r{  r~  s     rH   __gt__Note.__gt__7  r  r  c                b     U R                   UR                   :*  $ ! [         a	    [        s $ f = fr   r{  r~  s     rH   __le__Note.__le__=  /    	"::,, 	"!!	"r  c                b     U R                   UR                   :  $ ! [         a	    [        s $ f = fr   r{  r~  s     rH   __ge__Note.__ge__C  r  r  c                H    U R                  U5      nX"R                  l        U$ )z@
After doing a deepcopy of the pitch, be sure to set the client
)r#  rq  rv  )rv   r'  r(  s      rH   r+  Note.__deepcopy__I  s#     ((.		
rT   c                .    U R                   R                  $ )z
Return or set the pitch name from the :class:`~music21.pitch.Pitch` object.
See `Pitch`'s attribute :attr:`~music21.pitch.Pitch.name`.
rq  rs  r   s    rH   rs  	Note.nameU       zzrT   c                $    XR                   l        g r   r  r   s     rH   rs  r  ]      

rT   c                .    U R                   R                  $ )z
Return or set the pitch name with octave from the :class:`~music21.pitch.Pitch` object.
See `Pitch`'s attribute :attr:`~music21.pitch.Pitch.nameWithOctave`.
rq  rr  r   s    rH   rr  Note.nameWithOctavea  s     zz(((rT   c                $    XR                   l        g r   r  r   s     rH   rr  r  i  s    $)

!rT   c                .    U R                   R                  $ )zt
Return or set the pitch step from the :class:`~music21.pitch.Pitch` object.
See :attr:`~music21.pitch.Pitch.step`.
rq  stepr   s    rH   r  	Note.stepm  r  rT   c                $    XR                   l        g r   r  r   s     rH   r  r  u  r  rT   c                .    U R                   R                  $ )zx
Return or set the octave value from the :class:`~music21.pitch.Pitch` object.
See :attr:`~music21.pitch.Pitch.octave`.
rq  octaver   s    rH   r  Note.octavey  s     zz   rT   c                $    XR                   l        g r   r  r   s     rH   r  r    s    !

rT   c                    U R                   4$ )a  
Return the single :class:`~music21.pitch.Pitch` object in a tuple.
This property is designed to provide an interface analogous to
that found on :class:`~music21.chord.Chord` so that `[c.pitches for c in s.notes]`
provides a consistent interface for all objects.

>>> n = note.Note('g#')
>>> n.nameWithOctave
'G#'
>>> n.pitches
(<music21.pitch.Pitch G#>,)

Since this is a Note, not a chord, from the list or tuple,
only the first one will be used:

>>> n.pitches = [pitch.Pitch('c2'), pitch.Pitch('g2')]
>>> n.nameWithOctave
'C2'
>>> n.pitches
(<music21.pitch.Pitch C2>,)

The value for setting must be a list or tuple:

>>> n.pitches = pitch.Pitch('C4')
Traceback (most recent call last):
music21.note.NoteException: cannot set pitches with provided object: C4

For setting a single one, use `n.pitch` instead.

Don't use strings, or you will get a string back!

>>> n.pitches = ('C4', 'D4')
>>> n.pitch
'C4'
>>> n.pitch.diatonicNoteNum
Traceback (most recent call last):
AttributeError: 'str' object has no attribute 'diatonicNoteNum'
rp  r   s    rH   r   Note.pitches  s    P 

}rT   c                x    [         R                  " U5      (       a  U(       a  US   U l        g [        SU 35      e)Nr   z)cannot set pitches with provided object: )r   
isListLikerq  rW   r   s     rH   r   r    s3    U##qDJ"KE7 STTrT   Fr   c                  SSK Jn  [        U[        R                  5      (       a  UnO[        R
                  " U5      nU(       d  [        R                  " U 5      nOU nUR                  R                  USS9  UR                  R                  b  [        U[        [        R                  45      (       a  U R                  UR                  5      nUb  UR                   H|  nUR                  R                   UR                   :X  d  M)  UR                  R                  R"                  UR                  R"                  :w  d  Mc  UR                  R%                  SS9  M~     U(       d  SUR&                  l        U$ g)aa  
Transpose the Note by the user-provided
value. If the value is an integer, the transposition is treated in half steps.

If the value is a string, any Interval string specification can be provided.

>>> a = note.Note('g4')
>>> b = a.transpose('m3')
>>> b
<music21.note.Note B->
>>> aInterval = interval.Interval(-6)
>>> b = a.transpose(aInterval)
>>> b
<music21.note.Note C#>

>>> c = b.transpose(interval.GenericInterval(2))
>>> c
<music21.note.Note D#>

>>> a.transpose(aInterval, inPlace=True)
>>> a
<music21.note.Note C#>


If the transposition value is an integer, take the KeySignature or Key context
into account

>>> s = stream.Stream()
>>> s.append(key.Key('D'))
>>> s.append(note.Note('F'))
>>> s.append(key.Key('b-', 'minor'))
>>> s.append(note.Note('F'))
>>> s.show('text')
{0.0} <music21.key.Key of D major>
{0.0} <music21.note.Note F>
{1.0} <music21.key.Key of b- minor>
{1.0} <music21.note.Note F>
>>> for n in s.notes:
...     n.transpose(1, inPlace=True)
>>> s.show('text')
{0.0} <music21.key.Key of D major>
{0.0} <music21.note.Note F#>
{1.0} <music21.key.Key of b- minor>
{1.0} <music21.note.Note G->

r   )keyTr   N	transpose)rh  r  r   r   IntervalBaseIntervalr@   r   rq  r  
accidentalr   ChromaticIntervalri  KeySignaturealteredPitches
pitchClassaltergetEnharmonic
derivationmethod)rv   r   r   r  intervalObjr  	ksContextalteredPitchs           rH   r  Note.transpose  s   ^ 	 eX2233K"++E2K==&DD 	

[$7JJ!!-usH,F,F&GHH..s/?/?@I$$-$<$<L

--1H1HH $

 5 5 ; ;|?V?V?\?\ \

000> %=
 %0DOO"KrT   c                    / nUR                  U R                  R                  S-   5        UR                  U R                  R                  5        UR                  S5        SR	                  U5      $ )a  
Return the most complete representation of this Note,
providing duration and pitch information.


>>> n = note.Note('A-', quarterLength=1.5)
>>> n.fullName
'A-flat Dotted Quarter Note'

>>> n = note.Note('E~3', quarterLength=2)
>>> n.fullName
'E-half-sharp in octave 3 Half Note'

>>> n = note.Note('D', quarterLength=0.25)
>>> n.pitch.microtone = 25
>>> n.fullName
'D (+25c) 16th Note'
rq   z Noterp   )r   rq  r   r   r   )rv   msgs     rH   r   Note.fullName  sT    ( 

4::&&,-

4==))*

7wws|rT   c                b    0 U l         U R                  b  U R                  R                  5         gg)z<
Called by the underlying pitch if something changed there.
N)_cacher  
clearCacher   s    rH   pitchChangedNote.pitchChanged  s.     ***, +rT   )r  rq  r   )rq  zstr | int | Pitch | Noners  r   rr  r   )rv   ro  r   ro  r   )r   r   )r   r   )r   r   )r   
int | None)r   r  r
  )r   r  r   r   )rO   rP   rQ   rR   r   r  r   r  rA   r   rs   r|   r  r  r  r  r+  r   rs  r   rr  r  r  r   r  r   r  rS   r   r   s   @rH   ro  ro    s   rf F*44 AJ VV@!I~  .2" #',0	"*"  " "*	" "6""""   
[[    ) ) * *   
[[    ! ! ]]" " ' 'R ^^U U +0 JX  2- -rT   ro  c                  `   ^  \ rS rSrSrSr S	 S
U 4S jjjrS rSS jr\	SS j5       r
SrU =r$ )	Unpitchedi)  aM  
A General class of unpitched objects which appear at different places
on the staff.  Examples: percussion notation.

>>> unp = note.Unpitched()

Unpitched elements have :attr:`displayStep` and :attr:`displayOctave`,
which shows where they should be displayed as if the staff were a
5-line staff in treble clef, but they do not have pitch
objects:

>>> unp.displayStep
'B'
>>> unp.displayOctave
4
>>> unp.displayStep = 'G'
>>> unp.pitch
Traceback (most recent call last):
AttributeError: 'Unpitched' object has no attribute 'pitch...

Unpitched elements generally have an instrument object associated with them:

>>> unp.storedInstrument = instrument.Woodblock()
>>> unp
<music21.note.Unpitched 'Woodblock'>

Two unpitched objects compare the same if their instrument and displayStep and
displayOctave are equal (and satisfy all the equality requirements of
their base classes):

>>> unp2 = note.Unpitched()
>>> unp == unp2
False
>>> unp2.displayStep = 'G'
>>> unp2.storedInstrument = instrument.Woodblock()
>>> unp == unp2
True
>>> unp2.storedInstrument = instrument.Triangle()
>>> unp == unp2
False
)displayStepdisplayOctaver  c                   > [         TU ]  " S0 UD6  S U l        SU l        SU l        U(       a.  [        U5      nUR                  U l        UR                  U l        g g )NB   rM   )rr   rs   r  r  r  r   r  implicitOctave)rv   displayNamerx   display_pitchry   s       rH   rs   Unpitched.__init__X  s[    
 	$8$?C%("#!+.M,11D!.!=!=D rT   c                d    U R                   (       d  g[        U R                   R                  5      $ )Nrp   )r  reprinstrumentNamer   s    rH   r|   Unpitched._reprInternalg  s%    $$--<<==rT   c                >    [        U R                  U R                  S9$ )z
returns a pitch object that is the same as the displayStep and displayOctave.
it will never have an accidental.

>>> unp = note.Unpitched()
>>> unp.displayStep = 'E'
>>> unp.displayOctave = 4
>>> unp.displayPitch()
<music21.pitch.Pitch E4>
)r  r  )r   r  r  r   s    rH   displayPitchUnpitched.displayPitchm  s     $**43E3EFFrT   c                :    U R                  5       nUR                  $ )zt
Returns the `nameWithOctave` of the :meth:`displayPitch`.

>>> unp = note.Unpitched('B2')
>>> unp.displayName
'B2'
)r  rr  )rv   r  s     rH   r  Unpitched.displayNamez  s     ))++++rT   )r  r  r  r   )r  r   )r   r   r   )rO   rP   rQ   rR   r   r   rs   r|   r  r   r  rS   r   r   s   @rH   r  r  )  sH    (X N !%>> >>G 	, 	,rT   r  c                     ^  \ rS rSr% SrSrSrSSSSS	S
.rS\S'    SSSS.     SU 4S jjjjr	S r
\SS j5       rSrU =r$ )Resti  a  
Rests are represented in music21 as GeneralNote objects that do not have
a pitch object attached to them.  By default, they have length 1.0 (Quarter Rest)

Calling :attr:`~music21.stream.Stream.notes` on a Stream does not get rests.
However, the property :attr:`~music21.stream.Stream.notesAndRests` of Streams
gets rests as well.

>>> r = note.Rest()
>>> r.isRest
True
>>> r.isNote
False
>>> r.duration.quarterLength = 2.0
>>> r.duration.type
'half'

All Rests have the name property 'rest':

>>> r.name
'rest'

And their .pitches is an empty tuple

>>> r.pitches
()


All arguments to Duration are valid in constructing:

>>> r2 = note.Rest(type='whole')
>>> r2.duration.quarterLength
4.0

Or they can just be specified in without a type, and they'll be evaluated automatically

>>> r3, r4 = note.Rest('half'), note.Rest(2.0)
>>> r3 == r4
True
>>> r3.duration.quarterLength
2.0

Two rests are considered equal if their durations are equal.

>>> r1 = note.Rest('quarter')
>>> r2 = note.Rest('quarter')
>>> r1 == r2
True
>>> r1 != r2
False

>>> r2.duration.quarterLength = 4/3
>>> r1 == r2
False

A rest is never equal to a note.

>>> r1 == note.Note()
False
TrestzBBoolean read-only value describing if this Rest is a Note (False).zLBoolean read-only value describing if this Rest is a Rest (True, obviously).znreturns "rest" always.  It is here so that you can get
               `x.name` on all `.notesAndRests` objectszJnumber of lines/spaces to shift the note upwards or downwards for display.a;  does this rest last a full measure or if it does, should it display
                itself as whole rest (or breve rest) and centered.

                Options are "auto" (default), False, True, and "always"

                "auto" is the default, where if the rest value happens to match the current
                time signature context (and there is no pickup or other padding),
                then display it as a whole rest, centered, etc. otherwise will display normally.

                False means do not display the rest as full measure whole rest,
                no matter what.  This setting is often used by composers in very small time
                signatures such as 1/8, where a whole rest can look incongruous.

                True keeps the set duration, but will always display as a full measure rest
                even if it's not the length of the measure
                (generally a whole note unless the time signature is very long).

                "always" means that on export, the duration will (EVENTUALLY, not yet!)
                update automatically to match the time signature context and always display
                as a whole rest. "always" does not work yet -- functions as True.

                See examples in :meth:`music21.musicxml.m21ToXml.MeasureExporter.restToXml`
                )r  r  rs  	stepShiftfullMeasurer   r   r   auto)r  r  c                  > Ub*  [        U[        5      (       a  SU;  a  XS'   O
SU;  a  XS'   [        TU ]  " S0 UD6  X l        X0l        g )Nr   r   rM   )r   r   rr   rs   r  r  )rv   lengthr  r  rx   ry   s        rH   rs   Rest.__init__  sR     &#&&6+A#)  0,2)$8$"&rT   c                   U R                   R                  R                  5       n[        U5      S:  a  UR	                  SS5      $ U R                   R
                  nU[        U5      :X  a  [        U5      n[        U5      nU S3$ )N   rq   r   ql)r   r   lowerr   replacer   r   r   )rv   duration_namer  	ql_strings       rH   r|   Rest._reprInternal  ss    ..446}" ((c22,,BSW}WBI[##rT   c                4    U R                   R                  S-   $ )z
Return the most complete representation of this Rest,
providing duration information.

>>> r = note.Rest(quarterLength=1.5)
>>> r.fullName
'Dotted Quarter Rest'

>>> note.Rest(type='whole').fullName
'Whole Rest'
z Rest)r   r   r   s    rH   r   Rest.fullName  s     }}%%//rT   )r  r  r   )r  zstr | OffsetQLIn | Noner  r   r  z(t.Literal[True, False, 'auto', 'always']r   )rO   rP   rQ   rR   r   r  rs  r   r  rs   r|   r   r   rS   r   r   s   @rH   r  r    s    ;x FD W`;a!I~ @ 04' #$IO	','  ' G	' ' 	$ 0 0rT   r  c                  (    \ rS rSrSrSrS rS rSrg)TestExternali  zA
These are tests that open windows and rely on external software
Tc                    SSK Jn  UR                  S5      nSUl        U R                  (       a  UR	                  5         gg)z.
Need to test direct note creation w/o stream
r   r    zD-3g      @N)rh  r    ro  r   show)rv   r    as      rH   
testSingleTestExternal.testSingle  s1     	!IIe99FFH rT   c                   SSK Jn  SSK Jn  UR                  5       nS HC  u  pEUR	                  5       nXVl        XFl        SUR                  l        UR                  U5        ME     U R                  (       a  UR                  5         g g )Nr   r  )stream)zd-3g      @zc#6g      
@za--5g      ?)f      ?)g3g      ?)zd##4g      ?r  r  r  )zf#2r  )zg-3gUUUUUU?)zd#6gUUUUUU?z#FF00FF)rh  r    r  Streamro  r   rs  r   colorr   r  )rv   r    r  r  	pitchNameqLenbs          rH   	testBasicTestExternal.testBasic%  se     "MMO "OI
 		A"OF%AGGMHHQK " 99FFH rT   rM   N)	rO   rP   rQ   rR   r   r  r  r  rS   rM   rT   rH   r  r    s     DrT   r  c                      \ rS rSrS rSrg)r<   i;  c                2    SSK Jn  U" U [        5       5        g )Nr   )testCopyAll)music21.test.commonTestr  rC   )rv   r  s     rH   testCopyAndDeepcopyTest.testCopyAndDeepcopy<  s    7D')$rT   rM   N)rO   rP   rQ   rR   r  rS   rM   rT   rH   r<   r<   ;  s    %rT   r<   __main__)Cr   
__future__r   r@   typingr=   r   r>   rh  r   r   r   music21.durationr   r	   r
   r   r   music21.pitchr   r   r   r   r   r   collections.abcr   r   music21.common.typesr   r   r   r   r   r   music21.styler   TypeVarr   Environmentr?   r6  r1  rI   Music21ExceptionrK   rW   rZ   LiteralrB   ra   r  ProtoM21Object
StyleMixinrc   Music21Objectr   r   ro  r  r  TestCaser  r<   rA   rO   mainTestrM   rT   rH   <module>r     s   #        %          ??29%""#99^9=L&&v. > :	\22 		L11 		|44 	
 ))QR+ ' 
\)G""E$4$4 \)Dr$$$ rldAk dAPU-7 U-x[, [,~G0; G0Z"8$$ "L%8 % D)Wk5A
zT rT   