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. Finale), 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 Configuring Environment Settings.
# TODO: Update to user’s guide
Return the current setting of a UserSettings key.
This will create a user settings file if necessary:
>>> from music21 import environment
>>> for x in sorted(environment.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.get('musicxmlPath')
'/Applications/Finale Reader.app'
Return all valid UserSettings keys.
Directly set a single UserSettings key, by providing a key and the appropriate value. This will create a user settings file if necessary.
>>> from music21 import environment
>>> for x in sorted(environment.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.set('wer', 'asdf')
Traceback (most recent call last):
EnvironmentException: no preference: wer
>>> environment.set('musicxmlPath', '/Applications/Finale Reader.app')
The UserSettings object provides a simple interface for configuring the user preferences in the Environment object.
First, create an instance of UserSettings:
>>> from music21 import environment
>>> 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']
u'/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'
>>> us['localCorpusSettings']
['~/Documents']
Alternatively, the environment.py module provides convenience functions for setting these settings: keys(), get(), and set().
UserSettings methods
If a environment configuration file does not exist, create one based on the default settings.
Permanently remove the user configuration file.
Return the path to the platform specific settings file.
Return the keys found in the user’s Environment object.
Restore platform specific defaults.
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 more a user-friendly interface for creating and editing settings, see the UserSettings object.
>>> from music21 import environment
>>> env = environment.Environment(forcePlatform='darwin')
>>> env['musicxmlPath'] = '/Applications/Finale Reader.app'
>>> env['musicxmlPath']
'/Applications/Finale Reader.app'
Environment methods
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.
Get the keys that refer to file paths.
>>> from music21 import environment
>>> a = environment.Environment()
>>> for x in sorted(a.getKeysToPaths()):
... x
...
'braillePath'
'graphicsPath'
'lilypondPath'
'localCorpusPath'
'manualCoreCorpusPath'
'midiPath'
'musescoreDirectPNGPath'
'musicxmlPath'
'pdfPath'
'vectorPath'
Get the raw keys stored in the internal reference dictionary.
These are different than the keys() method in that the ‘localCorpusPath’ entry is not included.
>>> from music21 import environment
>>> 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'
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).
Return the path to the platform specific settings file.
Return a file path to a temporary file with the specified suffix (file extension).
Return valid keys to get and set values for the Environment instance.
>>> from music21 import environment
>>> 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'
Opens a file with an either default or user-specified applications.
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().
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.
Restore only defaults for all parameters. Useful for testing.
>>> from music21 import environment
>>> 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()
To print a warning to the user, send a list of strings to this method. Similar to printDebug but even if debug is off.
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 instance variables
A string representation of the module that contains this Environment instance.
An xmlnode.XMLNode subclass representing a single environment preference:
>>> from music21 import environment
>>> a = environment.Preference()
Preference bases
Preference read/write properties
Read/write properties inherited from XMLNode:
|
Preference methods
Methods inherited from XMLNode:
|
|
|
An xmlnode.XMLNode subclass representing information about various secondary local corpora:
>>> from music21 import environment
>>> localCorpora = environment.LocalCorporaSettings()
>>> corpusA = environment.LocalCorpusSettings(name='A')
>>> corpusA.append(environment.LocalCorpusPath(path='foo'))
>>> corpusA.append(environment.LocalCorpusPath(path='bar'))
>>> corpusB = environment.LocalCorpusSettings(name='B')
>>> corpusB.append(environment.LocalCorpusPath(path='baz'))
>>> localCorpora.append(corpusA)
>>> localCorpora.append(corpusB)
>>> print(localCorpora.xmlStr())
<?xml version="1.0" ...?>
<localCorporaSettings>
<localCorpusSettings name="A">
<localCorpusPath>foo</localCorpusPath>
<localCorpusPath>bar</localCorpusPath>
</localCorpusSettings>
<localCorpusSettings name="B">
<localCorpusPath>baz</localCorpusPath>
</localCorpusSettings>
</localCorporaSettings>
LocalCorporaSettings bases
LocalCorporaSettings read/write properties
Read/write properties inherited from XMLNode:
|
LocalCorporaSettings methods
Methods inherited from XMLNodeList:
|
Methods inherited from XMLNode:
|
|
|
An xmlnode.XMLNode subclass representing a list of environment preference:
>>> from music21 import environment
>>> lcs = environment.LocalCorpusSettings()
>>> lcp = environment.LocalCorpusPath()
>>> lcp.charData = 'testing'
>>> lcs.append(lcp)
>>> print(lcs.xmlStr())
<?xml version="1.0" ...?>
<localCorpusSettings>
<localCorpusPath>testing</localCorpusPath>
</localCorpusSettings>
LocalCorpusPath bases
LocalCorpusPath read/write properties
Read/write properties inherited from XMLNode:
|
LocalCorpusPath methods
Methods inherited from XMLNode:
|
|
|
>>> from music21 import environment
>>> a = environment.LocalCorpusSettings()
LocalCorpusSettings bases
LocalCorpusSettings read/write properties
Read/write properties inherited from XMLNode:
|
LocalCorpusSettings methods
Methods inherited from XMLNodeList:
|
Methods inherited from XMLNode:
|
|
|
A settings object:
>>> from music21 import environment
>>> a = environment.Settings()
Settings bases
Settings read/write properties
Read/write properties inherited from XMLNode:
|
Settings methods
Methods inherited from XMLNodeList:
|
Methods inherited from XMLNode:
|
|
|
An xml.sax.ContentHandler subclass holding settings:
>>> from music21 import environment
>>> sh = environment.SettingsHandler()
SettingsHandler methods