[Python-3000-checkins] r59275 - in python/branches/py3k: Doc/ACKS.txt Doc/Makefile Doc/README.txt Doc/c-api/init.rst Doc/c-api/utilities.rst Doc/c-api/veryhigh.rst Doc/data/refcounts.dat Doc/distutils/extending.rst Doc/extending/extending.rst Doc/glossary.rst Doc/library/atexit.rst Doc/library/bdb.rst Doc/library/codeop.rst Doc/library/contextlib.rst Doc/library/doctest.rst Doc/library/functions.rst Doc/library/functools.rst Doc/library/inspect.rst Doc/library/mmap.rst Doc/library/operator.rst Doc/library/stdtypes.rst Doc/library/sys.rst Doc/library/timeit.rst Doc/library/weakref.rst Doc/library/windows.rst Doc/library/xml.etree.elementtree.rst Doc/reference/compound_stmts.rst Doc/tutorial/stdlib2.rst Doc/using/cmdline.rst Doc/using/index.rst Doc/using/windows.rst Lib/tarfile.py Lib/test/test_cmd.py Lib/test/test_tarfile.py Misc/ACKS
christian.heimes
python-3000-checkins at python.org
Sun Dec 2 16:22:17 CET 2007
Author: christian.heimes
Date: Sun Dec 2 16:22:16 2007
New Revision: 59275
Added:
python/branches/py3k/Doc/using/windows.rst
- copied unchanged from r59274, python/trunk/Doc/using/windows.rst
python/branches/py3k/Lib/test/test_cmd.py
- copied unchanged from r59274, python/trunk/Lib/test/test_cmd.py
Modified:
python/branches/py3k/ (props changed)
python/branches/py3k/Doc/ACKS.txt
python/branches/py3k/Doc/Makefile
python/branches/py3k/Doc/README.txt
python/branches/py3k/Doc/c-api/init.rst
python/branches/py3k/Doc/c-api/utilities.rst
python/branches/py3k/Doc/c-api/veryhigh.rst
python/branches/py3k/Doc/data/refcounts.dat
python/branches/py3k/Doc/distutils/extending.rst
python/branches/py3k/Doc/extending/extending.rst
python/branches/py3k/Doc/glossary.rst
python/branches/py3k/Doc/library/atexit.rst
python/branches/py3k/Doc/library/bdb.rst
python/branches/py3k/Doc/library/codeop.rst
python/branches/py3k/Doc/library/contextlib.rst
python/branches/py3k/Doc/library/doctest.rst
python/branches/py3k/Doc/library/functions.rst
python/branches/py3k/Doc/library/functools.rst
python/branches/py3k/Doc/library/inspect.rst
python/branches/py3k/Doc/library/mmap.rst
python/branches/py3k/Doc/library/operator.rst
python/branches/py3k/Doc/library/stdtypes.rst
python/branches/py3k/Doc/library/sys.rst
python/branches/py3k/Doc/library/timeit.rst
python/branches/py3k/Doc/library/weakref.rst
python/branches/py3k/Doc/library/windows.rst
python/branches/py3k/Doc/library/xml.etree.elementtree.rst
python/branches/py3k/Doc/reference/compound_stmts.rst
python/branches/py3k/Doc/tutorial/stdlib2.rst
python/branches/py3k/Doc/using/cmdline.rst
python/branches/py3k/Doc/using/index.rst
python/branches/py3k/Lib/tarfile.py
python/branches/py3k/Lib/test/test_tarfile.py
python/branches/py3k/Misc/ACKS
Log:
Merged revisions 59259-59274 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r59260 | lars.gustaebel | 2007-12-01 22:02:12 +0100 (Sat, 01 Dec 2007) | 5 lines
Issue #1531: Read fileobj from the current offset, do not seek to
the start.
(will backport to 2.5)
........
r59262 | georg.brandl | 2007-12-01 23:24:47 +0100 (Sat, 01 Dec 2007) | 4 lines
Document PyEval_* functions from ceval.c.
Credits to Michael Sloan from GHOP.
........
r59263 | georg.brandl | 2007-12-01 23:27:56 +0100 (Sat, 01 Dec 2007) | 2 lines
Add a few refcount data entries.
........
r59264 | georg.brandl | 2007-12-01 23:38:48 +0100 (Sat, 01 Dec 2007) | 4 lines
Add test suite for cmd module.
Written by Michael Schneider for GHOP.
........
r59265 | georg.brandl | 2007-12-01 23:42:46 +0100 (Sat, 01 Dec 2007) | 3 lines
Add examples to the ElementTree documentation.
Written by h4wk.cz for GHOP.
........
r59266 | georg.brandl | 2007-12-02 00:12:45 +0100 (Sun, 02 Dec 2007) | 3 lines
Add "Using Python on Windows" document, by Robert Lehmann.
Written for GHOP.
........
r59271 | georg.brandl | 2007-12-02 15:34:34 +0100 (Sun, 02 Dec 2007) | 3 lines
Add example to mmap docs.
Written for GHOP by Rafal Rawicki.
........
r59272 | georg.brandl | 2007-12-02 15:37:29 +0100 (Sun, 02 Dec 2007) | 2 lines
Convert bdb.rst line endings to Unix style.
........
r59274 | georg.brandl | 2007-12-02 15:58:50 +0100 (Sun, 02 Dec 2007) | 4 lines
Add more entries to the glossary.
Written by Jeff Wheeler for GHOP.
........
Modified: python/branches/py3k/Doc/ACKS.txt
==============================================================================
--- python/branches/py3k/Doc/ACKS.txt (original)
+++ python/branches/py3k/Doc/ACKS.txt Sun Dec 2 16:22:16 2007
@@ -163,6 +163,7 @@
* Justin Sheehy
* Michael Simcich
* Ionel Simionescu
+* Michael Sloan
* Gregory P. Smith
* Roy Smith
* Clay Spence
@@ -185,6 +186,7 @@
* Glyn Webster
* Bob Weiner
* Eddy Welbourne
+* Jeff Wheeler
* Mats Wichmann
* Gerry Wiener
* Timothy Wild
Modified: python/branches/py3k/Doc/Makefile
==============================================================================
--- python/branches/py3k/Doc/Makefile (original)
+++ python/branches/py3k/Doc/Makefile Sun Dec 2 16:22:16 2007
@@ -57,6 +57,10 @@
@echo "Build finished; now you can run HTML Help Workshop with the" \
"build/htmlhelp/pydoc.hhp project file."
+latex: BUILDER = latex
+latex: build
+ @echo "Build finished; the LaTeX files are in build/latex."
+
clean:
-rm -rf build/*
-rm -rf tools/sphinx
Modified: python/branches/py3k/Doc/README.txt
==============================================================================
--- python/branches/py3k/Doc/README.txt (original)
+++ python/branches/py3k/Doc/README.txt Sun Dec 2 16:22:16 2007
@@ -53,6 +53,9 @@
To create the CHM file, you need to run the Microsoft HTML Help Workshop
over the generated project (.hhp) file.
+ * "latex", which builds LaTeX source files that can be run with "pdflatex"
+ to produce PDF documents.
+
A "make update" updates the Subversion checkouts in `tools/`.
Modified: python/branches/py3k/Doc/c-api/init.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/init.rst (original)
+++ python/branches/py3k/Doc/c-api/init.rst Sun Dec 2 16:22:16 2007
@@ -615,6 +615,14 @@
deadlock ensues. (This function is available even when thread support is
disabled at compile time.)
+
+.. cfunction:: void PyEval_ReInitThreads()
+
+ This function is called from :cfunc:`PyOS_AfterFork` to ensure that newly
+ created child processes don't hold locks referring to threads which
+ are not running in the child process.
+
+
The following macros are normally used without a trailing semicolon; look for
example usage in the Python source distribution.
@@ -876,6 +884,46 @@
:cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number
events.
+.. cfunction:: PyObject* PyEval_GetCallStats(PyObject *self)
+
+ Return a tuple of function call counts. There are constants defined for the
+ positions within the tuple:
+
+ +-------------------------------+-------+
+ | Name | Value |
+ +===============================+=======+
+ | :const:`PCALL_ALL` | 0 |
+ +-------------------------------+-------+
+ | :const:`PCALL_FUNCTION` | 1 |
+ +-------------------------------+-------+
+ | :const:`PCALL_FAST_FUNCTION` | 2 |
+ +-------------------------------+-------+
+ | :const:`PCALL_FASTER_FUNCTION`| 3 |
+ +-------------------------------+-------+
+ | :const:`PCALL_METHOD` | 4 |
+ +-------------------------------+-------+
+ | :const:`PCALL_BOUND_METHOD` | 5 |
+ +-------------------------------+-------+
+ | :const:`PCALL_CFUNCTION` | 6 |
+ +-------------------------------+-------+
+ | :const:`PCALL_TYPE` | 7 |
+ +-------------------------------+-------+
+ | :const:`PCALL_GENERATOR` | 8 |
+ +-------------------------------+-------+
+ | :const:`PCALL_OTHER` | 9 |
+ +-------------------------------+-------+
+ | :const:`PCALL_POP` | 10 |
+ +-------------------------------+-------+
+
+ :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created.
+ :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used.
+
+ If there is a method call where the call can be optimized by changing
+ the argument tuple and calling the function directly, it gets recorded
+ twice.
+
+ This function is only present if Python is compiled with :const:`CALL_PROFILE`
+ defined.
.. _advanced-debugging:
Modified: python/branches/py3k/Doc/c-api/utilities.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/utilities.rst (original)
+++ python/branches/py3k/Doc/c-api/utilities.rst Sun Dec 2 16:22:16 2007
@@ -989,3 +989,52 @@
See the Unix man page :manpage:`atof(2)` for details.
+
+.. _reflection:
+
+Reflection
+==========
+
+.. cfunction:: PyObject* PyEval_GetBuiltins()
+
+ Return a dictionary of the builtins in the current execution frame,
+ or the interpreter of the thread state if no frame is currently executing.
+
+
+.. cfunction:: PyObject* PyEval_GetLocals()
+
+ Return a dictionary of the local variables in the current execution frame,
+ or *NULL* if no frame is currently executing.
+
+
+.. cfunction:: PyObject* PyEval_GetGlobals()
+
+ Return a dictionary of the global variables in the current execution frame,
+ or *NULL* if no frame is currently executing.
+
+
+.. cfunction:: PyFrameObject* PyEval_GetFrame()
+
+ Return the current thread state's frame, which is *NULL* if no frame is
+ currently executing.
+
+
+.. cfunction:: int PyEval_GetRestricted()
+
+ If there is a current frame and it is executing in restricted mode, return true,
+ otherwise false.
+
+
+.. cfunction:: const char* PyEval_GetFuncName(PyObject *func)
+
+ Return the name of *func* if it is a function, class or instance object, else the
+ name of *func*\s type.
+
+
+.. cfunction:: const char* PyEval_GetFuncDesc(PyObject *func)
+
+ Return a description string, depending on the type of *func*.
+ Return values include "()" for functions and methods, " constructor",
+ " instance", and " object". Concatenated with the result of
+ :cfunc:`PyEval_GetFuncName`, the result will be a description of
+ *func*.
Modified: python/branches/py3k/Doc/c-api/veryhigh.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/veryhigh.rst (original)
+++ python/branches/py3k/Doc/c-api/veryhigh.rst Sun Dec 2 16:22:16 2007
@@ -229,6 +229,43 @@
be parsed or compiled.
+.. cfunction:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)
+
+ This is a simplified interface to :cfunc:`PyEval_EvalCodeEx`, with just
+ the code object, and the dictionaries of global and local variables.
+ The other arguments are set to *NULL*.
+
+
+.. cfunction:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)
+
+ Evaluate a precompiled code object, given a particular environment for its
+ evaluation. This environment consists of dictionaries of global and local
+ variables, arrays of arguments, keywords and defaults, and a closure tuple of
+ cells.
+
+
+.. cfunction:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
+
+ Evaluate an execution frame. This is a simplified interface to
+ PyEval_EvalFrameEx, for backward compatibility.
+
+
+.. cfunction:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
+
+ This is the main, unvarnished function of Python interpretation. It is
+ literally 2000 lines long. The code object associated with the execution
+ frame *f* is executed, interpreting bytecode and executing calls as needed.
+ The additional *throwflag* parameter can mostly be ignored - if true, then
+ it causes an exception to immediately be thrown; this is used for the
+ :meth:`throw` methods of generator objects.
+
+
+.. cfunction:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
+
+ This function changes the flags of the current evaluation frame, and returns
+ true on success, false on failure.
+
+
.. cvar:: int Py_eval_input
.. index:: single: Py_CompileString()
Modified: python/branches/py3k/Doc/data/refcounts.dat
==============================================================================
--- python/branches/py3k/Doc/data/refcounts.dat (original)
+++ python/branches/py3k/Doc/data/refcounts.dat Sun Dec 2 16:22:16 2007
@@ -309,6 +309,11 @@
PyEval_AcquireThread:void:::
PyEval_AcquireThread:PyThreadState*:tstate::
+PyEval_GetBuiltins:PyObject*::0:
+PyEval_GetLocals:PyObject*::0:
+PyEval_GetGlobals:PyObject*::0:
+PyEval_GetFrame:PyObject*::0:
+
PyEval_InitThreads:void:::
PyEval_ReleaseLock:void:::
Modified: python/branches/py3k/Doc/distutils/extending.rst
==============================================================================
--- python/branches/py3k/Doc/distutils/extending.rst (original)
+++ python/branches/py3k/Doc/distutils/extending.rst Sun Dec 2 16:22:16 2007
@@ -1,4 +1,4 @@
-.. _extending:
+.. _extending-distutils:
*******************
Extending Distutils
Modified: python/branches/py3k/Doc/extending/extending.rst
==============================================================================
--- python/branches/py3k/Doc/extending/extending.rst (original)
+++ python/branches/py3k/Doc/extending/extending.rst Sun Dec 2 16:22:16 2007
@@ -466,10 +466,10 @@
:cfunc:`PyEval_CallObject`. This function has two arguments, both pointers to
arbitrary Python objects: the Python function, and the argument list. The
argument list must always be a tuple object, whose length is the number of
-arguments. To call the Python function with no arguments, pass an empty tuple;
-to call it with one argument, pass a singleton tuple. :cfunc:`Py_BuildValue`
-returns a tuple when its format string consists of zero or more format codes
-between parentheses. For example::
+arguments. To call the Python function with no arguments, pass in NULL, or
+an empty tuple; to call it with one argument, pass a singleton tuple.
+:cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero
+or more format codes between parentheses. For example::
int arg;
PyObject *arglist;
@@ -527,9 +527,22 @@
Py_DECREF(result);
Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
-the error check! Also note that strictly spoken this code is not complete:
+the error check! Also note that strictly speaking this code is not complete:
:cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
+You may also call a function with keyword arguments by using
+:cfunc:`PyEval_CallObjectWithKeywords`. As in the above example, we use
+:cfunc:`Py_BuildValue` to construct the dictionary. ::
+
+ PyObject *dict;
+ ...
+ dict = Py_BuildValue("{s:i}", "name", val);
+ result = PyEval_CallObjectWithKeywords(my_callback, NULL, dict);
+ Py_DECREF(dict);
+ if (result == NULL)
+ return NULL; /* Pass error back */
+ /* Here maybe use the result */
+ Py_DECREF(result);
.. _parsetuple:
Modified: python/branches/py3k/Doc/glossary.rst
==============================================================================
--- python/branches/py3k/Doc/glossary.rst (original)
+++ python/branches/py3k/Doc/glossary.rst Sun Dec 2 16:22:16 2007
@@ -15,6 +15,17 @@
``...``
The typical Python prompt of the interactive shell when entering code for
an indented code block.
+
+ argument
+ A value passed to a function or method, assigned to a name local to
+ the body. A function or method may have both positional arguments and
+ keyword arguments in its definition. Positional and keyword arguments
+ may be variable-length: ``*`` accepts or passes (if in the function
+ definition or call) several positional arguments in a list, while ``**``
+ does the same for keyword arguments in a dictionary.
+
+ Any expression may be used within the argument list, and the evaluated
+ value is passed to the local variable.
BDFL
Benevolent Dictator For Life, a.k.a. `Guido van Rossum
@@ -44,6 +55,22 @@
advanced mathematical feature. If you're not aware of a need for them,
it's almost certain you can safely ignore them.
+ decorator
+ A function returning another function, usually applied as a function
+ transformation using the ``@wrapper`` syntax. Common examples for
+ decorators are :func:`classmethod` and :func:`staticmethod`.
+
+ The decorator syntax is merely syntactic sugar, the following two
+ function definitions are semantically equivalent::
+
+ def f(...):
+ ...
+ f = staticmethod(f)
+
+ @staticmethod
+ def f(...):
+ ...
+
descriptor
An object that defines the methods :meth:`__get__`, :meth:`__set__`, or
:meth:`__delete__`. When a class attribute is a descriptor, its special
@@ -81,10 +108,24 @@
statements. The technique contrasts with the :term:`LBYL` style that is
common in many other languages such as C.
+ expression
+ A piece of syntax which can be evaluated to some value. In other words,
+ an expression is an accumulation of expression elements like literals, names,
+ attribute access, operators or function calls that all return a value.
+ In contrast to other languages, not all language constructs are expressions,
+ but there are also :term:`statement`\s that cannot be used as expressions,
+ such as :keyword:`print` or :keyword:`if`. Assignments are also not
+ expressions.
+
extension module
A module written in C, using Python's C API to interact with the core and
with user code.
-
+
+ function
+ A series of statements which returns some value to a caller. It can also
+ be passed zero or more arguments which may be used in the execution of
+ the body. See also :term:`argument` and :term:`method`.
+
__future__
A pseudo module which programmers can use to enable new language features
which are not compatible with the current interpreter. For example, the
@@ -228,6 +269,17 @@
More information can be found in :ref:`typeiter`.
+ keyword argument
+ Arguments which are preceded with a ``variable_name=`` in the call.
+ The variable name designates the local name in the function to which the
+ value is assigned. ``**`` is used to accept or pass a dictionary of
+ keyword arguments. See :term:`argument`.
+
+ lambda
+ An anonymous inline function consisting of a single :term:`expression`
+ which is evaluated when the function is called. The syntax to create
+ a lambda function is ``lambda [arguments]: expression``
+
LBYL
Look before you leap. This coding style explicitly tests for
pre-conditions before making calls or lookups. This style contrasts with
@@ -258,6 +310,12 @@
singletons, and many other tasks.
More information can be found in :ref:`metaclasses`.
+
+ method
+ A function that is defined inside a class body. If called as an attribute
+ of an instance of that class, the method will get the instance object as
+ its first :term:`argument` (which is usually called ``self``).
+ See :term:`function` and :term:`nested scope`.
mutable
Mutable objects can change their value but keep their :func:`id`. See
@@ -291,10 +349,32 @@
More information can be found in :ref:`newstyle`.
+ positional argument
+ The arguments assigned to local names inside a function or method,
+ determined by the order in which they were given in the call. ``*`` is
+ used to either accept multiple positional arguments (when in the
+ definition), or pass several arguments as a list to a function. See
+ :term:`argument`.
+
Python 3000
Nickname for the next major Python version, 3.0 (coined long ago when the
release of version 3 was something in the distant future.)
+ Pythonic
+ An idea or piece of code which closely follows the most common idioms of
+ the Python language, rather than implementing code using concepts common
+ in other languages. For example, a common idiom in Python is the :keyword:`for`
+ loop structure; other languages don't have this easy keyword, so people
+ use a numerical counter instead::
+
+ for i in range(len(food)):
+ print food[i]
+
+ As opposed to the cleaner, Pythonic method::
+
+ for piece in food:
+ print piece
+
reference count
The number of places where a certain object is referenced to. When the
reference count drops to zero, an object is deallocated. While reference
@@ -317,6 +397,18 @@
mapping rather than a sequence because the lookups use arbitrary
:term:`immutable` keys rather than integers.
+ slice
+ A list containing a portion of an indexed list-like object. A slice is
+ created using the subscript notation, ``[]`` with colons between numbers
+ when several are given, such as in ``variable_name[1:3:5]``. The bracket
+ (subscript) notation uses :class:`slice` objects internally (or in older
+ versions, :meth:`__getslice__` and :meth:`__setslice__`).
+
+ statement
+ A statement is part of a suite (a "block" of code). A statement is either
+ an :term:`expression` or a one of several constructs with a keyword, such
+ as :keyword:`if`, :keyword:`while` or :keyword:`print`.
+
type
The type of a Python object determines what kind of object it is; every
object has a type. An object's type is accessible as its
Modified: python/branches/py3k/Doc/library/atexit.rst
==============================================================================
--- python/branches/py3k/Doc/library/atexit.rst (original)
+++ python/branches/py3k/Doc/library/atexit.rst Sun Dec 2 16:22:16 2007
@@ -88,7 +88,7 @@
# or:
atexit.register(goodbye, adjective='nice', name='Donny')
-Usage as a decorator::
+Usage as a :term:`decorator`::
import atexit
Modified: python/branches/py3k/Doc/library/bdb.rst
==============================================================================
--- python/branches/py3k/Doc/library/bdb.rst (original)
+++ python/branches/py3k/Doc/library/bdb.rst Sun Dec 2 16:22:16 2007
@@ -1,337 +1,337 @@
-:mod:`bdb` --- Debugger framework
-=================================
-
-.. module:: bdb
- :synopsis: Debugger framework.
-
-The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
-or managing execution via the debugger.
-
-The following exception is defined:
-
-.. exception:: BdbQuit
-
- Exception raised by the :class:`Bdb` class for quitting the debugger.
-
-
-The :mod:`bdb` module also defines two classes:
-
-.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])
-
- This class implements temporary breakpoints, ignore counts, disabling and
- (re-)enabling, and conditionals.
-
- Breakpoints are indexed by number through a list called :attr:`bpbynumber`
- and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a
- single instance of class :class:`Breakpoint`. The latter points to a list of
- such instances since there may be more than one breakpoint per line.
-
- When creating a breakpoint, its associated filename should be in canonical
- form. If a *funcname* is defined, a breakpoint hit will be counted when the
- first line of that function is executed. A conditional breakpoint always
- counts a hit.
-
-:class:`Breakpoint` instances have the following methods:
-
-.. method:: Breakpoint.deleteMe()
-
- Delete the breakpoint from the list associated to a file/line. If it is the
- last breakpoint in that position, it also deletes the entry for the
- file/line.
-
-.. method:: Breakpoint.enable()
-
- Mark the breakpoint as enabled.
-
-.. method:: Breakpoint.disable()
-
- Mark the breakpoint as disabled.
-
-.. method:: Breakpoint.bpprint([out])
-
- Print all the information about the breakpoint:
-
- * The breakpoint number.
- * If it is temporary or not.
- * Its file,line position.
- * The condition that causes a break.
- * If it must be ignored the next N times.
- * The breakpoint hit count.
-
-
-.. class:: Bdb()
-
- The :class:`Bdb` acts as a generic Python debugger base class.
-
- This class takes care of the details of the trace facility; a derived class
- should implement user interaction. The standard debugger class
- (:class:`pdb.Pdb`) is an example.
-
-
-The following methods of :class:`Bdb` normally don't need to be overridden.
-
-.. method:: Bdb.canonic(filename)
-
- Auxiliary method for getting a filename in a canonical form, that is, as a
- case-normalized (on case-insensitive filesystems) absolute path, stripped
- of surrounding angle brackets.
-
-.. method:: Bdb.reset()
-
- Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
- :attr:`quitting` attributes with values ready to start debugging.
-
-
-.. method:: Bdb.trace_dispatch(frame, event, arg)
-
- This function is installed as the trace function of debugged frames. Its
- return value is the new trace function (in most cases, that is, itself).
-
- The default implementation decides how to dispatch a frame, depending on the
- type of event (passed as a string) that is about to be executed. *event* can
- be one of the following:
-
- * ``"line"``: A new line of code is going to be executed.
- * ``"call"``: A function is about to be called, or another code block
- entered.
- * ``"return"``: A function or other code block is about to return.
- * ``"exception"``: An exception has occurred.
- * ``"c_call"``: A C function is about to be called.
- * ``"c_return"``: A C function has returned.
- * ``"c_exception"``: A C function has thrown an exception.
-
- For the Python events, specialized functions (see below) are called. For the
- C events, no action is taken.
-
- The *arg* parameter depends on the previous event.
-
- For more information on trace functions, see :ref:`debugger-hooks`. For more
- information on code and frame objects, refer to :ref:`types`.
-
-.. method:: Bdb.dispatch_line(frame)
-
- If the debugger should stop on the current line, invoke the :meth:`user_line`
- method (which should be overridden in subclasses). Raise a :exc:`BdbQuit`
- exception if the :attr:`Bdb.quitting` flag is set (which can be set from
- :meth:`user_line`). Return a reference to the :meth:`trace_dispatch` method
- for further tracing in that scope.
-
-.. method:: Bdb.dispatch_call(frame, arg)
-
- If the debugger should stop on this function call, invoke the
- :meth:`user_call` method (which should be overridden in subclasses). Raise a
- :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
- be set from :meth:`user_call`). Return a reference to the
- :meth:`trace_dispatch` method for further tracing in that scope.
-
-.. method:: Bdb.dispatch_return(frame, arg)
-
- If the debugger should stop on this function return, invoke the
- :meth:`user_return` method (which should be overridden in subclasses). Raise
- a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
- be set from :meth:`user_return`). Return a reference to the
- :meth:`trace_dispatch` method for further tracing in that scope.
-
-.. method:: Bdb.dispatch_exception(frame, arg)
-
- If the debugger should stop at this exception, invokes the
- :meth:`user_exception` method (which should be overridden in subclasses).
- Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
- (which can be set from :meth:`user_exception`). Return a reference to the
- :meth:`trace_dispatch` method for further tracing in that scope.
-
-Normally derived classes don't override the following methods, but they may if
-they want to redefine the definition of stopping and breakpoints.
-
-.. method:: Bdb.stop_here(frame)
-
- This method checks if the *frame* is somewhere below :attr:`botframe` in the
- call stack. :attr:`botframe` is the frame in which debugging started.
-
-.. method:: Bdb.break_here(frame)
-
- This method checks if there is a breakpoint in the filename and line
- belonging to *frame* or, at least, in the current function. If the
- breakpoint is a temporary one, this method deletes it.
-
-.. method:: Bdb.break_anywhere(frame)
-
- This method checks if there is a breakpoint in the filename of the current
- frame.
-
-Derived classes should override these methods to gain control over debugger
-operation.
-
-.. method:: Bdb.user_call(frame, argument_list)
-
- This method is called from :meth:`dispatch_call` when there is the
- possibility that a break might be necessary anywhere inside the called
- function.
-
-.. method:: Bdb.user_line(frame)
-
- This method is called from :meth:`dispatch_line` when either
- :meth:`stop_here` or :meth:`break_here` yields True.
-
-.. method:: Bdb.user_return(frame, return_value)
-
- This method is called from :meth:`dispatch_return` when :meth:`stop_here`
- yields True.
-
-.. method:: Bdb.user_exception(frame, exc_info)
-
- This method is called from :meth:`dispatch_exception` when :meth:`stop_here`
- yields True.
-
-.. method:: Bdb.do_clear(arg)
-
- Handle how a breakpoint must be removed when it is a temporary one.
-
- This method must be implemented by derived classes.
-
-
-Derived classes and clients can call the following methods to affect the
-stepping state.
-
-.. method:: Bdb.set_step()
-
- Stop after one line of code.
-
-.. method:: Bdb.set_next(frame)
-
- Stop on the next line in or below the given frame.
-
-.. method:: Bdb.set_return(frame)
-
- Stop when returning from the given frame.
-
-.. method:: Bdb.set_trace([frame])
-
- Start debugging from *frame*. If *frame* is not specified, debugging starts
- from caller's frame.
-
-.. method:: Bdb.set_continue()
-
- Stop only at breakpoints or when finished. If there are no breakpoints, set
- the system trace function to None.
-
-.. method:: Bdb.set_quit()
-
- Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in
- the next call to one of the :meth:`dispatch_\*` methods.
-
-
-Derived classes and clients can call the following methods to manipulate
-breakpoints. These methods return a string containing an error message if
-something went wrong, or ``None`` if all is well.
-
-.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
-
- Set a new breakpoint. If the *lineno* line doesn't exist for the *filename*
- passed as argument, return an error message. The *filename* should be in
- canonical form, as described in the :meth:`canonic` method.
-
-.. method:: Bdb.clear_break(filename, lineno)
-
- Delete the breakpoints in *filename* and *lineno*. If none were set, an
- error message is returned.
-
-.. method:: Bdb.clear_bpbynumber(arg)
-
- Delete the breakpoint which has the index *arg* in the
- :attr:`Breakpoint.bpbynumber`. If `arg` is not numeric or out of range,
- return an error message.
-
-.. method:: Bdb.clear_all_file_breaks(filename)
-
- Delete all breakpoints in *filename*. If none were set, an error message is
- returned.
-
-.. method:: Bdb.clear_all_breaks()
-
- Delete all existing breakpoints.
-
-.. method:: Bdb.get_break(filename, lineno)
-
- Check if there is a breakpoint for *lineno* of *filename*.
-
-.. method:: Bdb.get_breaks(filename, lineno)
-
- Return all breakpoints for *lineno* in *filename*, or an empty list if none
- are set.
-
-.. method:: Bdb.get_file_breaks(filename)
-
- Return all breakpoints in *filename*, or an empty list if none are set.
-
-.. method:: Bdb.get_all_breaks()
-
- Return all breakpoints that are set.
-
-
-Derived classes and clients can call the following methods to get a data
-structure representing a stack trace.
-
-.. method:: Bdb.get_stack(f, t)
-
- Get a list of records for a frame and all higher (calling) and lower frames,
- and the size of the higher part.
-
-.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])
-
- Return a string with information about a stack entry, identified by a
- ``(frame, lineno)`` tuple:
-
- * The canonical form of the filename which contains the frame.
- * The function name, or ``"<lambda>"``.
- * The input arguments.
- * The return value.
- * The line of code (if it exists).
-
-
-The following two methods can be called by clients to use a debugger to debug a
-statement, given as a string.
-
-.. method:: Bdb.run(cmd, [globals, [locals]])
-
- Debug a statement executed via the :func:`exec` function. *globals*
- defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
-
-.. method:: Bdb.runeval(expr, [globals, [locals]])
-
- Debug an expression executed via the :func:`eval` function. *globals* and
- *locals* have the same meaning as in :meth:`run`.
-
-.. method:: Bdb.runctx(cmd, globals, locals)
-
- For backwards compatibility. Calls the :meth:`run` method.
-
-.. method:: Bdb.runcall(func, *args, **kwds)
-
- Debug a single function call, and return its result.
-
-
-Finally, the module defines the following functions:
-
-.. function:: checkfuncname(b, frame)
-
- Check whether we should break here, depending on the way the breakpoint *b*
- was set.
-
- If it was set via line number, it checks if ``b.line`` is the same as the one
- in the frame also passed as argument. If the breakpoint was set via function
- name, we have to check we are in the right frame (the right function) and if
- we are in its first executable line.
-
-.. function:: effective(file, line, frame)
-
- Determine if there is an effective (active) breakpoint at this line of code.
- Return breakpoint number or 0 if none.
-
- Called only if we know there is a breakpoint at this location. Returns the
- breakpoint that was triggered and a flag that indicates if it is ok to delete
- a temporary breakpoint.
-
-.. function:: set_trace()
-
- Starts debugging with a :class:`Bdb` instance from caller's frame.
+:mod:`bdb` --- Debugger framework
+=================================
+
+.. module:: bdb
+ :synopsis: Debugger framework.
+
+The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
+or managing execution via the debugger.
+
+The following exception is defined:
+
+.. exception:: BdbQuit
+
+ Exception raised by the :class:`Bdb` class for quitting the debugger.
+
+
+The :mod:`bdb` module also defines two classes:
+
+.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])
+
+ This class implements temporary breakpoints, ignore counts, disabling and
+ (re-)enabling, and conditionals.
+
+ Breakpoints are indexed by number through a list called :attr:`bpbynumber`
+ and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a
+ single instance of class :class:`Breakpoint`. The latter points to a list of
+ such instances since there may be more than one breakpoint per line.
+
+ When creating a breakpoint, its associated filename should be in canonical
+ form. If a *funcname* is defined, a breakpoint hit will be counted when the
+ first line of that function is executed. A conditional breakpoint always
+ counts a hit.
+
+:class:`Breakpoint` instances have the following methods:
+
+.. method:: Breakpoint.deleteMe()
+
+ Delete the breakpoint from the list associated to a file/line. If it is the
+ last breakpoint in that position, it also deletes the entry for the
+ file/line.
+
+.. method:: Breakpoint.enable()
+
+ Mark the breakpoint as enabled.
+
+.. method:: Breakpoint.disable()
+
+ Mark the breakpoint as disabled.
+
+.. method:: Breakpoint.bpprint([out])
+
+ Print all the information about the breakpoint:
+
+ * The breakpoint number.
+ * If it is temporary or not.
+ * Its file,line position.
+ * The condition that causes a break.
+ * If it must be ignored the next N times.
+ * The breakpoint hit count.
+
+
+.. class:: Bdb()
+
+ The :class:`Bdb` acts as a generic Python debugger base class.
+
+ This class takes care of the details of the trace facility; a derived class
+ should implement user interaction. The standard debugger class
+ (:class:`pdb.Pdb`) is an example.
+
+
+The following methods of :class:`Bdb` normally don't need to be overridden.
+
+.. method:: Bdb.canonic(filename)
+
+ Auxiliary method for getting a filename in a canonical form, that is, as a
+ case-normalized (on case-insensitive filesystems) absolute path, stripped
+ of surrounding angle brackets.
+
+.. method:: Bdb.reset()
+
+ Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
+ :attr:`quitting` attributes with values ready to start debugging.
+
+
+.. method:: Bdb.trace_dispatch(frame, event, arg)
+
+ This function is installed as the trace function of debugged frames. Its
+ return value is the new trace function (in most cases, that is, itself).
+
+ The default implementation decides how to dispatch a frame, depending on the
+ type of event (passed as a string) that is about to be executed. *event* can
+ be one of the following:
+
+ * ``"line"``: A new line of code is going to be executed.
+ * ``"call"``: A function is about to be called, or another code block
+ entered.
+ * ``"return"``: A function or other code block is about to return.
+ * ``"exception"``: An exception has occurred.
+ * ``"c_call"``: A C function is about to be called.
+ * ``"c_return"``: A C function has returned.
+ * ``"c_exception"``: A C function has thrown an exception.
+
+ For the Python events, specialized functions (see below) are called. For the
+ C events, no action is taken.
+
+ The *arg* parameter depends on the previous event.
+
+ For more information on trace functions, see :ref:`debugger-hooks`. For more
+ information on code and frame objects, refer to :ref:`types`.
+
+.. method:: Bdb.dispatch_line(frame)
+
+ If the debugger should stop on the current line, invoke the :meth:`user_line`
+ method (which should be overridden in subclasses). Raise a :exc:`BdbQuit`
+ exception if the :attr:`Bdb.quitting` flag is set (which can be set from
+ :meth:`user_line`). Return a reference to the :meth:`trace_dispatch` method
+ for further tracing in that scope.
+
+.. method:: Bdb.dispatch_call(frame, arg)
+
+ If the debugger should stop on this function call, invoke the
+ :meth:`user_call` method (which should be overridden in subclasses). Raise a
+ :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
+ be set from :meth:`user_call`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
+
+.. method:: Bdb.dispatch_return(frame, arg)
+
+ If the debugger should stop on this function return, invoke the
+ :meth:`user_return` method (which should be overridden in subclasses). Raise
+ a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
+ be set from :meth:`user_return`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
+
+.. method:: Bdb.dispatch_exception(frame, arg)
+
+ If the debugger should stop at this exception, invokes the
+ :meth:`user_exception` method (which should be overridden in subclasses).
+ Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
+ (which can be set from :meth:`user_exception`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
+
+Normally derived classes don't override the following methods, but they may if
+they want to redefine the definition of stopping and breakpoints.
+
+.. method:: Bdb.stop_here(frame)
+
+ This method checks if the *frame* is somewhere below :attr:`botframe` in the
+ call stack. :attr:`botframe` is the frame in which debugging started.
+
+.. method:: Bdb.break_here(frame)
+
+ This method checks if there is a breakpoint in the filename and line
+ belonging to *frame* or, at least, in the current function. If the
+ breakpoint is a temporary one, this method deletes it.
+
+.. method:: Bdb.break_anywhere(frame)
+
+ This method checks if there is a breakpoint in the filename of the current
+ frame.
+
+Derived classes should override these methods to gain control over debugger
+operation.
+
+.. method:: Bdb.user_call(frame, argument_list)
+
+ This method is called from :meth:`dispatch_call` when there is the
+ possibility that a break might be necessary anywhere inside the called
+ function.
+
+.. method:: Bdb.user_line(frame)
+
+ This method is called from :meth:`dispatch_line` when either
+ :meth:`stop_here` or :meth:`break_here` yields True.
+
+.. method:: Bdb.user_return(frame, return_value)
+
+ This method is called from :meth:`dispatch_return` when :meth:`stop_here`
+ yields True.
+
+.. method:: Bdb.user_exception(frame, exc_info)
+
+ This method is called from :meth:`dispatch_exception` when :meth:`stop_here`
+ yields True.
+
+.. method:: Bdb.do_clear(arg)
+
+ Handle how a breakpoint must be removed when it is a temporary one.
+
+ This method must be implemented by derived classes.
+
+
+Derived classes and clients can call the following methods to affect the
+stepping state.
+
+.. method:: Bdb.set_step()
+
+ Stop after one line of code.
+
+.. method:: Bdb.set_next(frame)
+
+ Stop on the next line in or below the given frame.
+
+.. method:: Bdb.set_return(frame)
+
+ Stop when returning from the given frame.
+
+.. method:: Bdb.set_trace([frame])
+
+ Start debugging from *frame*. If *frame* is not specified, debugging starts
+ from caller's frame.
+
+.. method:: Bdb.set_continue()
+
+ Stop only at breakpoints or when finished. If there are no breakpoints, set
+ the system trace function to None.
+
+.. method:: Bdb.set_quit()
+
+ Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in
+ the next call to one of the :meth:`dispatch_\*` methods.
+
+
+Derived classes and clients can call the following methods to manipulate
+breakpoints. These methods return a string containing an error message if
+something went wrong, or ``None`` if all is well.
+
+.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
+
+ Set a new breakpoint. If the *lineno* line doesn't exist for the *filename*
+ passed as argument, return an error message. The *filename* should be in
+ canonical form, as described in the :meth:`canonic` method.
+
+.. method:: Bdb.clear_break(filename, lineno)
+
+ Delete the breakpoints in *filename* and *lineno*. If none were set, an
+ error message is returned.
+
+.. method:: Bdb.clear_bpbynumber(arg)
+
+ Delete the breakpoint which has the index *arg* in the
+ :attr:`Breakpoint.bpbynumber`. If `arg` is not numeric or out of range,
+ return an error message.
+
+.. method:: Bdb.clear_all_file_breaks(filename)
+
+ Delete all breakpoints in *filename*. If none were set, an error message is
+ returned.
+
+.. method:: Bdb.clear_all_breaks()
+
+ Delete all existing breakpoints.
+
+.. method:: Bdb.get_break(filename, lineno)
+
+ Check if there is a breakpoint for *lineno* of *filename*.
+
+.. method:: Bdb.get_breaks(filename, lineno)
+
+ Return all breakpoints for *lineno* in *filename*, or an empty list if none
+ are set.
+
+.. method:: Bdb.get_file_breaks(filename)
+
+ Return all breakpoints in *filename*, or an empty list if none are set.
+
+.. method:: Bdb.get_all_breaks()
+
+ Return all breakpoints that are set.
+
+
+Derived classes and clients can call the following methods to get a data
+structure representing a stack trace.
+
+.. method:: Bdb.get_stack(f, t)
+
+ Get a list of records for a frame and all higher (calling) and lower frames,
+ and the size of the higher part.
+
+.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])
+
+ Return a string with information about a stack entry, identified by a
+ ``(frame, lineno)`` tuple:
+
+ * The canonical form of the filename which contains the frame.
+ * The function name, or ``"<lambda>"``.
+ * The input arguments.
+ * The return value.
+ * The line of code (if it exists).
+
+
+The following two methods can be called by clients to use a debugger to debug a
+:term:`statement`, given as a string.
+
+.. method:: Bdb.run(cmd, [globals, [locals]])
+
+ Debug a statement executed via the :keyword:`exec` statement. *globals*
+ defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
+
+.. method:: Bdb.runeval(expr, [globals, [locals]])
+
+ Debug an expression executed via the :func:`eval` function. *globals* and
+ *locals* have the same meaning as in :meth:`run`.
+
+.. method:: Bdb.runctx(cmd, globals, locals)
+
+ For backwards compatibility. Calls the :meth:`run` method.
+
+.. method:: Bdb.runcall(func, *args, **kwds)
+
+ Debug a single function call, and return its result.
+
+
+Finally, the module defines the following functions:
+
+.. function:: checkfuncname(b, frame)
+
+ Check whether we should break here, depending on the way the breakpoint *b*
+ was set.
+
+ If it was set via line number, it checks if ``b.line`` is the same as the one
+ in the frame also passed as argument. If the breakpoint was set via function
+ name, we have to check we are in the right frame (the right function) and if
+ we are in its first executable line.
+
+.. function:: effective(file, line, frame)
+
+ Determine if there is an effective (active) breakpoint at this line of code.
+ Return breakpoint number or 0 if none.
+
+ Called only if we know there is a breakpoint at this location. Returns the
+ breakpoint that was triggered and a flag that indicates if it is ok to delete
+ a temporary breakpoint.
+
+.. function:: set_trace()
+
+ Starts debugging with a :class:`Bdb` instance from caller's frame.
Modified: python/branches/py3k/Doc/library/codeop.rst
==============================================================================
--- python/branches/py3k/Doc/library/codeop.rst (original)
+++ python/branches/py3k/Doc/library/codeop.rst Sun Dec 2 16:22:16 2007
@@ -43,8 +43,8 @@
:exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
The *symbol* argument determines whether *source* is compiled as a statement
- (``'single'``, the default) or as an expression (``'eval'``). Any other value
- will cause :exc:`ValueError` to be raised.
+ (``'single'``, the default) or as an :term:`expression` (``'eval'``). Any
+ other value will cause :exc:`ValueError` to be raised.
.. warning::
Modified: python/branches/py3k/Doc/library/contextlib.rst
==============================================================================
--- python/branches/py3k/Doc/library/contextlib.rst (original)
+++ python/branches/py3k/Doc/library/contextlib.rst Sun Dec 2 16:22:16 2007
@@ -15,9 +15,9 @@
.. function:: contextmanager(func)
- This function is a decorator that can be used to define a factory function for
- :keyword:`with` statement context managers, without needing to create a class or
- separate :meth:`__enter__` and :meth:`__exit__` methods.
+ This function is a :term:`decorator` that can be used to define a factory
+ function for :keyword:`with` statement context managers, without needing to
+ create a class or separate :meth:`__enter__` and :meth:`__exit__` methods.
A simple example (this is not recommended as a real way of generating HTML!)::
Modified: python/branches/py3k/Doc/library/doctest.rst
==============================================================================
--- python/branches/py3k/Doc/library/doctest.rst (original)
+++ python/branches/py3k/Doc/library/doctest.rst Sun Dec 2 16:22:16 2007
@@ -1070,7 +1070,8 @@
The advanced API revolves around two container classes, which are used to store
the interactive examples extracted from doctest cases:
-* :class:`Example`: A single python statement, paired with its expected output.
+* :class:`Example`: A single python :term:`statement`, paired with its expected
+ output.
* :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
from a single docstring or text file.
Modified: python/branches/py3k/Doc/library/functions.rst
==============================================================================
--- python/branches/py3k/Doc/library/functions.rst (original)
+++ python/branches/py3k/Doc/library/functions.rst Sun Dec 2 16:22:16 2007
@@ -177,8 +177,8 @@
@classmethod
def f(cls, arg1, arg2, ...): ...
- The ``@classmethod`` form is a function decorator -- see the description of
- function definitions in :ref:`function` for details.
+ The ``@classmethod`` form is a function :term:`decorator` -- see the description
+ of function definitions in :ref:`function` for details.
It can be called either on the class (such as ``C.f()``) or on an instance (such
as ``C().f()``). The instance is ignored except for its class. If a class
@@ -814,7 +814,7 @@
If given, *doc* will be the docstring of the property attribute. Otherwise, the
property will copy *fget*'s docstring (if it exists). This makes it possible to
- create read-only properties easily using :func:`property` as a decorator::
+ create read-only properties easily using :func:`property` as a :term:`decorator`::
class Parrot(object):
def __init__(self):
@@ -906,7 +906,7 @@
.. index:: single: Numerical Python
- Return a slice object representing the set of indices specified by
+ Return a :term:`slice` object representing the set of indices specified by
``range(start, stop, step)``. The *start* and *step* arguments default to
``None``. Slice objects have read-only data attributes :attr:`start`,
:attr:`stop` and :attr:`step` which merely return the argument values (or their
@@ -952,8 +952,8 @@
@staticmethod
def f(arg1, arg2, ...): ...
- The ``@staticmethod`` form is a function decorator -- see the description of
- function definitions in :ref:`function` for details.
+ The ``@staticmethod`` form is a function :term:`decorator` -- see the
+ description of function definitions in :ref:`function` for details.
It can be called either on the class (such as ``C.f()``) or on an instance (such
as ``C().f()``). The instance is ignored except for its class.
Modified: python/branches/py3k/Doc/library/functools.rst
==============================================================================
--- python/branches/py3k/Doc/library/functools.rst (original)
+++ python/branches/py3k/Doc/library/functools.rst Sun Dec 2 16:22:16 2007
@@ -76,9 +76,9 @@
*WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the
instance dictionary).
- The main intended use for this function is in decorator functions which wrap the
- decorated function and return the wrapper. If the wrapper function is not
- updated, the metadata of the returned function will reflect the wrapper
+ The main intended use for this function is in :term:`decorator` functions which
+ wrap the decorated function and return the wrapper. If the wrapper function is
+ not updated, the metadata of the returned function will reflect the wrapper
definition rather than the original function definition, which is typically less
than helpful.
Modified: python/branches/py3k/Doc/library/inspect.rst
==============================================================================
--- python/branches/py3k/Doc/library/inspect.rst (original)
+++ python/branches/py3k/Doc/library/inspect.rst Sun Dec 2 16:22:16 2007
@@ -220,7 +220,7 @@
.. function:: isfunction(object)
- Return true if the object is a Python function or unnamed (lambda) function.
+ Return true if the object is a Python function or unnamed (:term:`lambda`) function.
.. function:: istraceback(object)
Modified: python/branches/py3k/Doc/library/mmap.rst
==============================================================================
--- python/branches/py3k/Doc/library/mmap.rst (original)
+++ python/branches/py3k/Doc/library/mmap.rst Sun Dec 2 16:22:16 2007
@@ -84,6 +84,49 @@
*offset* may be specified as a non-negative integer offset. mmap references will
be relative to the offset from the beginning of the file. *offset* defaults to 0.
*offset* must be a multiple of the PAGESIZE or ALLOCATIONGRANULARITY.
+
+ This example shows a simple way of using :func:`mmap`::
+
+ import mmap
+
+ # write a simple example file
+ with open("hello.txt", "w") as f:
+ f.write("Hello Python!\n")
+
+ with open("hello.txt", "r+") as f:
+ # memory-map the file, size 0 means whole file
+ map = mmap.mmap(f.fileno(), 0)
+ # read content via standard file methods
+ print map.readline() # prints "Hello Python!"
+ # read content via slice notation
+ print map[:5] # prints "Hello"
+ # update content using slice notation;
+ # note that new content must have same size
+ map[6:] = " world!\n"
+ # ... and read again using standard file methods
+ map.seek(0)
+ print map.readline() # prints "Hello world!"
+ # close the map
+ map.close()
+
+
+ The next example demonstrates how to create an anonymous map and exchange
+ data between the parent and child processes::
+
+ import mmap
+ import os
+
+ map = mmap.mmap(-1, 13)
+ map.write("Hello world!")
+
+ pid = os.fork()
+
+ if pid == 0: # In a child process
+ map.seek(0)
+ print map.readline()
+
+ map.close()
+
Memory-mapped file objects support the following methods:
Modified: python/branches/py3k/Doc/library/operator.rst
==============================================================================
--- python/branches/py3k/Doc/library/operator.rst (original)
+++ python/branches/py3k/Doc/library/operator.rst Sun Dec 2 16:22:16 2007
@@ -262,10 +262,10 @@
Many operations have an "in-place" version. The following functions provide a
more primitive access to in-place operators than the usual syntax does; for
-example, the statement ``x += y`` is equivalent to ``x = operator.iadd(x, y)``.
-Another way to put it is to say that ``z = operator.iadd(x, y)`` is equivalent
-to the compound statement ``z = x; z += y``.
-
+example, the :term:`statement` ``x += y`` is equivalent to
+``x = operator.iadd(x, y)``. Another way to put it is to say that
+``z = operator.iadd(x, y)`` is equivalent to the compound statement
+``z = x; z += y``.
.. function:: iadd(a, b)
__iadd__(a, b)
Modified: python/branches/py3k/Doc/library/stdtypes.rst
==============================================================================
--- python/branches/py3k/Doc/library/stdtypes.rst (original)
+++ python/branches/py3k/Doc/library/stdtypes.rst Sun Dec 2 16:22:16 2007
@@ -2149,8 +2149,8 @@
their implementation of the context management protocol. See the
:mod:`contextlib` module for some examples.
-Python's :term:`generator`\s and the ``contextlib.contextfactory`` decorator provide a
-convenient way to implement these protocols. If a generator function is
+Python's :term:`generator`\s and the ``contextlib.contextfactory`` :term:`decorator`
+provide a convenient way to implement these protocols. If a generator function is
decorated with the ``contextlib.contextfactory`` decorator, it will return a
context manager implementing the necessary :meth:`__enter__` and
:meth:`__exit__` methods, rather than the iterator produced by an undecorated
Modified: python/branches/py3k/Doc/library/sys.rst
==============================================================================
--- python/branches/py3k/Doc/library/sys.rst (original)
+++ python/branches/py3k/Doc/library/sys.rst Sun Dec 2 16:22:16 2007
@@ -80,9 +80,9 @@
If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves
it in ``builtins._``.
- ``sys.displayhook`` is called on the result of evaluating an expression entered
- in an interactive Python session. The display of these values can be customized
- by assigning another one-argument function to ``sys.displayhook``.
+ ``sys.displayhook`` is called on the result of evaluating an :term:`expression`
+ entered in an interactive Python session. The display of these values can be
+ customized by assigning another one-argument function to ``sys.displayhook``.
.. function:: excepthook(type, value, traceback)
@@ -536,14 +536,16 @@
stderr
File objects corresponding to the interpreter's standard input, output and error
- streams. ``stdin`` is used for all interpreter input except for scripts.
- ``stdout`` is used for the output of :func:`print` and expression statements.
- The interpreter's own prompts and (almost all of) its error messages go to
- ``stderr``. ``stdout`` and ``stderr`` needn't be built-in file objects: any
- object is acceptable as long as it has a :meth:`write` method that takes a
- string argument. (Changing these objects doesn't affect the standard I/O
- streams of processes executed by :func:`os.popen`, :func:`os.system` or the
- :func:`exec\*` family of functions in the :mod:`os` module.)
+ streams. ``stdin`` is used for all interpreter input except for scripts but
+ including calls to :func:`input`. ``stdout`` is used for
+ the output of :func:`print` and :term:`expression` statements and for the
+ prompts of :func:`input`. The interpreter's own prompts
+ and (almost all of) its error messages go to ``stderr``. ``stdout`` and
+ ``stderr`` needn't be built-in file objects: any object is acceptable as long
+ as it has a :meth:`write` method that takes a string argument. (Changing these
+ objects doesn't affect the standard I/O streams of processes executed by
+ :func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in
+ the :mod:`os` module.)
.. data:: __stdin__
Modified: python/branches/py3k/Doc/library/timeit.rst
==============================================================================
--- python/branches/py3k/Doc/library/timeit.rst (original)
+++ python/branches/py3k/Doc/library/timeit.rst Sun Dec 2 16:22:16 2007
@@ -85,11 +85,12 @@
.. note::
- By default, :meth:`timeit` temporarily turns off garbage collection during the
- timing. The advantage of this approach is that it makes independent timings
- more comparable. This disadvantage is that GC may be an important component of
- the performance of the function being measured. If so, GC can be re-enabled as
- the first statement in the *setup* string. For example::
+ By default, :meth:`timeit` temporarily turns off :term:`garbage collection`
+ during the timing. The advantage of this approach is that it makes
+ independent timings more comparable. This disadvantage is that GC may be
+ an important component of the performance of the function being measured.
+ If so, GC can be re-enabled as the first statement in the *setup* string.
+ For example::
timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
Modified: python/branches/py3k/Doc/library/weakref.rst
==============================================================================
--- python/branches/py3k/Doc/library/weakref.rst (original)
+++ python/branches/py3k/Doc/library/weakref.rst Sun Dec 2 16:22:16 2007
@@ -20,22 +20,22 @@
by a weak reference.
A weak reference to an object is not enough to keep the object alive: when the
-only remaining references to a referent are weak references, garbage collection
-is free to destroy the referent and reuse its memory for something else. A
-primary use for weak references is to implement caches or mappings holding large
-objects, where it's desired that a large object not be kept alive solely because
-it appears in a cache or mapping. For example, if you have a number of large
-binary image objects, you may wish to associate a name with each. If you used a
-Python dictionary to map names to images, or images to names, the image objects
-would remain alive just because they appeared as values or keys in the
-dictionaries. The :class:`WeakKeyDictionary`, :class:`WeakValueDictionary`
-and :class:`WeakSet` classes supplied by the :mod:`weakref` module are an
-alternative, using weak references to construct mappings that don't keep objects
-alive solely because they appear in the container objects.
-If, for example, an image object is a value in a :class:`WeakValueDictionary`,
-then when the last remaining references to that image object are the weak
-references held by weak mappings, garbage collection can reclaim the object,
-and its corresponding entries in weak mappings are simply deleted.
+only remaining references to a referent are weak references,
+:term:`garbage collection` is free to destroy the referent and reuse its memory
+for something else. A primary use for weak references is to implement caches or
+mappings holding large objects, where it's desired that a large object not be
+kept alive solely because it appears in a cache or mapping. For example, if you
+have a number of large binary image objects, you may wish to associate a name
+with each. If you used a Python dictionary to map names to images, or images to
+names, the image objects would remain alive just because they appeared as values
+or keys in the dictionaries. The :class:`WeakKeyDictionary` and
+:class:`WeakValueDictionary` classes supplied by the :mod:`weakref` module are
+an alternative, using weak references to construct mappings that don't keep
+objects alive solely because they appear in the mapping objects. If, for
+example, an image object is a value in a :class:`WeakValueDictionary`, then when
+the last remaining references to that image object are the weak references held
+by weak mappings, garbage collection can reclaim the object, and its
+corresponding entries in weak mappings are simply deleted.
:class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references
in their implementation, setting up callback functions on the weak references
Modified: python/branches/py3k/Doc/library/windows.rst
==============================================================================
--- python/branches/py3k/Doc/library/windows.rst (original)
+++ python/branches/py3k/Doc/library/windows.rst Sun Dec 2 16:22:16 2007
@@ -1,3 +1,4 @@
+.. _mswin-specific-services:
****************************
MS Windows Specific Services
Modified: python/branches/py3k/Doc/library/xml.etree.elementtree.rst
==============================================================================
--- python/branches/py3k/Doc/library/xml.etree.elementtree.rst (original)
+++ python/branches/py3k/Doc/library/xml.etree.elementtree.rst Sun Dec 2 16:22:16 2007
@@ -31,6 +31,9 @@
A C implementation of this API is available as :mod:`xml.etree.cElementTree`.
+See http://effbot.org/zone/element-index.htm for tutorials and links to other
+docs. Fredrik Lundh's page is also the location of the development version of the
+xml.etree.ElementTree.
.. _elementtree-functions:
@@ -355,6 +358,33 @@
object opened for writing. *encoding* is the output encoding (default is
US-ASCII).
+This is the XML file that is going to be manipulated::
+
+ <html>
+ <head>
+ <title>Example page</title>
+ </head>
+ <body>
+ <p>Moved to <a href="http://example.org/">example.org</a>
+ or <a href="http://example.com/">example.com</a>.</p>
+ </body>
+ </html>
+
+Example of changing the attribute "target" of every link in first paragraph::
+
+ >>> from xml.etree.ElementTree import ElementTree
+ >>> tree = ElementTree()
+ >>> tree.parse("index.xhtml")
+ <Element html at b7d3f1ec>
+ >>> p = tree.find("body/p") # Finds first occurrence of tag p in body
+ >>> p
+ <Element p at 8416e0c>
+ >>> links = p.getiterator("a") # Returns list of all links
+ >>> links
+ [<Element a at b7d4f9ec>, <Element a at b7d4fb0c>]
+ >>> for i in links: # Iterates through all found links
+ ... i.attrib["target"] = "blank"
+ >>> tree.write("output.xhtml")
.. _elementtree-qname-objects:
@@ -440,3 +470,41 @@
Feeds data to the parser. *data* is encoded data.
+:meth:`XMLTreeBuilder.feed` calls *target*\'s :meth:`start` method
+for each opening tag, its :meth:`end` method for each closing tag,
+and data is processed by method :meth:`data`. :meth:`XMLTreeBuilder.close`
+calls *target*\'s method :meth:`close`.
+:class:`XMLTreeBuilder` can be used not only for building a tree structure.
+This is an example of counting the maximum depth of an XML file::
+
+ >>> from xml.etree.ElementTree import XMLTreeBuilder
+ >>> class MaxDepth: # The target object of the parser
+ ... maxDepth = 0
+ ... depth = 0
+ ... def start(self, tag, attrib): # Called for each opening tag.
+ ... self.depth += 1
+ ... if self.depth > self.maxDepth:
+ ... self.maxDepth = self.depth
+ ... def end(self, tag): # Called for each closing tag.
+ ... self.depth -= 1
+ ... def data(self, data):
+ ... pass # We do not need to do anything with data.
+ ... def close(self): # Called when all data has been parsed.
+ ... return self.maxDepth
+ ...
+ >>> target = MaxDepth()
+ >>> parser = XMLTreeBuilder(target=target)
+ >>> exampleXml = """
+ ... <a>
+ ... <b>
+ ... </b>
+ ... <b>
+ ... <c>
+ ... <d>
+ ... </d>
+ ... </c>
+ ... </b>
+ ... </a>"""
+ >>> parser.feed(exampleXml)
+ >>> parser.close()
+ 4
Modified: python/branches/py3k/Doc/reference/compound_stmts.rst
==============================================================================
--- python/branches/py3k/Doc/reference/compound_stmts.rst (original)
+++ python/branches/py3k/Doc/reference/compound_stmts.rst Sun Dec 2 16:22:16 2007
@@ -421,7 +421,7 @@
The function definition does not execute the function body; this gets executed
only when the function is called.
-A function definition may be wrapped by one or more decorator expressions.
+A function definition may be wrapped by one or more :term:`decorator` expressions.
Decorator expressions are evaluated when the function is defined, in the scope
that contains the function definition. The result must be a callable, which is
invoked with the function object as the only argument. The returned value is
Modified: python/branches/py3k/Doc/tutorial/stdlib2.rst
==============================================================================
--- python/branches/py3k/Doc/tutorial/stdlib2.rst (original)
+++ python/branches/py3k/Doc/tutorial/stdlib2.rst Sun Dec 2 16:22:16 2007
@@ -244,8 +244,8 @@
===============
Python does automatic memory management (reference counting for most objects and
-garbage collection to eliminate cycles). The memory is freed shortly after the
-last reference to it has been eliminated.
+:term:`garbage collection` to eliminate cycles). The memory is freed shortly
+after the last reference to it has been eliminated.
This approach works fine for most applications but occasionally there is a need
to track objects only as long as they are being used by something else.
Modified: python/branches/py3k/Doc/using/cmdline.rst
==============================================================================
--- python/branches/py3k/Doc/using/cmdline.rst (original)
+++ python/branches/py3k/Doc/using/cmdline.rst Sun Dec 2 16:22:16 2007
@@ -1,5 +1,7 @@
.. highlightlang:: none
+.. _using-on-general:
+
Command line and environment
============================
@@ -12,6 +14,8 @@
:ref:`implementations` for further resources.
+.. _using-on-cmdline:
+
Command line
------------
@@ -289,35 +293,7 @@
.. warning:: The line numbers in error messages will be off by one!
-
-Related files -- UNIX
----------------------
-
-These are subject to difference depending on local installation conventions;
-:envvar:`prefix` (``${prefix}``) and :envvar:`exec_prefix` (``${exec_prefix}``)
-are installation-dependent and should be interpreted as for GNU software; they
-may be the same.
-
-For example, on most Linux systems, the default for both is :file:`/usr`.
-
-+-----------------------------------------------+------------------------------------------+
-| File/directory | Meaning |
-+===============================================+==========================================+
-| :file:`{exec_prefix}/bin/python` | Recommended location of the interpreter. |
-+-----------------------------------------------+------------------------------------------+
-| :file:`{prefix}/lib/python{version}`, | Recommended locations of the directories |
-| :file:`{exec_prefix}/lib/python{version}` | containing the standard modules. |
-+-----------------------------------------------+------------------------------------------+
-| :file:`{prefix}/include/python{version}`, | Recommended locations of the directories |
-| :file:`{exec_prefix}/include/python{version}` | containing the include files needed for |
-| | developing Python extensions and |
-| | embedding the interpreter. |
-+-----------------------------------------------+------------------------------------------+
-| :file:`~/.pythonrc.py` | User-specific initialization file loaded |
-| | by the user module; not used by default |
-| | or by most applications. |
-+-----------------------------------------------+------------------------------------------+
-
+.. _using-on-envvars:
Environment variables
---------------------
Modified: python/branches/py3k/Doc/using/index.rst
==============================================================================
--- python/branches/py3k/Doc/using/index.rst (original)
+++ python/branches/py3k/Doc/using/index.rst Sun Dec 2 16:22:16 2007
@@ -13,5 +13,6 @@
.. toctree::
cmdline.rst
+ windows.rst
mac.rst
Modified: python/branches/py3k/Lib/tarfile.py
==============================================================================
--- python/branches/py3k/Lib/tarfile.py (original)
+++ python/branches/py3k/Lib/tarfile.py Sun Dec 2 16:22:16 2007
@@ -1542,7 +1542,8 @@
self.closed = False
self.members = [] # list of members as TarInfo objects
self._loaded = False # flag if all members have been read
- self.offset = 0 # current position in the archive file
+ self.offset = self.fileobj.tell()
+ # current position in the archive file
self.inodes = {} # dictionary caching the inodes of
# archive members already added
Modified: python/branches/py3k/Lib/test/test_tarfile.py
==============================================================================
--- python/branches/py3k/Lib/test/test_tarfile.py (original)
+++ python/branches/py3k/Lib/test/test_tarfile.py Sun Dec 2 16:22:16 2007
@@ -159,6 +159,38 @@
tar = tarfile.open(fileobj=fobj, mode=self.mode)
self.assertEqual(tar.name, None)
+ def test_fileobj_with_offset(self):
+ # Skip the first member and store values from the second member
+ # of the testtar.
+ tar = tarfile.open(self.tarname, mode=self.mode)
+ tar.next()
+ t = tar.next()
+ name = t.name
+ offset = t.offset
+ data = tar.extractfile(t).read()
+ tar.close()
+
+ # Open the testtar and seek to the offset of the second member.
+ if self.mode.endswith(":gz"):
+ _open = gzip.GzipFile
+ elif self.mode.endswith(":bz2"):
+ _open = bz2.BZ2File
+ else:
+ _open = open
+ fobj = _open(self.tarname, "rb")
+ fobj.seek(offset)
+
+ # Test if the tarfile starts with the second member.
+ tar = tar.open(self.tarname, mode="r:", fileobj=fobj)
+ t = tar.next()
+ self.assertEqual(t.name, name)
+ # Read to the end of fileobj and test if seeking back to the
+ # beginning works.
+ tar.getmembers()
+ self.assertEqual(tar.extractfile(t).read(), data,
+ "seek back did not work")
+ tar.close()
+
def test_fail_comp(self):
# For Gzip and Bz2 Tests: fail with a ReadError on an uncompressed file.
if self.mode == "r:":
Modified: python/branches/py3k/Misc/ACKS
==============================================================================
--- python/branches/py3k/Misc/ACKS (original)
+++ python/branches/py3k/Misc/ACKS Sun Dec 2 16:22:16 2007
@@ -579,6 +579,7 @@
David Scherer
Gregor Schmid
Ralf Schmitt
+Michael Schneider
Peter Schneider-Kamp
Arvin Schnell
Chad J. Schroeder
More information about the Python-3000-checkins
mailing list