Doc/lib/libcfgparser.tex

   1 \section{\module{ConfigParser} ---
   2          Configuration file parser}
   3
   4 \declaremodule{standard}{ConfigParser}
   5 \modulesynopsis{Configuration file parser.}
   6 \sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
   7
   8 This module defines the class \class{ConfigParser}.
   9 \indexii{.ini}{file}\indexii{configuration}{file}\index{ini file}
  10 \index{Windows ini file}
  11 The \class{ConfigParser} class implements a basic configuration file
  12 parser language which provides a structure similar to what you would
  13 find on Microsoft Windows INI files.  You can use this to write Python
  14 programs which can be customized by end users easily.
  15
  16 The configuration file consists of sections, lead by a
  17 \samp{[section]} header and followed by \samp{name: value} entries,
  18 with continuations in the style of \rfc{822}; \samp{name=value} is
  19 also accepted.  The optional values can contain format strings which
  20 refer to other values in the same section, or values in a special
  21 \code{DEFAULT} section.  Additional defaults can be provided upon
  22 initialization and retrieval.  Lines beginning with \character{\#} are
  23 ignored and may be used to provide comments.
  24
  25 For example:
  26
  27 \begin{verbatim}
  28 foodir: %(dir)s/whatever
  29 \end{verbatim}
  30
  31 would resolve the \samp{\%(dir)s} to the value of dir. All reference
  32 expansions are done late, on demand.
  33
  34 Intrinsic defaults can be specified by passing them into the
  35 \class{ConfigParser} constructor as a dictionary.  Additional defaults
  36 may be passed into the \method{get} method which will override all
  37 others.
  38
  39 \begin{classdesc}{ConfigParser}{\optional{defaults}}
  40 Return a new instance of the \class{ConfigParser} class.  When
  41 \var{defaults} is given, it is initialized into the dictionairy of
  42 intrinsic defaults.  They keys must be strings, and the values must be
  43 appropriate for the \samp{\%()s} string interpolation.  Note that
  44 \var{__name__} is always an intrinsic default; its value is the
  45 section name.
  46 \end{classdesc}
  47
  48 \begin{excdesc}{NoSectionError}
  49 Exception raised when a specified section is not found.
  50 \end{excdesc}
  51
  52 \begin{excdesc}{DuplicateSectionError}
  53 Exception raised when mutliple sections with the same name are found.
  54 \end{excdesc}
  55
  56 \begin{excdesc}{NoOptionError}
  57 Exception raised when a specified option is not found in the specified
  58 section.
  59 \end{excdesc}
  60
  61 \begin{excdesc}{InterpolationError}
  62 Exception raised when problems occur performing string interpolation.
  63 \end{excdesc}
  64
  65 \begin{excdesc}{MissingSectionHeaderError}
  66 Exception raised when attempting to parse a file which has no section
  67 headers.
  68 \end{excdesc}
  69
  70 \begin{excdesc}{ParsingError}
  71 Exception raised when errors occur attempting to parse a file.
  72 \end{excdesc}
  73
  74
  75 \begin{seealso}
  76   \seemodule{shlex}{Support for a creating \UNIX{} shell-like
  77                     minilanguages which can be used as an alternate format
  78                     for application configuration files.}
  79 \end{seealso}
  80
  81 \subsection{ConfigParser Objects \label{ConfigParser-objects}}
  82
  83 \class{ConfigParser} instances have the following methods:
  84
  85 \begin{methoddesc}{defaults}{}
  86 Return a dictionairy containing the instance-wide defaults.
  87 \end{methoddesc}
  88
  89 \begin{methoddesc}{sections}{}
  90 Return a list of the sections available.
  91 \end{methoddesc}
  92
  93 \begin{methoddesc}{has_section}{section}
  94 Indicates whether the named section is present in the
  95 configuration. The \code{DEFAULT} section is not acknowledged.
  96 \end{methoddesc}
  97
  98 \begin{methoddesc}{options}{section}
  99 Returns a list of options available in the specified \var{section}.
 100 \end{methoddesc}
 101
 102 \begin{methoddesc}{read}{filenames}
 103 Read and parse a list of filenames.
 104 \end{methoddesc}
 105
 106 \begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
 107 Get an \var{option} value for the provided \var{section}.  All the
 108 \character{\%} interpolations are expanded in the return values, based on
 109 the defaults passed into the constructor, as well as the options
 110 \var{vars} provided, unless the \var{raw} argument is true.
 111 \end{methoddesc}
 112
 113 \begin{methoddesc}{getint}{section, option}
 114 A convenience method which coerces the \var{option} in the specified
 115 \var{section} to an integer.
 116 \end{methoddesc}
 117
 118 \begin{methoddesc}{getfloat}{section, option}
 119 A convenience method which coerces the \var{option} in the specified
 120 \var{section} to a floating point number.
 121 \end{methoddesc}
 122
 123 \begin{methoddesc}{getboolean}{section, option}
 124 A convenience method which coerces the \var{option} in the specified
 125 \var{section} to a boolean value.  Note that the only accepted values
 126 for the option are \code{0} and \code{1}, any others will raise
 127 \exception{ValueError}.
 128 \end{methoddesc}