mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Merged revisions 59259-59274 via svnmerge from

Browse source 
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
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 * Justin Sheehy
* Michael Simcich * Michael Simcich
* Ionel Simionescu * Ionel Simionescu
* Michael Sloan
* Gregory P. Smith * Gregory P. Smith
* Roy Smith * Roy Smith
* Clay Spence * Clay Spence
@ -185,6 +186,7 @@ docs@python.org), and we'll be glad to correct the problem.
* Glyn Webster * Glyn Webster
* Bob Weiner * Bob Weiner
* Eddy Welbourne * Eddy Welbourne
* Jeff Wheeler
* Mats Wichmann * Mats Wichmann
* Gerry Wiener * Gerry Wiener
* Timothy Wild * 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" \ @echo "Build finished; now you can run HTML Help Workshop with the" \
"build/htmlhelp/pydoc.hhp project file." "build/htmlhelp/pydoc.hhp project file."
latex: BUILDER = latex
latex: build
@echo "Build finished; the LaTeX files are in build/latex."
clean: clean:
-rm -rf build/* -rm -rf build/*
-rm -rf tools/sphinx -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 To create the CHM file, you need to run the Microsoft HTML Help Workshop
over the generated project (.hhp) file. 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/`. 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 deadlock ensues. (This function is available even when thread support is
disabled at compile time.) 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 The following macros are normally used without a trailing semicolon; look for
example usage in the Python source distribution. 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 :cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number
events. 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: .. _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. 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. 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 .. cvar:: int Py_eval_input
.. index:: single: Py_CompileString() .. index:: single: Py_CompileString()

5
Doc/data/refcounts.dat
View file

@ -309,6 +309,11 @@ PyEval_AcquireLock:void:::
PyEval_AcquireThread:void::: PyEval_AcquireThread:void:::
PyEval_AcquireThread:PyThreadState*:tstate:: PyEval_AcquireThread:PyThreadState*:tstate::
PyEval_GetBuiltins:PyObject*::0:
PyEval_GetLocals:PyObject*::0:
PyEval_GetGlobals:PyObject*::0:
PyEval_GetFrame:PyObject*::0:
PyEval_InitThreads:void::: PyEval_InitThreads:void:::
PyEval_ReleaseLock:void::: PyEval_ReleaseLock:void:::

2
Doc/distutils/extending.rst
View file

@ -1,4 +1,4 @@
.. _extending: .. _extending-distutils:
******************* *******************
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 :cfunc:`PyEval_CallObject`. This function has two arguments, both pointers to
arbitrary Python objects: the Python function, and the argument list. The 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 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; arguments. To call the Python function with no arguments, pass in NULL, or
to call it with one argument, pass a singleton tuple. :cfunc:`Py_BuildValue` an empty tuple; to call it with one argument, pass a singleton tuple.
returns a tuple when its format string consists of zero or more format codes :cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero
between parentheses. For example:: or more format codes between parentheses. For example::
int arg; int arg;
PyObject *arglist; PyObject *arglist;
@ -527,9 +527,22 @@ event code, you might use the following code::
Py_DECREF(result); Py_DECREF(result);
Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before 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. :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: .. _parsetuple:

94
Doc/glossary.rst
View file

@ -15,6 +15,17 @@ Glossary
``...`` ``...``
The typical Python prompt of the interactive shell when entering code for The typical Python prompt of the interactive shell when entering code for
an indented code block. 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 BDFL
Benevolent Dictator For Life, a.k.a. `Guido van Rossum 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, advanced mathematical feature. If you're not aware of a need for them,
it's almost certain you can safely ignore 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 descriptor
An object that defines the methods :meth:`__get__`, :meth:`__set__`, or An object that defines the methods :meth:`__get__`, :meth:`__set__`, or
:meth:`__delete__`. When a class attribute is a descriptor, its special :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 statements. The technique contrasts with the :term:`LBYL` style that is
common in many other languages such as C. 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 extension module
A module written in C, using Python's C API to interact with the core and A module written in C, using Python's C API to interact with the core and
with user code. 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__ __future__
A pseudo module which programmers can use to enable new language features A pseudo module which programmers can use to enable new language features
which are not compatible with the current interpreter. For example, the which are not compatible with the current interpreter. For example, the
@ -228,6 +269,17 @@ Glossary
More information can be found in :ref:`typeiter`. 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 LBYL
Look before you leap. This coding style explicitly tests for Look before you leap. This coding style explicitly tests for
pre-conditions before making calls or lookups. This style contrasts with pre-conditions before making calls or lookups. This style contrasts with
@ -258,6 +310,12 @@ Glossary
singletons, and many other tasks. singletons, and many other tasks.
More information can be found in :ref:`metaclasses`. 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
Mutable objects can change their value but keep their :func:`id`. See 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`. 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 Python 3000
Nickname for the next major Python version, 3.0 (coined long ago when the Nickname for the next major Python version, 3.0 (coined long ago when the
release of version 3 was something in the distant future.) 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 reference count
The number of places where a certain object is referenced to. When the The number of places where a certain object is referenced to. When the
reference count drops to zero, an object is deallocated. While reference 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 mapping rather than a sequence because the lookups use arbitrary
:term:`immutable` keys rather than integers. :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 type
The type of a Python object determines what kind of object it is; every 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 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: # or:
atexit.register(goodbye, adjective='nice', name='Donny') atexit.register(goodbye, adjective='nice', name='Donny')
Usage as a decorator:: Usage as a :term:`decorator`::
import atexit import atexit

674
Doc/library/bdb.rst
View file

@ -1,337 +1,337 @@
:mod:`bdb` --- Debugger framework :mod:`bdb` --- Debugger framework
================================= =================================
.. module:: bdb .. module:: bdb
:synopsis: Debugger framework. :synopsis: Debugger framework.
The :mod:`bdb` module handles basic debugger functions, like setting breakpoints The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
or managing execution via the debugger. or managing execution via the debugger.
The following exception is defined: The following exception is defined:
.. exception:: BdbQuit .. exception:: BdbQuit
Exception raised by the :class:`Bdb` class for quitting the debugger. Exception raised by the :class:`Bdb` class for quitting the debugger.
The :mod:`bdb` module also defines two classes: The :mod:`bdb` module also defines two classes:
.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]]) .. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])
This class implements temporary breakpoints, ignore counts, disabling and This class implements temporary breakpoints, ignore counts, disabling and
(re-)enabling, and conditionals. (re-)enabling, and conditionals.
Breakpoints are indexed by number through a list called :attr:`bpbynumber` Breakpoints are indexed by number through a list called :attr:`bpbynumber`
and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a 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 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. such instances since there may be more than one breakpoint per line.
When creating a breakpoint, its associated filename should be in canonical 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 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 first line of that function is executed. A conditional breakpoint always
counts a hit. counts a hit.
:class:`Breakpoint` instances have the following methods: :class:`Breakpoint` instances have the following methods:
.. method:: Breakpoint.deleteMe() .. method:: Breakpoint.deleteMe()
Delete the breakpoint from the list associated to a file/line. If it is the 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 last breakpoint in that position, it also deletes the entry for the
file/line. file/line.
.. method:: Breakpoint.enable() .. method:: Breakpoint.enable()
Mark the breakpoint as enabled. Mark the breakpoint as enabled.
.. method:: Breakpoint.disable() .. method:: Breakpoint.disable()
Mark the breakpoint as disabled. Mark the breakpoint as disabled.
.. method:: Breakpoint.bpprint([out]) .. method:: Breakpoint.bpprint([out])
Print all the information about the breakpoint: Print all the information about the breakpoint:
* The breakpoint number. * The breakpoint number.
* If it is temporary or not. * If it is temporary or not.
* Its file,line position. * Its file,line position.
* The condition that causes a break. * The condition that causes a break.
* If it must be ignored the next N times. * If it must be ignored the next N times.
* The breakpoint hit count. * The breakpoint hit count.
.. class:: Bdb() .. class:: Bdb()
The :class:`Bdb` acts as a generic Python debugger base class. 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 This class takes care of the details of the trace facility; a derived class
should implement user interaction. The standard debugger class should implement user interaction. The standard debugger class
(:class:`pdb.Pdb`) is an example. (:class:`pdb.Pdb`) is an example.
The following methods of :class:`Bdb` normally don't need to be overridden. The following methods of :class:`Bdb` normally don't need to be overridden.
.. method:: Bdb.canonic(filename) .. method:: Bdb.canonic(filename)
Auxiliary method for getting a filename in a canonical form, that is, as a Auxiliary method for getting a filename in a canonical form, that is, as a
case-normalized (on case-insensitive filesystems) absolute path, stripped case-normalized (on case-insensitive filesystems) absolute path, stripped
of surrounding angle brackets. of surrounding angle brackets.
.. method:: Bdb.reset() .. method:: Bdb.reset()
Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
:attr:`quitting` attributes with values ready to start debugging. :attr:`quitting` attributes with values ready to start debugging.
.. method:: Bdb.trace_dispatch(frame, event, arg) .. method:: Bdb.trace_dispatch(frame, event, arg)
This function is installed as the trace function of debugged frames. Its 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). 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 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 type of event (passed as a string) that is about to be executed. *event* can
be one of the following: be one of the following:
* ``"line"``: A new line of code is going to be executed. * ``"line"``: A new line of code is going to be executed.
* ``"call"``: A function is about to be called, or another code block * ``"call"``: A function is about to be called, or another code block
entered. entered.
* ``"return"``: A function or other code block is about to return. * ``"return"``: A function or other code block is about to return.
* ``"exception"``: An exception has occurred. * ``"exception"``: An exception has occurred.
* ``"c_call"``: A C function is about to be called. * ``"c_call"``: A C function is about to be called.
* ``"c_return"``: A C function has returned. * ``"c_return"``: A C function has returned.
* ``"c_exception"``: A C function has thrown an exception. * ``"c_exception"``: A C function has thrown an exception.
For the Python events, specialized functions (see below) are called. For the For the Python events, specialized functions (see below) are called. For the
C events, no action is taken. C events, no action is taken.
The *arg* parameter depends on the previous event. The *arg* parameter depends on the previous event.
For more information on trace functions, see :ref:`debugger-hooks`. For more For more information on trace functions, see :ref:`debugger-hooks`. For more
information on code and frame objects, refer to :ref:`types`. information on code and frame objects, refer to :ref:`types`.
.. method:: Bdb.dispatch_line(frame) .. method:: Bdb.dispatch_line(frame)
If the debugger should stop on the current line, invoke the :meth:`user_line` 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` 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 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 :meth:`user_line`). Return a reference to the :meth:`trace_dispatch` method
for further tracing in that scope. for further tracing in that scope.
.. method:: Bdb.dispatch_call(frame, arg) .. method:: Bdb.dispatch_call(frame, arg)
If the debugger should stop on this function call, invoke the If the debugger should stop on this function call, invoke the
:meth:`user_call` method (which should be overridden in subclasses). Raise a :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 :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
be set from :meth:`user_call`). Return a reference to the be set from :meth:`user_call`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope. :meth:`trace_dispatch` method for further tracing in that scope.
.. method:: Bdb.dispatch_return(frame, arg) .. method:: Bdb.dispatch_return(frame, arg)
If the debugger should stop on this function return, invoke the If the debugger should stop on this function return, invoke the
:meth:`user_return` method (which should be overridden in subclasses). Raise :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 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 be set from :meth:`user_return`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope. :meth:`trace_dispatch` method for further tracing in that scope.
.. method:: Bdb.dispatch_exception(frame, arg) .. method:: Bdb.dispatch_exception(frame, arg)
If the debugger should stop at this exception, invokes the If the debugger should stop at this exception, invokes the
:meth:`user_exception` method (which should be overridden in subclasses). :meth:`user_exception` method (which should be overridden in subclasses).
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set 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 (which can be set from :meth:`user_exception`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope. :meth:`trace_dispatch` method for further tracing in that scope.
Normally derived classes don't override the following methods, but they may if Normally derived classes don't override the following methods, but they may if
they want to redefine the definition of stopping and breakpoints. they want to redefine the definition of stopping and breakpoints.
.. method:: Bdb.stop_here(frame) .. method:: Bdb.stop_here(frame)
This method checks if the *frame* is somewhere below :attr:`botframe` in the This method checks if the *frame* is somewhere below :attr:`botframe` in the
call stack. :attr:`botframe` is the frame in which debugging started. call stack. :attr:`botframe` is the frame in which debugging started.
.. method:: Bdb.break_here(frame) .. method:: Bdb.break_here(frame)
This method checks if there is a breakpoint in the filename and line 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 belonging to *frame* or, at least, in the current function. If the
breakpoint is a temporary one, this method deletes it. breakpoint is a temporary one, this method deletes it.
.. method:: Bdb.break_anywhere(frame) .. method:: Bdb.break_anywhere(frame)
This method checks if there is a breakpoint in the filename of the current This method checks if there is a breakpoint in the filename of the current
frame. frame.
Derived classes should override these methods to gain control over debugger Derived classes should override these methods to gain control over debugger
operation. operation.
.. method:: Bdb.user_call(frame, argument_list) .. method:: Bdb.user_call(frame, argument_list)
This method is called from :meth:`dispatch_call` when there is the This method is called from :meth:`dispatch_call` when there is the
possibility that a break might be necessary anywhere inside the called possibility that a break might be necessary anywhere inside the called
function. function.
.. method:: Bdb.user_line(frame) .. method:: Bdb.user_line(frame)
This method is called from :meth:`dispatch_line` when either This method is called from :meth:`dispatch_line` when either
:meth:`stop_here` or :meth:`break_here` yields True. :meth:`stop_here` or :meth:`break_here` yields True.
.. method:: Bdb.user_return(frame, return_value) .. method:: Bdb.user_return(frame, return_value)
This method is called from :meth:`dispatch_return` when :meth:`stop_here` This method is called from :meth:`dispatch_return` when :meth:`stop_here`
yields True. yields True.
.. method:: Bdb.user_exception(frame, exc_info) .. method:: Bdb.user_exception(frame, exc_info)
This method is called from :meth:`dispatch_exception` when :meth:`stop_here` This method is called from :meth:`dispatch_exception` when :meth:`stop_here`
yields True. yields True.
.. method:: Bdb.do_clear(arg) .. method:: Bdb.do_clear(arg)
Handle how a breakpoint must be removed when it is a temporary one. Handle how a breakpoint must be removed when it is a temporary one.
This method must be implemented by derived classes. This method must be implemented by derived classes.
Derived classes and clients can call the following methods to affect the Derived classes and clients can call the following methods to affect the
stepping state. stepping state.
.. method:: Bdb.set_step() .. method:: Bdb.set_step()
Stop after one line of code. Stop after one line of code.
.. method:: Bdb.set_next(frame) .. method:: Bdb.set_next(frame)
Stop on the next line in or below the given frame. Stop on the next line in or below the given frame.
.. method:: Bdb.set_return(frame) .. method:: Bdb.set_return(frame)
Stop when returning from the given frame. Stop when returning from the given frame.
.. method:: Bdb.set_trace([frame]) .. method:: Bdb.set_trace([frame])
Start debugging from *frame*. If *frame* is not specified, debugging starts Start debugging from *frame*. If *frame* is not specified, debugging starts
from caller's frame. from caller's frame.
.. method:: Bdb.set_continue() .. method:: Bdb.set_continue()
Stop only at breakpoints or when finished. If there are no breakpoints, set Stop only at breakpoints or when finished. If there are no breakpoints, set
the system trace function to None. the system trace function to None.
.. method:: Bdb.set_quit() .. method:: Bdb.set_quit()
Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in
the next call to one of the :meth:`dispatch_\*` methods. the next call to one of the :meth:`dispatch_\*` methods.
Derived classes and clients can call the following methods to manipulate Derived classes and clients can call the following methods to manipulate
breakpoints. These methods return a string containing an error message if breakpoints. These methods return a string containing an error message if
something went wrong, or ``None`` if all is well. something went wrong, or ``None`` if all is well.
.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]]) .. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
Set a new breakpoint. If the *lineno* line doesn't exist for the *filename* 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 passed as argument, return an error message. The *filename* should be in
canonical form, as described in the :meth:`canonic` method. canonical form, as described in the :meth:`canonic` method.
.. method:: Bdb.clear_break(filename, lineno) .. method:: Bdb.clear_break(filename, lineno)
Delete the breakpoints in *filename* and *lineno*. If none were set, an Delete the breakpoints in *filename* and *lineno*. If none were set, an
error message is returned. error message is returned.
.. method:: Bdb.clear_bpbynumber(arg) .. method:: Bdb.clear_bpbynumber(arg)
Delete the breakpoint which has the index *arg* in the Delete the breakpoint which has the index *arg* in the
:attr:`Breakpoint.bpbynumber`. If `arg` is not numeric or out of range, :attr:`Breakpoint.bpbynumber`. If `arg` is not numeric or out of range,
return an error message. return an error message.
.. method:: Bdb.clear_all_file_breaks(filename) .. method:: Bdb.clear_all_file_breaks(filename)
Delete all breakpoints in *filename*. If none were set, an error message is Delete all breakpoints in *filename*. If none were set, an error message is
returned. returned.
.. method:: Bdb.clear_all_breaks() .. method:: Bdb.clear_all_breaks()
Delete all existing breakpoints. Delete all existing breakpoints.
.. method:: Bdb.get_break(filename, lineno) .. method:: Bdb.get_break(filename, lineno)
Check if there is a breakpoint for *lineno* of *filename*. Check if there is a breakpoint for *lineno* of *filename*.
.. method:: Bdb.get_breaks(filename, lineno) .. method:: Bdb.get_breaks(filename, lineno)
Return all breakpoints for *lineno* in *filename*, or an empty list if none Return all breakpoints for *lineno* in *filename*, or an empty list if none
are set. are set.
.. method:: Bdb.get_file_breaks(filename) .. method:: Bdb.get_file_breaks(filename)
Return all breakpoints in *filename*, or an empty list if none are set. Return all breakpoints in *filename*, or an empty list if none are set.
.. method:: Bdb.get_all_breaks() .. method:: Bdb.get_all_breaks()
Return all breakpoints that are set. Return all breakpoints that are set.
Derived classes and clients can call the following methods to get a data Derived classes and clients can call the following methods to get a data
structure representing a stack trace. structure representing a stack trace.
.. method:: Bdb.get_stack(f, t) .. method:: Bdb.get_stack(f, t)
Get a list of records for a frame and all higher (calling) and lower frames, Get a list of records for a frame and all higher (calling) and lower frames,
and the size of the higher part. and the size of the higher part.
.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': ']) .. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])
Return a string with information about a stack entry, identified by a Return a string with information about a stack entry, identified by a
``(frame, lineno)`` tuple: ``(frame, lineno)`` tuple:
* The canonical form of the filename which contains the frame. * The canonical form of the filename which contains the frame.
* The function name, or ``"<lambda>"``. * The function name, or ``"<lambda>"``.
* The input arguments. * The input arguments.
* The return value. * The return value.
* The line of code (if it exists). * The line of code (if it exists).
The following two methods can be called by clients to use a debugger to debug a The following two methods can be called by clients to use a debugger to debug a
statement, given as a string. :term:`statement`, given as a string.
.. method:: Bdb.run(cmd, [globals, [locals]]) .. method:: Bdb.run(cmd, [globals, [locals]])
Debug a statement executed via the :func:`exec` function. *globals* Debug a statement executed via the :keyword:`exec` statement. *globals*
defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*. defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
.. method:: Bdb.runeval(expr, [globals, [locals]]) .. method:: Bdb.runeval(expr, [globals, [locals]])
Debug an expression executed via the :func:`eval` function. *globals* and Debug an expression executed via the :func:`eval` function. *globals* and
*locals* have the same meaning as in :meth:`run`. *locals* have the same meaning as in :meth:`run`.
.. method:: Bdb.runctx(cmd, globals, locals) .. method:: Bdb.runctx(cmd, globals, locals)
For backwards compatibility. Calls the :meth:`run` method. For backwards compatibility. Calls the :meth:`run` method.
.. method:: Bdb.runcall(func, *args, **kwds) .. method:: Bdb.runcall(func, *args, **kwds)
Debug a single function call, and return its result. Debug a single function call, and return its result.
Finally, the module defines the following functions: Finally, the module defines the following functions:
.. function:: checkfuncname(b, frame) .. function:: checkfuncname(b, frame)
Check whether we should break here, depending on the way the breakpoint *b* Check whether we should break here, depending on the way the breakpoint *b*
was set. was set.
If it was set via line number, it checks if ``b.line`` is the same as the one 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 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 name, we have to check we are in the right frame (the right function) and if
we are in its first executable line. we are in its first executable line.
.. function:: effective(file, line, frame) .. function:: effective(file, line, frame)
Determine if there is an effective (active) breakpoint at this line of code. Determine if there is an effective (active) breakpoint at this line of code.
Return breakpoint number or 0 if none. Return breakpoint number or 0 if none.
Called only if we know there is a breakpoint at this location. Returns the 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 breakpoint that was triggered and a flag that indicates if it is ok to delete
a temporary breakpoint. a temporary breakpoint.
.. function:: set_trace() .. function:: set_trace()
Starts debugging with a :class:`Bdb` instance from caller's frame. 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. :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
The *symbol* argument determines whether *source* is compiled as a statement The *symbol* argument determines whether *source* is compiled as a statement
(``'single'``, the default) or as an expression (``'eval'``). Any other value (``'single'``, the default) or as an :term:`expression` (``'eval'``). Any
will cause :exc:`ValueError` to be raised. other value will cause :exc:`ValueError` to be raised.
.. warning:: .. warning::

6
Doc/library/contextlib.rst
View file

@ -15,9 +15,9 @@ Functions provided:
.. function:: contextmanager(func) .. function:: contextmanager(func)
This function is a decorator that can be used to define a factory function for This function is a :term:`decorator` that can be used to define a factory
:keyword:`with` statement context managers, without needing to create a class or function for :keyword:`with` statement context managers, without needing to
separate :meth:`__enter__` and :meth:`__exit__` methods. 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!):: 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 advanced API revolves around two container classes, which are used to store
the interactive examples extracted from doctest cases: 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 * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
from a single docstring or text file. 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 @classmethod
def f(cls, arg1, arg2, ...): ... def f(cls, arg1, arg2, ...): ...
The ``@classmethod`` form is a function decorator -- see the description of The ``@classmethod`` form is a function :term:`decorator` -- see the description
function definitions in :ref:`function` for details. 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 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 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 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 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): class Parrot(object):
def __init__(self): def __init__(self):
@ -906,7 +906,7 @@ available. They are listed here in alphabetical order.
.. index:: single: Numerical Python .. 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 ``range(start, stop, step)``. The *start* and *step* arguments default to
``None``. Slice objects have read-only data attributes :attr:`start`, ``None``. Slice objects have read-only data attributes :attr:`start`,
:attr:`stop` and :attr:`step` which merely return the argument values (or their :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 @staticmethod
def f(arg1, arg2, ...): ... def f(arg1, arg2, ...): ...
The ``@staticmethod`` form is a function decorator -- see the description of The ``@staticmethod`` form is a function :term:`decorator` -- see the
function definitions in :ref:`function` for details. 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 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. 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 *WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the
instance dictionary). instance dictionary).
The main intended use for this function is in decorator functions which wrap the The main intended use for this function is in :term:`decorator` functions which
decorated function and return the wrapper. If the wrapper function is not wrap the decorated function and return the wrapper. If the wrapper function is
updated, the metadata of the returned function will reflect the wrapper not updated, the metadata of the returned function will reflect the wrapper
definition rather than the original function definition, which is typically less definition rather than the original function definition, which is typically less
than helpful. than helpful.

2
Doc/library/inspect.rst
View file

@ -220,7 +220,7 @@ attributes:
.. function:: isfunction(object) .. 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) .. 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 *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. 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. *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: 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 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 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)``. example, the :term:`statement` ``x += y`` is equivalent to
Another way to put it is to say that ``z = operator.iadd(x, y)`` is equivalent ``x = operator.iadd(x, y)``. Another way to put it is to say that
to the compound statement ``z = x; z += y``. ``z = operator.iadd(x, y)`` is equivalent to the compound statement
``z = x; z += y``.
.. function:: iadd(a, b) .. function:: iadd(a, b)
__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 their implementation of the context management protocol. See the
:mod:`contextlib` module for some examples. :mod:`contextlib` module for some examples.
Python's :term:`generator`\s and the ``contextlib.contextfactory`` decorator provide a Python's :term:`generator`\s and the ``contextlib.contextfactory`` :term:`decorator`
convenient way to implement these protocols. If a generator function is provide a convenient way to implement these protocols. If a generator function is
decorated with the ``contextlib.contextfactory`` decorator, it will return a decorated with the ``contextlib.contextfactory`` decorator, it will return a
context manager implementing the necessary :meth:`__enter__` and context manager implementing the necessary :meth:`__enter__` and
:meth:`__exit__` methods, rather than the iterator produced by an undecorated :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 If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves
it in ``builtins._``. it in ``builtins._``.
``sys.displayhook`` is called on the result of evaluating an expression entered ``sys.displayhook`` is called on the result of evaluating an :term:`expression`
in an interactive Python session. The display of these values can be customized entered in an interactive Python session. The display of these values can be
by assigning another one-argument function to ``sys.displayhook``. customized by assigning another one-argument function to ``sys.displayhook``.
.. function:: excepthook(type, value, traceback) .. function:: excepthook(type, value, traceback)
@ -536,14 +536,16 @@ always available.
stderr stderr
File objects corresponding to the interpreter's standard input, output and error File objects corresponding to the interpreter's standard input, output and error
streams. ``stdin`` is used for all interpreter input except for scripts. streams. ``stdin`` is used for all interpreter input except for scripts but
``stdout`` is used for the output of :func:`print` and expression statements. including calls to :func:`input`. ``stdout`` is used for
The interpreter's own prompts and (almost all of) its error messages go to the output of :func:`print` and :term:`expression` statements and for the
``stderr``. ``stdout`` and ``stderr`` needn't be built-in file objects: any prompts of :func:`input`. The interpreter's own prompts
object is acceptable as long as it has a :meth:`write` method that takes a and (almost all of) its error messages go to ``stderr``. ``stdout`` and
string argument. (Changing these objects doesn't affect the standard I/O ``stderr`` needn't be built-in file objects: any object is acceptable as long
streams of processes executed by :func:`os.popen`, :func:`os.system` or the as it has a :meth:`write` method that takes a string argument. (Changing these
:func:`exec\*` family of functions in the :mod:`os` module.) 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__ .. data:: __stdin__

11
Doc/library/timeit.rst
View file

@ -85,11 +85,12 @@ The module defines the following public class:
.. note:: .. note::
By default, :meth:`timeit` temporarily turns off garbage collection during the By default, :meth:`timeit` temporarily turns off :term:`garbage collection`
timing. The advantage of this approach is that it makes independent timings during the timing. The advantage of this approach is that it makes
more comparable. This disadvantage is that GC may be an important component of independent timings more comparable. This disadvantage is that GC may be
the performance of the function being measured. If so, GC can be re-enabled as an important component of the performance of the function being measured.
the first statement in the *setup* string. For example:: 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() 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. by a weak reference.
A weak reference to an object is not enough to keep the object alive: when the 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 only remaining references to a referent are weak references,
is free to destroy the referent and reuse its memory for something else. A :term:`garbage collection` is free to destroy the referent and reuse its memory
primary use for weak references is to implement caches or mappings holding large for something else. A primary use for weak references is to implement caches or
objects, where it's desired that a large object not be kept alive solely because mappings holding large objects, where it's desired that a large object not be
it appears in a cache or mapping. For example, if you have a number of large kept alive solely because it appears in a cache or mapping. For example, if you
binary image objects, you may wish to associate a name with each. If you used a have a number of large binary image objects, you may wish to associate a name
Python dictionary to map names to images, or images to names, the image objects with each. If you used a Python dictionary to map names to images, or images to
would remain alive just because they appeared as values or keys in the names, the image objects would remain alive just because they appeared as values
dictionaries. The :class:`WeakKeyDictionary`, :class:`WeakValueDictionary` or keys in the dictionaries. The :class:`WeakKeyDictionary` and
and :class:`WeakSet` classes supplied by the :mod:`weakref` module are an :class:`WeakValueDictionary` classes supplied by the :mod:`weakref` module are
alternative, using weak references to construct mappings that don't keep objects an alternative, using weak references to construct mappings that don't keep
alive solely because they appear in the container objects. objects alive solely because they appear in the mapping objects. If, for
If, for example, an image object is a value in a :class:`WeakValueDictionary`, example, an image object is a value in a :class:`WeakValueDictionary`, then when
then when the last remaining references to that image object are the weak the last remaining references to that image object are the weak references held
references held by weak mappings, garbage collection can reclaim the object, by weak mappings, garbage collection can reclaim the object, and its
and its corresponding entries in weak mappings are simply deleted. corresponding entries in weak mappings are simply deleted.
:class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references
in their implementation, setting up callback functions on the 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 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`. 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: .. _elementtree-functions:
@ -355,6 +358,33 @@ ElementTree Objects
object opened for writing. *encoding* is the output encoding (default is object opened for writing. *encoding* is the output encoding (default is
US-ASCII). 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: .. _elementtree-qname-objects:
@ -440,3 +470,41 @@ XMLTreeBuilder Objects
Feeds data to the parser. *data* is encoded data. 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 The function definition does not execute the function body; this gets executed
only when the function is called. 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 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 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 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 Python does automatic memory management (reference counting for most objects and
garbage collection to eliminate cycles). The memory is freed shortly after the :term:`garbage collection` to eliminate cycles). The memory is freed shortly
last reference to it has been eliminated. after the last reference to it has been eliminated.
This approach works fine for most applications but occasionally there is a need 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. 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 .. highlightlang:: none
.. _using-on-general:
Command line and environment Command line and environment
============================ ============================
@ -12,6 +14,8 @@ settings.
:ref:`implementations` for further resources. :ref:`implementations` for further resources.
.. _using-on-cmdline:
Command line Command line
------------ ------------
@ -289,35 +293,7 @@ Miscellaneous options
.. warning:: The line numbers in error messages will be off by one! .. warning:: The line numbers in error messages will be off by one!
.. _using-on-envvars:
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. |
+-----------------------------------------------+------------------------------------------+
Environment variables Environment variables
--------------------- ---------------------

1
Doc/using/index.rst
View file

@ -13,5 +13,6 @@ interpreter and things that make working with Python easier.
.. toctree:: .. toctree::
cmdline.rst cmdline.rst
windows.rst
mac.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.closed = False
self.members = [] # list of members as TarInfo objects self.members = [] # list of members as TarInfo objects
self._loaded = False # flag if all members have been read 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 self.inodes = {} # dictionary caching the inodes of
# archive members already added # 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) tar = tarfile.open(fileobj=fobj, mode=self.mode)
self.assertEqual(tar.name, None) 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): def test_fail_comp(self):
# For Gzip and Bz2 Tests: fail with a ReadError on an uncompressed file. # For Gzip and Bz2 Tests: fail with a ReadError on an uncompressed file.
if self.mode == "r:": if self.mode == "r:":

1
Misc/ACKS
View file

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