.. _moduleEnvironment:

music21.environment
===================

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: 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. 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 :ref:`environment`.




.. function:: get(key)

    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'



.. function:: keys()

    Return all valid UserSettings keys.



.. function:: 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.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')



UserSettings
------------



.. class:: UserSettings()

    The UserSettings object provides a simple interface for configuring the user preferences in the :class:`~music21.environment.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: :func:`~music21.environment.keys`, :func:`~music21.environment.get`, and :func:`~music21.environment.set`.



    **UserSettings** **methods**

        .. method:: create()

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



        .. method:: delete()

            Permanently remove the user configuration file.



        .. method:: getSettingsPath()

            Return the path to the platform specific settings file.



        .. method:: keys()

            Return the keys found in the user's :class:`~music21.environment.Environment` object.



        .. method:: restoreDefaults()

            Restore platform specific defaults.




Environment
-----------



.. class:: 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.

    For more a user-friendly interface for creating and editing settings, see
    the :class:`~music21.environment.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**

        .. attribute:: modNameParent

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


    **Environment** **methods**

        .. method:: 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.



        .. method:: 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.



        .. method:: getSettingsPath()

            Return the path to the platform specific settings file.



        .. method:: 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.



        .. method:: getKeysToPaths()

            Get the keys that refer to file paths.

                   >>> from music21 import *
                   >>> a = environment.Environment()
                   >>> a.getKeysToPaths()
                   ['lilypondPath', 'musicxmlPath', 'graphicsPath', 'vectorPath', 'pdfPath', 'midiPath', 'localCorpusPath']



        .. method:: 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']



        .. method:: 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).



        .. method:: getTempFile(suffix='')

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



        .. method:: 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']




        .. method:: launch(fmt, fp, options='', app=None)


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



        .. method:: pd(msg, statusLevel=1, format=None)

            Shortcut for printDebug. Useful as is typed frequently.



        .. method:: 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().



        .. method:: restoreDefaults()

            Restore only defaults for all parameters. Useful for testing.



            >>> from music21 import *
            >>> a = environment.Environment()
            >>> a['debug'] = 1
            >>> a.restoreDefaults()
            >>> a['debug']
            0



        .. method:: 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.




Preference
----------

Inherits from: :class:`~music21.xmlnode.XMLNode`

.. class:: Preference()


    An xmlnode.XMLNode subclass representing a single environment preference







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




LocalCorpusPath
---------------

Inherits from: :class:`~music21.xmlnode.XMLNode`

.. class:: LocalCorpusPath()


    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>
    <BLANKLINE>






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




LocalCorpusSettings
-------------------

Inherits from: :class:`~music21.xmlnode.XMLNodeList`, :class:`~music21.xmlnode.XMLNode`

.. class:: LocalCorpusSettings()


    An xmlnode.XMLNode subclass representing a a list of environment preference






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




Settings
--------

Inherits from: :class:`~music21.xmlnode.XMLNodeList`, :class:`~music21.xmlnode.XMLNode`

.. class:: Settings()








    >>> a = Settings()




