Merge pull request #1739 from cuthbertLab/fix-doctests

music21 9.3.0
cuthbertLab · Oct 29, 2024 · 2d93372 · 2d93372
2 parents 4e90bfc + 2c153ec
commit 2d93372
Show file tree

Hide file tree

Showing 28 changed files with 265 additions and 151 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,13 +1,13 @@
 `Music21` welcomes contributions such as bug reports, new features, fixes, and
 documentation improvements. The
-[project repository](http://www.github.com/cuthbertLab/music21) is hosted at GitHub.
+[project repository](https://github.com/cuthbertLab/music21) is hosted at GitHub.
 
 Information that was formerly here is now in 
-[Developer Reference](https://web.mit.edu/music21/doc/developerReference/index.html)
+[Developer Reference](https://www.music21.org/music21docs/developerReference/index.html)
 
 ## Resources ##
 
-[Module Documentation and User's Guide](https://web.mit.edu/music21/doc/index.html)
+[Module Documentation and User's Guide](https://www.music21.org/music21docs/)
 
 [Mailing List](https://groups.google.com/forum/#!forum/music21list)
 

diff --git a/README.md b/README.md
@@ -40,7 +40,7 @@ See: https://groups.google.com/forum/#!forum/music21list
 
 [Contributing Guide](CONTRIBUTING.md)
 
-## Community Code of Conduct ##
+## Community Code of Conduct<a name="community-code-of-conduct"></a> ##
 
 `Music21` encourages contributions, discussions, and usage from all people interested in
 music and computers. This encouragement extends to all people regardless of (among other aspects)

diff --git a/dist/dist.py b/dist/dist.py
@@ -28,51 +28,51 @@
 
 
 4. run test/warningMultiprocessTest.py for lowest and highest Py version -- fix all warnings!
-4b. run `from music21.test import treeYield
+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()`.
-5. commit and wait for results on GitHub Actions
+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).
 
-6. run documentation/make.py clean  (skip on minor version changes)
-7. run documentation/make.py linkcheck  [*]
-8. run documentation/make.py   [*]
+7. run documentation/make.py clean  (skip on minor version changes)
+8. run documentation/make.py linkcheck  [*]
+9. run documentation/make.py   [*]
 
 [*] you will need sphinx, Jupyter (pip or easy_install), markdown, and pandoc (.dmg) installed
 
-10. ssh to athena.dialup.mit.edu (yes, dialup!), cd music21/doc and rm -rf *  (skip on minor version changes)
+10. move music21 documentation/build/html to music21.org/music21docs/
+    via Amazon S3 (contact MSAC for authentication if need be)
 
-11. run documentation/upload.py or upload via ssh.
-   -- you will need an MIT username and password + a dual authentication passcode
-
-12. zip up documentation/build/html and get ready to upload/delete it.
+11. zip up documentation/build/html and get ready to upload/delete it.
     Rename to music21.v.7.1.0-docs.zip (skip for Alpha/Beta)
 
-13. Run "hatch build" -- requires hatch to be installed "brew install hatch"
+12. Run "hatch build" -- requires hatch to be installed "brew install hatch"
+    This builds the dist/music21-9.3.0.tar.gz and dist/music21-9.3.0-py3-none-any.whl
+    files.  That used to be what *this* script did, but now hatch does it better!
 
-14. Run this file -- it builds the no-corpus version of music21.
-    DO NOT RUN THIS ON A PC -- the Mac .tar.gz might have an incorrect permission if you do.
+13. Run this file: it builds the no-corpus version of music21.
+    DO NOT RUN THIS ON A PC or the Mac .tar.gz might have an incorrect permission if you do.
 
-15. PR and Commit to GitHub at this point w/ commit comment of the new version,
+14. PR and Commit to GitHub at this point w/ commit comment of the new version,
     then don't change anything until the next step is done.
     (.gitignore will avoid uploading the large files created here.)
 
-16. Switch back to master/main branch
+15. Switch back to master/main branch
 
-17. Tag the commit: git tag -a vX.Y.Z -m "music21 vX.Y.Z"
+16. Tag the commit: git tag -a vX.Y.Z -m "music21 vX.Y.Z"
     Don't forget the "v" in the release tag.
     Sanity check that the correct commit was tagged: git log
 
-18. Push tags: git push --tags  (or git push upstream --tags if not on main branch)
+17. Push tags: git push --tags  (or git push upstream --tags if not on main branch)
 
-19. Create a new release on GitHub and upload the TWO non-wheel files created here and docs.
+18. Create a new release on GitHub and upload the TWO non-wheel files created here and docs.
     Drag in this order: .tar.gz, -docs.zip, no-corpus.tar.gz
 
     Finish this before doing the next step, even though it looks like it could be done in parallel.
 
-20. Upload the new file to PyPI with "twine upload music21-7.3.5a2.tar.gz", and same for the
+19. Upload the new file to PyPI with "twine upload music21-7.3.5a2.tar.gz", and same for the
     whl file (but NOT no corpus) [*]
 
     [*] Requires twine to be installed
@@ -87,9 +87,9 @@
         username:your_username
         password:your_password
 
-21. Delete the two .tar.gz files and .whl file in dist.
+20. Delete the two .tar.gz files and .whl file in dist.
 
-22. For starting a new major release create a GitHub branch for the old one.
+21. For starting a new major release create a GitHub branch for the old one.
 
 22. Immediately increment the number in _version.py and run tests on it here
     to prepare for next release.

diff --git a/documentation/source/about/about.rst b/documentation/source/about/about.rst
@@ -10,19 +10,17 @@ the BSD license (see below).
 About the Authors
 -----------------------
 
-**Michael Cuthbert**, the creator of `music21`, is Associate Professor of Music at M.I.T.
+**Michael Cuthbert**, the creator of `music21`, is co-founder and chief music officer of
+`Artusi`_ and former tenured professor of music at M.I.T. where he created the Mellon-Funded
+Digital Humanities lab and taught computational music theory and musicology.
 He received his A.B. *summa cum laude*, A.M. and Ph.D. degrees from Harvard University.
 Cuthbert spent 2004-05 at the American Academy as a Rome Prize winner in Medieval Studies,
 2009-10 as Fellow at Harvard's Villa I Tatti Center for Italian Renaissance Studies
 in Florence, and 2012-13 at the Radcliffe Institute.
 
 Prior to joining the M.I.T. faculty, Cuthbert was on the faculties of Smith
 and Mount Holyoke Colleges.  He has worked extensively on computer-aided musical analysis,
-fourteenth-century music, and the music of the past forty years.  He has published
-on computer-aided treatment of fragments and palimpsests of the late Middle Ages and
-on set analysis of Sub-Saharan African Rhythm and the music of John Zorn. In addition to
-work on music21, Cuthbert is currently writing a book on sacred music in Italy during the
-age of the Black Death and Great Papal Schism.
+fourteenth-century music, and the music since 1960.
 
 **Christopher Ariza** is Emeritus Lead Programmer of `music21` and was
 Visiting Assistant Professor of Music
@@ -41,6 +39,8 @@ degree from Harvard University and his M.A. and Ph.D. degrees from New York Univ
 Additional contributions by many MIT students and visitors and the
 Open Source software community.
 
+.. _Artusi: https://www.artusimusic.com/
+
 
 Acknowledgements
 ----------------
@@ -52,7 +52,7 @@ Funding
 from the **Seaver Institute** and
 the **National Endowment for the Humanities**/Digging into Data research fund.
 
-In addition, we acknowledge consistent support from `M.I.T.`_, the
+In addition, we acknowledge previous support from `M.I.T.`_, the
 `School of Humanities Arts and Social Sciences`_, and the
 `Music and Theater Arts`_ section.
 
@@ -91,6 +91,10 @@ to this project.  Their contributions and generosity are greatly appreciated.
    support and for their contributions to the open source music notation projects,
    including the Bach Goldberg Variations and the Handel Arias included.
 
+* `Jacob Tylor Walls`_, contributed greatly to the type-safety, speed, and test coverage
+   of `music21`.  If your music21 program "just works" without needing to guess what
+   any argument goes where, Jacob is to thank.
+
 * `Donald Byrd`_, researcher on University of Indiana who created
    a schema for computer-aided musicology (along with the source of all sorts of
    examples of how music notation is difficult).
@@ -119,10 +123,10 @@ to this project.  Their contributions and generosity are greatly appreciated.
 * Walter B. Hewlett and Craig Sapp of Stanford's CCARH for support.
 
 * `Justin London` compiled and maintained the list of Second-Viennese
-   row forms now available in serial.py.
+   row forms that form the original backbone of serial.py.
 
 * `McGill University`_ ELVIS project for including the MEI parser. Special thanks to Julie
-   Cumming, Andrew Hankinson, and especially Christopher Antila for contributing.
+   Cumming, Andrew Hankinson, Ichiro Fujinaga, and especially Christopher Antila for contributing.
 
 * `Manuel Op de Coul`_ has kindly gave permission to use the Scala
    scale archive of nearly 4000 scales in music21.
@@ -138,6 +142,7 @@ to this project.  Their contributions and generosity are greatly appreciated.
   Haydn, and Mozart, in musicxml format which we have been able to include in music21.
 
 .. _Donald Byrd: https://web.archive.org/web/20220610200930/https://homes.luddy.indiana.edu/donbyrd/CMNExtremes.htm
+.. _Jacob Tylor Walls: https://jacobtylerwalls.com/
 .. _Laura E. Conrad: http://www.serpentpublications.org/drupal7/
 .. _MuseScore: https://musescore.com/
 .. _Bryen Travis: http://www.bachcentral.com/

diff --git a/documentation/source/developerReference/developerGuidelines.ipynb b/documentation/source/developerReference/developerGuidelines.ipynb
@@ -7,7 +7,7 @@
     "\n",
     "`Music21` welcomes contributions such as bug reports, new features, fixes, and\n",
     "documentation improvements. The\n",
-    "[project repository](http://www.github.com/cuthbertLab/music21) is hosted at GitHub."
+    "[project repository](https://github.com/cuthbertLab/music21) is hosted at GitHub."
    ],
    "metadata": {
     "collapsed": false
@@ -20,7 +20,7 @@
     "\n",
     "Get to know this before contributing:\n",
     "\n",
-    "[Module Documentation and User's Guide](https://web.mit.edu/music21/doc/index.html)\n",
+    "[Module Documentation and User's Guide](https://www.music21.org/music21docs/index.html)\n",
     "\n",
     "[Mailing List](https://groups.google.com/forum/#!forum/music21list)\n",
     "\n",
@@ -186,7 +186,7 @@
     "    - `Music21` was originally designed without this principle in mind, so you will find\n",
     "      parts of the system that do not follow LSP and for backwards compatibility never will.\n",
     "      I (Myke) have personally apologized to Barbara Liskov for my past ignorance.\n",
-    "  - Use [Sphinx formatting](https://web.mit.edu/music21/doc/developerReference/documenting.html#documenting-modules-and-classes)\n",
+    "  - Use [Sphinx formatting](https://www.music21.org/music21docs/developerReference/documenting.html#documenting-modules-and-classes)\n",
     "      to link to classes and methods in docstrings\n",
     "  - Prefer methods that by default do not alter the object passed in and instead return a new one.\n",
     "      It is permitted and encouraged to have an `inPlace: bool = False` argument that allows for\n",
@@ -216,7 +216,7 @@
     "\n",
     "We write doctests and unit tests, and we strive for the total\n",
     "test coverage of the project to increase with every pull request. See the\n",
-    "[developer docs](https://web.mit.edu/music21/doc/developerReference/index.html)\n",
+    "[developer docs](https://www.music21.org/music21docs/developerReference/index.html)\n",
     "to dig in to specific topics like adjusting doctests to prevent\n",
     "actions we don't want executed when running the general test suite (such as opening\n",
     "browser windows or playing music).\n",

diff --git a/documentation/source/developerReference/musicxmlTest.ipynb b/documentation/source/developerReference/musicxmlTest.ipynb
diff --git a/documentation/source/usersGuide/usersGuide_08_installingMusicXML.ipynb b/documentation/source/usersGuide/usersGuide_08_installingMusicXML.ipynb
diff --git a/documentation/source/usersGuide/usersGuide_11_corpusSearching.ipynb b/documentation/source/usersGuide/usersGuide_11_corpusSearching.ipynb
@@ -69,7 +69,7 @@
     {
      "data": {
       "text/plain": [
-       "3193"
+       "3194"
       ]
      },
      "execution_count": 2,

diff --git a/documentation/source/usersGuide/usersGuide_22_graphing.ipynb b/documentation/source/usersGuide/usersGuide_22_graphing.ipynb
diff --git a/documentation/source/usersGuide/usersGuide_44_advancedGraphing.ipynb b/documentation/source/usersGuide/usersGuide_44_advancedGraphing.ipynb
@@ -1122,7 +1122,7 @@
     "\n",
     "* 'alpha' sets transparency, from 0 (transparent) to 1 (opaque).\n",
     "* 'color' gives a color to the data point -- specified like \"red\" or \"green\" or an HTML color like \"#ff0044\"\n",
-    "* 'marker' on a scatter plot will choose a shape for a marker as in [this diagram](https://matplotlib.org/api/markers_api.html)\n",
+    "* 'marker' on a scatter plot will choose a shape for a marker as in [this diagram](https://matplotlib.org/stable/api/markers_api.html)\n",
     "* 'markersize' gives the size of the marker -- notice that we're using matplotlib names, so the \"s\" of size is lowercased (in `music21` almost everything is camelCase)\n",
     "\n",
     "Let's make a new axis class which returns the frequency of each pitch but also changes its marker according to whether it's in a certain key or not:"
@@ -1328,7 +1328,7 @@
    "source": [
     "## Graph Primitives\n",
     "\n",
-    "Untill now, all our our examples have used Plot classes taken from :ref:`moduleGraphPlot` because they were acting on streams to get their data.  If you wanted to make graphs of data not coming from a Stream you could use matplotlib directly -- they have a great tutorial on [using their `pyplot` interface](https://matplotlib.org/users/pyplot_tutorial.html), for instance.  Or if you want to get some of the advantages of the `music21` Plot types without going all the way into matplotlib, there are Graph primitives in the :ref:`moduleGraphPrimitives` module.  Here are some examples of how those work:"
+    "Untill now, all our our examples have used Plot classes taken from :ref:`moduleGraphPlot` because they were acting on streams to get their data.  If you wanted to make graphs of data not coming from a Stream you could use matplotlib directly -- they have a great tutorial on [using their `pyplot` interface]( https://matplotlib.org/2.0.2/users/pyplot_tutorial.html), for instance.  Or if you want to get some of the advantages of the `music21` Plot types without going all the way into matplotlib, there are Graph primitives in the :ref:`moduleGraphPrimitives` module.  Here are some examples of how those work:"
    ]
   },
   {

diff --git a/documentation/source/usersGuide/usersGuide_53_advancedCorpus.ipynb b/documentation/source/usersGuide/usersGuide_53_advancedCorpus.ipynb
@@ -120,9 +120,9 @@
      "text": [
       "/Users/cuthbert/git/music21base/music21/corpus/corpora.py: WARNING: newCorpus metadata cache: starting processing of paths: 0\n",
       "/Users/cuthbert/git/music21base/music21/corpus/corpora.py: WARNING: cache: filename: /var/folders/qg/klchy5t14bb2ty9pswk6c2bw0000gn/T/music21/local-newCorpus.p.gz\n",
-      "metadata.bundles: WARNING: MetadataBundle Modification Time: 1686508943.60752\n",
+      "metadata.bundles: WARNING: MetadataBundle Modification Time: 1730173618.922734\n",
       "metadata.bundles: WARNING: Skipped 0 sources already in cache.\n",
-      "/Users/cuthbert/git/music21base/music21/corpus/corpora.py: WARNING: cache: writing time: 0.202 md items: 0\n",
+      "/Users/cuthbert/git/music21base/music21/corpus/corpora.py: WARNING: cache: writing time: 0.035 md items: 0\n",
       "\n",
       "/Users/cuthbert/git/music21base/music21/corpus/corpora.py: WARNING: cache: filename: /var/folders/qg/klchy5t14bb2ty9pswk6c2bw0000gn/T/music21/local-newCorpus.p.gz\n"
      ]
@@ -290,7 +290,7 @@
     {
      "data": {
       "text/plain": [
-       "<music21.metadata.RichMetadata object at 0x11804b950>"
+       "<music21.metadata.RichMetadata object at 0x10af31690>"
       ]
      },
      "execution_count": 10,
@@ -521,7 +521,7 @@
     {
      "data": {
       "text/plain": [
-       "<music21.metadata.bundles.MetadataBundle 'core': {15111 entries}>"
+       "<music21.metadata.bundles.MetadataBundle 'core': {15112 entries}>"
       ]
      },
      "execution_count": 16,
@@ -609,7 +609,7 @@
     {
      "data": {
       "text/plain": [
-       "<music21.metadata.bundles.MetadataBundle 'core': {15111 entries}>"
+       "<music21.metadata.bundles.MetadataBundle 'core': {15112 entries}>"
       ]
      },
      "execution_count": 20,
@@ -638,7 +638,7 @@
     {
      "data": {
       "text/plain": [
-       "<music21.metadata.bundles.MetadataBundle 'core': {15111 entries}>"
+       "<music21.metadata.bundles.MetadataBundle 'core': {15112 entries}>"
       ]
      },
      "execution_count": 21,

diff --git a/music21/_version.py b/music21/_version.py
@@ -47,7 +47,7 @@
 '''
 from __future__ import annotations
 
-__version__ = '9.2.0b2'
+__version__ = '9.3.0'
 
 def get_version_tuple(vv):
     v = vv.split('.')

diff --git a/music21/audioSearch/recording.py b/music21/audioSearch/recording.py
@@ -12,7 +12,7 @@
 '''
 modules for audio searching that directly record from the microphone.
 
-Requires PyAudio and portaudio to be installed (http://www.portaudio.com/download.html)
+Requires PyAudio and portaudio to be installed (https://www.portaudio.com/download.html)
 
 To download pyaudio for windows 64-bit go to https://www.lfd.uci.edu/~gohlke/pythonlibs/
 
@@ -37,7 +37,7 @@
 # to download pyaudio for windows 64-bit go to https://www.lfd.uci.edu/~gohlke/pythonlibs/
 # users of 64-bit windows but 32-bit python should download the win32 port
 # users of 64-bit windows and 64-bit python should download the amd64 port
-# requires portaudio to be installed http://www.portaudio.com/download.html
+# requires portaudio to be installed https://www.portaudio.com/download.html
 
 default_recordChannels = 1
 default_recordSampleRate = 44100

diff --git a/music21/base.py b/music21/base.py
@@ -27,7 +27,7 @@
 <class 'music21.base.Music21Object'>
 
 >>> music21.VERSION_STR
-'9.2.0b2'
+'9.3.0'
 
 Alternatively, after doing a complete import, these classes are available
 under the module "base":

diff --git a/music21/braille/segment.py b/music21/braille/segment.py
@@ -14,7 +14,7 @@
 This module was made in consultation with the manual "Introduction to Braille
 Music Transcription, Second Edition" by Mary Turner De Garmo, 2005. It is
 available from the Library of Congress
-`here <https://www.loc.gov/nls/braille-audio-reading-materials/music-materials/>`_,
+`here <https://www.loc.gov/nls/services-and-resources/music-service-and-materials/>`_,
 and will henceforth be referred to as BMTM.
 '''
 from __future__ import annotations

diff --git a/music21/braille/test.py b/music21/braille/test.py
@@ -53,7 +53,7 @@ def example11_2():
 # Examples follow the order in:
 #   Introduction to Braille Music Transcription, Second Edition (2005)
 # Mary Turner De Garmo
-# https://www.loc.gov/nls/music/
+# https://www.loc.gov/nls/services-and-resources/music-service-and-materials/
 # ------------------------------------------------------------------------------
 class Test(unittest.TestCase):
     '''

diff --git a/music21/braille/translate.py b/music21/braille/translate.py
@@ -13,7 +13,7 @@
 This module was made in consultation with the manual "Introduction to Braille
 Music Transcription, Second Edition" by Mary Turner De Garmo, 2005. It is
 available from the Library of Congress
-`here <https://www.loc.gov/nls/braille-audio-reading-materials/music-materials/>`_,
+`here <https://www.loc.gov/nls/services-and-resources/music-service-and-materials/>`_,
 and will henceforth be referred to as BMTM.
 
 

diff --git a/music21/common/misc.py b/music21/common/misc.py
@@ -115,26 +115,26 @@ def getMissingImportStr(modNameList):
     >>> print(common.getMissingImportStr(['matplotlib']))
     Certain music21 functions might need the optional package matplotlib;
     if you run into errors, install it by following the instructions at
-    http://mit.edu/music21/doc/installing/installAdditional.html
+    https://www.music21.org/music21docs/installing/installAdditional.html
 
     >>> print(common.getMissingImportStr(['matplotlib', 'numpy']))
     Certain music21 functions might need these optional packages: matplotlib, numpy;
     if you run into errors, install them by following the instructions at
-    http://mit.edu/music21/doc/installing/installAdditional.html
+    https://www.music21.org/music21docs/installing/installAdditional.html
     '''
     if not modNameList:
         return None
     elif len(modNameList) == 1:
         m = modNameList[0]
         return textwrap.dedent(f'''Certain music21 functions might need the optional package {m};
                   if you run into errors, install it by following the instructions at
-                  http://mit.edu/music21/doc/installing/installAdditional.html''')
+                  https://www.music21.org/music21docs/installing/installAdditional.html''')
     else:
         m = ', '.join(modNameList)
         return textwrap.dedent(
             f'''Certain music21 functions might need these optional packages: {m};
                    if you run into errors, install them by following the instructions at
-                   http://mit.edu/music21/doc/installing/installAdditional.html''')
+                   https://www.music21.org/music21docs/installing/installAdditional.html''')
 
 
 def getPlatform() -> str: