Documented new built-in function vars().

Documented new formatting features: %s takes any type, and
'%(key)format' % dictionary.
Documented posixpath.expandvars().

6 files changed, 72 insertions, 2 deletions

diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index 73bc1454b7..ab4b03c98b 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -355,6 +355,18 @@ its goal is to return a printable string.
 \end{verbatim}\ecode
 \end{funcdesc}
 
+\begin{funcdesc}{vars}{}
+Without arguments, return a dictionary corresponding to the current
+local symbol table.  With a module, class or class instance object as
+argument (or anything else that has a \code{__dict__} attribute),
+returns a dictionary corresponding to the object's symbol table.
+The returned dictionary should not be modified: the effects on the
+corresponding symbol table are undefined.%
+\footnote{In the current implementation, local variable bindings
+cannot normally be affected this way, but variables retrieved from
+other scopes can be.  This may change.}
+\end{funcdesc}
+
 \begin{funcdesc}{xrange}{start\, end\, step}
 This function is very similar to \code{range()}, but returns an
 ``xrange object'' instead of a list.  This is an opaque sequence type
diff --git a/Doc/lib/libppath.tex b/Doc/lib/libppath.tex
index e6430be3ef..731d344dbe 100644
--- a/Doc/lib/libppath.tex
+++ b/Doc/lib/libppath.tex
@@ -34,6 +34,14 @@ the built-in module \code{pwd}.  If the expansion fails, or if the
 path does not begin with a tilde, the path is returned unchanged.
 \end{funcdesc}
 
+\begin{funcdesc}{expandvars}{p}
+Return the argument with environment variables expanded.  Substrings
+of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
+replaced by the value of environment variable \var{name}.  Malformed
+variable names and references to non-existing variables are left
+unchanged.
+\end{funcdesc}
+
 \begin{funcdesc}{isabs}{p}
 Return true if \var{p} is an absolute pathname (begins with a slash).
 \end{funcdesc}
diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex
index be8d9906dc..8c77e49aa1 100644
--- a/Doc/lib/libtypes.tex
+++ b/Doc/lib/libtypes.tex
@@ -300,7 +300,9 @@ characters are understood: \%, c, s, i, d, u, o, x, X, e, E, f, g, G.
 Width and precision may be a * to specify that an integer argument
 specifies the actual width or precision.  The flag characters -, +,
 blank, \# and 0 are understood.  The size specifiers h, l or L may be
-present but are ignored.  The ANSI features \code{\%p} and \code{\%n}
+present but are ignored.  The \code{\%s} conversion takes any Python
+object and converts it to a string using \code{str()} before
+formatting it.  The ANSI features \code{\%p} and \code{\%n}
 are not supported.  Since Python strings have an explicit length,
 \code{\%s} conversions don't assume that \code{'\\0'} is the end of
 the string.
@@ -309,6 +311,19 @@ For safety reasons, huge floating point precisions are truncated;
 \code{\%f} conversions for huge numbers are replaced by
 \code{\%g} conversions.  All other errors raise exceptions.
 
+If the right argument is a dictionary (or any kind of mapping), then
+the formats in the string must have a parenthesized key into that
+dictionary inserted immediately after the \code{\%} character, and
+each format formats the corresponding entry from the mapping.  E.g.
+\begin{verbatim}
+    >>> count = 2
+    >>> language = 'Python'
+    >>> print '%(language)s has %(count)03d quote types.' % vars()
+    Python has 002 quote types.
+    >>> 
+\end{verbatim}
+In this case no * specifiers may occur in a format.
+
 Additional string operations are defined in standard module
 \code{string} and in built-in module \code{regex}.
 \index{string}
diff --git a/Doc/libfuncs.tex b/Doc/libfuncs.tex
index 73bc1454b7..ab4b03c98b 100644
--- a/Doc/libfuncs.tex
+++ b/Doc/libfuncs.tex
@@ -355,6 +355,18 @@ its goal is to return a printable string.
 \end{verbatim}\ecode
 \end{funcdesc}
 
+\begin{funcdesc}{vars}{}
+Without arguments, return a dictionary corresponding to the current
+local symbol table.  With a module, class or class instance object as
+argument (or anything else that has a \code{__dict__} attribute),
+returns a dictionary corresponding to the object's symbol table.
+The returned dictionary should not be modified: the effects on the
+corresponding symbol table are undefined.%
+\footnote{In the current implementation, local variable bindings
+cannot normally be affected this way, but variables retrieved from
+other scopes can be.  This may change.}
+\end{funcdesc}
+
 \begin{funcdesc}{xrange}{start\, end\, step}
 This function is very similar to \code{range()}, but returns an
 ``xrange object'' instead of a list.  This is an opaque sequence type
diff --git a/Doc/libppath.tex b/Doc/libppath.tex
index e6430be3ef..731d344dbe 100644
--- a/Doc/libppath.tex
+++ b/Doc/libppath.tex
@@ -34,6 +34,14 @@ the built-in module \code{pwd}.  If the expansion fails, or if the
 path does not begin with a tilde, the path is returned unchanged.
 \end{funcdesc}
 
+\begin{funcdesc}{expandvars}{p}
+Return the argument with environment variables expanded.  Substrings
+of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
+replaced by the value of environment variable \var{name}.  Malformed
+variable names and references to non-existing variables are left
+unchanged.
+\end{funcdesc}
+
 \begin{funcdesc}{isabs}{p}
 Return true if \var{p} is an absolute pathname (begins with a slash).
 \end{funcdesc}
diff --git a/Doc/libtypes.tex b/Doc/libtypes.tex
index be8d9906dc..8c77e49aa1 100644
--- a/Doc/libtypes.tex
+++ b/Doc/libtypes.tex
@@ -300,7 +300,9 @@ characters are understood: \%, c, s, i, d, u, o, x, X, e, E, f, g, G.
 Width and precision may be a * to specify that an integer argument
 specifies the actual width or precision.  The flag characters -, +,
 blank, \# and 0 are understood.  The size specifiers h, l or L may be
-present but are ignored.  The ANSI features \code{\%p} and \code{\%n}
+present but are ignored.  The \code{\%s} conversion takes any Python
+object and converts it to a string using \code{str()} before
+formatting it.  The ANSI features \code{\%p} and \code{\%n}
 are not supported.  Since Python strings have an explicit length,
 \code{\%s} conversions don't assume that \code{'\\0'} is the end of
 the string.
@@ -309,6 +311,19 @@ For safety reasons, huge floating point precisions are truncated;
 \code{\%f} conversions for huge numbers are replaced by
 \code{\%g} conversions.  All other errors raise exceptions.
 
+If the right argument is a dictionary (or any kind of mapping), then
+the formats in the string must have a parenthesized key into that
+dictionary inserted immediately after the \code{\%} character, and
+each format formats the corresponding entry from the mapping.  E.g.
+\begin{verbatim}
+    >>> count = 2
+    >>> language = 'Python'
+    >>> print '%(language)s has %(count)03d quote types.' % vars()
+    Python has 002 quote types.
+    >>> 
+\end{verbatim}
+In this case no * specifiers may occur in a format.
+
 Additional string operations are defined in standard module
 \code{string} and in built-in module \code{regex}.
 \index{string}