Describe the behavior of the read() method when the list of filenames

freddrake · freddrake · commit 7151da0aa953 · 2001-12-07T21:35:57.000Z
includes files that do not exist, explain the intended use of the interface,
and show how to ensure an expected file really exists.
This closes SF bug #490399.
diff --git a/Doc/lib/libcfgparser.tex b/Doc/lib/libcfgparser.tex
@@ -135,6 +135,24 @@ \subsection{ConfigParser Objects \label{ConfigParser-objects}}
 \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.
+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}
 \end{methoddesc}
 
 \begin{methoddesc}{readfp}{fp\optional{, filename}}
