
    rh                       S r SSKJr  SSK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 S	 jjr  S     S S
 jjr  S     S S jjrS!S jrS!S jrS"S jrS"S jrS"S jrS"S jrS!S jrS!S jrS"S jrS"S jrS rS rS#S jr    S$S jr\\\\\\\\\\\\\/r " S S\R<                  5      r " S S\R@                  5      r!\"S:X  a  SSKr\RF                  " \!5        gg)%al  
.. note:: The terminology, V43, viio, iv, etc. are explained elsewhere,
     such as *The Music Theory Handbook* by Marjorie Merryman.

This module contains methods which can properly resolve
`dominant seventh <https://en.wikipedia.org/wiki/Dominant_seventh_chord>`_,
`diminished seventh <https://en.wikipedia.org/wiki/Diminished_seventh_chord>`_, and
`augmented sixth <https://en.wikipedia.org/wiki/Augmented_sixth_chord>`_
chords expressed as possibilities (See :mod:`~music21.figuredBass.possibility`).
Although these methods can stand alone, they are speed-enhanced for instances
of :class:`~music21.figuredBass.segment.Segment`, where there are many
possibilities formed around the same chord. If provided with additional
arguments, the methods only :meth:`~music21.pitch.Pitch.transpose` each
:class:`~music21.pitch.Pitch` in a possibility by the appropriate interval.
    )annotationsN)exceptions21)chord)note)pitch)streamc                  ^^^^^	 Uc  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nTcg  UR                  5       (       a  [        S5      eUR                  5       (       a  SmO/UR                  5       (       a  SmOUR                  5       (       a  Sm[        R                  (       a  Uc   eTS;   a	  Uu  mmm	nmOTS:X  a	  Uu  mm	nmmO[        ST< 35      e[        R                  (       a  [        T[        R                  5      (       d   e[        T	[        R                  5      (       d   e[        T[        R                  5      (       d   e[        T[        R                  5      (       d   eU4S jS	4U	4S
 jS4U4S jS	4UU4S jS4UU4S jS	4/n[        X5      $ )a  
Resolves French (augSixthType = 1), German (augSixthType = 2), and Swiss (augSixthType = 3)
augmented sixth chords to the root position dominant triad.

Proper Italian augmented sixth resolutions not supported within this method.

>>> from music21.figuredBass import resolution
>>> Bb2 = pitch.Pitch('B-2')
>>> D4 = pitch.Pitch('D4')
>>> E4 = pitch.Pitch('E4')
>>> Es4 = pitch.Pitch('E#4')
>>> F4 = pitch.Pitch('F4')
>>> G4 = pitch.Pitch('G4')
>>> Gs4 = pitch.Pitch('G#4')
>>> iv6 = (G4, D4, D4, Bb2)
>>> itAug6 = (Gs4, D4, D4, Bb2)
>>> frAug6 = (Gs4, E4, D4, Bb2)
>>> grAug6 = (Gs4, F4, D4, Bb2)
>>> swAug6 = (Gs4, Es4, D4, Bb2)

>>> frRes = resolution.augmentedSixthToDominant(frAug6)
>>> frRes
(<music21.pitch.Pitch A4>, <music21.pitch.Pitch E4>,
 <music21.pitch.Pitch C#4>, <music21.pitch.Pitch A2>)
>>> [str(p) for p in frRes]
['A4', 'E4', 'C#4', 'A2']

>>> grRes = resolution.augmentedSixthToDominant(grAug6)
>>> [str(p) for p in grRes]
['A4', 'E4', 'C#4', 'A2']

>>> swRes = resolution.augmentedSixthToDominant(swAug6)
>>> [str(p) for p in swRes]
['A4', 'E4', 'C#4', 'A2']
>>> #_DOCS_SHOW resolution.showResolutions(frAug6, frRes, grAug6, grRes, swAug6, swRes)

    .. image:: images/figuredBass/fbResolution_a6toV.*
        :width: 700


Above: French, German, and Swiss resolutions, respectively.
,Possibility is not an augmented sixth chord.@Italian augmented sixth resolution not supported in this method.         r   r   Unknown augSixthType: c                Z   > U =(       a"    T=(       a    U R                   TR                   :H  $ Nnamepbasss    X/home/james-whalen/.local/lib/python3.13/site-packages/music21/figuredBass/resolution.py<lambda>*augmentedSixthToDominant.<locals>.<lambda>u       qATAaff		.AA    -m2c                Z   > U =(       a"    T=(       a    U R                   TR                   :H  $ r   r   r   roots    r   r   r   v   r   r   m2c                Z   > U =(       a"    T=(       a    U R                   TR                   :H  $ r   r   r   fifths    r   r   r   w       qCUCqvv/CCr   c                r   > U =(       a.    T=(       a%    U R                   TR                   :H  =(       a    TS:H  $ Nr   r   r   augSixthTypeothers    r   r   r   x   *    qYUYqvv/CYXYHYYr   d1c                r   > U =(       a.    T=(       a%    U R                   TR                   :H  =(       a    TS:H  $ Nr   r   r(   s    r   r   r   y   r+   r   r   ChordisAugmentedSixthResolutionException_unpackSeventhChordisItalianAugmentedSixthisFrenchAugmentedSixthisGermanAugmentedSixthisSwissAugmentedSixthtTYPE_CHECKING
isinstancer   Pitch_resolvePitches
augSixthPossibr)   augSixthChordInfoaugSixthChordunused_thirdhowToResolver   r$   r*   r    s
    `    @@@@r   augmentedSixthToDominantrC   %   s   ^  N3--//%&TUU/N0KL4466)VX X 3355 5577 4466  ,,,v3D0udL%		3D0t\5%!$:<:J"KLL$,,,,$,,,,%----%----A5IA4HCUKY[_`Y[`a	cL >88r   c                  ^^^^^	 Uc  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nTcg  UR                  5       (       a  [        S5      eUR                  5       (       a  SmO/UR                  5       (       a  SmOUR                  5       (       a  Sm[        R                  (       a  Uc   eTS;   a	  Uu  mmm	nmOTS:X  a	  Uu  mm	nmmO[        ST< 35      e[        R                  (       a  [        T[        R                  5      (       d   e[        T	[        R                  5      (       d   e[        T[        R                  5      (       d   e[        T[        R                  5      (       d   eU4S jS	4U	4S
 jS4U4S jS4UU4S jS4UU4S jS4UU4S jS4/n[        X5      $ )a  
Resolves French (augSixthType = 1), German (augSixthType = 2), and Swiss (augSixthType = 3)
augmented sixth chords to the major tonic 6,4.


Proper Italian augmented sixth resolutions not supported within this method.

>>> from music21.figuredBass import resolution
>>> Bb2 = pitch.Pitch('B-2')
>>> D4 = pitch.Pitch('D4')
>>> E4 = pitch.Pitch('E4')
>>> Es4 = pitch.Pitch('E#4')
>>> F4 = pitch.Pitch('F4')
>>> G4 = pitch.Pitch('G4')
>>> Gs4 = pitch.Pitch('G#4')
>>> iv6 = (G4, D4, D4, Bb2)
>>> itAug6 = (Gs4, D4, D4, Bb2)
>>> frAug6 = (Gs4, E4, D4, Bb2)
>>> grAug6 = (Gs4, F4, D4, Bb2)
>>> swAug6 = (Gs4, Es4, D4, Bb2)
>>> frRes = resolution.augmentedSixthToMajorTonic(frAug6)
>>> [str(p) for p in frRes]
['A4', 'F#4', 'D4', 'A2']
>>> grRes = resolution.augmentedSixthToMajorTonic(grAug6)
>>> [str(p) for p in grRes]
['A4', 'F#4', 'D4', 'A2']
>>> swRes = resolution.augmentedSixthToMajorTonic(swAug6)
>>> [str(p) for p in swRes]
['A4', 'F#4', 'D4', 'A2']
>>> #_DOCS_SHOW resolution.showResolutions(frAug6, frRes, grAug6, grRes, swAug6, swRes)

    .. image:: images/figuredBass/fbResolution_a6toI.*
        :width: 700


Above: French, German, and Swiss resolutions, respectively.
r
   r   r   r   r   r   r   c                Z   > U =(       a"    T=(       a    U R                   TR                   :H  $ r   r   r   s    r   r   ,augmentedSixthToMajorTonic.<locals>.<lambda>   r   r   r   c                Z   > U =(       a"    T=(       a    U R                   TR                   :H  $ r   r   r   s    r   r   rF      r   r   r!   c                Z   > U =(       a"    T=(       a    U R                   TR                   :H  $ r   r   r#   s    r   r   rF      r%   r   P1c                r   > U =(       a.    T=(       a%    U R                   TR                   :H  =(       a    TS:H  $ Nr   r   r(   s    r   r   rF      r+   r   M2c                r   > U =(       a.    T=(       a%    U R                   TR                   :H  =(       a    TS:H  $ r.   r   r(   s    r   r   rF      r+   r   A1c                r   > U =(       a.    T=(       a%    U R                   TR                   :H  =(       a    TS:H  $ r'   r   r(   s    r   r   rF      r+   r   r/   r=   s
    `    @@@@r   augmentedSixthToMajorTonicrP   ~   s   T  N3--//%&TUU/N0KL4466)VX X 3355 5577 4466  ,,,v3D0udL%		3D0t\5%!$:<:J"KLL$,,,,$,,,,%----%----A5IA4HCTJY[_`Y[_`Y[_`bL >88r   c                  ^^^^^	 Uc  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nTcg  UR                  5       (       a  [        S5      eUR                  5       (       a  SmO/UR                  5       (       a  SmOUR                  5       (       a  Sm[        R                  (       a  Uc   eTS;   a	  Uu  mmm	nmOTS:X  a	  Uu  mm	nmmO[        ST< 35      e[        R                  (       a  [        T[        R                  5      (       d   e[        T	[        R                  5      (       d   e[        T[        R                  5      (       d   e[        T[        R                  5      (       d   eU4S jS	4U	4S
 jS4U4S jS4UU4S jS4UU4S jS4/n[        X5      $ )a  
Resolves French (augSixthType = 1), German (augSixthType = 2), and Swiss (augSixthType = 3)
augmented sixth chords to the minor tonic 6,4.

Proper Italian augmented sixth resolutions not supported within this method.

>>> from music21.figuredBass import resolution
>>> Bb2 = pitch.Pitch('B-2')
>>> D4 = pitch.Pitch('D4')
>>> E4 = pitch.Pitch('E4')
>>> Es4 = pitch.Pitch('E#4')
>>> F4 = pitch.Pitch('F4')
>>> G4 = pitch.Pitch('G4')
>>> Gs4 = pitch.Pitch('G#4')
>>> iv6 = (G4, D4, D4, Bb2)
>>> itAug6 = (Gs4, D4, D4, Bb2)
>>> frAug6 = (Gs4, E4, D4, Bb2)
>>> grAug6 = (Gs4, F4, D4, Bb2)
>>> swAug6 = (Gs4, Es4, D4, Bb2)
>>> frRes = resolution.augmentedSixthToMinorTonic(frAug6)
>>> [str(p) for p in frRes]
['A4', 'F4', 'D4', 'A2']
>>> grRes = resolution.augmentedSixthToMinorTonic(grAug6)
>>> [str(p) for p in grRes]
['A4', 'F4', 'D4', 'A2']
>>> swRes = resolution.augmentedSixthToMinorTonic(swAug6)
>>> [str(p) for p in swRes]
['A4', 'F4', 'D4', 'A2']
>>> #_DOCS_SHOW resolution.showResolutions(frAug6, frRes, grAug6, grRes, swAug6, swRes)

    .. image:: images/figuredBass/fbResolution_a6toIm.*
        :width: 700


Above: French, German, and Swiss resolutions, respectively.
r
   r   r   r   r   r   r   c                Z   > U =(       a"    T=(       a    U R                   TR                   :H  $ r   r   r   s    r   r   ,augmentedSixthToMinorTonic.<locals>.<lambda>  r   r   r   c                Z   > U =(       a"    T=(       a    U R                   TR                   :H  $ r   r   r   s    r   r   rS      r   r   r!   c                Z   > U =(       a"    T=(       a    U R                   TR                   :H  $ r   r   r#   s    r   r   rS   !  r%   r   rI   c                r   > U =(       a.    T=(       a%    U R                   TR                   :H  =(       a    TS:H  $ rK   r   r(   s    r   r   rS   "  r+   r   c                r   > U =(       a.    T=(       a%    U R                   TR                   :H  =(       a    TS:H  $ r'   r   r(   s    r   r   rS   #  r+   r   d2r/   r=   s
    `    @@@@r   augmentedSixthToMinorTonicrY      s   R  N3--//%&TUU/N0KL4466)VX X 3355 5577 4466  ,,,v3D0udL%		3D0t\5%!$:<:J"KLL$,,,,$,,,,%----%----A5IA4HCTJY[_`Y[_`	bL >88r   c                B  ^^^^^^	 UcU  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUu  mmm	mmUU4S jS4U	4S jS4UU4S jS4U4S jS	4UU4S
 jS4U4S jS4/n[        X5      $ )a
  
Resolves a dominant seventh chord in root position or any of its
inversions to the major tonic, in root position or first inversion.


The second inversion (4,3) dominant seventh chord can resolve to
the tonic in either inversion. This is controlled by
resolveV43toI6, and is set to True
by :meth:`~music21.figuredBass.segment.Segment.resolveDominantSeventhSegment`
only when the :attr:`~music21.figuredBass.segment.Segment.segmentChord`
of a :class:`~music21.figuredBass.segment.Segment`
spells out a dominant seventh chord in second inversion.

>>> from music21.figuredBass import resolution
>>> G2 = pitch.Pitch('G2')
>>> C3 = pitch.Pitch('C3')
>>> E3 = pitch.Pitch('E3')
>>> G3 = pitch.Pitch('G3')
>>> Bb3 = pitch.Pitch('B-3')
>>> B3 = pitch.Pitch('B3')
>>> C4 = pitch.Pitch('C4')
>>> F4 = pitch.Pitch('F4')
>>> Bb4 = pitch.Pitch('B-4')
>>> D5 = pitch.Pitch('D5')
>>> E5 = pitch.Pitch('E5')
>>> domPossibA1 = (D5, F4, B3, G2)
>>> resPossibA1 = resolution.dominantSeventhToMajorTonic(domPossibA1)
>>> resPossibA1
(<music21.pitch.Pitch C5>, <music21.pitch.Pitch E4>,
 <music21.pitch.Pitch C4>, <music21.pitch.Pitch C3>)
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA1, resPossibA1)

.. image:: images/figuredBass/fbResolution_V7toI_1.*
        :width: 150

>>> domPossibA2 = (Bb3, G3, E3, C3)
>>> resPossibA2 = resolution.dominantSeventhToMajorTonic(domPossibA2)
>>> [str(p) for p in resPossibA2]
['A3', 'F3', 'F3', 'F3']
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA2, resPossibA2)

.. image:: images/figuredBass/fbResolution_V7toI_2.*
        :width: 150

>>> domPossibA3 = (E5, Bb4, C4, G3)
>>> resPossibA3a = resolution.dominantSeventhToMajorTonic(domPossibA3, False)
>>> [str(p) for p in resPossibA3a]
['F5', 'A4', 'C4', 'F3']
>>> resPossibA3b = resolution.dominantSeventhToMajorTonic(domPossibA3, True)
>>> [str(p) for p in resPossibA3b]
['F5', 'C5', 'C4', 'A3']
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA3, resPossibA3a, domPossibA3, resPossibA3b)

.. image:: images/figuredBass/fbResolution_V7toI_3.*
        :width: 200
,Possibility is not a dominant seventh chord.c                N   > U R                   TR                   :H  =(       a    U T:H  $ r   r   r   r   r    s    r   r   -dominantSeventhToMajorTonic.<locals>.<lambda>h      qvv2@qDy@r   P4c                6   > U R                   TR                   :H  $ r   r   r   thirds    r   r   r^   i      qvv3r   r!   c                H   > U R                   TR                   :H  =(       a    T$ r   r   )r   r$   resolveV43toI6s    r   r   r^   j      qvv3FFr   rL   c                6   > U R                   TR                   :H  $ r   r   r#   s    r   r   r^   k  rd   r   -M2c                H   > U R                   TR                   :H  =(       a    T$ r   r   )r   rf   sevenths    r   r   r^   l      qvv5H.Hr   c                6   > U R                   TR                   :H  $ r   r   r   rk   s    r   r   r^   m      qvv5r   r   r   r0   isDominantSeventhr2   r3   r<   )
	domPossibrf   domChordInfodomChordrB   r   r$   r    rk   rc   s
    `   @@@@@r   dominantSeventhToMajorTonicru   (      r ;;y)))++%&TUU*5;;y+AB*6'T4w@$G3T:FM3U;H$O5u=?L 933r   c                B  ^^^^^^	 UcU  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUu  mmm	mmUU4S jS4U	4S jS4UU4S jS4U4S jS4UU4S	 jS
4U4S jS4/n[        X5      $ )a  
Resolves a dominant seventh chord in root position or any of its
inversions to the minor tonic, in root position or first inversion,
accordingly.


The second inversion (4,3) dominant seventh chord can resolve to
the tonic in either inversion. This is controlled by
resolveV43toi6, and is set to True by
:meth:`~music21.figuredBass.segment.Segment.resolveDominantSeventhSegment`
only when the :attr:`~music21.figuredBass.segment.Segment.segmentChord`
of a :class:`~music21.figuredBass.segment.Segment`
spells out a dominant seventh chord in second inversion.

>>> from music21.figuredBass import resolution
>>> G2 = pitch.Pitch('G2')
>>> C3 = pitch.Pitch('C3')
>>> E3 = pitch.Pitch('E3')
>>> G3 = pitch.Pitch('G3')
>>> Bb3 = pitch.Pitch('B-3')
>>> B3 = pitch.Pitch('B3')
>>> C4 = pitch.Pitch('C4')
>>> F4 = pitch.Pitch('F4')
>>> Bb4 = pitch.Pitch('B-4')
>>> D5 = pitch.Pitch('D5')
>>> E5 = pitch.Pitch('E5')
>>> domPossibA1 = (D5, F4, B3, G2)
>>> resPossibA1 = resolution.dominantSeventhToMinorTonic(domPossibA1)
>>> [str(p) for p in resPossibA1]
['C5', 'E-4', 'C4', 'C3']
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA1, resPossibA1)

.. image:: images/figuredBass/fbResolution_V7toIm_1.*
        :width: 150

>>> domPossibA2 = (Bb3, G3, E3, C3)
>>> resPossibA2 = resolution.dominantSeventhToMinorTonic(domPossibA2)
>>> ', '.join([str(p) for p in resPossibA2])
'A-3, F3, F3, F3'
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA2, resPossibA2)

.. image:: images/figuredBass/fbResolution_V7toIm_2.*
        :width: 150

>>> domPossibA3 = (E5, Bb4, C4, G3)
>>> resPossibA3a = resolution.dominantSeventhToMinorTonic(domPossibA3, False)
>>> [str(p) for p in resPossibA3a]
['F5', 'A-4', 'C4', 'F3']
>>> resPossibA3b = resolution.dominantSeventhToMinorTonic(domPossibA3, True)
>>> [str(p) for p in resPossibA3b]
['F5', 'C5', 'C4', 'A-3']
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA3, resPossibA3a, domPossibA3, resPossibA3b)

.. image:: images/figuredBass/fbResolution_V7toIm_3.*
        :width: 200
r[   c                N   > U R                   TR                   :H  =(       a    U T:H  $ r   r   r]   s    r   r   -dominantSeventhToMinorTonic.<locals>.<lambda>  r_   r   r`   c                6   > U R                   TR                   :H  $ r   r   rb   s    r   r   ry     rd   r   r!   c                H   > U R                   TR                   :H  =(       a    T$ r   r   )r   r$   resolveV43toi6s    r   r   ry     rg   r   c                6   > U R                   TR                   :H  $ r   r   r#   s    r   r   ry     rd   r   ri   c                H   > U R                   TR                   :H  =(       a    T$ r   r   )r   r|   rk   s    r   r   ry     rl   r   rL   c                6   > U R                   TR                   :H  $ r   r   rn   s    r   r   ry     ro   r   rp   )
rr   r|   rs   rt   rB   r   r$   r    rk   rc   s
    `   @@@@@r   dominantSeventhToMinorTonicr   r  rv   r   c                Z  ^^^^ Uct  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUR                  5       S:X  d  [        S5      eUu  nmmmmU4S jS4U4S jS4U4S jS4U4S	 jS4/n[        X5      $ )
aB  
Resolves a dominant seventh chord in root position to the
major submediant (VI) in root position.

>>> from music21.figuredBass import resolution
>>> G2 = pitch.Pitch('G2')
>>> B3 = pitch.Pitch('B3')
>>> F4 = pitch.Pitch('F4')
>>> D5 = pitch.Pitch('D5')
>>> domPossibA1 = (D5, F4, B3, G2)
>>> resPossibA1 = resolution.dominantSeventhToMajorSubmediant(domPossibA1)
>>> [p.nameWithOctave for p in resPossibA1]
['C5', 'E-4', 'C4', 'A-2']
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA1, resPossibA1)

.. image:: images/figuredBass/fbResolution_V7toVI.*
        :width: 150
r[   r   %Possibility must be in root position.c                6   > U R                   TR                   :H  $ r   r   r   s    r   r   2dominantSeventhToMajorSubmediant.<locals>.<lambda>      qvv2r   r!   c                6   > U R                   TR                   :H  $ r   r   rb   s    r   r   r     rd   r   c                6   > U R                   TR                   :H  $ r   r   r#   s    r   r   r     rd   r   ri   c                6   > U R                   TR                   :H  $ r   r   rn   s    r   r   r     ro   r   r   r0   rq   r2   r3   	inversionr<   	rr   rs   rt   unused_bassrB   r$   r    rk   rc   s	        @@@@r    dominantSeventhToMajorSubmediantr         & ;;y)))++%&TUU*5;;y+AB!!#q(%&MNN1=.[$ug2D93T:3U;5u=?L
 933r   c                Z  ^^^^ Uct  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUR                  5       S:X  d  [        S5      eUu  nmmmmU4S jS4U4S jS4U4S jS	4U4S
 jS4/n[        X5      $ )aA  
Resolves a dominant seventh chord in root position to the
minor submediant (vi) in root position.

>>> from music21.figuredBass import resolution
>>> G2 = pitch.Pitch('G2')
>>> B3 = pitch.Pitch('B3')
>>> F4 = pitch.Pitch('F4')
>>> D5 = pitch.Pitch('D5')
>>> domPossibA1 = (D5, F4, B3, G2)
>>> resPossibA1 = resolution.dominantSeventhToMinorSubmediant(domPossibA1)
>>> [p.nameWithOctave for p in resPossibA1]
['C5', 'E4', 'C4', 'A2']
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA1, resPossibA1)

.. image:: images/figuredBass/fbResolution_V7toVIm.*
        :width: 150
r[   r   r   c                6   > U R                   TR                   :H  $ r   r   r   s    r   r   2dominantSeventhToMinorSubmediant.<locals>.<lambda>  r   r   rL   c                6   > U R                   TR                   :H  $ r   r   rb   s    r   r   r     rd   r   r!   c                6   > U R                   TR                   :H  $ r   r   r#   s    r   r   r     rd   r   ri   c                6   > U R                   TR                   :H  $ r   r   rn   s    r   r   r     ro   r   r   r   r   s	        @@@@r    dominantSeventhToMinorSubmediantr     r   r   c                J  ^^^ Uct  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUR                  5       S:X  d  [        S5      eUu  nmmmnU4S jS4U4S jS4U4S jS	4/n[        X5      $ )
aD  
Resolves a dominant seventh chord in root position
to the major subdominant (IV) in first inversion.

>>> from music21.figuredBass import resolution
>>> G2 = pitch.Pitch('G2')
>>> B3 = pitch.Pitch('B3')
>>> F4 = pitch.Pitch('F4')
>>> D5 = pitch.Pitch('D5')
>>> domPossibA1 = (D5, F4, B3, G2)
>>> resPossibA1 = resolution.dominantSeventhToMajorSubdominant(domPossibA1)
>>> [p.nameWithOctave for p in resPossibA1]
['C5', 'F4', 'C4', 'A2']
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA1, resPossibA1)

.. image:: images/figuredBass/fbResolution_V7toIV.*
        :width: 150
r[   r   r   c                6   > U R                   TR                   :H  $ r   r   r   s    r   r   3dominantSeventhToMajorSubdominant.<locals>.<lambda>   r   r   rL   c                6   > U R                   TR                   :H  $ r   r   rb   s    r   r   r   !  rd   r   r!   c                6   > U R                   TR                   :H  $ r   r   r#   s    r   r   r   "  rd   r   ri   r   	rr   rs   rt   r   unused_seventhrB   r$   r    rc   s	         @@@r   !dominantSeventhToMajorSubdominantr         & ;;y)))++%&TUU*5;;y+AB!!#q(%&MNN8D5[$un2D93T:3U;=L 933r   c                J  ^^^ Uct  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUR                  5       S:X  d  [        S5      eUu  nmmmnU4S jS4U4S jS4U4S jS4/n[        X5      $ )	aF  
Resolves a dominant seventh chord in root position
to the minor subdominant (iv) in first inversion.

>>> from music21.figuredBass import resolution
>>> G2 = pitch.Pitch('G2')
>>> B3 = pitch.Pitch('B3')
>>> F4 = pitch.Pitch('F4')
>>> D5 = pitch.Pitch('D5')
>>> domPossibA1 = (D5, F4, B3, G2)
>>> resPossibA1 = resolution.dominantSeventhToMinorSubdominant(domPossibA1)
>>> [p.nameWithOctave for p in resPossibA1]
['C5', 'F4', 'C4', 'A-2']
>>> #_DOCS_SHOW resolution.showResolutions(domPossibA1, resPossibA1)

.. image:: images/figuredBass/fbResolution_V7toIVm.*
        :width: 150
r[   r   r   c                6   > U R                   TR                   :H  $ r   r   r   s    r   r   3dominantSeventhToMinorSubdominant.<locals>.<lambda>C  r   r   r!   c                6   > U R                   TR                   :H  $ r   r   rb   s    r   r   r   D  rd   r   c                6   > U R                   TR                   :H  $ r   r   r#   s    r   r   r   E  rd   r   ri   r   r   s	         @@@r   !dominantSeventhToMinorSubdominantr   '  r   r   c                .  ^^^^^	 UcU  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUu  nmm	mmU4S jS4UU	4S jS4U	4S jS4U4S jS	4U4S
 jS	4/n[        X5      $ )aM  
Resolves a fully diminished seventh chord to the major tonic,
in root position or either inversion.


The resolution of the diminished seventh chord can have a
doubled third (standard resolution) or a doubled root
(alternate resolution), because the third of the diminished
chord can either rise or fall. The desired resolution is
attained using doubledRoot, and is set by
:meth:`~music21.figuredBass.segment.Segment.resolveDiminishedSeventhSegment`.

>>> from music21.figuredBass import resolution
>>> Cs3 = pitch.Pitch('C#3')
>>> G3 = pitch.Pitch('G3')
>>> E4 = pitch.Pitch('E4')
>>> Bb4 = pitch.Pitch('B-4')
>>> dimPossibA = (Bb4, E4, G3, Cs3)
>>> resPossibAa = resolution.diminishedSeventhToMajorTonic(dimPossibA, False)
>>> [str(p) for p in resPossibAa]
['A4', 'F#4', 'F#3', 'D3']
>>> resPossibAb = resolution.diminishedSeventhToMajorTonic(dimPossibA, True)
>>> [p.nameWithOctave for p in resPossibAb]
['A4', 'D4', 'F#3', 'D3']
>>> #_DOCS_SHOW resolution.showResolutions(dimPossibA, resPossibAa, dimPossibA, resPossibAb)

.. image:: images/figuredBass/fbResolution_vii7toI.*
        :width: 200
4Possibility is not a fully diminished seventh chord.c                6   > U R                   TR                   :H  $ r   r   r   s    r   r   /diminishedSeventhToMajorTonic.<locals>.<lambda>o  r   r   r!   c                H   > U R                   TR                   :H  =(       a    T$ r   r   r   doubledRootrc   s    r   r   r   p      qvv3CCr   ri   c                6   > U R                   TR                   :H  $ r   r   rb   s    r   r   r   q  rd   r   rL   c                6   > U R                   TR                   :H  $ r   r   r#   s    r   r   r   r  rd   r   r   c                6   > U R                   TR                   :H  $ r   r   rn   s    r   r   r   s  ro   r   r   r0   isDiminishedSeventhr2   r3   r<   
	dimPossibr   dimChordInfodimChordr   rB   r$   r    rk   rc   s
    `    @@@@r   diminishedSeventhToMajorTonicr   J      < ;;y)++--%&\]]*5;;y+AB1=.[$ug2D9CUK3T:3U;5u=	?L 933r   c                .  ^^^^^	 UcU  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUu  nmm	mmU4S jS4UU	4S jS4U	4S jS4U4S jS4U4S jS	4/n[        X5      $ )
aU  
Resolves a fully diminished seventh chord to the minor tonic,
in root position or either inversion.


The resolution of the diminished seventh chord can have a
doubled third (standard resolution) or a doubled root
(alternate resolution), because the third of the diminished
chord can either rise or fall. The desired resolution is
attained using doubledRoot, and is set by
:meth:`~music21.figuredBass.segment.Segment.resolveDiminishedSeventhSegment`.

>>> from music21.figuredBass import resolution
>>> Cs3 = pitch.Pitch('C#3')
>>> G3 = pitch.Pitch('G3')
>>> E4 = pitch.Pitch('E4')
>>> Bb4 = pitch.Pitch('B-4')
>>> dimPossibA = (Bb4, E4, G3, Cs3)
>>> resPossibAa = resolution.diminishedSeventhToMinorTonic(dimPossibA, False)
>>> [p.nameWithOctave for p in resPossibAa]
['A4', 'F4', 'F3', 'D3']
>>> resPossibAb = resolution.diminishedSeventhToMinorTonic(dimPossibA, True)
>>> [p.nameWithOctave for p in resPossibAb]
['A4', 'D4', 'F3', 'D3']
>>> #_DOCS_SHOW resolution.showResolutions(dimPossibA, resPossibAa, dimPossibA, resPossibAb)

.. image:: images/figuredBass/fbResolution_vii7toIm.*
        :width: 200
r   c                6   > U R                   TR                   :H  $ r   r   r   s    r   r   /diminishedSeventhToMinorTonic.<locals>.<lambda>  r   r   r!   c                H   > U R                   TR                   :H  =(       a    T$ r   r   r   s    r   r   r     r   r   ri   c                6   > U R                   TR                   :H  $ r   r   rb   s    r   r   r     rd   r   c                6   > U R                   TR                   :H  $ r   r   r#   s    r   r   r     rd   r   c                6   > U R                   TR                   :H  $ r   r   rn   s    r   r   r     ro   r   r   r   r   s
    `    @@@@r   diminishedSeventhToMinorTonicr   x  r   r   c                  ^^^ UcU  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUu  nmmnmU4S jS4U4S jS4U4S jS4/n[        X5      $ )a"  
Resolves a fully diminished seventh chord to the
major subdominant (IV).

>>> from music21.figuredBass import resolution
>>> Cs3 = pitch.Pitch('C#3')
>>> G3 = pitch.Pitch('G3')
>>> E4 = pitch.Pitch('E4')
>>> Bb4 = pitch.Pitch('B-4')
>>> dimPossibA = (Bb4, E4, G3, Cs3)
>>> resPossibA = resolution.diminishedSeventhToMajorSubdominant(dimPossibA)
>>> [str(p) for p in resPossibA]
['B4', 'D4', 'G3', 'D3']
>>> #_DOCS_SHOW resolution.showResolutions(dimPossibA, resPossibA)

.. image:: images/figuredBass/fbResolution_vii7toIV.*
        :width: 150
r   c                6   > U R                   TR                   :H  $ r   r   r   s    r   r   5diminishedSeventhToMajorSubdominant.<locals>.<lambda>  r   r   r!   c                6   > U R                   TR                   :H  $ r   r   rb   s    r   r   r     rd   r   ri   c                6   > U R                   TR                   :H  $ r   r   rn   s    r   r   r     ro   r   rN   r   )	r   r   r   r   unused_fifthrB   r    rk   rc   s	         @@@r   #diminishedSeventhToMajorSubdominantr     s    & ;;y)++--%&\]]*5;;y+AB8D5[$|W2D93U;5t<>L 933r   c                   ^^ UcU  [         R                  " U 5      nUR                  5       (       d  [        S5      e[	        [         R                  " U 5      5      nUu  nmmpEU4S jS4U4S jS4/n[        X5      $ )a$  
Resolves a fully diminished seventh chord to the
minor subdominant (iv).

>>> from music21.figuredBass import resolution
>>> Cs3 = pitch.Pitch('C#3')
>>> G3 = pitch.Pitch('G3')
>>> E4 = pitch.Pitch('E4')
>>> Bb4 = pitch.Pitch('B-4')
>>> dimPossibA = (Bb4, E4, G3, Cs3)
>>> resPossibA = resolution.diminishedSeventhToMinorSubdominant(dimPossibA)
>>> [str(p) for p in resPossibA]
['B-4', 'D4', 'G3', 'D3']
>>> #_DOCS_SHOW resolution.showResolutions(dimPossibA, resPossibA)

.. image:: images/figuredBass/fbResolution_vii7toIVm.*
        :width: 150
r   c                6   > U R                   TR                   :H  $ r   r   r   s    r   r   5diminishedSeventhToMinorSubdominant.<locals>.<lambda>  r   r   r!   c                6   > U R                   TR                   :H  $ r   r   rb   s    r   r   r     rd   r   ri   r   )	r   r   r   r   r   r   rB   r    rc   s	          @@r   #diminishedSeventhToMinorSubdominantr     sy    & ;;y)++--%&\]]*5;;y+AB?K<[$|2D93U;=L 933r   c                    [         R                  " 5       n[         R                  " 5       nU  He  n[        R                  " USS 5      nSUl        [
        R                  " US   5      nSUl        UR                  U5        UR                  U5        Mg     [         R                  " 5       nUR                  SU5        UR                  SU5        UR                  5         g)z
Takes in possibilities as arguments and adds them in order
to a :class:`~music21.stream.Score` which is then displayed
in external software.
r   g       @N)r   Partr   r0   quarterLengthr   NoteappendScoreinsertshow)	allPossib
upperPartsbassLinepossibAchordAbassAscores          r   showResolutionsr     s     J{{}HWQr]+"		'"+&!&!  LLNE	LLJ	LLH	JJLr   c                $    U R                  U5      $ r   )	transpose)samplePitchintervalStrings     r   
_transposer     s      00r   c                    UR                  S S45        / nU  H8  nU H/  u  pEU" U5      (       d  M  UR                  [        X55      5          M6     M:     [        U5      $ )z
Takes in a possibility to resolve and a list of (lambda function, intervalString)
pairs and transposes each pitch by the intervalString corresponding to the lambda
function that returns True when applied to the pitch.
c                    g)NT )r   s    r   r   !_resolvePitches.<locals>.<lambda>	  s    4r   rI   )r   r   tuple)possibToResolverB   
resPitchesr   
expressionr   s         r   r<   r<     sa     ./$&J&,8(Z+&&!!*["IJ -9 ' r   c                    U R                  5       nU R                  5       nU R                  S5      nU R                  S5      nU R                  S5      nXX4U/nU$ )zl
Takes in a Chord and returns a list of Pitches (or Nones) corresponding
to the bass, root, fifth, seventh.
r         )r   r    getChordStep)seventhChordr   r    rc   r$   rk   seventhChordInfos          r   r3   r3     sc     DD%%a(E%%a(E''*GE':r   c                      \ rS rSrSrg)r2   i/  r   N__name__
__module____qualname____firstlineno____static_attributes__r   r   r   r2   r2   /      r   r2   c                      \ rS rSrSrg)Testi5  r   Nr   r   r   r   r   r   5  r   r   r   __main__)NN)r)   z
int | Noner?   zlist[pitch.Pitch | None] | Nonereturntuple[pitch.Pitch, ...])FNr   )r   r   )r   zchord.Chordr   zlist[pitch.Pitch | None])$__doc__
__future__r   typingr8   unittestmusic21r   r   r   r   r   rC   rP   rY   ru   r   r   r   r   r   r   r   r   r   r   r   r<   r3   
_DOC_ORDERMusic21Exceptionr2   TestCaser   r   mainTestr   r   r   <module>r     s   #        
  $9=V9V9 7V9 	V9v  $9=S9S9 7S9 	S9p  $9=Q9Q9 7Q9 	Q9hG4TG4T!4H!4H 4F 4F+4\+4\4B4@01"  '(*D)+F.0P/1R+-J13VX
	,77 		8 	 zT r   