def 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
    '''
    if not common.isListLike(extList):
        extList = [extList]

    paths = getPaths(extList)
    post = []

    # permit workName to be a list of paths/branches
    if common.isListLike(workName):
        workName = os.path.sep.join(workName)
    # replace with os-dependent separators 
    workSlashes = workName.replace('/', os.path.sep)

    for path in paths:
        if workName.lower() in path.lower():
            post.append(path)
        elif workSlashes.lower() in path.lower():
            post.append(path)

    post.sort()
    postMvt = []
    if movementNumber is not None and len(post) > 0:
        movementStrList = ['movement%s' % movementNumber]
        for fp in post:
            for movementStr in movementStrList:
                if movementStr.lower() in fp.lower():
                    postMvt.append(fp)
        if len(postMvt) == 0:
            pass # return an empty list
    else:
        postMvt = post

    if len(postMvt) == 0:
        return []
    else:
        return postMvt

def getWork(workName, movementNumber=None, fileExtensions=None):
    '''
    Search the corpus, then the virtual corpus, for a work, and return a file
    path or URL.  N.B. does not parse the work: but it's suitable for passing
    to converter.parse.

    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
        >>> from music21 import corpus
        >>> 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

    ::

        >>> trecentoFiles = corpus.getWork('trecento')
        >>> len(trecentoFiles) > 100 and len(trecentoFiles) < 200
        True

    '''
    if not common.isListLike(fileExtensions):
        fileExtensions = [fileExtensions]
    results = getWorkList(workName, movementNumber, fileExtensions)
    if len(results) == 0:
        if common.isListLike(workName):
            workName = os.path.sep.join(workName)
        if workName.endswith(".xml"):  # might be compressed MXL file
            newWorkName = workName[0:len(workName) - 4] + ".mxl"
            return getWork(newWorkName, movementNumber, fileExtensions)
        results = getVirtualWorkList(workName, movementNumber, fileExtensions)
    if len(results) == 1:
        return results[0]
    elif len(results) == 0:
        raise CorpusException(
            'Could not find a file/url that met these criteria')
    return results

    def getDoc(self, partName):
        element = self.getElement(partName)

        if hasattr(self.srcNameEval, '_DOC_ATTR'):
            docAttr = self.srcNameEval._DOC_ATTR
        else:
            docAttr = {}

        match = None
                
        if partName in docAttr.keys():
            match = docAttr[partName]
        # if its an undocumented public attribute and basic python
        # data structure, we do not want to show that documentation
        elif (element.kind in ['data'] and (
            common.isStr(element.object) or 
            common.isListLike(element.object) or
            common.isNum(element.object)
            )):
            pass
        else:
            try:
                match = element.object.__doc__
            except AttributeError:
                match = None

        if match == None:
            return NO_DOC
        else:
            return match

    def __setitem__(self, key, value):
        """
        Dictionary-like setting. Changes are made and written to the user
        configuration file.

        >>> from music21 import environment
        >>> us = environment.UserSettings()
        >>> us['musicxmlPath'] = 'asdfwerasdffasdfwer'
        Traceback (most recent call last):
        UserSettingsException: attempting to set a path that does not exist: asdfwerasdffasdfwer

        >>> us['localCorpusPath'] = '/path/to/local'
        Traceback (most recent call last):
        UserSettingsException: attempting to set a path that does not exist: /path/to/local
        """
        # NOTE: testing setting of any UserSettings key will result
        # in a change in your local preferences files

        # before setting value, see if this is a path and test existence
        # this will accept localCorpusPath
        if key in self._environment.getKeysToPaths():
            # try to expand user if found; otherwise return unaltered
            if value is not None:
                value = os.path.expanduser(value)
                if not os.path.exists(value):
                    raise UserSettingsException("attempting to set a path that does not exist: {}".format(value))
        # when setting a local corpus setting, if not a list, append
        elif key == "localCorpusSettings":
            if not common.isListLike(value):
                raise UserSettingsException("localCorpusSettings must be provided as a list.")
        # location specific, cannot test further
        self._environment.__setitem__(key, value)
        self._environment.write()

    def __init__(self, target=()):
        super().__init__()
        if not common.isListLike(target):
            target = (target,)

        self.target = target
        self.numToFind = len(target)

def getWork(workName, movementNumber=None, extList=None):
    '''Search the corpus, then the virtual corpus, for a work. 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

    '''
    if not common.isListLike(extList):
        extList = [extList]

    post = getWorkList(workName, movementNumber, extList)
    if len(post) == 0:
        post = getVirtualWorkList(workName, movementNumber, extList)

    if len(post) == 1:
        return post[0]
    elif len(post) == 0:
        raise CorpusException("Could not find a file/url that met this criteria")
    else: # return a list
        return post

def parse(value, *args, **keywords):
    '''Given a file path, encoded data in a Python string, or a URL, attempt to parse the item into a Stream. Note: URL downloading will not happen automatically unless the user has set their Environment "autoDownload" preference to "allow". 

    >>> s = parse(["E4 r f# g=lastG trip{b-8 a g} c", "3/4"])
    >>> s = parse("E8 f# g#' G f g# g G#", "2/4")

    '''

    #environLocal.printDebug(['attempting to parse()', value])
    if 'forceSource' in keywords.keys():
        forceSource = keywords['forceSource']
    else:   
        forceSource = False

    if common.isListLike(value) or len(args) > 0: # tiny notation list
        if len(args) > 0: # add additional args to a lost
            value = [value] + list(args)
        return parseData(value)
    elif os.path.exists(value):
        return parseFile(value, forceSource=forceSource)
    elif value.startswith('http://'): 
        # its a url; may need to broaden these criteria
        return parseURL(value, forceSource=forceSource)
    else:
        return parseData(value)

    def parseFile(self, fp, number=None):
        '''
        parse fp and number
        '''
        from music21 import converter
        from music21 import musedata as musedataModule
        from music21.musedata import translate as musedataTranslate

        mdw = musedataModule.MuseDataWork()

        af = converter.ArchiveManager(fp)

        #environLocal.printDebug(['ConverterMuseData: parseFile', fp, af.isArchive()])
        # for dealing with one or more files
        if fp.endswith('.zip') or af.isArchive():
            #environLocal.printDebug(['ConverterMuseData: found archive', fp])
            # get data will return all data from the zip as a single string
            for partStr in af.getData(dataFormat='musedata'):
                #environLocal.printDebug(['partStr', len(partStr)])
                mdw.addString(partStr)
        else:
            if os.path.isdir(fp):
                mdd = musedataModule.MuseDataDirectory(fp)
                fpList = mdd.getPaths()
            elif not common.isListLike(fp):
                fpList = [fp]
            else:
                fpList = fp

            for fp in fpList:
                mdw.addFile(fp)

        #environLocal.printDebug(['ConverterMuseData: mdw file count', len(mdw.files)])

        musedataTranslate.museDataWorkToStreamScore(mdw, self.stream)

def parseWork(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 = parseWork('opus74no1/movement3')
    '''
    if not common.isListLike(extList):
        extList = [extList]

    post = getWorkList(workName, movementNumber, extList)
    #environLocal.printDebug(['result of getWorkList()', post])
    if len(post) == 0:
        post = getVirtualWorkList(workName, movementNumber, extList)    

    if len(post) == 1:
        fp = post[0]
    elif len(post) == 0:
        raise CorpusException("Could not find a work that met this criteria")
    else: # greater than zero:
        fp = post[0] # get first
      
    return converter.parse(fp, forceSource=forceSource, number=number)

    def getWorkList(
        self,
        workName,
        movementNumber=None,
        fileExtensions=None,
        ):
        '''
        Given a work name, search all virtual works and return a list of URLs
        for any matches.

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

        >>> virtualCorpus.getWorkList('junk')
        []

        '''
        if not common.isListLike(fileExtensions):
            fileExtensions = [fileExtensions]
        for obj in VirtualCorpus._virtual_works:
            if obj.corpusPath is not None and \
                workName.lower() in obj.corpusPath.lower():
                return obj.getUrlByExt(fileExtensions)
        return []

 def _setPitches(self, value):
     if common.isListLike(value):
         if 'Pitch' in value[0].classes:
             self.pitch = value[0]
         else:
             raise NoteException('must provide a list containing a Pitch, not: %s' % value)
     else:
         raise NoteException('cannot set pitches with provided object: %s' % value)

def cacheMetadata(
    corpusNames=('local', 'core', 'virtual'),
    useMultiprocessing=True,
    ):
    '''
    Cache metadata from corpuses in `corpusNames` as local cache files:

    Call as ``metadata.cacheMetadata()``

    '''
    from music21 import corpus
    from music21 import metadata

    if not common.isListLike(corpusNames):
        corpusNames = (corpusNames,)

    timer = common.Timer()
    timer.start()

    # store list of file paths that caused an error
    failingFilePaths = []

    # the core cache is based on local files stored in music21
    # virtual is on-line
    for corpusName in corpusNames:
        if corpusName == 'core':
            metadataBundle = metadata.MetadataBundle.fromCoreCorpus()
            paths = corpus.getCorePaths()
            useCorpus = True
        elif corpusName == 'local':
            metadataBundle = metadata.MetadataBundle.fromLocalCorpus()
            paths = corpus.getLocalPaths()
            useCorpus = False
        elif corpusName == 'virtual':
            metadataBundle = metadata.MetadataBundle.fromVirtualCorpus()
            paths = corpus.getVirtualPaths()
            useCorpus = False
        else:
            message = 'invalid corpus name provided: {0!r}'.format(corpusName)
            raise MetadataCacheException(message)
        message = 'metadata cache: starting processing of paths: {0}'.format(
                len(paths))
        environLocal.printDebug(message)
        failingFilePaths += metadataBundle.addFromPaths(
            paths,
            useCorpus=useCorpus,
            useMultiprocessing=useMultiprocessing,
            )
        message = 'cache: writing time: {0} md items: {1}'.format(
            timer, len(metadataBundle))
        environLocal.printDebug(message)
        del metadataBundle
    message = 'cache: final writing time: {0} seconds'.format(timer)
    environLocal.printDebug(message)
    for failingFilePath in failingFilePaths:
        message = 'path failed to parse: {0}'.format(failingFilePath)
        environLocal.printDebug(message)

def cacheMetadata(corpusNames=('local',)):
    '''
    Rebuild the metadata cache.
    '''
    if not common.isListLike(corpusNames):
        corpusNames = [corpusNames]
    for name in corpusNames:
        corpora.Corpus._metadataBundles[name] = None
    metadata.cacheMetadata(corpusNames)

def 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

    '''
    if not common.isListLike(extList):
        extList = [extList]

    if extList == [None]:
        extList = _ALL_EXTENSIONS
    elif expandExtensions:
        extMod = []
        for e in extList:
            extMod += common.findInputExtension(e)
        extList = extMod
        
    #environLocal.printDebug(['getting paths with extensions:', extList])
    paths = []    
    for moduleName in MODULES:
        if not hasattr(moduleName, '__path__'):
            # when importing a package name (a directory) the moduleName        
            # may be a list of all paths contained within the package
            # this seems to be dependent on the context of the call:
            # from the command line is different than from the interpreter
            dirListing = moduleName
        else:
            # returns a list with one or more paths
            # the first is the path to the directory that contains xml files
            dir = moduleName.__path__[0] 
            dirListing = [os.path.join(dir, x) for x in os.listdir(dir)]

        for fp in dirListing:
            if fp in paths:
                continue
            match = False
            for ext in extList:
                if fp.endswith(ext):
                    match = True
                    break 
            if match:
                if fp not in paths:
                    paths.append(fp)    
    return paths

 def _dynamicToWeight(targets):
     # permit a stream
     if hasattr(targets, 'isStream') and targets.isStream:
         pass
     elif not common.isListLike(targets):
         targets = [targets]
     summation = 0
     for e in targets: # a Stream
         summation += e.volumeScalar # for dynamics
     return summation / float(len(target))

    def __setitem__(self, key, value):
        #saxutils.escape # used for escaping strings going to xml
        # with unicode encoding
        # http://www.xml.com/pub/a/2002/11/13/py-xml.html?page=2
        # saxutils.escape(msg).encode('UTF-8')

        # add local corpus path as a key
        #if six.PY3 and isinstance(value, bytes):
        #    value = value.decode(errors='replace')
        if 'path' in key.lower() and value is not None:
            value = common.cleanpath(value)
        
        if key not in self._ref:
            if key != 'localCorpusPath':
                raise EnvironmentException('no preference: %s' % key)
        if value == '':
            value = None  # always replace '' with None

        valid = False
        if key == 'showFormat':
            value = value.lower()
            if value in common.VALID_SHOW_FORMATS:
                valid = True
        elif key == 'writeFormat':
            value = value.lower()
            if value in common.VALID_WRITE_FORMATS:
                valid = True
        elif key == 'autoDownload':
            value = value.lower()
            if value in common.VALID_AUTO_DOWNLOAD:
                valid = True
        elif key == 'localCorpusSettings':
            # needs to be a list of strings for now
            if common.isListLike(value):
                valid = True
        else:  # temporarily not validating other preferences
            valid = True

        if not valid:
            raise EnvironmentException(
                '{} is not an acceptable value for preference: {}'.format(
                    value, key))

        # need to escape problematic characters for xml storage
        if isinstance(value, six.string_types):
            value = saxutils.escape(value) #.encode('UTF-8')
        # set value
        if key == 'localCorpusPath':
            # only add if unique
            #value = xmlnode.fixBytes(value)
            if value not in self._ref['localCorpusSettings']:
                # check for malicious values here
                self._ref['localCorpusSettings'].append(value)
        else:
            self._ref[key] = value

    def _translateExtensions(
        self,
        fileExtensions=None,
        expandExtensions=True,
        ):
        '''
        Utility to get default extensions, or, optionally, expand extensions to
        all known formats.

        >>> from music21 import corpus
        >>> coreCorpus = corpus.CoreCorpus()
        >>> for extension in coreCorpus._translateExtensions():
        ...     extension
        ...
        '.abc'
        '.capx'
        '.mid'
        '.midi'
        '.xml'
        '.mxl'
        '.mx'
        '.musicxml'
        '.md'
        '.musedata'
        '.zip'
        '.krn'
        '.rntxt'
        '.rntext'
        '.romantext'
        '.rtxt'
        '.nwctxt'
        '.nwc'

        >>> coreCorpus._translateExtensions('.mid', False)
        ['.mid']

        >>> coreCorpus._translateExtensions('.mid', True)
        ['.mid', '.midi']

        '''
        if not common.isListLike(fileExtensions):
            fileExtensions = [fileExtensions]
        if fileExtensions == [None]:
            fileExtensions = Corpus._allExtensions
        elif expandExtensions:
            expandedExtensions = []
            for extension in fileExtensions:
                allInputExtensions = common.findInputExtension(extension)
                if allInputExtensions is None:
                    pass
                else:
                    expandedExtensions += allInputExtensions
            return expandedExtensions
        return fileExtensions

def getWork(workName,
            movementNumber=None,
            fileExtensions=None,
        ):
    '''
    this parse method is called from `corpus.parse()` and does nothing differently from it.
    
    Searches all corpora for a file that matches the name and returns it parsed.
    '''
    addXMLWarning = False
    workNameJoined = workName
    mxlWorkName = workName
    
    if workName in (None, ''):
        raise CorpusException(
            'a work name must be provided as an argument')
    if not common.isListLike(fileExtensions):
        fileExtensions = [fileExtensions]
    if common.isIterable(workName):
        workNameJoined = os.path.sep.join(workName)

    if workNameJoined.endswith(".xml"):
        # might be compressed MXL file
        mxlWorkName = os.path.splitext(workNameJoined)[0] + ".mxl"
        addXMLWarning = True

    filePaths = None    
    for corpusObject in iterateCorpora():    
        workList = corpusObject.getWorkList(workName, movementNumber, fileExtensions)
        if not workList and addXMLWarning:
            workList = corpusObject.getWorkList(mxlWorkName, movementNumber, fileExtensions)
            if not workList:
                continue
        if len(workList) >= 1:
            filePaths = workList
            break

    if filePaths is None:
        warningMessage = 'Could not find a'
        if addXMLWarning:
            warningMessage += 'n xml or mxl'
        warningMessage += ' work that met this criterion: {0};'.format(workName)
        warningMessage += ' if you are searching for a file on disk, '
        warningMessage += 'use "converter" instead of "corpus".'
        raise CorpusException(warningMessage)
    else:
        if len(filePaths) == 1:
            return filePaths[0]
        else:
            return filePaths

def midiEventsToKeySignature(eventList):
    '''Convert a single MIDI event into a music21 TimeSignature object.

    >>> from music21 import *
    >>> mt = midi.MidiTrack(1)
    >>> me1 = midi.MidiEvent(mt)
    >>> me1.type = "KEY_SIGNATURE"
    >>> me1.data = midi.putNumbersAsList([2, 0]) # d major
    >>> ks = midiEventsToKeySignature(me1)
    >>> ks
    <music21.key.KeySignature of 2 sharps>

    >>> me2 = midi.MidiEvent(mt)
    >>> me2.type = "KEY_SIGNATURE"
    >>> me2.data = midi.putNumbersAsList([-2, 0]) # b- major
    >>> me2.data
    '\\xfe\\x00'
    >>> midi.getNumbersAsList(me2.data)
    [254, 0]
    >>> ks = midiEventsToKeySignature(me2)
    >>> ks
    <music21.key.KeySignature of 2 flats>

    '''
    # This meta event is used to specify the key (number of sharps or flats) and scale (major or minor) of a sequence. A positive value for the key specifies the number of sharps and a negative value specifies the number of flats. A value of 0 for the scale specifies a major key and a value of 1 specifies a minor key.
    from music21 import key

    if not common.isListLike(eventList):
        event = eventList
    else: # get the second event; first is delta time
        event = eventList[1]
    post = midiModule.getNumbersAsList(event.data)

    if post[0] > 12:
        # flip around 256
        sharpCount = post[0] - 256 # need negative values
    else:
        sharpCount = post[0]

    environLocal.printDebug(['midiEventsToKeySignature', post, sharpCount])

    # first value is number of sharp, or neg for number of flat
    ks = key.KeySignature(sharpCount)

    if post[1] == 0:
        ks.mode = 'major'
    if post[1] == 1:
        ks.mode = 'minor'
    return ks

def cacheMetadata(domainList=['local','core', 'virtual']): 
    '''The core cache is all locally-stored corpus files. 
    '''
    from music21 import corpus, metadata

    if not common.isListLike(domainList):
        domainList = [domainList]

    t = common.Timer()
    t.start()

    # store list of file paths that caused an error
    fpError = []

    # the core cache is based on local files stored in music21
    # virtual is on-line
    for domain in domainList:
        # the domain passed here becomes the name of the bundle
        # determines the file name of the json bundle
        mdb = metadata.MetadataBundle(domain)

        if domain == 'virtual':
            getPaths = corpus.getVirtualPaths
        elif domain == 'core':
            getPaths = corpus.getCorePaths
        elif domain == 'local':
            getPaths = corpus.getLocalPaths  
        else:
            raise MetadataCacheException('invalid domain provided: %s' % domain)
            
        paths = getPaths()
    
        environLocal.warn([
            'metadata cache: starting processing of paths:', len(paths)])
    
        #mdb.addFromPaths(paths[-3:])
        # returns any paths that failed to load
        fpError += mdb.addFromPaths(paths, printDebugAfter = 50) 
        #print mdb.storage
        mdb.write() # will use a default file path based on domain

        environLocal.warn(['cache: writing time:', t, 'md items:', len(mdb.storage)])
        del mdb

    environLocal.warn(['cache: final writing time:', t])
    
    for fp in fpError:
        environLocal.warn('path failed to parse: %s' % fp)