backports:

revision 1.127
date: 2003/01/04 02:16:22;  author: rhettinger;  state: Exp;  lines: +1 -1
SF bug #655271: Slightly modify locals() doc

Clarify the operation of locals().

revision 1.125
date: 2002/12/17 01:08:06;  author: nnorwitz;  state: Exp;  lines: +6 -1
Fix SF # 641111, Undocumented side effect of eval

Try to clear up confusion about the current globals being copied
into a globals dict passed to eval().  This wording (more or less)
was suggested in bug report.  It should probably be made clearer.

revision 1.124
date: 2002/12/17 01:02:57;  author: nnorwitz;  state: Exp;  lines: +78 -0
Fix SF #642742, property() builtin not documented

Added doc for functions new to 2.2:  classmethod property staticmethod super
Taken from docstrings.  Could use review.
Hope there wasn't a reason why these shouldn't have been added.

diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index 2be606fbb100f05e523018706d94ecae318904cf..7d7a0da26d79edbfd2ed93af12bdbea0733823b5 100644 (file)
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -82,6 +82,17 @@ def my_import(name):
                    above.}
 \end{funcdesc}
 
+\begin{funcdesc}{bool}{x}
+  Convert a value to a Boolean, using the standard truth testing
+  procedure.  If \code{x} is false, this returns \code{False};
+  otherwise it returns \code{True}.  \code{bool} is also a class,
+  which is a subclass of \code{int}.  Class \code{bool} cannot be
+  subclassed further.  Its only instances are \code{False} and
+  \code{True}.
+\indexii{Boolean}{type}
+\versionadded{2.2.1}
+\end{funcdesc}
+
 \begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}}
   The \var{object} argument must be an object that supports the buffer
   call interface (such as strings, arrays, and buffers).  A new buffer
@@ -109,6 +120,29 @@ def my_import(name):
   if \var{i} is outside that range.
 \end{funcdesc}
 
+\begin{funcdesc}{classmethod}{function}
+  Return a class method for \var{function}.
+
+  A class method receives the class as implicit first argument,
+  just like an instance method receives the instance.
+  To declare a class method, use this idiom:
+
+\begin{verbatim}
+class C:
+    def f(cls, arg1, arg2, ...): ...
+    f = classmethod(f)
+\end{verbatim}
+
+  It can be called either on the class (e.g. C.f()) or on an instance
+  (e.g. C().f()).  The instance is ignored except for its class.
+  If a class method is called for a derived class, the derived class
+  object is passed as the implied first argument.
+
+  Class methods are different than C++ or Java static methods.
+  If you want those, see \ref{staticmethod}.
+  \versionadded{2.2}
+\end{funcdesc}
+
 \begin{funcdesc}{cmp}{x, y}
   Compare the two objects \var{x} and \var{y} and return an integer
   according to the outcome.  The return value is negative if \code{\var{x}
@@ -264,7 +298,12 @@ def my_import(name):
   \var{expression} argument is parsed and evaluated as a Python
   expression (technically speaking, a condition list) using the
   \var{globals} and \var{locals} dictionaries as global and local name
-  space.  If the \var{locals} dictionary is omitted it defaults to
+  space.  If the \var{globals} dictionary is present and lacks
+  '__builtins__', the current globals are copied into \var{globals} before
+  \var{expression} is parsed.  This means that \var{expression}
+  normally has full access to the standard
+  \refmodule[builtin]{__builtin__} module and restricted environments
+  are propagated.  If the \var{locals} dictionary is omitted it defaults to
   the \var{globals} dictionary.  If both dictionaries are omitted, the
   expression is executed in the environment where \keyword{eval} is
   called.  The return value is the result of the evaluated expression.
@@ -545,7 +584,7 @@ def my_import(name):
 \end{funcdesc}
 
 \begin{funcdesc}{locals}{}
-  Return a dictionary representing the current local symbol table.
+  Update and return a dictionary representing the current local symbol table.
   \warning{The contents of this dictionary should not be modified;
   changes may not affect the values of local variables used by the
   interpreter.}
@@ -632,6 +671,25 @@ def my_import(name):
   rounding accidents.)
 \end{funcdesc}
 
+\begin{funcdesc}{property}{\optional{fget\optional{, fset\optional{, fdel\optional{, doc}}}}}
+  Return a property attribute for new-style classes (classes that
+  derive from \function{object}.
+
+  \var{fget} is a function for getting an attribute value, likewise
+  \var{fset} is a function for setting, and \var{fdel} a function
+  for del'ing, an attribute.  Typical use is to define a managed attribute x:
+
+\begin{verbatim}
+class C(object):
+    def getx(self): return self.__x
+    def setx(self, value): self.__x = value
+    def delx(self): del self.__x
+        x = property(getx, setx, delx, "I'm the 'x' property.")
+\end{verbatim}
+
+  \versionadded{2.2}
+\end{funcdesc}
+
 \begin{funcdesc}{range}{\optional{start,} stop\optional{, step}}
   This is a versatile function to create lists containing arithmetic
   progressions.  It is most often used in \keyword{for} loops.  The
@@ -779,6 +837,41 @@ def my_import(name):
   \samp{a[start:stop, i]}.
 \end{funcdesc}
 
+\begin{funcdesc}{staticmethod}{function}
+  Return a static method for \var{function}.
+
+  A static method does not receive an implicit first argument.
+  To declare a static method, use this idiom:
+
+\begin{verbatim}
+class C:
+    def f(arg1, arg2, ...): ...
+    f = staticmethod(f)
+\end{verbatim}
+
+  It can be called either on the class (e.g. C.f()) or on an instance
+  (e.g. C().f()).  The instance is ignored except for its class.
+
+  Static methods in Python are similar to those found in Java or C++.
+  For a more advanced concept, see \ref{classmethod}.
+  \versionadded{2.2}
+\end{funcdesc}
+
+\begin{funcdesc}{super}{type\optional{object-or-type}}
+  Return the superclass of \var{type}.  If the second argument is omitted
+  the super object returned is unbound.  If the second argument is an
+  object, isinstance(obj, type) must be true.  If the second argument is a
+  type, issubclass(type2, type) must be true.
+
+  A typical use for calling a cooperative superclass method is:
+\begin{verbatim}
+class C(B):
+    def meth(self, arg):
+        super(C, self).meth(arg)
+\end{verbatim}
+\versionadded{2.2}
+\end{funcdesc}
+
 \begin{funcdesc}{str}{object}
   Return a string containing a nicely printable representation of an
   object.  For strings, this returns the string itself.  The