diff options
author | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 (GMT) |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 (GMT) |
commit | 739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (patch) | |
tree | f82b450d291927fc1758b96d981aa0610947b529 /Doc/lib/libcfgparser.tex | |
parent | 2d1649094402ef393ea2b128ba2c08c3937e6b93 (diff) | |
download | cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.zip cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.gz cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.bz2 |
Delete the LaTeX doc tree.
Diffstat (limited to 'Doc/lib/libcfgparser.tex')
-rw-r--r-- | Doc/lib/libcfgparser.tex | 322 |
1 files changed, 0 insertions, 322 deletions
diff --git a/Doc/lib/libcfgparser.tex b/Doc/lib/libcfgparser.tex deleted file mode 100644 index a41aee1..0000000 --- a/Doc/lib/libcfgparser.tex +++ /dev/null @@ -1,322 +0,0 @@ -\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 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. - -Sections are normally stored in a builtin dictionary. An alternative -dictionary type can be passed to the \class{ConfigParser} constructor. -For example, if a dictionary type is passed that sorts its keys, -the sections will be sorted on write-back, as will be the keys within -each section. - -\begin{classdesc}{RawConfigParser}{\optional{defaults\optional{, dict_type}}} -The basic configuration object. When \var{defaults} is given, it is -initialized into the dictionary of intrinsic defaults. When \var{dict_type} -is given, it will be used to create the dictionary objects for the list -of sections, for the options within a section, and for the default values. -This class does not support the magical interpolation behavior. -\versionadded{2.3} -\versionchanged[\var{dict_type} was added]{2.6} -\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}[RawConfigParser]{defaults}{} -Return a dictionary containing the instance-wide defaults. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{sections}{} -Return a list of the sections available; \code{DEFAULT} is not -included in the list. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{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}[RawConfigParser]{has_section}{section} -Indicates whether the named section is present in the -configuration. The \code{DEFAULT} section is not acknowledged. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{options}{section} -Returns a list of options available in the specified \var{section}. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{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}[RawConfigParser]{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}[RawConfigParser]{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}[RawConfigParser]{get}{section, option} -Get an \var{option} value for the named \var{section}. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{getint}{section, option} -A convenience method which coerces the \var{option} in the specified -\var{section} to an integer. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{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}[RawConfigParser]{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}[RawConfigParser]{items}{section} -Return a list of \code{(\var{name}, \var{value})} pairs for each -option in the given \var{section}. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{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}[RawConfigParser]{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}[RawConfigParser]{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}[RawConfigParser]{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}[RawConfigParser]{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}[ConfigParser]{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}[ConfigParser]{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}[SafeConfigParser]{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} |