Previous topic

music21.editorial

Next topic

music21.expressions

Table Of Contents

Table Of Contents

This Page

music21.environment

Functions

music21.environment.get(key)

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

>>> 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')

UserSettings

class music21.environment.UserSettings

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

UserSettings.create()

If a 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 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

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.

Environment.getKeysToPaths()

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'
Environment.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 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'
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='')

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

Environment.keys()

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'
Environment.launch(fmt, filePath, options='', app=None)

Opens a file with an either default or user-specified applications.

Environment.printDebug(msg, statusLevel=1, debugFormat=None)

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.

>>> 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()
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 instance variables

Environment.modNameParent

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

Preference

class music21.environment.Preference

An xmlnode.XMLNode subclass representing a single environment preference:

>>> from music21 import environment
>>> a = environment.Preference()

Preference bases

  • XMLNode

Preference read/write properties

Read/write properties inherited from XMLNode:

  • tag

Preference methods

Methods inherited from XMLNode:

  • get()
  • getNewDoc()
  • hasAttrs()
  • loadAttrs()
  • merge()
  • set()
  • setDefaults()
  • toxml()
  • xmlStr()

LocalCorporaSettings

class music21.environment.LocalCorporaSettings

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

  • XMLNodeList
  • XMLNode

LocalCorporaSettings read/write properties

Read/write properties inherited from XMLNode:

  • tag

LocalCorporaSettings methods

Methods inherited from XMLNodeList:

  • append()

Methods inherited from XMLNode:

  • get()
  • getNewDoc()
  • hasAttrs()
  • loadAttrs()
  • merge()
  • set()
  • setDefaults()
  • toxml()
  • xmlStr()

LocalCorpusPath

class music21.environment.LocalCorpusPath(path=None)

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

  • XMLNode

LocalCorpusPath read/write properties

Read/write properties inherited from XMLNode:

  • tag

LocalCorpusPath methods

Methods inherited from XMLNode:

  • get()
  • getNewDoc()
  • hasAttrs()
  • loadAttrs()
  • merge()
  • set()
  • setDefaults()
  • toxml()
  • xmlStr()

LocalCorpusSettings

class music21.environment.LocalCorpusSettings(name=None)
>>> from music21 import environment
>>> a = environment.LocalCorpusSettings()

LocalCorpusSettings bases

  • XMLNodeList
  • XMLNode

LocalCorpusSettings read/write properties

Read/write properties inherited from XMLNode:

  • tag

LocalCorpusSettings methods

Methods inherited from XMLNodeList:

  • append()

Methods inherited from XMLNode:

  • get()
  • getNewDoc()
  • hasAttrs()
  • loadAttrs()
  • merge()
  • set()
  • setDefaults()
  • toxml()
  • xmlStr()

Settings

class music21.environment.Settings

A settings object:

>>> from music21 import environment
>>> a = environment.Settings()

Settings bases

  • XMLNodeList
  • XMLNode

Settings read/write properties

Read/write properties inherited from XMLNode:

  • tag

Settings methods

Methods inherited from XMLNodeList:

  • append()

Methods inherited from XMLNode:

  • get()
  • getNewDoc()
  • hasAttrs()
  • loadAttrs()
  • merge()
  • set()
  • setDefaults()
  • toxml()
  • xmlStr()

SettingsHandler

class music21.environment.SettingsHandler(tagLib=None)

An xml.sax.ContentHandler subclass holding settings:

>>> from music21 import environment
>>> sh = environment.SettingsHandler()

SettingsHandler methods

SettingsHandler.characters(characters)
SettingsHandler.endElement(name)
SettingsHandler.getSettings()
SettingsHandler.startElement(name, attrs)