music21.environment

The environment module describes an object for accessing and setting variables related to the user’s music21 environment. Such variables include the location of external applications such as MusicXML readers (e.g. MuseScore), whether music21 is allowed to download files directly (via the virtual corpus), and other settings.

Additional documentation for and examples of using this module are found in User’s Guide, Chapter 24, Environment.

# TODO: Update to user’s guide – showing each function

UserSettings

class music21.environment.UserSettings

The UserSettings object provides a simple interface for configuring the user preferences in the Environment object.

It automatically writes all changes to disk.

First, create an instance of UserSettings:

>>> us = environment.UserSettings()

Second, view the available settings keys.

>>> for key in sorted(us.keys()):
...     key
'autoDownload'
'braillePath'
'debug'
'directoryScratch'
'graphicsPath'
'ipythonShowFormat'
'lilypondBackend'
'lilypondFormat'
'lilypondPath'
'lilypondVersion'
'localCorporaSettings'
'localCorpusPath'
'localCorpusSettings'
'manualCoreCorpusPath'
'midiPath'
'musescoreDirectPNGPath'
'musicxmlPath'
'pdfPath'
'showFormat'
'vectorPath'
'warnings'
'writeFormat'

Third, after finding the desired setting, supply the new value as a Python dictionary key value pair. Setting this value updates the user’s settings file. For example, to set the file path to the Application that will be used to open MusicXML files, use the ‘musicxmlPath’ key.

>>> us['musicxmlPath'] = '/Applications/Finale Reader.app'
>>> us['musicxmlPath']
'/Applications/Finale Reader.app'

Note that the ‘localCorpusPath’ setting operates in a slightly different manner than other settings. Each time the ‘localCorpusPath’ setting is set, an additional local corpus file path is added to the list of local corpus paths (unless that path is already defined in the list of local corpus paths). To view all local corpus paths, access the ‘localCorpusSettings’ settings. This setting can also be used to set a complete list of file paths.

>>> us['localCorpusPath'] = '~/Documents'
>>> list(us['localCorpusSettings'])
['~/Documents']

Alternatively, the environment.py module provides convenience functions for setting these settings: keys(), get(), and set().

UserSettings methods

UserSettings.__getitem__(key)

UserSettings.create()

If an environment configuration file does not exist, create one based on the default settings.

UserSettings.delete()

Permanently remove the user configuration file.

UserSettings.getSettingsPath()

Return the path to the platform specific settings file.

UserSettings.keys()

Return the keys found in the user’s Environment object.

UserSettings.restoreDefaults()

Restore platform specific defaults.

Environment

class music21.environment.Environment(modName=None, forcePlatform=None)

The environment.Environment object stores user preferences as a dictionary-like object. Additionally, the Environment object provides convenience methods to music21 modules for getting temporary files, launching files with external applications, and printing debug and warning messages.

Generally, each module creates a single, module-level instance of Environment, passing the module’s name during creation. (This is an efficient operation since the Environment module caches most information from module to module)

For a more user-friendly interface for creating and editing settings, see the UserSettings object.

>>> env = environment.Environment(forcePlatform='darwin')
>>> env['musicxmlPath'] = '/Applications/Finale Reader.app'
>>> env['musicxmlPath']
PosixPath('/Applications/Finale Reader.app')

Environment methods

Environment.__getitem__(key)

Environment.formatToApp(m21Format)

Environment.formatToKey(m21Format)

Environment.getDefaultRootTempDir()

Use the Python tempfile.gettempdir() to get the system specified temporary directory, and try to add a new ‘music21’ directory, and then return this directory.

This method is only called if the no scratch directory preference has been set.

If not able to create a ‘music21’ directory, the standard default is returned.

Returns a pathlib.Path

Environment.getKeysToPaths()

Get the keys that refer to file paths.

>>> a = environment.Environment()
>>> for x in sorted(a.getKeysToPaths()):
...     x
...
'braillePath'
'graphicsPath'
'lilypondPath'
'localCorpusPath'
'manualCoreCorpusPath'
'midiPath'
'musescoreDirectPNGPath'
'musicxmlPath'
'pdfPath'
'vectorPath'

Environment.getRefKeys()

Get the raw keys stored in the internal reference dictionary.

These are different from the keys() method in that the ‘localCorpusPath’ entry is not included.

>>> a = environment.Environment()
>>> for x in sorted(a.getRefKeys()):
...     x
...
'autoDownload'
'braillePath'
'debug'
'directoryScratch'
'graphicsPath'
'ipythonShowFormat'
'lilypondBackend'
'lilypondFormat'
'lilypondPath'
'lilypondVersion'
'localCorporaSettings'
'localCorpusSettings'
'manualCoreCorpusPath'
'midiPath'
'musescoreDirectPNGPath'
'musicxmlPath'
'pdfPath'
'showFormat'
'vectorPath'
'warnings'
'writeFormat'

Environment.getRootTempDir()

Return a directory for writing temporary files. This does not create a new directory for each use, but either uses the user-set preference or gets the system-provided directory (with a music21 subdirectory, if possible).

Environment.getSettingsPath()

Return the path to the platform specific settings file.

Environment.getTempFile(suffix: str, returnPathlib: Literal[False]) → str

Environment.getTempFile(suffix: str = '', returnPathlib: Literal[True] = True) → Path

Return a file path to a temporary file with the specified suffix (file extension).

v5 – added returnPathlib. v6 – returnPathlib defaults to True.

Environment.keys()

Return valid keys to get and set values for the Environment instance.

>>> e = environment.Environment()
>>> for x in sorted(list(e.keys())):
...     x
...
'autoDownload'
'braillePath'
'debug'
'directoryScratch'
'graphicsPath'
'ipythonShowFormat'
'lilypondBackend'
'lilypondFormat'
'lilypondPath'
'lilypondVersion'
'localCorporaSettings'
'localCorpusPath'
'localCorpusSettings'
'manualCoreCorpusPath'
'midiPath'
'musescoreDirectPNGPath'
'musicxmlPath'
'pdfPath'
'showFormat'
'vectorPath'
'warnings'
'writeFormat'

Environment.printDebug(msg, statusLevel=1)

Format one or more data elements into string, and print it to stderr. The first arg can be a list of strings or a string; lists are concatenated with common.formatStr().

Environment.read(filePath=None)

Load an XML preference file if and only if the file is available and has been written in the past. This means that no preference file will ever be written unless manually done so. If no preference file exists, the method returns None.

Environment.restoreDefaults()

Restore only defaults for all parameters. Useful for testing.

>>> a = environment.Environment()
>>> a['debug'] = 1
>>> a.restoreDefaults()
>>> a['debug']
0

And we can read() the environment settings back from our configuration file to restore our normal working environment.

>>> a = environment.Environment().read()

Environment.warn(msg, header=None)

To print a warning to the user, send a list of strings to this method. Similar to printDebug but even if debug is off.

Environment.write(filePath=None)

Write an XML preference file. This must be manually called to store any changes made to the object and access preferences later. If filePath is None, the default storage location will be used.

Environment.xmlReaderType()

Returns an xmlReaderType depending on the ‘musicxmlPath’

>>> a = environment.Environment()
>>> a['musicxmlPath'] = '/Applications/Musescore.app'
>>> a.xmlReaderType()
'Musescore'
>>> a['musicxmlPath'] = '/Applications/Sibelius 7.app'
>>> a.xmlReaderType()
'Sibelius'
>>> a['musicxmlPath'] = r'C:\Program Files\Finale\Finale 2014.exe'
>>> a.xmlReaderType()
'Finale'

Nostalgia is unknown…

>>> a['musicxmlPath'] = r'C:\Program Files\Deluxe Music Construction Set.exe'
>>> a.xmlReaderType()
'unknown'

>>> a['musicxmlPath'] = None
>>> a.xmlReaderType() is None
True

Environment instance variables

Environment.modNameParent

A string representation of the module that contains this Environment instance.

LocalCorpusSettings

class music21.environment.LocalCorpusSettings(paths=None, name=None, cacheFilePath=None)

A lightweight object for storing the ‘LocalCorpusSettings’ tag in the .music21rc

It is a subclass of list and has two additional attributes, name (which should be None for the unnamed localCorpus) and cacheFilePath for a full filepath (ending in .json) as a location to store the .metadataBundle (.json) cache for the LocalCorpus. This can be None, in which case the (volatile) temp directory is used.

>>> lcs = environment.LocalCorpusSettings(['/tmp', '/home'])
>>> lcs
LocalCorpusSettings(['/tmp', '/home'])

>>> lcs.name = 'theWholeEnchilada'
>>> lcs
LocalCorpusSettings(['/tmp', '/home'], name='theWholeEnchilada')

>>> lcs.cacheFilePath = '/home/enchilada.json'
>>> lcs
LocalCorpusSettings(['/tmp', '/home'],
                    name='theWholeEnchilada',
                    cacheFilePath='/home/enchilada.json')

>>> list(lcs)
['/tmp', '/home']
>>> lcs.name
'theWholeEnchilada'
>>> lcs.cacheFilePath
'/home/enchilada.json'
>>> '/home' in lcs
True
>>> '/root' in lcs
False

Functions

music21.environment.envSingleton()

returns the _environStorage[‘instance’], _EnvironmentCore singleton object

music21.environment.etIndent(elem, level=0, spaces=2)

indent an elementTree element for printing

music21.environment.get(key)

Return the current setting of a UserSettings key.

This will create a user settings file if necessary:

>>> environment.get('musicxmlPath')
'/Applications/Finale Reader.app'

music21.environment.keys()

Return all valid UserSettings keys.

music21.environment.set(key, value)

Directly set a single UserSettings key, by providing a key and the appropriate value. This will create a user settings file if necessary.

>>> environment.set('wer', 'asdf')
Traceback (most recent call last):
music21.environment.EnvironmentException: no preference: wer

>>> environment.set('musicxmlPath', '/Applications/Finale Reader.app')