Merge branch 'cuthbertLab:master' into midilyrics

Author: oxygen-dioxide

documentation/source/usersGuide/usersGuide_07_chords.ipynb

@@ -526,7 +526,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can find the third and fifth of the `Chord` with .third and .fifth.  Note that these properties do not have `()` after them.  This was a mistake in how we created `music21` and hopefully this will all be fixed and consistent soon:"
+    "You can find the third and fifth of the `Chord` with `.third` and `.fifth`.  Note that these properties do not have `()` after them.  This was a mistake in how we created `music21` and hopefully this will all be fixed and consistent soon:"
    ]
   },
   {

music21/_version.py

@@ -50,7 +50,7 @@
 '''
 from __future__ import annotations
 
-__version__ = '9.6.0b3'
+__version__ = '9.6.0b4'
 
 def get_version_tuple(vv):
     v = vv.split('.')

music21/articulations.py

@@ -76,18 +76,17 @@
 '''
 from __future__ import annotations
 
-import typing as t
 import unittest
 
 from music21 import base
 from music21 import common
 from music21.common.classTools import tempAttribute
+from music21.common.types import OffsetQL
 from music21 import environment
-from music21 import style
+from music21 import interval
 from music21 import spanner
+from music21 import style
 
-if t.TYPE_CHECKING:
-    from music21 import interval
 
 
 environLocal = environment.Environment('articulations')
@@ -582,10 +581,57 @@ class PullOff(spanner.Spanner, TechnicalIndication):
     pass
 
 class FretBend(FretIndication):
-    bendAlter: interval.IntervalBase|None = None
-    preBend: t.Any = None
-    release: t.Any = None
-    withBar: t.Any = None
+    '''
+    Bend indication for fretted instruments
+
+    Bend in musicxml
+
+    `number` is an identifier for the articulation. Defaults to 0.
+
+    `bendAlter` is the interval defined by the bend,
+    bend-alter in musicxml. Defaults to `None`.
+
+    `preBend` indicates if the string is bent before
+    the onset of the note. Defaults to `False`.
+
+    `release` is the quarterLength value from the start
+    of the note for releasing the bend, if any. Defaults to `None`.
+
+    `withBar` indicates what whammy bar movement is used, if any.
+    MusicXML supports 'scoop' or 'dip'. Defaults to `None`.
+
+    >>> fb = articulations.FretBend(1, bendAlter=interval.ChromaticInterval(-2),  release=0.5)
+    >>> fb
+    <music21.articulations.FretBend 1>
+    >>> fb.preBend
+    False
+    >>> fb.withBar is None
+    True
+    >>> fb.bendAlter
+    <music21.interval.ChromaticInterval -2>
+    >>> fb.release
+    0.5
+    '''
+    bendAlter: interval.Interval | interval.ChromaticInterval | None
+    preBend: bool
+    release: OffsetQL | None
+    withBar: str | None
+
+    def __init__(
+        self,
+        number: int = 0,
+        *,
+        bendAlter: interval.Interval | interval.ChromaticInterval | None = None,
+        preBend: bool = False,
+        release: OffsetQL | None = None,
+        withBar: str | None = None,
+        **keywords
+    ):
+        super().__init__(number=number, **keywords)
+        self.bendAlter = bendAlter
+        self.preBend = preBend
+        self.release = release
+        self.withBar = withBar
 
 class FretTap(FretIndication):
     pass

music21/base.py

@@ -27,7 +27,7 @@
 <class 'music21.base.Music21Object'>
 
 >>> music21.VERSION_STR
-'9.6.0b3'
+'9.6.0b4'
 
 Alternatively, after doing a complete import, these classes are available
 under the module "base":

music21/chord/__init__.py

@@ -2318,7 +2318,7 @@ def inversion(
         *,
         find: bool = True,
         testRoot: pitch.Pitch|None = None,
-        transposeOnSet: bool = True
+        transposeOnSet: bool = True,
     ) -> int|None:
         '''
         Find the chord's inversion or (if called with a number) set the chord to
@@ -2393,7 +2393,6 @@ def inversion(
         Traceback (most recent call last):
         music21.chord.ChordException: Could not invert chord: inversion may not exist
 
-
         If testRoot is True then that temporary root is used instead of self.root().
 
         Get the inversion for a seventh chord showing different roots
@@ -2430,7 +2429,7 @@ def inversion(
         sets the value to be returned later, which might be useful for
         cases where the chords are poorly spelled, or there is an added note.
 
-        * Changed in v8: chords without pitches
+        * Changed in v8: deal with chords without pitches
         '''
         if not self.pitches:
             return -1
@@ -2460,11 +2459,12 @@ def inversion(
         else:
             return -1
 
-    def _setInversion(self,
-                      newInversion: int,
-                      rootPitch: pitch.Pitch,
-                      transposeOnSet: bool
-                      ) -> None:
+    def _setInversion(
+        self,
+        newInversion: int,
+        rootPitch: pitch.Pitch,
+        transposeOnSet: bool,
+    ) -> None:
         '''
         Helper function for inversion(int)
         '''

music21/harmony.py

@@ -263,38 +263,47 @@ def _reprInternal(self):
             summary += ' '.join([p.name for p in self.pitches])
         return summary
 
-    # PRIVATE METHODS #
+    # PROTECTED METHODS #
     def _parseFigure(self):
         '''
-        subclass this in extensions (SO WHY IS IT PRIVATE???)
+        subclass this in extensions (protected in TypeScript/Java speak)
         '''
         return
 
     def _updatePitches(self):
         '''
-        subclass this in extensions (SO WHY IS IT PRIVATE???)
+        subclass this in extensions (protected in TypeScript/Java speak)
         '''
         return
 
-    def _updateFromParameters(self, root, bass, inversion: int|None = None):
+    def _updateFromParameters(
+        self,
+        root: str|pitch.Pitch|None,
+        bass: str|pitch.Pitch|None,
+        inversion: int|None = None
+    ) -> None:
         '''
         This method must be called twice, once before the pitches
         are rendered, and once after. This is because after the pitches
-        are rendered, the root() and bass() becomes reset by the chord class,
+        are rendered, the root() and bass() become reset by the chord class,
         but we want the objects to retain their initial root, bass, and inversion.
         '''
         if root and isinstance(root, str):
             root = common.cleanedFlatNotation(root)
             self.root(pitch.Pitch(root, octave=3))
         elif root is not None:
             self.root(root)
+
+        # set inversion first...
+        if inversion is not None:
+            self.inversion(inversion, transposeOnSet=True)
+
+        # and then bass.
         if bass and isinstance(bass, str):
             bass = common.cleanedFlatNotation(bass)
             self.bass(pitch.Pitch(bass, octave=3), allow_add=True)
         elif bass is not None:
             self.bass(bass, allow_add=True)
-        if inversion is not None:
-            self.inversion(inversion, transposeOnSet=True)
 
     # PUBLIC PROPERTIES #
 
@@ -1609,7 +1618,7 @@ class ChordSymbol(Harmony):
     # INITIALIZER #
 
     def __init__(self,
-                 figure=None,
+                 figure: str|None = None,
                  root: pitch.Pitch|str|None = None,
                  bass: pitch.Pitch|str|None = None,
                  inversion: int|None = None,
@@ -2473,7 +2482,13 @@ class NoChord(ChordSymbol):
     >>> nc2.pitches
     ()
     '''
-    def __init__(self, figure=None, kind='none', kindStr=None, **keywords):
+    def __init__(
+        self,
+        figure: str|None = None,
+        kind: str|None = 'none',
+        kindStr: str|None = None,
+        **keywords
+    ):
         super().__init__(figure, kind=kind, kindStr=kindStr or figure or 'N.C.', **keywords)
 
         if self._figure is None:
@@ -2655,6 +2670,17 @@ def testChordSymbolSetsBassOctave(self):
         b = d.bass()
         self.assertEqual(b.nameWithOctave, 'E-3')
 
+    def testHarmonyPreservesInversionAndBass(self):
+        '''
+        Test that bass is preserved even when both bass and inversion are given
+        '''
+        explicitFm6 = ChordSymbol(root='F', bass='A-', inversion=1, kind='minor')
+        self.assertEqual(explicitFm6.inversion(), 1)
+        self.assertEqual(explicitFm6.bass(find=False).name, 'A-')
+        self.assertEqual(explicitFm6.root(find=False).name, 'F')
+        self.assertLess(explicitFm6.bass(find=False).octave,
+                        explicitFm6.root(find=False).octave)
+
     def testClassSortOrderHarmony(self):
         '''
         This tests a former bug in getContextByClass

music21/musicxml/m21ToXml.py

@@ -5473,11 +5473,18 @@ def articulationToXmlTechnical(self, articulationMark: articulations.Articulatio
         >>> mxOther = MEX.articulationToXmlTechnical(g)
         >>> MEX.dump(mxOther)
         <other-technical>unda maris</other-technical>
+
+        Same with technical marks not yet supported.
+        TODO: support HammerOn, PullOff, Hole, Arrow.
+
+        >>> h = articulations.HammerOn()
+        >>> mxOther = MEX.articulationToXmlTechnical(h)
+        >>> MEX.dump(mxOther)
+        <other-technical />
         '''
         # these technical have extra information
         # TODO: hammer-on
         # TODO: pull-off
-        # TODO: bend
         # TODO: hole
         # TODO: arrow
         musicXMLTechnicalName = None
@@ -5489,7 +5496,7 @@ def articulationToXmlTechnical(self, articulationMark: articulations.Articulatio
             musicXMLTechnicalName = 'other-technical'
 
         # TODO: support additional technical marks listed above
-        if musicXMLTechnicalName in ('bend', 'hole', 'arrow'):
+        if musicXMLTechnicalName in ('hole', 'arrow'):
             musicXMLTechnicalName = 'other-technical'
 
         mxTechnicalMark = Element(musicXMLTechnicalName)
@@ -5523,7 +5530,10 @@ def articulationToXmlTechnical(self, articulationMark: articulations.Articulatio
             if t.TYPE_CHECKING:
                 assert isinstance(articulationMark, articulations.FretIndication)
             mxTechnicalMark.text = str(articulationMark.number)
-
+        if musicXMLTechnicalName == 'bend':
+            if t.TYPE_CHECKING:
+                assert isinstance(articulationMark, articulations.FretBend)
+            self.setBend(mxTechnicalMark, articulationMark)
         # harmonic needs to check for whether it is artificial or natural, and
         # whether it is base-pitch, sounding-pitch, or touching-pitch
         if musicXMLTechnicalName == 'harmonic':
@@ -5539,6 +5549,67 @@ def articulationToXmlTechnical(self, articulationMark: articulations.Articulatio
         # mxArticulations.append(mxArticulationMark)
         return mxTechnicalMark
 
+    @staticmethod
+    def setBend(mxh: Element, bend: articulations.FretBend) -> None:
+        '''
+        Sets the bend-alter SubElement and the pre-bend,
+        release and with-bar SubElements when present.
+
+        Called from articulationToXmlTechnical
+
+        >>> from xml.etree.ElementTree import Element
+        >>> from fractions import Fraction
+
+        >>> MEXclass = musicxml.m21ToXml.MeasureExporter
+
+        >>> a = articulations.FretBend(bendAlter=interval.Interval(2))
+        >>> mxh = Element('bend')
+        >>> MEXclass.setBend(mxh, a)
+        >>> MEXclass.dump(mxh)
+        <bend>
+          <bend-alter>2</bend-alter>
+        </bend>
+        >>> mxh = Element('bend')
+        >>> a = articulations.FretBend(bendAlter=interval.Interval(2))
+        >>> a.preBend = True
+        >>> MEXclass.setBend(mxh, a)
+        >>> MEXclass.dump(mxh)
+        <bend>
+          <bend-alter>2</bend-alter>
+          <pre-bend />
+        </bend>
+        >>> mxh = Element('bend')
+        >>> a = articulations.FretBend(bendAlter=interval.Interval(-2), release=Fraction(1, 10080))
+        >>> MEXclass.setBend(mxh, a)
+        >>> MEXclass.dump(mxh)
+        <bend>
+          <bend-alter>-2</bend-alter>
+          <release offset="1" />
+        </bend>
+        >>> mxh = Element('bend')
+        >>> a = articulations.FretBend(bendAlter=interval.Interval(-2), withBar='scoop')
+        >>> MEXclass.setBend(mxh, a)
+        >>> MEXclass.dump(mxh)
+        <bend>
+          <bend-alter>-2</bend-alter>
+          <with-bar>scoop</with-bar>
+        </bend>
+        '''
+        bendAlterSubElement = SubElement(mxh, 'bend-alter')
+        alter = bend.bendAlter
+        if alter is not None:
+            bendAlterSubElement.text = str(alter.semitones)
+        if bend.preBend:
+            SubElement(mxh, 'pre-bend')
+        if bend.release is not None:
+            releaseSubElement = SubElement(mxh, 'release')
+            quarterLengthValue = bend.release
+            divisionsValue = int(defaults.divisionsPerQuarter * quarterLengthValue)
+            releaseSubElement.set('offset', str(divisionsValue))
+        if bend.withBar is not None:
+            withBarSubElement = SubElement(mxh, 'with-bar')
+            withBarSubElement.text = str(bend.withBar)
+
     @staticmethod
     def setHarmonic(mxh: Element, harm: articulations.StringHarmonic) -> None:
         # noinspection PyShadowingNames
@@ -5951,7 +6022,6 @@ def chordSymbolToXml(self,
         self.setPrintStyle(mxHarmony, cs)
 
         csRoot = cs.root()
-        csBass = cs.bass(find=False)
         # TODO: do not look at ._attributes
         if cs._roman is not None:
             mxFunction = SubElement(mxHarmony, 'function')
@@ -5994,6 +6064,9 @@ def chordSymbolToXml(self,
             mxInversion = SubElement(mxHarmony, 'inversion')
             mxInversion.text = str(csInv)
 
+        # first -- go with the already defined bass, from overrides, etc.
+        # but if that is not defined, then find the bass itself.
+        csBass = cs.bass(find=False) or cs.bass(find=True)
         if csBass is not None and (csRoot is None or csRoot.name != csBass.name):
             # TODO.. reuse above from Root
             mxBass = SubElement(mxHarmony, 'bass')