\section{\module{ConfigParser} ---         Configuration file parser} \declaremodule{standard}{ConfigParser}\modulesynopsis{Configuration file parser.}\moduleauthor{Ken Manheimer}{klm@zope.com}\moduleauthor{Barry Warsaw}{bwarsaw@python.org}\moduleauthor{Eric S. Raymond}{esr@thyrsus.com}\sectionauthor{Christopher G. Petrilli}{petrilli@amber.org} This module defines the class \class{ConfigParser}.\indexii{.ini}{file}\indexii{configuration}{file}\index{ini file}\index{Windows ini file}The \class{ConfigParser} class implements a basic configuration fileparser language which provides a structure similar to what you wouldfind on Microsoft Windows INI files.  You can use this to write Pythonprograms which can be customized by end users easily. \begin{notice}[warning]  This library does \emph{not} interpret or write the value-type  prefixes used in the Windows Registry extended version of INI syntax.\end{notice} The configuration file consists of sections, led by a\samp{[section]} header and followed by \samp{name: value} entries,with continuations in the style of \rfc{822}; \samp{name=value} isalso accepted.  Note that leading whitespace is removed from values.The optional values can contain format strings which refer to othervalues in the same section, or values in a special\code{DEFAULT} section.  Additional defaults can be provided oninitialization and retrieval.  Lines beginning with \character{\#} or\character{;} are ignored and may be used to provide comments. For example: \begin{verbatim}[My Section]foodir: %(dir)s/whateverdir=frob\end{verbatim} would resolve the \samp{\%(dir)s} to the value of\samp{dir} (\samp{frob} in this case).  All reference expansions aredone on demand. Default values can be specified by passing them into the\class{ConfigParser} constructor as a dictionary.  Additional defaults may be passed into the \method{get()} method which will override allothers. \begin{classdesc}{RawConfigParser}{\optional{defaults}}The basic configuration object.  When \var{defaults} is given, it isinitialized into the dictionary of intrinsic defaults.  This classdoes not support the magical interpolation behavior.\versionadded{2.3}\end{classdesc} \begin{classdesc}{ConfigParser}{\optional{defaults}}Derived class of \class{RawConfigParser} that implements the magicalinterpolation feature and adds optional arguments to the \method{get()}and \method{items()} methods.  The values in \var{defaults} must beappropriate for the \samp{\%()s} string interpolation.  Note that\var{__name__} is an intrinsic default; its value is the section name,and will override any value provided in \var{defaults}. All option names used in interpolation will be passed through the\method{optionxform()} method just like any other option namereference.  For example, using the default implementation of\method{optionxform()} (which converts option names to lower case),the values \samp{foo \%(bar)s} and \samp{foo \%(BAR)s} areequivalent.\end{classdesc} \begin{classdesc}{SafeConfigParser}{\optional{defaults}}Derived class of \class{ConfigParser} that implements a more-sanevariant of the magical interpolation feature.  This implementation ismore predictable as well.% XXX Need to explain what's safer/more predictable about it.New applications should prefer this version if they don't need to becompatible with older versions of Python.\versionadded{2.3}\end{classdesc} \begin{excdesc}{NoSectionError}Exception raised when a specified section is not found.\end{excdesc} \begin{excdesc}{DuplicateSectionError}Exception raised if \method{add_section()} is called with the name ofa section that is already present.\end{excdesc} \begin{excdesc}{NoOptionError}Exception raised when a specified option is not found in the specified section.\end{excdesc} \begin{excdesc}{InterpolationError}Base class for exceptions raised when problems occur performing stringinterpolation.\end{excdesc} \begin{excdesc}{InterpolationDepthError}Exception raised when string interpolation cannot be completed becausethe number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}.Subclass of \exception{InterpolationError}.\end{excdesc} \begin{excdesc}{InterpolationMissingOptionError}Exception raised when an option referenced from a value does not exist.Subclass of \exception{InterpolationError}.\versionadded{2.3}\end{excdesc} \begin{excdesc}{InterpolationSyntaxError}Exception raised when the source text into which substitutions aremade does not conform to the required syntax.Subclass of \exception{InterpolationError}.\versionadded{2.3}\end{excdesc} \begin{excdesc}{MissingSectionHeaderError}Exception raised when attempting to parse a file which has no sectionheaders.\end{excdesc} \begin{excdesc}{ParsingError}Exception raised when errors occur attempting to parse a file.\end{excdesc} \begin{datadesc}{MAX_INTERPOLATION_DEPTH}The maximum depth for recursive interpolation for \method{get()} whenthe \var{raw} parameter is false.  This is relevant only for the\class{ConfigParser} class.\end{datadesc}  \begin{seealso}  \seemodule{shlex}{Support for a creating \UNIX{} shell-like                    mini-languages which can be used as an alternate                    format for application configuration files.}\end{seealso}  \subsection{RawConfigParser Objects \label{RawConfigParser-objects}} \class{RawConfigParser} instances have the following methods: \begin{methoddesc}{defaults}{}Return a dictionary containing the instance-wide defaults.\end{methoddesc} \begin{methoddesc}{sections}{}Return a list of the sections available; \code{DEFAULT} is notincluded in the list.\end{methoddesc} \begin{methoddesc}{add_section}{section}Add a section named \var{section} to the instance.  If a section bythe given name already exists, \exception{DuplicateSectionError} israised.\end{methoddesc} \begin{methoddesc}{has_section}{section}Indicates whether the named section is present in theconfiguration. The \code{DEFAULT} section is not acknowledged.\end{methoddesc} \begin{methoddesc}{options}{section}Returns a list of options available in the specified \var{section}.\end{methoddesc} \begin{methoddesc}{has_option}{section, option}If the given section exists, and contains the given option,return \constant{True}; otherwise return \constant{False}.\versionadded{1.6}\end{methoddesc} \begin{methoddesc}{read}{filenames}Attempt to read and parse a list of filenames, returning a list of filenameswhich were successfully parsed.  If \var{filenames} is a string orUnicode string, it is treated as a single filename.If a file named in \var{filenames} cannot be opened, that file will beignored.  This is designed so that you can specify a list of potentialconfiguration file locations (for example, the current directory, theuser's home directory, and some system-wide directory), and allexisting configuration files in the list will be read.  If none of thenamed files exist, the \class{ConfigParser} instance will contain anempty dataset.  An application which requires initial values to beloaded from a file should load the required file or files using\method{readfp()} before calling \method{read()} for any optionalfiles: \begin{verbatim}import ConfigParser, os config = ConfigParser.ConfigParser()config.readfp(open('defaults.cfg'))config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])\end{verbatim}\versionchanged[Returns list of successfully parsed filenames]{2.4}\end{methoddesc} \begin{methoddesc}{readfp}{fp\optional{, filename}}Read and parse configuration data from the file or file-like object in\var{fp} (only the \method{readline()} method is used).  If\var{filename} is omitted and \var{fp} has a \member{name} attribute,that is used for \var{filename}; the default is \samp{<???>}.\end{methoddesc} \begin{methoddesc}{get}{section, option}Get an \var{option} value for the named \var{section}.\end{methoddesc} \begin{methoddesc}{getint}{section, option}A convenience method which coerces the \var{option} in the specified\var{section} to an integer.\end{methoddesc} \begin{methoddesc}{getfloat}{section, option}A convenience method which coerces the \var{option} in the specified\var{section} to a floating point number.\end{methoddesc} \begin{methoddesc}{getboolean}{section, option}A convenience method which coerces the \var{option} in the specified\var{section} to a Boolean value.  Note that the accepted valuesfor the option are \code{"1"}, \code{"yes"}, \code{"true"}, and \code{"on"},which cause this method to return \code{True}, and \code{"0"}, \code{"no"},\code{"false"}, and \code{"off"}, which cause it to return \code{False}.  Thesestring values are checked in a case-insensitive manner.  Any other value willcause it to raise \exception{ValueError}.\end{methoddesc} \begin{methoddesc}{items}{section}Return a list of \code{(\var{name}, \var{value})} pairs for eachoption in the given \var{section}.\end{methoddesc} \begin{methoddesc}{set}{section, option, value}If the given section exists, set the given option to the specifiedvalue; otherwise raise \exception{NoSectionError}.  While it ispossible to use \class{RawConfigParser} (or \class{ConfigParser} with\var{raw} parameters set to true) for \emph{internal} storage ofnon-string values, full functionality (including interpolation andoutput to files) can only be achieved using string values.\versionadded{1.6}\end{methoddesc} \begin{methoddesc}{write}{fileobject}Write a representation of the configuration to the specified fileobject.  This representation can be parsed by a future \method{read()}call.\versionadded{1.6}\end{methoddesc} \begin{methoddesc}{remove_option}{section, option}Remove the specified \var{option} from the specified \var{section}.If the section does not exist, raise \exception{NoSectionError}. If the option existed to be removed, return \constant{True};otherwise return \constant{False}.\versionadded{1.6}\end{methoddesc} \begin{methoddesc}{remove_section}{section}Remove the specified \var{section} from the configuration.If the section in fact existed, return \code{True}.Otherwise return \code{False}.\end{methoddesc} \begin{methoddesc}{optionxform}{option}Transforms the option name \var{option} as found in an input file oras passed in by  client code to the form that should be used in theinternal structures.  The default implementation returns a lower-caseversion of \var{option}; subclasses may override this or client codecan set an attribute of this name on instances to affect thisbehavior.  Setting this to \function{str()}, for example, would makeoption names case sensitive.\end{methoddesc}  \subsection{ConfigParser Objects \label{ConfigParser-objects}} The \class{ConfigParser} class extends some methods of the\class{RawConfigParser} interface, adding some optional arguments. \begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}Get an \var{option} value for the named \var{section}.  All the\character{\%} interpolations are expanded in the return values, basedon the defaults passed into the constructor, as well as the options\var{vars} provided, unless the \var{raw} argument is true.\end{methoddesc} \begin{methoddesc}{items}{section\optional{, raw\optional{, vars}}}Return a list of \code{(\var{name}, \var{value})} pairs for eachoption in the given \var{section}. Optional arguments have thesame meaning as for the \method{get()} method.\versionadded{2.3}\end{methoddesc}  \subsection{SafeConfigParser Objects \label{SafeConfigParser-objects}} The \class{SafeConfigParser} class implements the same extendedinterface as \class{ConfigParser}, with the following addition: \begin{methoddesc}{set}{section, option, value}If the given section exists, set the given option to the specifiedvalue; otherwise raise \exception{NoSectionError}.  \var{value} mustbe a string (\class{str} or \class{unicode}); if not,\exception{TypeError} is raised.\versionadded{2.4}\end{methoddesc}