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.
Return the current setting of a UserSettings key. This will create a user settings file if necessary.
>>> from music21 import *
>>> environment.keys()
['lilypondBackend', 'pdfPath', 'lilypondVersion', 'graphicsPath', 'warnings', 'showFormat', 'localCorpusSettings', 'vectorPath', 'writeFormat', 'lilypondPath', 'directoryScratch', 'lilypondFormat', 'debug', 'musicxmlPath', 'autoDownload', 'midiPath', 'localCorpusPath']
>>> 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.keys()
['lilypondBackend', 'pdfPath', 'lilypondVersion', 'graphicsPath', 'warnings', 'showFormat', 'localCorpusSettings', 'vectorPath', 'writeFormat', 'lilypondPath', 'directoryScratch', 'lilypondFormat', 'debug', 'musicxmlPath', 'autoDownload', 'midiPath', 'localCorpusPath']
>>> 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 *
>>> us = environment.UserSettings()
Second, view the available settings keys.
>>> us.keys()
['lilypondBackend', 'pdfPath', 'lilypondVersion', 'graphicsPath', 'warnings', 'showFormat', 'localCorpusSettings', 'vectorPath', 'writeFormat', 'lilypondPath', 'directoryScratch', 'lilypondFormat', 'debug', 'musicxmlPath', 'autoDownload', 'midiPath', 'localCorpusPath']
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
- create()¶
If a environment configuration file does not exist, create one based on the default settings.
- delete()¶
Permanently remove the user configuration file.
- getSettingsPath()¶
Return the path to the platform specific settings file.
- keys()¶
Return the keys found in the user’s Environment object.
- restoreDefaults()¶
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.
For more a user-friendly interface for creating and editing settings, see the UserSettings object.
>>> env = Environment(forcePlatform='darwin')
>>> env['musicxmlPath'] = '/Applications/Finale Reader.app'
>>> env['musicxmlPath']
'/Applications/Finale Reader.app'
Create an instance of this object, reading settings from disk.
When created from a module, the modName parameter stores a string naming the module. This is used to identify the output of printDebug() calls.
The forcePlatform argument can be used for testing.
>>> from music21 import *
>>> myEnv = environment.Environment()
>>> post = myEnv['writeFormat']
>>> post
'musicxml'
Environment attributes
- modNameParent¶
A string representation of the module that contains this Environment instance.
Environment methods
- read(fp=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.
- write(fp=None)¶
Write an XML preference file. This must be manually called to store any changes made to the object and access preferences later. If fp is None, the default storage location will be used.
- getSettingsPath()¶
Return the path to the platform specific settings file.
- 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.
- getKeysToPaths()¶
Get the keys that refer to file paths.
>>> from music21 import * >>> a = environment.Environment() >>> a.getKeysToPaths() ['lilypondPath', 'musicxmlPath', 'graphicsPath', 'vectorPath', 'pdfPath', 'midiPath', 'localCorpusPath']
- getRefKeys()¶
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 * >>> a = environment.Environment() >>> a.getRefKeys() ['lilypondBackend', 'pdfPath', 'lilypondVersion', 'graphicsPath', 'warnings', 'showFormat', 'localCorpusSettings', 'vectorPath', 'writeFormat', 'lilypondPath', 'directoryScratch', 'lilypondFormat', 'debug', 'musicxmlPath', 'autoDownload', 'midiPath']
- 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).
- getTempFile(suffix='')¶
Return a file path to a temporary file with the specified suffix (file extension).
- keys()¶
Return valid keys to get and set values for the Environment instance.
>>> from music21 import * >>> e = environment.Environment() >>> e.keys() ['lilypondBackend', 'pdfPath', 'lilypondVersion', 'graphicsPath', 'warnings', 'showFormat', 'localCorpusSettings', 'vectorPath', 'writeFormat', 'lilypondPath', 'directoryScratch', 'lilypondFormat', 'debug', 'musicxmlPath', 'autoDownload', 'midiPath', 'localCorpusPath']
- launch(fmt, fp, options='', app=None)¶
Opens a file with an either default or user-specified applications.
- pd(msg, statusLevel=1, format=None)¶
Shortcut for printDebug. Useful as is typed frequently.
- printDebug(msg, statusLevel=1, format=None)¶
Format one or more data elements into string, and print it to stderr. The first arg can be a list of string; lists are concatenated with common.formatStr().
- restoreDefaults()¶
Restore only defaults for all parameters. Useful for testing.
>>> from music21 import * >>> a = environment.Environment() >>> a['debug'] = 1 >>> a.restoreDefaults() >>> a['debug'] 0
- 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.
Inherits from: XMLNode
An xmlnode.XMLNode subclass representing a single environment preference
>>> from music21 import *
>>> a = environment.Preference()
Inherits from: XMLNode
An xmlnode.XMLNode subclass representing a a list of environment preference
>>> from music21 import *
>>> lcs = environment.LocalCorpusSettings()
>>> lcp = environment.LocalCorpusPath()
>>> lcp.charData = 'testing'
>>> lcs.append(lcp)
>>> print lcs.xmlStr()
<?xml version="1.0" encoding="utf-8"?>
<localCorpusSettings>
<localCorpusPath>testing</localCorpusPath>
</localCorpusSettings>
>>> from music21 import *
>>> a = environment.Preference()
Inherits from: XMLNodeList, XMLNode
An xmlnode.XMLNode subclass representing a a list of environment preference
>>> from music21 import *
>>> a = environment.Preference()
Inherits from: XMLNodeList, XMLNode
>>> a = Settings()