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

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.

1 files changed, 18 insertions, 0 deletions

diff --git a/Doc/lib/libcfgparser.tex b/Doc/lib/libcfgparser.tex
index 346ba8f..ff01fde 100644
--- a/Doc/lib/libcfgparser.tex
+++ b/Doc/lib/libcfgparser.tex
@@ -135,6 +135,24 @@ otherwise return 0.
 \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}}