Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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.
........
This commit is contained in:
Christian Heimes 2007-12-02 15:22:16 +00:00
parent b27ce7e468
commit d8654cf758
35 changed files with 1314 additions and 432 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doc/ACKS.txt
View File

@ -163,6 +163,7 @@ docs@python.org), and we'll be glad to correct the problem.
* Justin Sheehy
* Michael Simcich
* Ionel Simionescu
* Michael Sloan
* Gregory P. Smith
* Roy Smith
* Clay Spence
@ -185,6 +186,7 @@ docs@python.org), and we'll be glad to correct the problem.
* Glyn Webster
* Bob Weiner
* Eddy Welbourne
* Jeff Wheeler
* Mats Wichmann
* Gerry Wiener
* Timothy Wild

4
Doc/Makefile
View File

@ -57,6 +57,10 @@ htmlhelp: build
@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

3
Doc/README.txt
View File

@ -53,6 +53,9 @@ Available make targets are:
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/`.

48
Doc/c-api/init.rst
View File

@ -615,6 +615,14 @@ supports the creation of additional interpreters (using
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 @@ in previous versions.
: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:

49
Doc/c-api/utilities.rst
View File

@ -989,3 +989,52 @@ The following functions provide locale-independent string to number conversions.
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*.

37
Doc/c-api/veryhigh.rst
View File

@ -229,6 +229,43 @@ the same library that the Python runtime is using.
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()

5
Doc/data/refcounts.dat
View File

@ -309,6 +309,11 @@ PyEval_AcquireLock:void:::
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:::

2
Doc/distutils/extending.rst
View File

@ -1,4 +1,4 @@
.. _extending:
.. _extending-distutils:
*******************
Extending Distutils

23
Doc/extending/extending.rst
View File

@ -466,10 +466,10 @@ Later, when it is time to call the function, you call the C function
: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 @@ event code, you might use the following code::
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:

94
Doc/glossary.rst
View File

@ -15,6 +15,17 @@ Glossary
``...``
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 @@ Glossary
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 @@ Glossary
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 @@ Glossary
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 @@ Glossary
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 @@ Glossary
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 @@ Glossary
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

2
Doc/library/atexit.rst
View File

@ -88,7 +88,7 @@ passed along to the registered function when it is called::
# or:
atexit.register(goodbye, adjective='nice', name='Donny')
Usage as a decorator::
Usage as a :term:`decorator`::
import atexit

674
Doc/library/bdb.rst
View File

@ -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.

4
Doc/library/codeop.rst
View File

@ -43,8 +43,8 @@ To do just the former:
: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::

6
Doc/library/contextlib.rst
View File

@ -15,9 +15,9 @@ Functions provided:
.. 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!)::

3
Doc/library/doctest.rst
View File

@ -1070,7 +1070,8 @@ capabilities, then you should use the advanced API.
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.

12
Doc/library/functions.rst
View File

@ -177,8 +177,8 @@ available. They are listed here in alphabetical order.
@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 @@ available. They are listed here in alphabetical order.
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 @@ available. They are listed here in alphabetical order.
.. 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 @@ available. They are listed here in alphabetical order.
@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.

6
Doc/library/functools.rst
View File

@ -76,9 +76,9 @@ The :mod:`functools` module defines the following functions:
*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.

2
Doc/library/inspect.rst
View File

@ -220,7 +220,7 @@ attributes:
.. 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)

43
Doc/library/mmap.rst
View File

@ -84,6 +84,49 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
*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:

8
Doc/library/operator.rst
View File

@ -262,10 +262,10 @@ Operations which work with sequences include:
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)

4
Doc/library/stdtypes.rst
View File

@ -2149,8 +2149,8 @@ decimal arithmetic context. The specific types are not treated specially beyond
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

24
Doc/library/sys.rst
View File

@ -80,9 +80,9 @@ always available.
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 @@ always available.
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__

11
Doc/library/timeit.rst
View File

@ -85,11 +85,12 @@ The module defines the following public class:
.. 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()

32
Doc/library/weakref.rst
View File

@ -20,22 +20,22 @@ In the following, the term :dfn:`referent` means the object which is referred to
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

1
Doc/library/windows.rst
View File

@ -1,3 +1,4 @@
.. _mswin-specific-services:
****************************
MS Windows Specific Services

68
Doc/library/xml.etree.elementtree.rst
View File

@ -31,6 +31,9 @@ convert it from and to XML.
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 @@ ElementTree Objects
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 @@ XMLTreeBuilder Objects
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

2
Doc/reference/compound_stmts.rst
View File

@ -421,7 +421,7 @@ when the function is called.
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

4
Doc/tutorial/stdlib2.rst
View File

@ -244,8 +244,8 @@ Weak References
===============
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.

34
Doc/using/cmdline.rst
View File

@ -1,5 +1,7 @@
.. highlightlang:: none
.. _using-on-general:
Command line and environment
============================
@ -12,6 +14,8 @@ settings.
:ref:`implementations` for further resources.
.. _using-on-cmdline:
Command line
------------
@ -289,35 +293,7 @@ Miscellaneous options
.. 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
---------------------

1
Doc/using/index.rst
View File

@ -13,5 +13,6 @@ interpreter and things that make working with Python easier.
.. toctree::
cmdline.rst
windows.rst
mac.rst

316
Doc/using/windows.rst Normal file
View File

@ -0,0 +1,316 @@
.. highlightlang:: none
.. _using-on-windows:
*************************
Using Python on Windows
*************************
.. sectionauthor:: Robert Lehmann <lehmannro@gmail.com>
This document aims to give an overview of Windows-specific behaviour you should
know about when using Python on Microsoft Windows.
Installing Python
=================
Unlike most Unix systems and services, Windows does not require Python natively
and thus does not pre-install a version of Python. However, the CPython team
has compiled Windows installers (MSI packages) with every `release
<http://www.python.org/download/releases/>`_ for many years.
With ongoing development of Python, some platforms that used to be supported
earlier are not longer supported (due to the lack of users or developers).
Check :pep:`11` for details on all unsupported platforms.
* DOS and Windows 3.x are deprecated since Python 2.0 and code specific to these
systems was removed in Python 2.1.
* Up to 2.5, Python was still compatible with Windows 95, 98 and ME (but already
raised a deprecation warning on installation). For Python 2.6 (and all
following releases), this support was dropped and new releases are just
expected to work on the Windows NT family.
* `Windows CE <http://pythonce.sourceforge.net/>`_ is still supported.
* The `Cygwin <http://cygwin.com/>`_ installer offers to install the `Python
interpreter <http://cygwin.com/packages/python>`_ as well; it is located under
"Interpreters." (cf. `Cygwin package source
<ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/
release/python>`_, `Maintainer releases
<http://www.tishler.net/jason/software/python/>`_)
See `Python for Windows (and DOS) <http://www.python.org/download/windows/>`_
for detailed information about platforms with precompiled installers.
.. seealso::
`Python on XP <http://www.richarddooling.com/index.php/2006/03/14/python-on-xp-7-minutes-to-hello-world/>`_
"7 Minutes to "Hello World!""
by Richard Dooling, 2006
`Installing on Windows <http://diveintopython.org/installing_python/windows.html>`_
in "`Dive into Python: Python from novice to pro
<http://diveintopython.org/index.html>`_"
by Mark Pilgrim, 2004,
ISBN 1-59059-356-1
`For Windows users <http://swaroopch.com/text/Byte_of_Python:Installing_Python#For_Windows_users>`_
in "Installing Python"
in "`A Byte of Python <http://www.byteofpython.info>`_"
by Swaroop C H, 2003
Alternative bundles
===================
Besides the standard CPython distribution, there are modified packages including
additional functionality. The following is a list of popular versions and their
key features:
`ActivePython <http://www.activestate.com/Products/activepython/>`_
Installer with multi-platform compatibility, documentation, PyWin32
`Python Enthought Edition <http://code.enthought.com/enthon/>`_
Popular modules (such as PyWin32) with their respective documentation, tool
suite for building extensible python applications
Configuring Python
==================
In order to run Python flawlessly, you might have to change certain environment
settings in Windows.
Excursus: Setting environment variables
---------------------------------------
Windows has a built-in dialog for changing environment variables: Right-click
the icon for your machine (usually located on your Desktop and called "My
Computer") and choose :menuselection:`Properties` there. Then, open the
:guilabel:`Advanced` tab and click the :guilabel:`Environment Variables` button.
In short, your path is:
:menuselection:`My Computer
--> Properties
--> Advanced
--> Environment Variables`
In this dialog, you can add or modify User and System variables. To change
System variables, you need non-restricted access to your machine
(i.e. Administrator rights).
Another way of adding variables to your environment is using the :command:`set`
command::
set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
To make this setting permanent, you could add the corresponding command line to
your :file:`autoexec.bat`.
Viewing environment variables can also be done more straight-forward: The
command prompt will expand strings wrapped into percent signs automatically::
echo %PATH%
Consult :command:`set /?` for details on this behaviour.
.. seealso::
http://support.microsoft.com/kb/100843
Environment variables in Windows NT
http://support.microsoft.com/kb/310519
How To Manage Environment Variables in Windows XP
Finding the Python executable
-----------------------------
Besides using the automatically created start menu entry for the Python
interpreter, you might want to start Python in the DOS prompt. To make this
work, you need to set your :envvar:`%PATH%` environment variable to include the
directory of your Python distribution, delimited by a semicolon from other
entries. An example variable could look like this (assuming the first two
entries are Windows' default)::
C:\WINNT\system32;C:\WINNT;C:\Python25
Typing :command:`python` on your command prompt will now fire up the Python
interpreter. Thus, you can also execute your scripts with command line options,
see :ref:`using-on-cmdline` documentation.
Finding modules
---------------
Python usually stores its library (and thereby your site-packages folder) in the
installation directory. So, if you had installed Python to
:file:`C:\\Python\\`, the default library would reside in
:file:`C:\\Python\\Lib\\` and third-party modules should be stored in
:file:`C:\\Python\\Lib\\site-packages\\`.
.. % `` this fixes syntax highlighting errors in some editors
due to the \\ hackery
You can add folders to your search path to make Python's import mechanism search
in these directories as well. Use :envvar:`PYTHONPATH`, as described in
:ref:`using-on-envvars`, to modify :data:`sys.path`. On Windows, paths are
separated by semicolons, though, to distinguish them from drive identifiers
(:file:`C:\\` etc.).
.. % ``
Modifying the module search path can also be done through the Windows registry:
Edit
:file:`HKEY_LOCAL_MACHINE\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath\\`,
as described above for the environment variable :envvar:`%PYTHONPATH%`. A
convenient registry editor is :program:`regedit` (start it by typing "regedit"
into :menuselection:`Start --> Run`).
Executing scripts
-----------------
Python scripts (files with the extension ``.py``) will be executed by
:program:`python.exe` by default. This executable opens a terminal, which stays
open even if the program uses a GUI. If you do not want this to happen, use the
extension ``.pyw`` which will cause the script to be executed by
:program:`pythonw.exe` by default (both executables are located in the top-level
of your Python installation directory). This suppresses the terminal window on
startup.
You can also make all ``.py`` scripts execute with :program:`pythonw.exe`,
setting this through the usual facilites, for example (names might differ,
depending on your version of Windows):
#. Open the context menu of a :file:`{*}.py` file.
#. Click :menuselection:`Open with...`.
#. Choose the interpreter of your choice (utilize :guilabel:`Other...` or
:guilabel:`Choose Program...` if it is not in the list of default programs).
#. Check :guilabel:`Always open files with this program`.
#. Click :guilabel:`OK`.
Additional modules
==================
Even though Python aims to be portable among all platforms, there are features
that are unique to Windows. A couple of modules, both in the standard library
and external, and snippets exist to use these features.
The Windows-specific standard modules are documented in
:ref:`mswin-specific-services`.
PyWin32
-------
The `PyWin32 <http://python.net/crew/mhammond/win32/>`_ module by Mark Hammond
is a collection of modules for advanced Windows-specific support. This includes
utilites for:
* `Component Object Model <http://www.microsoft.com/com/>`_ (COM)
* Win32 API calls
* Registry
* Event log
* `Microsoft Foundation Classes <http://msdn.microsoft.com/library/
en-us/vclib/html/_mfc_Class_Library_Reference_Introduction.asp>`_ (MFC)
user interfaces
`PythonWin <http://web.archive.org/web/20060524042422/
http://www.python.org/windows/pythonwin/>`_ is a sample MFC application
shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
.. seealso::
`Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
by Tim Golden
`Python and COM <http://www.boddie.org.uk/python/COM.html>`_
by David and Paul Boddie
Py2exe
------
`Py2exe <http://www.py2exe.org/>`_ is a :mod:`distutils` extension (see
:ref:`extending-distutils`) which wraps Python scripts into executable Windows
programs (:file:`{*}.exe` files). When you have done this, you can distribute
your application without requiring your users to install Python.
WConio
------
Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
Unix-like systems, there is a library exclusive to Windows as well: Windows
Console I/O for Python.
`WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for
Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
Compiling Python on Windows
===========================
If you want to compile CPython yourself, first thing you should do is get the
`source <http://python.org/download/source/>`_. You can download either the
latest release's source or just grab a fresh `checkout
<http://www.python.org/dev/faq/
#how-do-i-get-a-checkout-of-the-repository-read-only-and-read-write>`_.
For Microsoft Visual C++, which is the compiler with which official Python
releases are built, the source tree contains solutions/project files. View the
:file:`readme.txt` in their respective directories:
+--------------------+--------------+-----------------------+
| Directory | MSVC version | Visual Studio version |
+====================+==============+=======================+
| :file:`PC/VC6/` | 5.0 | 97 |
| +--------------+-----------------------+
| | 6.0 | 6.0 |
+--------------------+--------------+-----------------------+
| :file:`PCbuild/` | 7.1 | 2003 |
+--------------------+--------------+-----------------------+
| :file:`PCbuild8/` | 8.0 | 2005 |
+--------------------+--------------+-----------------------+
| :file:`PCbuild9/` | 9.0 | 2008 |
+--------------------+--------------+-----------------------+
Note that not all of these build directories are fully supported. Read the
release notes to see which compiler version the official releases for your
version are built with.
Check :file:`PC/readme.txt` for general information on the build process.
For extension modules, consult :ref:`building-on-windows`.
.. seealso::
`Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
or "Creating Python extensions in C/C++ with SWIG and compiling them with
MinGW gcc under Windows" or "Installing Python extension with distutils
and without Microsoft Visual C++" by Sébastien Sauvage, 2003
`MingW -- Python extensions <http://www.mingw.org/MinGWiki/index.php/Python%20extensions>`_
by Trent Apted et al, 2007
Other resources
===============
.. seealso::
`Python Programming On Win32 <http://www.oreilly.com/catalog/pythonwin32/>`_
"Help for Windows Programmers"
by Mark Hammond and Andy Robinson, O'Reilly Media, 2000,
ISBN 1-56592-621-8
`A Python for Windows Tutorial <http://www.imladris.com/Scripts/PythonForWindows.html>`_
by Amanda Birmingham, 2004

3
Lib/tarfile.py
View File

@ -1542,7 +1542,8 @@ class TarFile(object):
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

186
Lib/test/test_cmd.py Normal file
View File

@ -0,0 +1,186 @@
#!/usr/bin/env python
"""
Test script for the 'cmd' module
Original by Michael Schneider
"""
from test import test_support
import cmd
import sys
class samplecmdclass(cmd.Cmd):
"""
Instance the sampleclass:
>>> mycmd = samplecmdclass()
Test for the function parseline():
>>> mycmd.parseline("")
(None, None, '')
>>> mycmd.parseline("?")
('help', '', 'help ')
>>> mycmd.parseline("?help")
('help', 'help', 'help help')
>>> mycmd.parseline("!")
('shell', '', 'shell ')
>>> mycmd.parseline("!command")
('shell', 'command', 'shell command')
>>> mycmd.parseline("func")
('func', '', 'func')
>>> mycmd.parseline("func arg1")
('func', 'arg1', 'func arg1')
Test for the function onecmd():
>>> mycmd.onecmd("")
>>> mycmd.onecmd("add 4 5")
9
>>> mycmd.onecmd("")
9
>>> mycmd.onecmd("test")
*** Unknown syntax: test
Test for the function emptyline():
>>> mycmd.emptyline()
*** Unknown syntax: test
Test for the function default():
>>> mycmd.default("default")
*** Unknown syntax: default
Test for the function completedefault():
>>> mycmd.completedefault()
This is the completedefault methode
>>> mycmd.completenames("a")
['add']
Test for the function completenames():
>>> mycmd.completenames("12")
[]
>>> mycmd.completenames("help")
['help', 'help']
Test for the function complete_help():
>>> mycmd.complete_help("a")
['add']
>>> mycmd.complete_help("he")
['help', 'help']
>>> mycmd.complete_help("12")
[]
Test for the function do_help():
>>> mycmd.do_help("testet")
*** No help on testet
>>> mycmd.do_help("add")
help text for add
>>> mycmd.onecmd("help add")
help text for add
>>> mycmd.do_help("")
<BLANKLINE>
Documented commands (type help <topic>):
========================================
add
<BLANKLINE>
Undocumented commands:
======================
exit help shell
<BLANKLINE>
Test for the function print_topics():
>>> mycmd.print_topics("header", ["command1", "command2"], 2 ,10)
header
======
command1
command2
<BLANKLINE>
Test for the function columnize():
>>> mycmd.columnize([str(i) for i in xrange(20)])
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
>>> mycmd.columnize([str(i) for i in xrange(20)], 10)
0 7 14
1 8 15
2 9 16
3 10 17
4 11 18
5 12 19
6 13
This is a interactive test, put some commands in the cmdqueue attribute
and let it execute
This test includes the preloop(), postloop(), default(), emptyline(),
parseline(), do_help() functions
>>> mycmd.use_rawinput=0
>>> mycmd.cmdqueue=["", "add", "add 4 5", "help", "help add","exit"]
>>> mycmd.cmdloop()
Hello from preloop
help text for add
*** invalid number of arguments
9
<BLANKLINE>
Documented commands (type help <topic>):
========================================
add
<BLANKLINE>
Undocumented commands:
======================
exit help shell
<BLANKLINE>
help text for add
Hello from postloop
"""
def preloop(self):
print "Hello from preloop"
def postloop(self):
print "Hello from postloop"
def completedefault(self, *ignored):
print "This is the completedefault methode"
return
def complete_command(self):
print "complete command"
return
def do_shell(self):
pass
def do_add(self, s):
l = s.split()
if len(l) != 2:
print "*** invalid number of arguments"
return
try:
l = [int(i) for i in l]
except ValueError:
print "*** arguments should be numbers"
return
print l[0]+l[1]
def help_add(self):
print "help text for add"
return
def do_exit(self, arg):
return True
def test_main(verbose=None):
from test import test_support, test_cmd
test_support.run_doctest(test_cmd, verbose)
import trace, sys,re,StringIO
def test_coverage(coverdir):
tracer=trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,],
trace=0, count=1)
tracer.run('reload(cmd);test_main()')
r=tracer.results()
print "Writing coverage results..."
r.write_results(show_missing=True, summary=True, coverdir=coverdir)
if __name__ == "__main__":
if "-c" in sys.argv:
test_coverage('/tmp/cmd.cover')
else:
test_main()

32
Lib/test/test_tarfile.py
View File

@ -159,6 +159,38 @@ class MiscReadTest(ReadTest):
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:":

1
Misc/ACKS
View File

@ -579,6 +579,7 @@ Neil Schemenauer
David Scherer
Gregor Schmid
Ralf Schmitt
Michael Schneider
Peter Schneider-Kamp
Arvin Schnell
Chad J. Schroeder