.. _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 complete listing of works in the music21 corpus, visit  :ref:`referenceCorpus`. 


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

    Search the corpus, then the virtual corpus, for a work, and return a parsed :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. If `forceSource` is True, the original file will always be loaded and pickled files, if available, will be ignored. 

    >>> aStream = parse('opus74no1/movement3')

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

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

.. 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. 

    >>> import os
    >>> a = getWork('opus74no2', 4)
    >>> a.endswith(os.path.sep.join(['haydn', 'opus74no2', 'movement4.xml']))
    True 
    >>> a = getWork(['haydn', 'opus74no2', 'movement4.xml'])
    >>> a.endswith(os.path.sep.join(['haydn', 'opus74no2', 'movement4.xml']))
    True 

    

.. 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. 

    >>> a = getBachChorales()
    >>> len(a) > 400
    True 
    >>> a = getBachChorales('krn')
    >>> len(a) > 10
    False 
    >>> a = getBachChorales('xml')
    >>> len(a) > 400
    True 

.. function:: getBeethovenStringQuartets(extList=None)

    Return all Beethoven String Quartets. 

    >>> a = getBeethovenStringQuartets()
    >>> len(a) > 10
    True 
    >>> a = getBeethovenStringQuartets('krn')
    >>> len(a) < 10 and len(a) > 0
    True 
    >>> a = 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. 

    >>> a = getComposer('beethoven')
    >>> len(a) > 10
    True 
    >>> a = getComposer('mozart')
    >>> len(a) > 10
    True 
    >>> a = getComposer('bach', 'krn')
    >>> len(a) < 10
    True 
    >>> a = 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 

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

.. function:: getLocalPaths(extList=None)

    Access files in additional directories supplied by the user and defined in environement settings. 

.. function:: getPaths(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. 

    >>> a = getPaths()
    >>> len(a) > 30
    True 
    >>> a = getPaths('krn')
    >>> len(a) >= 4
    True 
    >>> a = getPaths('abc')
    >>> len(a) >= 10
    True 

    

.. function:: getVirtualPaths(extList=None)

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

    >>> len(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. 

    >>> getVirtualWorkList('bach/bwv1007/prelude')
    ['http://kern.ccarh.org/cgi-bin/ksdata?l=cc/bach/cello&file=bwv1007-01.krn&f=xml'] 
    >>> 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. 

    >>> len(getWorkList('beethoven/opus18no1'))
    8 
    >>> len(getWorkList('beethoven/opus18no1', 1))
    2 
    >>> len(getWorkList('beethoven/opus18no1', 1, '.krn'))
    1 
    >>> len(getWorkList('beethoven/opus18no1', 1, '.xml'))
    1 
    >>> len(getWorkList('beethoven/opus18no1', 0, '.xml'))
    0 
    >>> len(getWorkList('handel/hwv56', '1-01', '.md'))
    1 
    >>> len(getWorkList('handel/hwv56', (1,1), '.md'))
    1 
    >>> len(getWorkList('bach/bwv1080', 1, '.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. 

    >>> post = getWorkReferences()

.. function:: search(query, field=None, domain=['core', 'virtual'], 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). This method uses stored metadata and thus, on first usage, will incur a performance penalty during metadata loading. 

