| \section{\module{ConfigParser} --- |
| Configuration file parser} |
| |
| \declaremodule{standard}{ConfigParser} |
| \modulesynopsis{Configuration file parser.} |
| \moduleauthor{Ken Manheimer}{klm@digicool.com} |
| \moduleauthor{Barry Warsaw}{bwarsaw@python.org} |
| \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 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. |
| |
| The configuration file consists of sections, lead 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 upon |
| initialization and retrieval. Lines beginning with \character{\#} or |
| \character{;} are ignored and may be used to provide comments. |
| |
| For example: |
| |
| \begin{verbatim} |
| 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}{ConfigParser}{\optional{defaults}} |
| Return a new instance of the \class{ConfigParser} class. When |
| \var{defaults} is given, it is initialized into the dictionairy of |
| intrinsic defaults. They keys must be strings, and the values must be |
| appropriate for the \samp{\%()s} string interpolation. Note that |
| \var{__name__} is always an intrinsic default; its value is the |
| section name. |
| \end{classdesc} |
| |
| \begin{excdesc}{NoSectionError} |
| Exception raised when a specified section is not found. |
| \end{excdesc} |
| |
| \begin{excdesc}{DuplicateSectionError} |
| Exception raised when mutliple sections with the same name are found, |
| or 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} |
| Exception raised when problems occur performing string interpolation. |
| \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{seealso} |
| \seemodule{shlex}{Support for a creating \UNIX{} shell-like |
| minilanguages which can be used as an alternate format |
| for application configuration files.} |
| \end{seealso} |
| |
| \subsection{ConfigParser Objects \label{ConfigParser-objects}} |
| |
| \class{ConfigParser} instances have the following methods: |
| |
| \begin{methoddesc}{defaults}{} |
| Return a dictionairy 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}{read}{filenames} |
| Read and parse a list of filenames. If \var{filenames} is a string or |
| Unicode string, it is treated as a single filename. |
| \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\optional{, raw\optional{, vars}}} |
| Get an \var{option} value for the provided \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}{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 only accepted values |
| for the option are \samp{0} and \samp{1}, any others will raise |
| \exception{ValueError}. |
| \end{methoddesc} |