.. _moduleCorpus.base:

music21.corpus.base
===================

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: music21.corpus.base


The music21 corpus provides a collection of freely distributable music in MusicXML, Humdrum, and other representations. The corpus package provides an interface to this data.

To see a complete listing of the works in the music21 corpus, visit  :ref:`referenceCorpus`.




.. function:: parse(workName, movementNumber=None, number=None, extList=None, forceSource=False)


    The most important method call for corpus.

    Similar to converer.parse(), the method searches the corpus (including the virtual corpus)
    for a work fitting the workName description and returns a :class:`music21.stream.Stream`.

    If `movementNumber` is defined, and a movement is included in the corpus, that movement will be returned.

    If `number` is defined, and the work is a collection with multiple components, that work number will be returned.
    For instance, some of our ABC documents contain dozens of folk songs within a single file.

    Advanced: if `forceSource` is True, the original file will always be loaded freshly and pickled (e.g., pre-parsed) files
    will be ignored.  This should not be needed if the file has been changed, since the filetime of the file and
    the filetime of the pickled version are compared.  But it might be needed if the music21 parsing routine has changed.


    Example, get a chorale by Bach.  Note that the source type does not need to be
    specified, nor does the name Bach even (since it's the only piece with the title BWV 66.6)



    >>> from music21 import *
    >>> bachChorale = corpus.parse('bwv66.6')
    >>> len(bachChorale.parts)
    4




.. function:: getWork(workName, movementNumber=None, extList=None)

    Search the corpus, then the virtual corpus, for a work, and return a file path or URL. This method will return either a list of file paths or, if there is a single match, a single file path. If no matches are found an Exception is raised.



    >>> from music21 import *
    >>> import os
    >>> a = corpus.getWork('opus74no2', 4)
    >>> a.endswith(os.path.sep.join(['haydn', 'opus74no2', 'movement4.mxl']))
    True
    ⁠ 
    >>> a = corpus.getWork(['haydn', 'opus74no2', 'movement4.xml'])
    >>> a.endswith(os.path.sep.join(['haydn', 'opus74no2', 'movement4.mxl']))
    True




.. function:: addPath(fp)

    Add a directory path to the local corpus on a temporary basis, i.e., just for the current Python session. All directories contained within the provided directory will be searched for files with file extensions matching the currently readable file types. Any number of file paths can be added one at a time.

    An error will be raised if the file path does not exist, is already defined as a temporary, or is already being searched by being defined with the :class:`~music21.environment.Environment` 'localCorpusSettings' setting.

    To permanently add a path to the list of stored local corpus paths, set the 'localCorpusPath' or 'localCorpusSettings' setting of the :class:`~music21.environment.UserSettings` object.



    >>> from music21 import *
    >>> coprus.addPath('~/Documents')




.. function:: cacheMetadata(domainList=['local'])


.. function:: compressAllXMLFiles(deleteOriginal=False)


    Takes all filenames in corpus.paths and runs :meth:`music21.corpus.base.compressXML` on each.
    If the musicXML files are compressed, the originals are deleted from the system.



.. function:: compressXML(filename, deleteOriginal=False)


    Takes a filename, and if the filename corresponds to a musicXML file with an .xml extension,
    creates a corresponding compressed .mxl file in the same directory. If deleteOriginal is set
    to True, the original musicXML file is deleted from the system.



.. function:: getBachChorales(extList='xml')

    Return the file name of all Bach chorales.

    By default, only Bach Chorales in xml format are returned, because the quality of
    the encoding and our parsing of those is superior.



    >>> from music21 import *
    >>> a = corpus.getBachChorales()
    >>> len(a) > 400
    True
    >>> a = corpus.getBachChorales('krn')
    >>> len(a) > 10
    False
    >>> a = corpus.getBachChorales('xml')
    >>> len(a) > 400
    True



.. function:: getBeethovenStringQuartets(extList=None)

    Return all Beethoven String Quartets.



    >>> from music21 import *
    >>> a = corpus.getBeethovenStringQuartets()
    >>> len(a) > 10
    True
    >>> a = corpus.getBeethovenStringQuartets('krn')
    >>> len(a) < 10 and len(a) > 0
    True
    >>> a = corpus.getBeethovenStringQuartets('xml')
    >>> len(a) > 400
    False



.. function:: getComposer(composerName, extList=None)

    Return all components of the corpus that match a composer's or a collection's name. An `extList`, if provided, defines which extensions are returned. An `extList` of None returns all extensions.



    >>> from music21 import *
    >>> a = corpus.getComposer('beethoven')
    >>> len(a) > 10
    True
    >>> a = corpus.getComposer('mozart')
    >>> len(a) > 10
    True
    >>> a = corpus.getComposer('bach', 'krn')
    >>> len(a) < 10
    True
    >>> a = corpus.getComposer('bach', 'xml')
    >>> len(a) > 10
    True



.. function:: getComposerDir(composerName)

    Given the name of a composer, get the path to the top-level directory
    of that composer



    >>> from music21 import *
    >>> import os
    >>> a = corpus.getComposerDir('beethoven')
    >>> a.endswith(os.path.join('corpus', os.sep, 'beethoven'))
    True
    >>> a = corpus.getComposerDir('bach')
    >>> a.endswith(os.path.join('corpus', os.sep, 'bach'))
    True
    >>> a = corpus.getComposerDir('mozart')
    >>> a.endswith(os.path.join('corpus', os.sep, 'mozart'))
    True
    >>> a = corpus.getComposerDir('luca')
    >>> a.endswith(os.path.join('corpus', os.sep, 'luca'))
    True



.. function:: getCorePaths(extList=None, expandExtensions=True)

    Get all paths in the corpus that match a known extension, or an extenion
    provided by an argument.

    If `expandExtensions` is True, a format for an extension, and related extensions, will replaced by all known input extensions. This is convenient when an input format might match for multiple extensions.



    >>> from music21 import *
    ⁠ 
    >>> a = corpus.getCorePaths()
    >>> len(a) # the current number of paths; update when adding to corpus
    2208



    >>> a = corpus.getCorePaths('krn')
    >>> len(a) >= 4
    True
    ⁠ 
    >>> a = corpus.getCorePaths('abc')
    >>> len(a) >= 10
    True




.. function:: getHandelMessiah(extList='md')

    Return the file name of all of handel's messiah.



    >>> from music21 import *
    >>> a = corpus.getHandelMessiah()
    >>> len(a)
    43



.. function:: getLocalPaths(extList=None, expandExtensions=True)


    Access files in additional directories supplied by the user and defined in environement settings. If addtional paths are added on a per-session basis witht the :func:`~music21.corpus.addPath` function, these paths are also retuned with this method.



.. function:: getMonteverdiMadrigals(extList='xml')

    Return the file name of all Monteverdi madrigals.



    >>> from music21 import *
    >>> a = corpus.getMonteverdiMadrigals()
    >>> len(a) > 40
    True



.. function:: getPaths(extList=None, expandExtensions=True, domain=['core', 'virtual', 'local'])

    Get paths from core, virtual, and/or local domains. This is the public interface for getting all corpus paths with one function.



.. function:: getVirtualPaths(extList=None, expandExtensions=True)

    Get all paths in the virtual corpus that match a known extension. An extension of None will return all known extensions.



    >>> from music21 import *
    >>> len(corpus.getVirtualPaths()) > 6
    True



.. function:: getVirtualWorkList(workName, movementNumber=None, extList=None)

    Given a work name, search all virtual works and return a list of URLs for any matches.



    >>> from music21 import *
    >>> corpus.getVirtualWorkList('bach/bwv1007/prelude')
    ['http://kern.ccarh.org/cgi-bin/ksdata?l=cc/bach/cello&file=bwv1007-01.krn&f=xml']
    ⁠ 
    >>> corpus.getVirtualWorkList('junk')
    []



.. function:: getWorkList(workName, movementNumber=None, extList=None)

    Search the corpus and return a list of works, always in a list. If no matches are found, an empty list is returned.



    >>> from music21 import *
    >>> len(corpus.getWorkList('beethoven/opus18no1'))
    8
    >>> len(corpus.getWorkList('beethoven/opus18no1', 1))
    2
    >>> len(corpus.getWorkList('beethoven/opus18no1', 1, '.krn'))
    1
    >>> len(corpus.getWorkList('beethoven/opus18no1', 1, '.xml'))
    1
    >>> len(corpus.getWorkList('beethoven/opus18no1', 0, '.xml'))
    0
    >>> len(corpus.getWorkList('handel/hwv56', '1-02', '.md'))
    1
    >>> len(corpus.getWorkList('handel/hwv56', (2,1), '.md'))
    1
    ⁠ 
    >>> len(corpus.getWorkList('bach/bwv1080', 2, '.md'))
    1




.. function:: getWorkReferences(sort=True)

    Return a data dictionary for all works in the corpus and (optionally) the virtual corpus. Returns a list of reference dictionaries, each each dictionary for a each composer. A 'works' dictionary for each composer provides references to dictionaries for all associated works.

    This is used in the generation of corpus documentation



    >>> from music21 import *
    >>> post = corpus.getWorkReferences()



.. function:: parseWork(*arguments, **keywords)

    This function exists for backwards compatibility. All calls should use :func:`~music21.corpus.parse` instead.



.. function:: search(query, field=None, domain=['core', 'virtual', 'local'], extList=None)

    Search all stored metadata and return a list of file paths; to
    return a list of parsed Streams, use searchParse().

    The `domain` parameter can be used to specify one of three corpora:
    core (included with music21), virtual (defined in music21 but hosted
    online), and local (hosted on the user's system (not yet implemented)).

    This method uses stored metadata and thus, on first usage, will
    incur a performance penalty during metadata loading.



BachChoraleList
---------------



.. class:: BachChoraleList()


    A searchable list of BachChorales by various numbering systems:

    Note that multiple chorales share the same title, so it's best to
    iterate over one of the other lists to get them all.




    >>> from music21 import *
    >>> bcl = corpus.BachChoraleList()
    >>> info358 = bcl.byBudapest[358]
    >>> for key in info358.keys():
    ...   print key, info358[key]
    budapest 358
    bwv 431
    title Wenn wir in höchsten Nöten sein
    notes None
    baerenreiter 68
    riemenschneider 68
    kalmus 358
    >>> c = corpus.parse('bach/bwv' + str(info358['bwv']))
    >>> c.show() # shows Bach BWV431



    **BachChoraleList** **attributes**

        Attributes without Documentation: `byKalmus`, `byBaerenreiter`, `byBWV`, `byBudapest`, `byTitle`, `byRiemenschneider`

    **BachChoraleList** **methods**

        .. method:: prepareList()


            puts a list of Bach Chorales into dicts of dicts called

            self.byBudapest
            self.byBWV
            self.byRiemenschneider

            etc.




