ref: f42e53655e9a2a1b516326f6522fba88db59a81c
dir: /sys/src/cmd/python/Doc/lib/libcfgparser.tex/
\section{\module{ConfigParser} --- Configuration file parser} \declaremodule{standard}{ConfigParser} \modulesynopsis{Configuration file parser.} \moduleauthor{Ken Manheimer}{[email protected]} \moduleauthor{Barry Warsaw}{[email protected]} \moduleauthor{Eric S. Raymond}{[email protected]} \sectionauthor{Christopher G. Petrilli}{[email protected]} 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 file parser language which provides a structure similar to what you would find on Microsoft Windows INI files. You can use this to write Python programs 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} is also accepted. Note that leading whitespace is removed from values. The optional values can contain format strings which refer to other values in the same section, or values in a special \code{DEFAULT} section. Additional defaults can be provided on initialization 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/whatever dir=frob \end{verbatim} would resolve the \samp{\%(dir)s} to the value of \samp{dir} (\samp{frob} in this case). All reference expansions are done 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 all others. \begin{classdesc}{RawConfigParser}{\optional{defaults}} The basic configuration object. When \var{defaults} is given, it is initialized into the dictionary of intrinsic defaults. This class does not support the magical interpolation behavior. \versionadded{2.3} \end{classdesc} \begin{classdesc}{ConfigParser}{\optional{defaults}} Derived class of \class{RawConfigParser} that implements the magical interpolation feature and adds optional arguments to the \method{get()} and \method{items()} methods. The values in \var{defaults} must be appropriate 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 name reference. 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} are equivalent. \end{classdesc} \begin{classdesc}{SafeConfigParser}{\optional{defaults}} Derived class of \class{ConfigParser} that implements a more-sane variant of the magical interpolation feature. This implementation is more 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 be compatible 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 of a 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 string interpolation. \end{excdesc} \begin{excdesc}{InterpolationDepthError} Exception raised when string interpolation cannot be completed because the 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 are made 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 section headers. \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()} when the \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 not included in the list. \end{methoddesc} \begin{methoddesc}{add_section}{section} Add a section named \var{section} to the instance. If a section by the given name already exists, \exception{DuplicateSectionError} is raised. \end{methoddesc} \begin{methoddesc}{has_section}{section} Indicates whether the named section is present in the configuration. 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 filenames which were successfully parsed. If \var{filenames} is a string or Unicode string, it is treated as a single filename. If a file named in \var{filenames} cannot be opened, that file will be ignored. This is designed so that you can specify a list of potential configuration file locations (for example, the current directory, the user's home directory, and some system-wide directory), and all existing configuration files in the list will be read. If none of the named files exist, the \class{ConfigParser} instance will contain an empty dataset. An application which requires initial values to be loaded from a file should load the required file or files using \method{readfp()} before calling \method{read()} for any optional files: \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 values for 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}. These string values are checked in a case-insensitive manner. Any other value will cause it to raise \exception{ValueError}. \end{methoddesc} \begin{methoddesc}{items}{section} Return a list of \code{(\var{name}, \var{value})} pairs for each option in the given \var{section}. \end{methoddesc} \begin{methoddesc}{set}{section, option, value} If the given section exists, set the given option to the specified value; otherwise raise \exception{NoSectionError}. While it is possible to use \class{RawConfigParser} (or \class{ConfigParser} with \var{raw} parameters set to true) for \emph{internal} storage of non-string values, full functionality (including interpolation and output 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 file object. 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 or as passed in by client code to the form that should be used in the internal structures. The default implementation returns a lower-case version of \var{option}; subclasses may override this or client code can set an attribute of this name on instances to affect this behavior. Setting this to \function{str()}, for example, would make option 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, based on 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 each option in the given \var{section}. Optional arguments have the same 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 extended interface as \class{ConfigParser}, with the following addition: \begin{methoddesc}{set}{section, option, value} If the given section exists, set the given option to the specified value; otherwise raise \exception{NoSectionError}. \var{value} must be a string (\class{str} or \class{unicode}); if not, \exception{TypeError} is raised. \versionadded{2.4} \end{methoddesc}