Release Candidate for M21 V10

README.md

@@ -11,7 +11,7 @@ For more information, visit:
 https://www.music21.org/music21docs/
 
 To try it out, visit:
-https://tinyurl.com/m21colab (runs music21 v7)
+https://tinyurl.com/m21colab (run all to set up an environment for the latest release)
 
 And to install, see:
 https://www.music21.org/music21docs/usersGuide/usersGuide_01_installing.html

dist/dist.py

@@ -18,29 +18,31 @@
     for a major change that affects parsing run corpus.corpora.CoreCorpus().rebuildMetadataCache()
     (2 min on M4) -- either of these MAY change a
     lot of tests in corpus, metadata, etc. so don't skip the next step!
-3. IMPORTANT: run python documentation/testDocumentation.py and afterwards fix errors [*]
+3. IMPORTANT: `uv run documentation/testDocumentation.py` and afterwards fix errors [*]
 
 [*] you will need pytest, docutils, nbval installed (along with ipython and jupyter),
 you cannot check to see if fixed tests work while it is running.
 This takes a while and runs single core, and then almost always needs code patches
 so allocate time (2 min on M4).  Start working on the announcement while it's running.
+Cannot run 2 and 3 in parallel, since often metadata changes cause documentation changes.
 
-4. run test/warningMultiprocessTest.py for lowest and highest Py version -- fix all warnings!
+4. `uv run music21/test/warningMultiprocessTest.py` for lowest and highest Py version -- fix all warnings!
 5. run `from music21.test import treeYield
     and then run `treeYield.find_all_non_hashable_m21objects()` and check that the set returned is
-    empty.  Note -- it will print a bunch of module names, but only the final set matters.
-    Then do the same for `treeYield.find_all_non_default_instantiation_m21objects()`.
+    empty.  Note -- it will print a bunch of module names, but only the final `set()` being empty matters.
+    Then do the same for `treeYield.find_all_non_default_instantiation_m21objects()`.  If that one isn't
+    empty it is not a bug, but it would be nice to keep is so Music21Objects don't need args.
 6. commit and wait for results on GitHub Actions
      (normally not necessary, because it's slower and mostly duplicates multiprocessTest,
      but should be done before making a release).
-
-7. run documentation/make.py clean  (skip on minor version changes) -- you may need to make a
+7. `uv run documentation/make.py clean`  (skip on minor version changes) -- you may need to make a
      documentation/build directory first.
-8. run documentation/make.py linkcheck  [*]
+8. `uv run documentation/make.py linkcheck`  [*]
      some persistent errors that actually work are in the conf.py file under linkcheck_ignore
-9. run documentation/make.py   [*]
+9. `uv run documentation/make.py`   [*]
+9b. `uv run documentation/upload.py`
 
-[*] you will need sphinx, Jupyter (pip or easy_install), markdown, and pandoc (.dmg) installed
+[*] you will need sphinx, Jupyter (uv will install it), markdown, and pandoc (.dmg) installed
 
 10. move music21 documentation/build/html to music21.org/music21docs/
     via Amazon S3 (contact MSAC for authentication if need be) (MSAC has a program:

documentation/docbuild/documenters.py

@@ -379,17 +379,14 @@ class ClassDocumenter(ObjectDocumenter):
     Methods inherited from :class:`~music21.base.Music21Object`:
     .. hlist::
        :columns: 3
+       - :meth:`~music21.base.Music21Object.__eq__`
        - :meth:`~music21.base.Music21Object.clearCache`
        - :meth:`~music21.base.Music21Object.containerHierarchy`
        - :meth:`~music21.base.Music21Object.contextSites`
                 ...
        - :meth:`~music21.base.Music21Object.splitAtQuarterLength`
        - :meth:`~music21.base.Music21Object.splitByQuarterLengths`
        - :meth:`~music21.base.Music21Object.write`
-    Methods inherited from :class:`~music21.prebase.ProtoM21Object`:
-    .. hlist::
-       :columns: 3
-       - :meth:`~music21.prebase.ProtoM21Object.isClassOrSubclass`
     .. rubric:: :class:`~music21.articulations.Caesura` instance variables
     Instance variables inherited from :class:`~music21.base.Music21Object`:
     .. hlist::
@@ -698,12 +695,12 @@ def inheritedReadonlyPropertiesMapping(self):
         - music21.stream.base.Stream.beatDuration
         - music21.stream.base.Stream.beatStr
         - music21.stream.base.Stream.beatStrength
-        - music21.stream.base.Stream.flat
         - music21.stream.base.Stream.highestOffset
         - music21.stream.base.Stream.highestTime
         - music21.stream.base.Stream.isGapless
         - music21.stream.base.Stream.lowestOffset
         - music21.stream.base.Stream.notes
+        - music21.stream.base.Stream.notesAndRests
         music21.stream.core.StreamCore:
         - music21.stream.core.StreamCore.spannerBundle
         '''
@@ -731,14 +728,12 @@ def inheritedMethodsMapping(self):
         - music21.base.Music21Object.contextSites
         - music21.base.Music21Object.getAllContextsByClass
         - music21.base.Music21Object.getContextByClass
-        music21.prebase.ProtoM21Object:
-        - music21.prebase.ProtoM21Object.isClassOrSubclass
         music21.stream.base.Stream:
+        - music21.stream.base.Stream.__eq__
         - music21.stream.base.Stream.__getitem__
         - music21.stream.base.Stream.activateVariants
         - music21.stream.base.Stream.addGroupForElements
         - music21.stream.base.Stream.allPlayingWhileSounding
-        - music21.stream.base.Stream.analyze
         music21.stream.core.StreamCore:
         - music21.stream.core.StreamCore.asTimespans
         - music21.stream.core.StreamCore.asTree
@@ -792,6 +787,8 @@ def methods(self):
         >>> for method in documenter.methods[:10]:
         ...     method
         ...
+        <docbuild.documenters.MethodDocumenter:
+            music21.stream.base.Stream.__eq__>
         <docbuild.documenters.MethodDocumenter:
             music21.stream.base.Stream.__getitem__>
         <docbuild.documenters.MethodDocumenter:
@@ -810,8 +807,6 @@ def methods(self):
             music21.stream.base.Stream.attachMelodicIntervals>
         <docbuild.documenters.MethodDocumenter:
             music21.stream.base.Stream.augmentOrDiminish>
-        <docbuild.documenters.MethodDocumenter:
-            music21.stream.base.Stream.beatAndMeasureFromOffset>
         '''
         return self._methods
 
@@ -830,7 +825,6 @@ def readonlyProperties(self):
         <docbuild.documenters.AttributeDocumenter: music21.stream.base.Stream.beatDuration>
         <docbuild.documenters.AttributeDocumenter: music21.stream.base.Stream.beatStr>
         <docbuild.documenters.AttributeDocumenter: music21.stream.base.Stream.beatStrength>
-        <docbuild.documenters.AttributeDocumenter: music21.stream.base.Stream.flat>
         ...
         '''
         return self._readonlyProperties
@@ -974,6 +968,7 @@ def rstInheritedMethodsFormat(self):
         '.. hlist::'
         '   :columns: 3'
         ''
+        '   - :meth:`~music21.note.GeneralNote.__eq__`'
         '   - :meth:`~music21.note.GeneralNote.addLyric`'
         '   - :meth:`~music21.note.GeneralNote.augmentOrDiminish`'
         '   - :meth:`~music21.note.GeneralNote.getGrace`'
@@ -989,7 +984,6 @@ def rstInheritedMethodsFormat(self):
         '   - :meth:`~music21.base.Music21Object.contextSites`'
         ...
         ''
-
         '''
         mapping = self.inheritedMethodsMapping
         banner = 'Methods inherited from {0}:'
@@ -1051,6 +1045,7 @@ def rstInheritedReadwritePropertiesFormat(self):
         '   - :attr:`~music21.note.NotRest.noteheadFill`'
         '   - :attr:`~music21.note.NotRest.noteheadParenthesis`'
         '   - :attr:`~music21.note.NotRest.stemDirection`'
+        '   - :attr:`~music21.note.NotRest.storedInstrument`'
         '   - :attr:`~music21.note.NotRest.volume`'
         ''
         'Read/write properties inherited from :class:`~music21.note.GeneralNote`:'
@@ -1131,14 +1126,6 @@ def rstMethodsFormat(self):
         ...
         '   - :meth:`~music21.base.Music21Object.splitByQuarterLengths`'
         ''
-        'Methods inherited from :class:`~music21.prebase.ProtoM21Object`:'
-        ''
-        '.. hlist::'
-        '   :columns: 3'
-        ''
-        '   - :meth:`~music21.prebase.ProtoM21Object.isClassOrSubclass`'
-        ''
-
         '''
         result = []
         if self.methods:

documentation/docbuild/iterators.py

@@ -45,8 +45,8 @@ class JupyterNotebookIterator(Iterator):
     ...         break
     ...     print(nb.relative_to(sp))
     documentation/source/about/what.ipynb
-    documentation/source/developerReference/devTest_inversions.ipynb
-    documentation/source/developerReference/devTest_timespans.ipynb
+    documentation/source/developerReference/developerGuidelines.ipynb
+    documentation/source/developerReference/installJupyter.ipynb
     '''
 
     # SPECIAL METHODS #
@@ -165,6 +165,7 @@ class CodebaseIterator(Iterator):
     <class 'music21.articulations.DetachedLegato'>
     <class 'music21.articulations.Doit'>
     <class 'music21.articulations.DoubleTongue'>
+    <class 'music21.articulations.DownBow'>
     '''
 
     # SPECIAL METHODS #
@@ -227,12 +228,12 @@ class FunctionIterator(Iterator):
     ('music21.abcFormat.translate', 'abcToStreamOpus')
     ('music21.abcFormat.translate', 'abcToStreamPart')
     ('music21.abcFormat.translate', 'abcToStreamScore')
+    ('music21.abcFormat.translate', 'metadataToM21Object')
+    ('music21.abcFormat.translate', 'parseABCNote')
     ('music21.abcFormat.translate', 'parseTokens')
     ('music21.abcFormat.translate', 'reBar')
     ('music21.alpha.analysis.fixer', 'getNotesWithinDuration')
     ('music21.alpha.analysis.ornamentRecognizer', 'calculateTrillNoteDuration')
-    ('music21.alpha.analysis.search', 'findConsecutiveScale')
-    ('music21.analysis.discrete', 'analysisClassFromMethodName')
     '''
 
     # SPECIAL METHODS #

documentation/docbuild/writers.py

@@ -261,8 +261,8 @@ def writeIndexRst(self):
         user's guide.  I added this because keeping up the visual
         table of contents and the index.rst was making my life miserable.
 
-        >>> ipRestWriter = IPythonNotebookReSTWriter()
-        >>> #_DOCS_HIDE ipRestWriter.writeIndexRst()
+        >>> jupyterReSTWriter = JupyterNotebookReSTWriter()
+        >>> #_DOCS_HIDE jupyterReSTWriter.writeIndexRst()
 
         WROTE   autogenerated/usersGuide/index.rst
         '''
@@ -344,8 +344,8 @@ def convertOneNotebook(self, jupyterNotebookFilePath):
         '''
         converts one .ipynb file to .rst using nbconvert.
 
-        returns True if IPythonNotebook was converted.
-        returns False if IPythonNotebook's converted .rst file is newer than the .ipynb file.
+        returns True if JupyterNotebook was converted.
+        returns False if JupyterNotebook's converted .rst file is newer than the .ipynb file.
 
         sends AssertionError if jupyterNotebookFilePath does not exist.
         '''
@@ -389,7 +389,7 @@ def cleanConvertedNotebook(self, oldLines, jupyterNotebookFilePath):
 
         while currentLineNumber < len(oldLines):
             currentLine = oldLines[currentLineNumber]
-            # Remove all IPython prompts and the blank line that follows:
+            # Remove all Jupyter prompts and the blank line that follows:
             if jupyterPromptPattern.match(currentLine) is not None:
                 currentLineNumber += 2
                 continue

documentation/source/_themes/m21/static/m21.css

@@ -491,3 +491,8 @@ dt:target, span.highlighted {
 dl.class > dt:first-of-type {
     display: block !important;
 }
+
+.viewcode-link {
+    font-size: 0.85em;
+    font-family: 'Bitter', serif;
+}

documentation/source/about/.ipynb_checkpoints/applications-checkpoint.rst

@@ -16,54 +16,53 @@ The following papers and publications make extensive use of `music21`. Start her
 Cuthbert, Michael Scott Cuthbert and Christopher Ariza. 2010. "`music21`: A
 Toolkit for Computer-Aided Musicology and Symbolic Music Data." In
 *Proceedings of the International Society for Music Information Retrieval*.
-https://www.academia.edu/243058/music21_A_Toolkit_for_Computer_Aided_Musicology_and_Symbolic_Music_Data
+https://www.trecento.com/research/Cuthbert_Ariza_Music21_ISMIR_2010.pdf
 
 
 Then continue with:
 
 Church, Maura and Michael Scott Cuthbert. 2014. "Improving Rhythmic
 Transcriptions via Probability Models Applied Post-OMR." In *Proceedings of the
 International Society for Music Information Retrieval*.
-https://www.academia.edu/7709124/Improving_Rhythmic_Transcriptions_via_Probability_Models_Applied_Post_OMR
+https://www.trecento.com/research/Church_Cuthbert_OMR.pdf
 
 Cuthbert, Michael Scott, Beth Hadley, Lars Johnson, and Christopher Reyes. 2012.
 "Interoperable Digital Musicology Research via `music21` Web Applications."
 From *Joint CLARIN-D/DARIAH Workshop at Digital Humanities Conference Hamburg*.
-https://www.academia.edu/1787946/Interoperable_Digital_Musicology_Research_via_music21_Web_Applications
+https://www.trecento.com/research/Cuthbert_Hadley_Johnson_Reyes_Music21_SOA.pdf
 
 Cuthbert, Michael Scott, Chris Ariza, Jose Cabal-Ugaz, Beth Hadley, and Neena Parikh. 2011.
 "Hidden Beyond MIDI’s Reach:Feature Extraction and Machine Learning with Rich Symbolic Formats
 in `music21`" In *Proceedings of the Neural Information Processing Systems Conference*.
-https://www.academia.edu/1256513/Hidden_Beyond_MIDI_s_Reach_Feature_Extraction_and_Machine_Learning_with_Rich_Symbolic_Formats_in_music21
+https://www.trecento.com/research/Cuthbert_Ariza_Cabal-Ugaz_Hadley_Parikh-Hidden-NIPS2011.pdf
 
 Cuthbert, Michael Scott, Chris Ariza, and Lisa D. Friedland. 2011. "Feature Extraction and
 Machine Learning on Symbolic Music using the `music21` Toolkit" In
 *Proceedings of the International Symposium on Music Information Retrieval*
-https://www.academia.edu/1256514/Feature_Extraction_and_Machine_Learning_on_Symbolic_Music_using_the_music21_Toolkit
+https://www.trecento.com/research/Cuthbert_Ariza_Friedland_Feature-Extraction_ISMIR_2011.pdf
 
 Jordi Barthomé Guillen and Michael Scott Cuthbert. 2011. "Score Following from
 Inaccurate Score and Audio Data using OMR and `music21`." In *Proceedings of the Neural
 Information Processing Systems Conference (Music and Machine Learning, Workshop 4*.
-https://www.academia.edu/1256512/Score_Following_from_Inaccurate_Score_and_Audio_Data_using_OMR_and_music21
+https://www.trecento.com/research/Bartolome-Guillen_Cuthbert_ScoreFollower.pdf
 
 Ariza, C. and Michael Scott Cuthbert. 2011. "The `music21` Stream: A New Object
 Model for Representing, Filtering, and Transforming Symbolic Musical
 Structures." In *Proceedings of the International Computer Music Conference*.
 San Francisco: International Computer Music Association, pp. 61-68.
-Available online at https://www.flexatone.net/static/docs/music21Stream.pdf
+Available online at https://www.trecento.com/research/Ariza_Cuthbert_Stream_ICMC_2011.pdf
 
 Ariza, C. and Michael Scott Cuthbert. 2011. "Analytical and Compositional
 Applications of a Network-Based Scale Model in `music21`." In *Proceedings of the
 International Computer Music Conference*. San Francisco: International Computer
 Music Association, pp. 701-708. Available online at
-https://www.flexatone.net/static/docs/scaleNetwork.pdf
+https://www.trecento.com/research/Ariza_Cuthbert_Scale_ICMC_2011.pdf
 
 Ariza, C. and Michael Scott Cuthbert. 2010. "Modeling Beats, Accents, Beams, and
 Time Signatures Hierarchically with `music21` Meter Objects." In *Proceedings of the
 International Computer Music Conference*. San Francisco: International Computer Music
 Association. 216-223. Available online at
-https://www.academia.edu/243059/Modeling_Beats_Accents_Beams_and_Time_Signatures_Hierarchically_with_music21_Meter_Objects
-
+https://www.trecento.com/research/Ariza_Cuthbert_Meter_ICMC_2010.pdf
 
 Future Goals and Potential Applications
 ---------------------------------------------------
@@ -93,7 +92,3 @@ interesting suggestions. To contact the authors, visit :ref:`about`.
 - Identify potential clefs for fragmentary Renaissance and Medieval pieces that are
   missing their clefs. (Use their staff-lines and minimizing number of melodic and
   harmonic tritones).
-
-
-
-

documentation/source/about/about.rst

@@ -152,7 +152,7 @@ to this project.  Their contributions and generosity are greatly appreciated.
 .. _Seymour Shlien: https://ifdo.ca/~seymour/runabc/esac/esacdatabase.html
 .. _Manuel Op de Coul: https://www.huygens-fokker.org/scala
 .. _John Chambers: http://trillian.mit.edu/~jc/music/book
-.. _Jack Campin: http://www.campin.me.uk/
+.. _Jack Campin: https://web.archive.org/web/20090226015201/http://www.campin.me.uk/
 .. _McGill University: https://works.hcommons.org/records/c6ew2-tth07
 .. _Project Gutenberg: https://www.gutenberg.org/browse/categories/4
 

documentation/source/about/applications.rst

@@ -50,15 +50,13 @@ Ariza, C. and Michael Scott Cuthbert. 2011. "The `music21` Stream: A New Object
 Model for Representing, Filtering, and Transforming Symbolic Musical
 Structures." In *Proceedings of the International Computer Music Conference*.
 San Francisco: International Computer Music Association, pp. 61-68.
-Available online at https://www.flexatone.net/static/docs/music21Stream.pdf
-and https://www.trecento.com/research/Ariza_Cuthbert_Stream_ICMC_2011.pdf
+Available online at https://www.trecento.com/research/Ariza_Cuthbert_Stream_ICMC_2011.pdf
 
 Ariza, C. and Michael Scott Cuthbert. 2011. "Analytical and Compositional
 Applications of a Network-Based Scale Model in `music21`." In *Proceedings of the
 International Computer Music Conference*. San Francisco: International Computer
 Music Association, pp. 701-708. Available online at
-https://www.flexatone.net/static/docs/scaleNetwork.pdf
-and https://www.trecento.com/research/Ariza_Cuthbert_Scale_ICMC_2011.pdf
+https://www.trecento.com/research/Ariza_Cuthbert_Scale_ICMC_2011.pdf
 
 Ariza, C. and Michael Scott Cuthbert. 2010. "Modeling Beats, Accents, Beams, and
 Time Signatures Hierarchically with `music21` Meter Objects." In *Proceedings of the

documentation/source/conf.py

@@ -17,6 +17,7 @@
 from datetime import date
 import os
 import sys
+import sphinx.util.logging as _sxl
 sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration -----------------------------------------------------
@@ -28,10 +29,33 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    # 'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
     'docbuild.extensions',
 ]
 
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable', None),
+    'matplotlib': ('https://matplotlib.org/stable', None),
+}
+
+# Filter noisy ambiguous cross-reference warnings for bare `type`.
+# Sphinx's py-domain resolver partial-matches the four music21 `.type`
+# instance attributes (Barline.type, Tie.type, Duration.type, Ottava.type)
+# before consulting intersphinx, so every `type[X]` annotation triggers a
+# false-positive ambiguity warning. Suppress just that specific message.
+_orig_warning = _sxl.SphinxLoggerAdapter.warning
+def _filtered_warning(self, msg, *args, **kw):
+    if (
+        'more than one target found for cross-reference' in str(msg)
+        and args
+        and args[0] == 'type'
+    ):
+        return
+    return _orig_warning(self, msg, *args, **kw)
+_sxl.SphinxLoggerAdapter.warning = _filtered_warning
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -245,6 +269,8 @@
     r'https://easyabc.sourceforge.net',  # works 2025-10
     # does not find anchor immediately.  should wait longer
     r'https://github.com/cuthbertLab/music21/blob/master/README.md#community-code-of-conduct',
+    r'https://docutils.sourceforge.io/rst.html',  # anti bot?
+    r'https://id.loc.gov/vocabulary/relators.html', # LOC + captcha? Shame!
 ]
 
 # -- Options for manual page output --------------------------------------------