traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from 

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r70712 | benjamin.peterson | 2009-03-30 10:15:38 -0500 (Mon, 30 Mar 2009) | 1 line

  don't rely on the order dict repr #5605
........
  r70714 | brett.cannon | 2009-03-30 10:20:53 -0500 (Mon, 30 Mar 2009) | 1 line

  Add an entry to developers.txt.
........
  r70764 | martin.v.loewis | 2009-03-30 17:06:33 -0500 (Mon, 30 Mar 2009) | 2 lines

  Add several VM developers.
........
  r70765 | georg.brandl | 2009-03-30 17:09:34 -0500 (Mon, 30 Mar 2009) | 1 line

  #5199: make warning about vars() assignment more visible.
........
  r70769 | andrew.kuchling | 2009-03-30 17:29:53 -0500 (Mon, 30 Mar 2009) | 1 line

  Remove comment
........
  r70770 | andrew.kuchling | 2009-03-30 17:30:20 -0500 (Mon, 30 Mar 2009) | 1 line

  Add several items and placeholders
........
  r70771 | andrew.kuchling | 2009-03-30 17:31:11 -0500 (Mon, 30 Mar 2009) | 1 line

  Many edits
........
  r70773 | georg.brandl | 2009-03-30 17:43:00 -0500 (Mon, 30 Mar 2009) | 1 line

  #5039: make it clear that the impl. note refers to CPython.
........
  r70776 | andrew.kuchling | 2009-03-30 18:08:24 -0500 (Mon, 30 Mar 2009) | 1 line

  typo fix
........
  r70777 | andrew.kuchling | 2009-03-30 18:09:46 -0500 (Mon, 30 Mar 2009) | 1 line

  Add more items
........
  r70788 | andrew.kuchling | 2009-03-30 20:21:01 -0500 (Mon, 30 Mar 2009) | 1 line

  Add various items
........
  r70789 | georg.brandl | 2009-03-30 20:25:15 -0500 (Mon, 30 Mar 2009) | 1 line

  Fix a wrong struct field assignment (docstring as closure).
........
  r70824 | georg.brandl | 2009-03-31 10:43:20 -0500 (Tue, 31 Mar 2009) | 1 line

  #5519: remove reference to Kodos, which seems dead.
........
  r70828 | georg.brandl | 2009-03-31 10:50:16 -0500 (Tue, 31 Mar 2009) | 1 line

  #5581: fget argument of abstractproperty is optional as well.
........
  r70832 | georg.brandl | 2009-03-31 11:31:11 -0500 (Tue, 31 Mar 2009) | 1 line

  #1386675: specify WindowsError as the exception, because it has a winerror attribute that EnvironmentError doesnt have.
........
  r70836 | georg.brandl | 2009-03-31 11:50:25 -0500 (Tue, 31 Mar 2009) | 1 line

  #5417: replace references to undocumented functions by ones to documented functions.
........
  r70842 | georg.brandl | 2009-03-31 12:13:06 -0500 (Tue, 31 Mar 2009) | 1 line

  #970783: document PyObject_Generic[GS]etAttr.
........
  r70851 | georg.brandl | 2009-03-31 13:26:55 -0500 (Tue, 31 Mar 2009) | 1 line

  #837577: note cryptic return value of spawn*e on invalid env dicts.
........
  r70855 | georg.brandl | 2009-03-31 13:30:37 -0500 (Tue, 31 Mar 2009) | 1 line

  #5245: note that PyRun_SimpleString doesnt return on SystemExit.
........
  r70857 | georg.brandl | 2009-03-31 13:33:10 -0500 (Tue, 31 Mar 2009) | 1 line

  #5227: note that Py_Main doesnt return on SystemExit.
........
  r70866 | georg.brandl | 2009-03-31 14:06:57 -0500 (Tue, 31 Mar 2009) | 1 line

  #4882: document named group behavior a bit better.
........
  r70867 | georg.brandl | 2009-03-31 14:10:35 -0500 (Tue, 31 Mar 2009) | 1 line

  #1096310: document usage of sys.__std*__ a bit better.
........
  r70868 | georg.brandl | 2009-03-31 14:12:17 -0500 (Tue, 31 Mar 2009) | 1 line

  #5190: export make_option in __all__.
........
  r70869 | georg.brandl | 2009-03-31 14:14:42 -0500 (Tue, 31 Mar 2009) | 1 line

  Fix-up unwanted change.
........
  r70870 | georg.brandl | 2009-03-31 14:26:24 -0500 (Tue, 31 Mar 2009) | 1 line

  #4411: document mro() and __mro__. (I hope I got it right.)
........
  r70871 | georg.brandl | 2009-03-31 14:30:56 -0500 (Tue, 31 Mar 2009) | 1 line

  #5618: fix typo.
........
  r70872 | r.david.murray | 2009-03-31 14:31:17 -0500 (Tue, 31 Mar 2009) | 3 lines

  Delete out-of-date and little-known README from the test
  directory by consensus of devs at pycon sprint.
........
  r70883 | georg.brandl | 2009-03-31 15:41:08 -0500 (Tue, 31 Mar 2009) | 1 line

  #1674032: return value of flag from Event.wait(). OKed by Guido.
........
  r70885 | tarek.ziade | 2009-03-31 15:48:31 -0500 (Tue, 31 Mar 2009) | 1 line

  using log.warn for sys.stderr
........
  r70893 | georg.brandl | 2009-03-31 15:56:32 -0500 (Tue, 31 Mar 2009) | 1 line

  #1530012: move TQS section before raw strings.
........
  r70894 | benjamin.peterson | 2009-03-31 16:06:30 -0500 (Tue, 31 Mar 2009) | 1 line

  take the usual lock precautions around _active_limbo_lock
........
  r70896 | georg.brandl | 2009-03-31 16:15:33 -0500 (Tue, 31 Mar 2009) | 1 line

  #5598: document DocFileSuite *args argument.
........
  r70897 | benjamin.peterson | 2009-03-31 16:34:42 -0500 (Tue, 31 Mar 2009) | 1 line

  fix Thread.ident when it is the main thread or a dummy thread #5632
........
  r70903 | georg.brandl | 2009-03-31 16:45:18 -0500 (Tue, 31 Mar 2009) | 1 line

  #1676135: remove trailing slashes from --prefix argument.
........
  r70905 | georg.brandl | 2009-03-31 17:03:40 -0500 (Tue, 31 Mar 2009) | 1 line

  #5563: more documentation for bdist_msi.
........
  r70906 | georg.brandl | 2009-03-31 17:11:53 -0500 (Tue, 31 Mar 2009) | 1 line

  #1651995: fix _convert_ref for non-ASCII characters.
........
  r70907 | georg.brandl | 2009-03-31 17:18:19 -0500 (Tue, 31 Mar 2009) | 1 line

  #3427: document correct return type for urlopen().info().
........
  r70915 | georg.brandl | 2009-03-31 17:40:16 -0500 (Tue, 31 Mar 2009) | 1 line

  #5018: remove confusing paragraph.
........
  r70927 | georg.brandl | 2009-03-31 18:01:27 -0500 (Tue, 31 Mar 2009) | 1 line

  Dont shout to users.
........
  r70933 | georg.brandl | 2009-03-31 19:04:33 -0500 (Tue, 31 Mar 2009) | 2 lines

  Issue #5635: Fix running test_sys with tracing enabled.
........
  r70951 | georg.brandl | 2009-04-01 09:02:27 -0500 (Wed, 01 Apr 2009) | 1 line

  Add Maksim, who worked on several issues at the sprint.
........
  r70960 | jesse.noller | 2009-04-01 11:42:19 -0500 (Wed, 01 Apr 2009) | 1 line

  Issue 3270: document Listener address restrictions on windows
........
  r70962 | brett.cannon | 2009-04-01 12:07:16 -0500 (Wed, 01 Apr 2009) | 2 lines

  Ron DuPlain was given commit privileges at PyCon 2009 to work on 3to2.
........
  r70963 | georg.brandl | 2009-04-01 12:46:01 -0500 (Wed, 01 Apr 2009) | 1 line

  #5655: fix docstring oversight.
........
  r70964 | brett.cannon | 2009-04-01 12:52:13 -0500 (Wed, 01 Apr 2009) | 2 lines

  Paul Kippes was given commit privileges to work on 3to2.
........
  r70998 | georg.brandl | 2009-04-01 16:54:21 -0500 (Wed, 01 Apr 2009) | 1 line

  In Pdb, stop assigning values to __builtin__._ which interferes with the one commonly installed by gettext.
........
  r71001 | brett.cannon | 2009-04-01 18:01:12 -0500 (Wed, 01 Apr 2009) | 3 lines

  Add my initials to Misc/developers.txt. Names are now sorted by number of
  characters in the person's name.
........
  r71006 | georg.brandl | 2009-04-01 18:32:17 -0500 (Wed, 01 Apr 2009) | 1 line

  Cache the f_locals dict of the current frame, since every access to frame.f_locals overrides its contents with the real locals which undoes modifications made by the debugging user.
........
  r71008 | andrew.kuchling | 2009-04-01 19:02:14 -0500 (Wed, 01 Apr 2009) | 1 line

  Typo fix
........
  r71010 | benjamin.peterson | 2009-04-01 19:11:52 -0500 (Wed, 01 Apr 2009) | 1 line

  fix markup
........
  r71011 | benjamin.peterson | 2009-04-01 19:12:47 -0500 (Wed, 01 Apr 2009) | 1 line

  this should be :noindex:
........
  r71019 | georg.brandl | 2009-04-01 21:00:01 -0500 (Wed, 01 Apr 2009) | 1 line

  Fix test_doctest, missed two assignments to curframe.
........
  r71037 | r.david.murray | 2009-04-01 23:34:04 -0500 (Wed, 01 Apr 2009) | 6 lines

  Clarify that datetime strftime does not produce leap seconds and datetime
  strptime does not accept it in the strftime behavior section of the
  datetime docs.

  Closes issue 2568.
........
  r71056 | georg.brandl | 2009-04-02 12:43:07 -0500 (Thu, 02 Apr 2009) | 2 lines

  Actually the displayhook should print the repr.
........
  r71094 | vinay.sajip | 2009-04-03 05:23:18 -0500 (Fri, 03 Apr 2009) | 1 line

  Added warning about logging use from asynchronous signal handlers.
........
  r71101 | andrew.kuchling | 2009-04-03 16:43:00 -0500 (Fri, 03 Apr 2009) | 1 line

  Add some items
........
  r71102 | andrew.kuchling | 2009-04-03 16:44:49 -0500 (Fri, 03 Apr 2009) | 1 line

  Fix 'the the'; grammar fix
........
  r71103 | andrew.kuchling | 2009-04-03 16:45:29 -0500 (Fri, 03 Apr 2009) | 1 line

  Fix 'the the' duplication
........
  r71106 | vinay.sajip | 2009-04-03 16:58:16 -0500 (Fri, 03 Apr 2009) | 1 line

  Clarified warning about logging use from asynchronous signal handlers.
........
  r71119 | raymond.hettinger | 2009-04-04 00:37:47 -0500 (Sat, 04 Apr 2009) | 1 line

  Add helpful link.
........
  r71123 | r.david.murray | 2009-04-04 01:39:56 -0500 (Sat, 04 Apr 2009) | 2 lines

  Fix error in description of 'oct' (issue 5678).
........
  r71149 | georg.brandl | 2009-04-04 08:42:39 -0500 (Sat, 04 Apr 2009) | 1 line

  #5642: clarify map() compatibility to the builtin.
........
  r71150 | georg.brandl | 2009-04-04 08:45:49 -0500 (Sat, 04 Apr 2009) | 1 line

  #5601: clarify that webbrowser is not meant for file names.
........
  r71203 | benjamin.peterson | 2009-04-04 18:46:34 -0500 (Sat, 04 Apr 2009) | 1 line

  note how using iter* are unsafe while mutating and document iter(dict)
........
  r71212 | georg.brandl | 2009-04-05 05:24:20 -0500 (Sun, 05 Apr 2009) | 1 line

  #1742837: expand HTTP server docs, and fix SocketServer ones to document methods as methods, not functions.
........
  r71214 | georg.brandl | 2009-04-05 05:29:57 -0500 (Sun, 05 Apr 2009) | 1 line

  Normalize spelling of Mac OS X.
........
  r71215 | georg.brandl | 2009-04-05 05:32:26 -0500 (Sun, 05 Apr 2009) | 1 line

  Avoid sure signs of a diseased mind.
........
  r71216 | georg.brandl | 2009-04-05 05:41:02 -0500 (Sun, 05 Apr 2009) | 1 line

  #1718017: document the relation of os.path and the posixpath, ntpath etc. modules better.
........
  r71217 | georg.brandl | 2009-04-05 05:48:47 -0500 (Sun, 05 Apr 2009) | 1 line

  #1726172: dont raise an unexpected IndexError if a voidresp() call has an empty response.
........
  r71221 | vinay.sajip | 2009-04-05 06:06:24 -0500 (Sun, 05 Apr 2009) | 1 line

  Issue #5695: Moved logging.captureWarnings() call inside with statement in WarningsTest.test_warnings.
........
  r71240 | georg.brandl | 2009-04-05 09:40:06 -0500 (Sun, 05 Apr 2009) | 1 line

  #5370: doc update about unpickling objects with custom __getattr__ etc. methods.
........
This commit is contained in:
Benjamin Peterson 2009-04-05 19:13:16 +00:00
parent 5b9082a959
commit d23f8224e9
50 changed files with 679 additions and 760 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -787,7 +787,7 @@ created.
Asynchronous Notifications Asynchronous Notifications
========================== ==========================
A mechanism is provided to make asynchronous notifications to the the main A mechanism is provided to make asynchronous notifications to the main
interpreter thread. These notifications take the form of a function interpreter thread. These notifications take the form of a function
pointer and a void argument. pointer and a void argument.

4
Doc/c-api/number.rst
View File

@ -264,8 +264,8 @@ Number Protocol
.. cfunction:: PyObject* PyNumber_ToBase(PyObject *n, int base) .. cfunction:: PyObject* PyNumber_ToBase(PyObject *n, int base)
Returns the the integer *n* converted to *base* as a string with a base Returns the integer *n* converted to *base* as a string with a base
marker of ``'0b'``, ``'0o'``, or ``'0x'`` if appended applicable. When marker of ``'0b'``, ``'0o'``, or ``'0x'`` if applicable. When
*base* is not 2, 8, 10, or 16, the format is ``'x#num'`` where x is the *base* is not 2, 8, 10, or 16, the format is ``'x#num'`` where x is the
base. If *n* is not an int object, it is converted with base. If *n* is not an int object, it is converted with
:cfunc:`PyNumber_Index` first. :cfunc:`PyNumber_Index` first.

20
Doc/c-api/object.rst
View File

@ -42,6 +42,16 @@ Object Protocol
expression ``o.attr_name``. expression ``o.attr_name``.
.. cfunction:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
Generic attribute getter function that is meant to be put into a type
object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary
of classes in the object's MRO as well as an attribute in the object's
:attr:`__dict__` (if present). As outlined in :ref:`descriptors`, data
descriptors take preference over instance attributes, while non-data
descriptors don't. Otherwise, an :exc:`AttributeError` is raised.
.. cfunction:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v) .. cfunction:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
Set the value of the attribute named *attr_name*, for object *o*, to the value Set the value of the attribute named *attr_name*, for object *o*, to the value
@ -56,6 +66,16 @@ Object Protocol
``o.attr_name = v``. ``o.attr_name = v``.
.. cfunction:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
Generic attribute setter function that is meant to be put into a type
object's ``tp_setattro`` slot. It looks for a data descriptor in the
dictionary of classes in the object's MRO, and if found it takes preference
over setting the attribute in the instance dictionary. Otherwise, the
attribute is set in the object's :attr:`__dict__` (if present). Otherwise,
an :exc:`AttributeError` is raised and ``-1`` is returned.
.. cfunction:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name) .. cfunction:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure. Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.

2
Doc/c-api/structures.rst
View File

@ -241,7 +241,7 @@ definition with the same method name.
T_OBJECT_EX PyObject \* T_OBJECT_EX PyObject \*
T_CHAR char T_CHAR char
T_BYTE char T_BYTE char
T_UNBYTE unsigned char T_UBYTE unsigned char
T_UINT unsigned int T_UINT unsigned int
T_USHORT unsigned short T_USHORT unsigned short
T_ULONG unsigned long T_ULONG unsigned long

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

@ -38,6 +38,10 @@ the same library that the Python runtime is using.
interpreter exits due to an exception, or ``2`` if the parameter interpreter exits due to an exception, or ``2`` if the parameter
list does not represent a valid Python command line. list does not represent a valid Python command line.
Note that if an otherwise unhandled :exc:`SystemError` is raised, this
function will not return ``1``, but exit the process, as long as
``Py_InspectFlag`` is not set.
.. cfunction:: int PyRun_AnyFile(FILE *fp, const char *filename) .. cfunction:: int PyRun_AnyFile(FILE *fp, const char *filename)
@ -80,6 +84,10 @@ the same library that the Python runtime is using.
there was an error, there is no way to get the exception information. For the there was an error, there is no way to get the exception information. For the
meaning of *flags*, see below. meaning of *flags*, see below.
Note that if an otherwise unhandled :exc:`SystemError` is raised, this
function will not return ``-1``, but exit the process, as long as
``Py_InspectFlag`` is not set.
.. cfunction:: int PyRun_SimpleFile(FILE *fp, const char *filename) .. cfunction:: int PyRun_SimpleFile(FILE *fp, const char *filename)

20
Doc/distutils/apiref.rst
View File

@ -1050,8 +1050,8 @@ This module contains some utility functions for operating on individual files.
.. warning:: .. warning::
Handles cross-device moves on Unix using :func:`copy_file`. What about other Handles cross-device moves on Unix using :func:`copy_file`. What about
systems??? other systems?
.. function:: write_file(filename, contents) .. function:: write_file(filename, contents)
@ -1091,17 +1091,17 @@ other utility module.
For non-POSIX platforms, currently just returns ``sys.platform``. For non-POSIX platforms, currently just returns ``sys.platform``.
For MacOS X systems the OS version reflects the minimal version on which For Mac OS X systems the OS version reflects the minimal version on which
binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
during the build of Python), not the OS version of the current system. during the build of Python), not the OS version of the current system.
For universal binary builds on MacOS X the architecture value reflects For universal binary builds on Mac OS X the architecture value reflects
the univeral binary status instead of the architecture of the current the univeral binary status instead of the architecture of the current
processor. For 32-bit universal binaries the architecture is ``fat``, processor. For 32-bit universal binaries the architecture is ``fat``,
for 64-bit universal binaries the architecture is ``fat64``, and for 64-bit universal binaries the architecture is ``fat64``, and
for 4-way universal binaries the architecture is ``universal``. for 4-way universal binaries the architecture is ``universal``.
Examples of returned values on MacOS X: Examples of returned values on Mac OS X:
* ``macosx-10.3-ppc`` * ``macosx-10.3-ppc``
@ -1758,8 +1758,16 @@ This module supplies the abstract base class :class:`Command`.
.. module:: distutils.command.bdist_msi .. module:: distutils.command.bdist_msi
:synopsis: Build a binary distribution as a Windows MSI file :synopsis: Build a binary distribution as a Windows MSI file
.. class:: bdist_msi(Command)
.. % todo Builds a `Windows Installer`_ (.msi) binary package.
.. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
In most cases, the ``bdist_msi`` installer is a better choice than the
``bdist_wininst`` installer, because it provides better support for
Win64 platforms, allows administrators to perform non-interactive
installations, and allows installation through group policies.
:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM :mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM

25
Doc/extending/extending.rst
View File

@ -476,10 +476,10 @@ reference count of an object and are safe in the presence of *NULL* pointers
(but note that *temp* will not be *NULL* in this context). More info on them (but note that *temp* will not be *NULL* in this context). More info on them
in section :ref:`refcounts`. in section :ref:`refcounts`.
.. index:: single: PyEval_CallObject() .. index:: single: PyObject_CallObject()
Later, when it is time to call the function, you call the C function 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:`PyObject_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 in NULL, or arguments. To call the Python function with no arguments, pass in NULL, or
@ -495,16 +495,16 @@ or more format codes between parentheses. For example::
... ...
/* Time to call the callback */ /* Time to call the callback */
arglist = Py_BuildValue("(i)", arg); arglist = Py_BuildValue("(i)", arg);
result = PyEval_CallObject(my_callback, arglist); result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist); Py_DECREF(arglist);
:cfunc:`PyEval_CallObject` returns a Python object pointer: this is the return :cfunc:`PyObject_CallObject` returns a Python object pointer: this is the return
value of the Python function. :cfunc:`PyEval_CallObject` is value of the Python function. :cfunc:`PyObject_CallObject` is
"reference-count-neutral" with respect to its arguments. In the example a new "reference-count-neutral" with respect to its arguments. In the example a new
tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\ tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\
-ed immediately after the call. -ed immediately after the call.
The return value of :cfunc:`PyEval_CallObject` is "new": either it is a brand The return value of :cfunc:`PyObject_CallObject` is "new": either it is a brand
new object, or it is an existing object whose reference count has been new object, or it is an existing object whose reference count has been
incremented. So, unless you want to save it in a global variable, you should incremented. So, unless you want to save it in a global variable, you should
somehow :cfunc:`Py_DECREF` the result, even (especially!) if you are not somehow :cfunc:`Py_DECREF` the result, even (especially!) if you are not
@ -512,7 +512,7 @@ interested in its value.
Before you do this, however, it is important to check that the return value Before you do this, however, it is important to check that the return value
isn't *NULL*. If it is, the Python function terminated by raising an exception. isn't *NULL*. If it is, the Python function terminated by raising an exception.
If the C code that called :cfunc:`PyEval_CallObject` is called from Python, it If the C code that called :cfunc:`PyObject_CallObject` is called from Python, it
should now return an error indication to its Python caller, so the interpreter should now return an error indication to its Python caller, so the interpreter
can print a stack trace, or the calling Python code can handle the exception. can print a stack trace, or the calling Python code can handle the exception.
If this is not possible or desirable, the exception should be cleared by calling If this is not possible or desirable, the exception should be cleared by calling
@ -524,7 +524,7 @@ If this is not possible or desirable, the exception should be cleared by calling
Py_DECREF(result); Py_DECREF(result);
Depending on the desired interface to the Python callback function, you may also Depending on the desired interface to the Python callback function, you may also
have to provide an argument list to :cfunc:`PyEval_CallObject`. In some cases have to provide an argument list to :cfunc:`PyObject_CallObject`. In some cases
the argument list is also provided by the Python program, through the same the argument list is also provided by the Python program, through the same
interface that specified the callback function. It can then be saved and used interface that specified the callback function. It can then be saved and used
in the same manner as the function object. In other cases, you may have to in the same manner as the function object. In other cases, you may have to
@ -535,7 +535,7 @@ event code, you might use the following code::
PyObject *arglist; PyObject *arglist;
... ...
arglist = Py_BuildValue("(l)", eventcode); arglist = Py_BuildValue("(l)", eventcode);
result = PyEval_CallObject(my_callback, arglist); result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist); Py_DECREF(arglist);
if (result == NULL) if (result == NULL)
return NULL; /* Pass error back */ return NULL; /* Pass error back */
@ -547,19 +547,20 @@ 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 You may also call a function with keyword arguments by using
:cfunc:`PyEval_CallObjectWithKeywords`. As in the above example, we use :cfunc:`PyObject_Call`, which supports arguments and keyword arguments. As in
:cfunc:`Py_BuildValue` to construct the dictionary. :: the above example, we use :cfunc:`Py_BuildValue` to construct the dictionary. ::
PyObject *dict; PyObject *dict;
... ...
dict = Py_BuildValue("{s:i}", "name", val); dict = Py_BuildValue("{s:i}", "name", val);
result = PyEval_CallObjectWithKeywords(my_callback, NULL, dict); result = PyObject_Call(my_callback, NULL, dict);
Py_DECREF(dict); Py_DECREF(dict);
if (result == NULL) if (result == NULL)
return NULL; /* Pass error back */ return NULL; /* Pass error back */
/* Here maybe use the result */ /* Here maybe use the result */
Py_DECREF(result); Py_DECREF(result);
.. _parsetuple: .. _parsetuple:
Extracting Parameters in Extension Functions Extracting Parameters in Extension Functions

2
Doc/howto/cporting.rst
View File

@ -98,7 +98,7 @@ In Python 3.0, there is only one integer type. It is called :func:`int` on the
Python level, but actually corresponds to 2.x's :func:`long` type. In the Python level, but actually corresponds to 2.x's :func:`long` type. In the
C-API, ``PyInt_*`` functions are replaced by their ``PyLong_*`` neighbors. The C-API, ``PyInt_*`` functions are replaced by their ``PyLong_*`` neighbors. The
best course of action here is using the ``PyInt_*`` functions aliased to best course of action here is using the ``PyInt_*`` functions aliased to
``PyLong_*`` found in :file:`intobject.h`. The the abstract ``PyNumber_*`` APIs ``PyLong_*`` found in :file:`intobject.h`. The abstract ``PyNumber_*`` APIs
can also be used in some cases. :: can also be used in some cases. ::
#include "Python.h" #include "Python.h"

3
Doc/library/abc.rst
View File

@ -132,7 +132,7 @@ It also provides the following decorators:
A class that has a metaclass derived from :class:`ABCMeta` A class that has a metaclass derived from :class:`ABCMeta`
cannot be instantiated unless all of its abstract methods and cannot be instantiated unless all of its abstract methods and
properties are overridden. properties are overridden.
The abstract methods can be called using any of the the normal 'super' call The abstract methods can be called using any of the normal 'super' call
mechanisms. mechanisms.
Dynamically adding abstract methods to a class, or attempting to modify the Dynamically adding abstract methods to a class, or attempting to modify the
@ -184,6 +184,7 @@ It also provides the following decorators:
def setx(self, value): ... def setx(self, value): ...
x = abstractproperty(getx, setx) x = abstractproperty(getx, setx)
.. rubric:: Footnotes .. rubric:: Footnotes
.. [#] C++ programmers should note that Python's virtual base class .. [#] C++ programmers should note that Python's virtual base class

56
Doc/library/doctest.rst
View File

@ -905,7 +905,7 @@ There are two main functions for creating :class:`unittest.TestSuite` instances
from text files and modules with doctests: from text files and modules with doctests:
.. function:: DocFileSuite([module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding]) .. function:: DocFileSuite(*paths, [module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])
Convert doctest tests from one or more text files to a Convert doctest tests from one or more text files to a
:class:`unittest.TestSuite`. :class:`unittest.TestSuite`.
@ -923,45 +923,47 @@ from text files and modules with doctests:
Optional argument *module_relative* specifies how the filenames in *paths* Optional argument *module_relative* specifies how the filenames in *paths*
should be interpreted: should be interpreted:
* If *module_relative* is ``True`` (the default), then each filename specifies * If *module_relative* is ``True`` (the default), then each filename in
an OS-independent module-relative path. By default, this path is relative to *paths* specifies an OS-independent module-relative path. By default, this
the calling module's directory; but if the *package* argument is specified, then path is relative to the calling module's directory; but if the *package*
it is relative to that package. To ensure OS-independence, each filename should argument is specified, then it is relative to that package. To ensure
use ``/`` characters to separate path segments, and may not be an absolute path OS-independence, each filename should use ``/`` characters to separate path
(i.e., it may not begin with ``/``). segments, and may not be an absolute path (i.e., it may not begin with
``/``).
* If *module_relative* is ``False``, then each filename specifies an OS-specific * If *module_relative* is ``False``, then each filename in *paths* specifies
path. The path may be absolute or relative; relative paths are resolved with an OS-specific path. The path may be absolute or relative; relative paths
respect to the current working directory. are resolved with respect to the current working directory.
Optional argument *package* is a Python package or the name of a Python package Optional argument *package* is a Python package or the name of a Python
whose directory should be used as the base directory for module-relative package whose directory should be used as the base directory for
filenames. If no package is specified, then the calling module's directory is module-relative filenames in *paths*. If no package is specified, then the
used as the base directory for module-relative filenames. It is an error to calling module's directory is used as the base directory for module-relative
specify *package* if *module_relative* is ``False``. filenames. It is an error to specify *package* if *module_relative* is
``False``.
Optional argument *setUp* specifies a set-up function for the test suite. This Optional argument *setUp* specifies a set-up function for the test suite.
is called before running the tests in each file. The *setUp* function will be This is called before running the tests in each file. The *setUp* function
passed a :class:`DocTest` object. The setUp function can access the test
globals as the *globs* attribute of the test passed.
Optional argument *tearDown* specifies a tear-down function for the test suite.
This is called after running the tests in each file. The *tearDown* function
will be passed a :class:`DocTest` object. The setUp function can access the will be passed a :class:`DocTest` object. The setUp function can access the
test globals as the *globs* attribute of the test passed. test globals as the *globs* attribute of the test passed.
Optional argument *tearDown* specifies a tear-down function for the test
suite. This is called after running the tests in each file. The *tearDown*
function will be passed a :class:`DocTest` object. The setUp function can
access the test globals as the *globs* attribute of the test passed.
Optional argument *globs* is a dictionary containing the initial global Optional argument *globs* is a dictionary containing the initial global
variables for the tests. A new copy of this dictionary is created for each variables for the tests. A new copy of this dictionary is created for each
test. By default, *globs* is a new empty dictionary. test. By default, *globs* is a new empty dictionary.
Optional argument *optionflags* specifies the default doctest options for the Optional argument *optionflags* specifies the default doctest options for the
tests, created by or-ing together individual option flags. See section tests, created by or-ing together individual option flags. See section
:ref:`doctest-options`. See function :func:`set_unittest_reportflags` below for :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
a better way to set reporting options. for a better way to set reporting options.
Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that Optional argument *parser* specifies a :class:`DocTestParser` (or subclass)
should be used to extract tests from the files. It defaults to a normal parser that should be used to extract tests from the files. It defaults to a normal
(i.e., ``DocTestParser()``). parser (i.e., ``DocTestParser()``).
Optional argument *encoding* specifies an encoding that should be used to Optional argument *encoding* specifies an encoding that should be used to
convert the file to unicode. convert the file to unicode.

6
Doc/library/functions.rst
View File

@ -1163,9 +1163,11 @@ are always available. They are listed here in alphabetical order.
Without arguments, return a dictionary corresponding to the current local symbol Without arguments, return a dictionary corresponding to the current local symbol
table. With a module, class or class instance object as argument (or anything table. With a module, class or class instance object as argument (or anything
else that has a :attr:`__dict__` attribute), returns a dictionary corresponding else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
to the object's symbol table. The returned dictionary should not be modified: to the object's symbol table.
the effects on the corresponding symbol table are undefined. [#]_
.. warning::
The returned dictionary should not be modified:
the effects on the corresponding symbol table are undefined. [#]_
.. function:: zip(*iterables) .. function:: zip(*iterables)

2
Doc/library/itertools.rst
View File

@ -207,7 +207,7 @@ loops that truncate the stream.
Make an iterator that filters elements from *data* returning only those that Make an iterator that filters elements from *data* returning only those that
have a corresponding element in *selectors* that evaluates to ``True``. have a corresponding element in *selectors* that evaluates to ``True``.
Stops when either the *data* or *selectors* iterables have been exhausted. Stops when either the *data* or *selectors* iterables has been exhausted.
Equivalent to:: Equivalent to::
def compress(data, selectors): def compress(data, selectors):

4
Doc/library/logging.rst
View File

@ -2290,6 +2290,10 @@ needing to be done by its clients. It achieves this though using threading
locks; there is one lock to serialize access to the module's shared data, and locks; there is one lock to serialize access to the module's shared data, and
each handler also creates a lock to serialize access to its underlying I/O. each handler also creates a lock to serialize access to its underlying I/O.
If you are implementing asynchronous signal handlers using the :mod:`signal`
module, you may not be able to use logging from within such handlers. This is
because lock implementations in the :mod:`threading` module are not always
re-entrant, and so cannot be invoked from such signal handlers.
Configuration Configuration
------------- -------------

12
Doc/library/multiprocessing.rst
View File

@ -1537,8 +1537,8 @@ with the :class:`Pool` class.
.. method:: map(func, iterable[, chunksize]) .. method:: map(func, iterable[, chunksize])
A parallel equivalent of the :func:`map` builtin function, collecting the A parallel equivalent of the :func:`map` builtin function (it supports only
result in a list. It blocks till the whole result is ready. one *iterable* argument though). It blocks till the result is ready.
This method chops the iterable into a number of chunks which it submits to This method chops the iterable into a number of chunks which it submits to
the process pool as separate tasks. The (approximate) size of these the process pool as separate tasks. The (approximate) size of these
@ -1697,6 +1697,12 @@ authentication* using the :mod:`hmac` module.
*address* is the address to be used by the bound socket or named pipe of the *address* is the address to be used by the bound socket or named pipe of the
listener object. listener object.
.. note::
If an address of '0.0.0.0' is used, the address will not be a connectable
end point on Windows. If you require a connectable end-point,
you should use '127.0.0.1'.
*family* is the type of socket (or named pipe) to use. This can be one of *family* is the type of socket (or named pipe) to use. This can be one of
the strings ``'AF_INET'`` (for a TCP socket), ``'AF_UNIX'`` (for a Unix the strings ``'AF_INET'`` (for a TCP socket), ``'AF_UNIX'`` (for a Unix
domain socket) or ``'AF_PIPE'`` (for a Windows named pipe). Of these only domain socket) or ``'AF_PIPE'`` (for a Windows named pipe). Of these only
@ -1839,7 +1845,7 @@ return value of ``current_process().authkey`` is used (see
any :class:`~multiprocessing.Process` object that the current process creates. any :class:`~multiprocessing.Process` object that the current process creates.
This means that (by default) all processes of a multi-process program will share This means that (by default) all processes of a multi-process program will share
a single authentication key which can be used when setting up connections a single authentication key which can be used when setting up connections
between the themselves. between themselves.
Suitable authentication keys can also be generated by using :func:`os.urandom`. Suitable authentication keys can also be generated by using :func:`os.urandom`.

24
Doc/library/os.path.rst
View File

@ -1,11 +1,9 @@
:mod:`os.path` --- Common pathname manipulations :mod:`os.path` --- Common pathname manipulations
================================================ ================================================
.. module:: os.path .. module:: os.path
:synopsis: Operations on pathnames. :synopsis: Operations on pathnames.
.. index:: single: path; operations .. index:: single: path; operations
This module implements some useful functions on pathnames. To read or This module implements some useful functions on pathnames. To read or
@ -31,6 +29,22 @@ applications should use string objects to access all files.
:func:`splitunc` and :func:`ismount` do handle them correctly. :func:`splitunc` and :func:`ismount` do handle them correctly.
.. note::
Since different operating systems have different path name conventions, there
are several versions of this module in the standard library. The
:mod:`os.path` module is always the path module suitable for the operating
system Python is running on, and therefore usable for local paths. However,
you can also import and use the individual modules if you want to manipulate
a path that is *always* in one of the different formats. They all have the
same interface:
* :mod:`posixpath` for UNIX-style paths
* :mod:`ntpath` for Windows paths
* :mod:`macpath` for old-style MacOS paths
* :mod:`os2emxpath` for OS/2 EMX paths
.. function:: abspath(path) .. function:: abspath(path)
Return a normalized absolutized version of the pathname *path*. On most Return a normalized absolutized version of the pathname *path*. On most
@ -189,9 +203,9 @@ applications should use string objects to access all files.
.. function:: normcase(path) .. function:: normcase(path)
Normalize the case of a pathname. On Unix and MacOSX, this returns the path unchanged; on Normalize the case of a pathname. On Unix and Mac OS X, this returns the
case-insensitive filesystems, it converts the path to lowercase. On Windows, it path unchanged; on case-insensitive filesystems, it converts the path to
also converts forward slashes to backward slashes. lowercase. On Windows, it also converts forward slashes to backward slashes.
.. function:: normpath(path) .. function:: normpath(path)

13
Doc/library/os.rst
View File

@ -51,15 +51,6 @@ the :mod:`os` module, but using them is of course a threat to portability!
``'ce'``, ``'java'``. ``'ce'``, ``'java'``.
.. data:: path
The corresponding operating system dependent standard module for pathname
operations, such as :mod:`posixpath` or :mod:`ntpath`. Thus, given the proper
imports, ``os.path.split(file)`` is equivalent to but more portable than
``posixpath.split(file)``. Note that this is also an importable module: it may
be imported directly as :mod:`os.path`.
.. _os-procinfo: .. _os-procinfo:
Process Parameters Process Parameters
@ -1491,7 +1482,9 @@ written in Python, such as a mail server's external command delivery program.
which is used to define the environment variables for the new process (they are which is used to define the environment variables for the new process (they are
used instead of the current process' environment); the functions used instead of the current process' environment); the functions
:func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
the new process to inherit the environment of the current process. the new process to inherit the environment of the current process. Note that
keys and values in the *env* dictionary must be strings; invalid keys or
values will cause the function to fail, with a return value of ``127``.
As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
equivalent:: equivalent::

2
Doc/library/pdb.rst
View File

@ -262,7 +262,7 @@ n(ext)
full speed, only stopping at the next line in the current function.) full speed, only stopping at the next line in the current function.)
unt(il) unt(il)
Continue execution until the line with the the line number greater than the Continue execution until the line with the line number greater than the
current one is reached or when returning from current frame. current one is reached or when returning from current frame.
r(eturn) r(eturn)

8
Doc/library/pickle.rst
View File

@ -436,6 +436,14 @@ items are assigned to the new instance's dictionary.
Refer to the section :ref:`pickle-state` for more information about how to use Refer to the section :ref:`pickle-state` for more information about how to use
the methods :meth:`__getstate__` and :meth:`__setstate__`. the methods :meth:`__getstate__` and :meth:`__setstate__`.
.. note::
At unpickling time, some methods like :meth:`__getattr__`,
:meth:`__getattribute__`, or :meth:`__setattr__` may be called upon the
instance. In case those methods rely on some internal invariant being
true, the type should implement either :meth:`__getinitargs__` or
:meth:`__getnewargs__` to establish such an invariant; otherwise, neither
:meth:`__new__` nor :meth:`__init__` will be called.
.. index:: .. index::
pair: copy; protocol pair: copy; protocol
single: __reduce__() (copy protocol) single: __reduce__() (copy protocol)

24
Doc/library/re.rst
View File

@ -8,10 +8,9 @@
.. sectionauthor:: Andrew M. Kuchling <amk@amk.ca> .. sectionauthor:: Andrew M. Kuchling <amk@amk.ca>
This module provides regular expression matching operations similar to This module provides regular expression matching operations similar to
those found in Perl. The :mod:`re` module is always available. those found in Perl. Both patterns and strings to be searched can be
Unicode strings as well as 8-bit strings.
Both patterns and strings to be searched can be Unicode strings as well as Both patterns and strings to be searched can be Unicode strings as well as
8-bit strings. However, Unicode strings and 8-bit strings cannot be mixed: 8-bit strings. However, Unicode strings and 8-bit strings cannot be mixed:
@ -47,9 +46,6 @@ fine-tuning parameters.
second edition of the book no longer covers Python at all, but the first second edition of the book no longer covers Python at all, but the first
edition covered writing good regular expression patterns in great detail. edition covered writing good regular expression patterns in great detail.
`Kodos <http://kodos.sf.net/>`_
is a graphical regular expression debugger written in Python.
.. _re-syntax: .. _re-syntax:
@ -241,16 +237,18 @@ The special characters are:
``(?P<name>...)`` ``(?P<name>...)``
Similar to regular parentheses, but the substring matched by the group is Similar to regular parentheses, but the substring matched by the group is
accessible via the symbolic group name *name*. Group names must be valid Python accessible within the rest of the regular expression via the symbolic group
identifiers, and each group name must be defined only once within a regular name *name*. Group names must be valid Python identifiers, and each group
expression. A symbolic group is also a numbered group, just as if the group name must be defined only once within a regular expression. A symbolic group
were not named. So the group named 'id' in the example below can also be is also a numbered group, just as if the group were not named. So the group
referenced as the numbered group 1. named ``id`` in the example below can also be referenced as the numbered group
``1``.
For example, if the pattern is ``(?P<id>[a-zA-Z_]\w*)``, the group can be For example, if the pattern is ``(?P<id>[a-zA-Z_]\w*)``, the group can be
referenced by its name in arguments to methods of match objects, such as referenced by its name in arguments to methods of match objects, such as
``m.group('id')`` or ``m.end('id')``, and also by name in pattern text (for ``m.group('id')`` or ``m.end('id')``, and also by name in the regular
example, ``(?P=id)``) and replacement text (such as ``\g<id>``). expression itself (using ``(?P=id)``) and replacement text given to
``.sub()`` (using ``\g<id>``).
``(?P=name)`` ``(?P=name)``
Matches whatever text was matched by the earlier group named *name*. Matches whatever text was matched by the earlier group named *name*.

2
Doc/library/shelve.rst
View File

@ -141,7 +141,7 @@ object)::
# as d was opened WITHOUT writeback=True, beware: # as d was opened WITHOUT writeback=True, beware:
d['xx'] = range(4) # this works as expected, but... d['xx'] = range(4) # this works as expected, but...
d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!!! d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!
# having opened d without writeback=True, you need to code carefully: # having opened d without writeback=True, you need to code carefully:
temp = d['xx'] # extracts the copy temp = d['xx'] # extracts the copy

61
Doc/library/socketserver.rst
View File

@ -122,15 +122,21 @@ another way to manage this.
Server Objects Server Objects
-------------- --------------
.. class:: BaseServer
.. function:: fileno() This is the superclass of all Server objects in the module. It defines the
interface, given below, but does not implement most of the methods, which is
done in subclasses.
.. method:: BaseServer.fileno()
Return an integer file descriptor for the socket on which the server is Return an integer file descriptor for the socket on which the server is
listening. This function is most commonly passed to :func:`select.select`, to listening. This function is most commonly passed to :func:`select.select`, to
allow monitoring multiple servers in the same process. allow monitoring multiple servers in the same process.
.. function:: handle_request() .. method:: BaseServer.handle_request()
Process a single request. This function calls the following methods in Process a single request. This function calls the following methods in
order: :meth:`get_request`, :meth:`verify_request`, and order: :meth:`get_request`, :meth:`verify_request`, and
@ -141,30 +147,30 @@ Server Objects
will return. will return.
.. function:: serve_forever(poll_interval=0.5) .. method:: BaseServer.serve_forever(poll_interval=0.5)
Handle requests until an explicit :meth:`shutdown` request. Polls for Handle requests until an explicit :meth:`shutdown` request. Polls for
shutdown every *poll_interval* seconds. shutdown every *poll_interval* seconds.
.. function:: shutdown() .. method:: BaseServer.shutdown()
Tells the :meth:`serve_forever` loop to stop and waits until it does. Tells the :meth:`serve_forever` loop to stop and waits until it does.
.. data:: address_family .. attribute:: BaseServer.address_family
The family of protocols to which the server's socket belongs. The family of protocols to which the server's socket belongs.
Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`. Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.
.. data:: RequestHandlerClass .. attribute:: BaseServer.RequestHandlerClass
The user-provided request handler class; an instance of this class is created The user-provided request handler class; an instance of this class is created
for each request. for each request.
.. data:: server_address .. attribute:: BaseServer.server_address
The address on which the server is listening. The format of addresses varies The address on which the server is listening. The format of addresses varies
depending on the protocol family; see the documentation for the socket module depending on the protocol family; see the documentation for the socket module
@ -172,22 +178,22 @@ Server Objects
the address, and an integer port number: ``('127.0.0.1', 80)``, for example. the address, and an integer port number: ``('127.0.0.1', 80)``, for example.
.. data:: socket .. attribute:: BaseServer.socket
The socket object on which the server will listen for incoming requests. The socket object on which the server will listen for incoming requests.
The server classes support the following class variables: The server classes support the following class variables:
.. XXX should class variables be covered before instance variables, or vice versa? .. XXX should class variables be covered before instance variables, or vice versa?
.. attribute:: BaseServer.allow_reuse_address
.. data:: allow_reuse_address
Whether the server will allow the reuse of an address. This defaults to Whether the server will allow the reuse of an address. This defaults to
:const:`False`, and can be set in subclasses to change the policy. :const:`False`, and can be set in subclasses to change the policy.
.. data:: request_queue_size .. attribute:: BaseServer.request_queue_size
The size of the request queue. If it takes a long time to process a single The size of the request queue. If it takes a long time to process a single
request, any requests that arrive while the server is busy are placed into a request, any requests that arrive while the server is busy are placed into a
@ -196,17 +202,19 @@ The server classes support the following class variables:
value is usually 5, but this can be overridden by subclasses. value is usually 5, but this can be overridden by subclasses.
.. data:: socket_type .. attribute:: BaseServer.socket_type
The type of socket used by the server; :const:`socket.SOCK_STREAM` and The type of socket used by the server; :const:`socket.SOCK_STREAM` and
:const:`socket.SOCK_DGRAM` are two common values. :const:`socket.SOCK_DGRAM` are two common values.
.. data:: timeout
.. attribute:: BaseServer.timeout
Timeout duration, measured in seconds, or :const:`None` if no timeout is Timeout duration, measured in seconds, or :const:`None` if no timeout is
desired. If :meth:`handle_request` receives no incoming requests within the desired. If :meth:`handle_request` receives no incoming requests within the
timeout period, the :meth:`handle_timeout` method is called. timeout period, the :meth:`handle_timeout` method is called.
There are various server methods that can be overridden by subclasses of base There are various server methods that can be overridden by subclasses of base
server classes like :class:`TCPServer`; these methods aren't useful to external server classes like :class:`TCPServer`; these methods aren't useful to external
users of the server object. users of the server object.
@ -214,27 +222,27 @@ users of the server object.
.. XXX should the default implementations of these be documented, or should .. XXX should the default implementations of these be documented, or should
it be assumed that the user will look at socketserver.py? it be assumed that the user will look at socketserver.py?
.. method:: BaseServer.finish_request()
.. function:: finish_request()
Actually processes the request by instantiating :attr:`RequestHandlerClass` and Actually processes the request by instantiating :attr:`RequestHandlerClass` and
calling its :meth:`handle` method. calling its :meth:`handle` method.
.. function:: get_request() .. method:: BaseServer.get_request()
Must accept a request from the socket, and return a 2-tuple containing the *new* Must accept a request from the socket, and return a 2-tuple containing the *new*
socket object to be used to communicate with the client, and the client's socket object to be used to communicate with the client, and the client's
address. address.
.. function:: handle_error(request, client_address) .. method:: BaseServer.handle_error(request, client_address)
This function is called if the :attr:`RequestHandlerClass`'s :meth:`handle` This function is called if the :attr:`RequestHandlerClass`'s :meth:`handle`
method raises an exception. The default action is to print the traceback to method raises an exception. The default action is to print the traceback to
standard output and continue handling further requests. standard output and continue handling further requests.
.. function:: handle_timeout()
.. method:: BaseServer.handle_timeout()
This function is called when the :attr:`timeout` attribute has been set to a This function is called when the :attr:`timeout` attribute has been set to a
value other than :const:`None` and the timeout period has passed with no value other than :const:`None` and the timeout period has passed with no
@ -242,31 +250,32 @@ users of the server object.
to collect the status of any child processes that have exited, while to collect the status of any child processes that have exited, while
in threading servers this method does nothing. in threading servers this method does nothing.
.. function:: process_request(request, client_address)
.. method:: BaseServer.process_request(request, client_address)
Calls :meth:`finish_request` to create an instance of the Calls :meth:`finish_request` to create an instance of the
:attr:`RequestHandlerClass`. If desired, this function can create a new process :attr:`RequestHandlerClass`. If desired, this function can create a new process
or thread to handle the request; the :class:`ForkingMixIn` and or thread to handle the request; the :class:`ForkingMixIn` and
:class:`ThreadingMixIn` classes do this. :class:`ThreadingMixIn` classes do this.
.. Is there any point in documenting the following two functions? .. Is there any point in documenting the following two functions?
What would the purpose of overriding them be: initializing server What would the purpose of overriding them be: initializing server
instance variables, adding new network families? instance variables, adding new network families?
.. method:: BaseServer.server_activate()
.. function:: server_activate()
Called by the server's constructor to activate the server. The default behavior Called by the server's constructor to activate the server. The default behavior
just :meth:`listen`\ s to the server's socket. May be overridden. just :meth:`listen`\ s to the server's socket. May be overridden.
.. function:: server_bind() .. method:: BaseServer.server_bind()
Called by the server's constructor to bind the socket to the desired address. Called by the server's constructor to bind the socket to the desired address.
May be overridden. May be overridden.
.. function:: verify_request(request, client_address) .. method:: BaseServer.verify_request(request, client_address)
Must return a Boolean value; if the value is :const:`True`, the request will be Must return a Boolean value; if the value is :const:`True`, the request will be
processed, and if it's :const:`False`, the request will be denied. This function processed, and if it's :const:`False`, the request will be denied. This function
@ -282,14 +291,14 @@ override any of the following methods. A new instance is created for each
request. request.
.. function:: finish() .. method:: RequestHandler.finish()
Called after the :meth:`handle` method to perform any clean-up actions Called after the :meth:`handle` method to perform any clean-up actions
required. The default implementation does nothing. If :meth:`setup` or required. The default implementation does nothing. If :meth:`setup` or
:meth:`handle` raise an exception, this function will not be called. :meth:`handle` raise an exception, this function will not be called.
.. function:: handle() .. method:: RequestHandler.handle()
This function must do all the work required to service a request. The This function must do all the work required to service a request. The
default implementation does nothing. Several instance attributes are default implementation does nothing. Several instance attributes are
@ -308,7 +317,7 @@ request.
data or return data to the client. data or return data to the client.
.. function:: setup() .. method:: RequestHandler.setup()
Called before the :meth:`handle` method to perform any initialization actions Called before the :meth:`handle` method to perform any initialization actions
required. The default implementation does nothing. required. The default implementation does nothing.

2
Doc/library/ssl.rst
View File

@ -293,7 +293,7 @@ SSLSocket Objects
If there is no certificate for the peer on the other end of the If there is no certificate for the peer on the other end of the
connection, returns ``None``. connection, returns ``None``.
If the the parameter ``binary_form`` is :const:`False`, and a If the parameter ``binary_form`` is :const:`False`, and a
certificate was received from the peer, this method returns a certificate was received from the peer, this method returns a
:class:`dict` instance. If the certificate was not validated, the :class:`dict` instance. If the certificate was not validated, the
dict is empty. If the certificate was validated, it returns a dict dict is empty. If the certificate was validated, it returns a dict

28
Doc/library/stdtypes.rst
View File

@ -1834,6 +1834,11 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
Equivalent to ``not key in d``. Equivalent to ``not key in d``.
.. describe:: iter(d)
Return an iterator over the keys of the dictionary. This is a shortcut
for :meth:`iterkeys`.
.. method:: clear() .. method:: clear()
Remove all items from the dictionary. Remove all items from the dictionary.
@ -1931,6 +1936,9 @@ support membership tests:
using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to
create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``. create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``.
Iterating views while adding or deleting entries in the dictionary will raise
a :exc:`RuntimeError`.
.. describe:: x in dictview .. describe:: x in dictview
Return ``True`` if *x* is in the underlying dictionary's keys, values or Return ``True`` if *x* is in the underlying dictionary's keys, values or
@ -2666,10 +2674,26 @@ types, where they are relevant. Some of these are not reported by the
The name of the class or type. The name of the class or type.
The following attributes are only supported by :term:`new-style class`\ es.
.. attribute:: class.__mro__
This attribute is a tuple of classes that are considered when looking for
base classes during method resolution.
.. method:: class.mro()
This method can be overridden by a metaclass to customize the method
resolution order for its instances. It is called at class instantiation, and
its result is stored in :attr:`__mro__`.
.. method:: class.__subclasses__ .. method:: class.__subclasses__
All classes keep a list of weak references to their immediate subclasses. Each new-style class keeps a list of weak references to its immediate
This method returns a list of all those references still alive. Example:: subclasses. This method returns a list of all those references still alive.
Example::
>>> int.__subclasses__() >>> int.__subclasses__()
[<type 'bool'>] [<type 'bool'>]

20
Doc/library/sys.rst
View File

@ -780,16 +780,20 @@ always available.
__stderr__ __stderr__
These objects contain the original values of ``stdin``, ``stderr`` and These objects contain the original values of ``stdin``, ``stderr`` and
``stdout`` at the start of the program. They are used during finalization, and ``stdout`` at the start of the program. They are used during finalization,
could be useful to restore the actual files to known working file objects in and could be useful to print to the actual standard stream no matter if the
case they have been overwritten with a broken object. ``sys.std*`` object has been redirected.
.. note:: It can also be used to restore the actual files to known working file objects
in case they have been overwritten with a broken object. However, the
preferred way to do this is to explicitly save the previous stream before
replacing it, and restore the saved object.
Under some conditions ``stdin``, ``stdout`` and ``stderr`` as well as the .. note::
original values ``__stdin__``, ``__stdout__`` and ``__stderr__`` can be Under some conditions ``stdin``, ``stdout`` and ``stderr`` as well as the
None. It is usually the case for Windows GUI apps that aren't connected to original values ``__stdin__``, ``__stdout__`` and ``__stderr__`` can be
a console and Python apps started with :program:`pythonw`. None. It is usually the case for Windows GUI apps that aren't connected
to a console and Python apps started with :program:`pythonw`.
.. data:: tracebacklimit .. data:: tracebacklimit

12
Doc/library/threading.rst
View File

@ -676,14 +676,20 @@ An event object manages an internal flag that can be set to true with the
.. method:: Event.wait([timeout]) .. method:: Event.wait([timeout])
Block until the internal flag is true. If the internal flag is true on entry, Block until the internal flag is true. If the internal flag is true on entry,
return immediately. Otherwise, block until another thread calls :meth:`set` to return immediately. Otherwise, block until another thread calls :meth:`set`
set the flag to true, or until the optional timeout occurs. to set the flag to true, or until the optional timeout occurs.
When the timeout argument is present and not ``None``, it should be a floating When the timeout argument is present and not ``None``, it should be a floating
point number specifying a timeout for the operation in seconds (or fractions point number specifying a timeout for the operation in seconds (or fractions
thereof). thereof).
This method returns the internal flag on exit, so it will always return
``True`` except if a timeout is given and the operation times out.
.. versionchanged:: 2.7
Previously, the method always returned ``None``.
.. _timer-objects: .. _timer-objects:

145
Doc/library/tkinter.ttk.rst
View File

@ -249,7 +249,7 @@ an exclamation point indicating that the bit is off.
ttk.Widget ttk.Widget
^^^^^^^^^^ ^^^^^^^^^^
Besides the methods described below, the class :class:`ttk.Widget` supports the Besides the methods described below, the :class:`ttk.Widget` supports the
methods :meth:`tkinter.Widget.cget` and :meth:`tkinter.Widget.configure`. methods :meth:`tkinter.Widget.cget` and :meth:`tkinter.Widget.configure`.
.. class:: Widget .. class:: Widget
@ -484,7 +484,7 @@ ttk.Notebook
The tab will not be displayed, but the associated window remains The tab will not be displayed, but the associated window remains
managed by the notebook and its configuration remembered. Hidden tabs managed by the notebook and its configuration remembered. Hidden tabs
may be restored with the add command. may be restored with the :meth:`add` command.
.. method:: identify(x, y) .. method:: identify(x, y)
@ -503,7 +503,7 @@ ttk.Notebook
Inserts a pane at the specified position. Inserts a pane at the specified position.
*pos* is either the string end, an integer index, or the name of a *pos* is either the string "end", an integer index, or the name of a
managed child. If *child* is already managed by the notebook, moves it to managed child. If *child* is already managed by the notebook, moves it to
the specified position. the specified position.
@ -523,7 +523,7 @@ ttk.Notebook
Query or modify the options of the specific *tab_id*. Query or modify the options of the specific *tab_id*.
If *kw* is not given, returns a dict of the tab option values. If If *kw* is not given, returns a dictionary of the tab option values. If
*option* is specified, returns the value of that *option*. Otherwise, *option* is specified, returns the value of that *option*. Otherwise,
sets the options to the corresponding values. sets the options to the corresponding values.
@ -540,14 +540,14 @@ ttk.Notebook
This will extend the bindings for the toplevel window containing the This will extend the bindings for the toplevel window containing the
notebook as follows: notebook as follows:
* Control-Tab: selects the tab following the currently selected one * Control-Tab: selects the tab following the currently selected one.
* Shift-Control-Tab: selects the tab preceding the currently selected one * Shift-Control-Tab: selects the tab preceding the currently selected one.
* Alt-K: where K is the mnemonic (underlined) character of any tab, will * Alt-K: where K is the mnemonic (underlined) character of any tab, will
select that tab. select that tab.
Multiple notebooks in a single toplevel may be enabled for traversal, Multiple notebooks in a single toplevel may be enabled for traversal,
including nested notebooks. However, notebook traversal only works including nested notebooks. However, notebook traversal only works
properly if all panes have as master the notebook they are in. properly if all panes have the notebook they are in as master.
Progressbar Progressbar
@ -580,12 +580,12 @@ This widget accepts the following specific options:
+----------+---------------------------------------------------------------+ +----------+---------------------------------------------------------------+
| value | The current value of the progress bar. In "determinate" mode, | | value | The current value of the progress bar. In "determinate" mode, |
| | this represents the amount of work completed. In | | | this represents the amount of work completed. In |
| | "indeterminate" mode, it is interpreted as modulo maximum; | | | "indeterminate" mode, it is interpreted as modulo *maximum*; |
| | that is, the progress bar completes one "cycle" when its value| | | that is, the progress bar completes one "cycle" when its value|
| | increases by maximum. | | | increases by *maximum*. |
+----------+---------------------------------------------------------------+ +----------+---------------------------------------------------------------+
| variable | A name which is linked to the option value. If specified, the | | variable | A name which is linked to the option value. If specified, the |
| | value of the progressbar is automatically set to the value of | | | value of the progress bar is automatically set to the value of|
| | this name whenever the latter is modified. | | | this name whenever the latter is modified. |
+----------+---------------------------------------------------------------+ +----------+---------------------------------------------------------------+
| phase | Read-only option. The widget periodically increments the value| | phase | Read-only option. The widget periodically increments the value|
@ -602,14 +602,14 @@ ttk.Progressbar
.. method:: start([interval]) .. method:: start([interval])
Begin autoincrement mode: schedules a recurring timer even that calls Begin autoincrement mode: schedules a recurring timer event that calls
:meth:`Progressbar.step` every *interval* milliseconds. If omitted, :meth:`Progressbar.step` every *interval* milliseconds. If omitted,
*interval* defaults to 50 milliseconds. *interval* defaults to 50 milliseconds.
.. method:: step([amount]) .. method:: step([amount])
Increments progressbar's value by *amount*. Increments the progress bar's value by *amount*.
*amount* defaults to 1.0 if omitted. *amount* defaults to 1.0 if omitted.
@ -617,7 +617,7 @@ ttk.Progressbar
.. method:: stop() .. method:: stop()
Stop autoincrement mode: cancels any recurring timer event initiated by Stop autoincrement mode: cancels any recurring timer event initiated by
:meth:`Progressbar.start` for this progressbar. :meth:`Progressbar.start` for this progress bar.
Separator Separator
@ -626,7 +626,7 @@ Separator
The :class:`ttk.Separator` widget displays a horizontal or vertical separator The :class:`ttk.Separator` widget displays a horizontal or vertical separator
bar. bar.
It has no other method besides the ones inherited from :class:`ttk.Widget`. It has no other methods besides the ones inherited from :class:`ttk.Widget`.
Options Options
@ -645,18 +645,18 @@ This widget accepts the following specific option:
Sizegrip Sizegrip
-------- --------
The :class:`ttk.Sizegrip` widget (also known as grow box) allows the user to The :class:`ttk.Sizegrip` widget (also known as a grow box) allows the user to
resize the containing toplevel window by pressing and dragging the grip. resize the containing toplevel window by pressing and dragging the grip.
This widget has no specific options neither specific methods, besides the This widget has neither specific options nor specific methods, besides the
ones inherited from :class:`ttk.Widget`. ones inherited from :class:`ttk.Widget`.
Platform-specific notes Platform-specific notes
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
* On Mac OSX, toplevel windows automatically include a built-in size grip * On MacOS X, toplevel windows automatically include a built-in size grip
by default. Adding a Sizegrip there is harmless, since the built-in by default. Adding a :class:`Sizegrip` is harmless, since the built-in
grip will just mask the widget. grip will just mask the widget.
@ -664,8 +664,8 @@ Bugs
^^^^ ^^^^
* If the containing toplevel's position was specified relative to the right * If the containing toplevel's position was specified relative to the right
or bottom of the screen (e.g. ....), the Sizegrip widget will not resize or bottom of the screen (e.g. ....), the :class:`Sizegrip` widget will
the window. not resize the window.
* This widget supports only "southeast" resizing. * This widget supports only "southeast" resizing.
@ -678,16 +678,16 @@ values. The data values are displayed in successive columns after the tree
label. label.
The order in which data values are displayed may be controlled by setting The order in which data values are displayed may be controlled by setting
the widget option displaycolumns. The tree widget can also display column the widget option ``displaycolumns``. The tree widget can also display column
headings. Columns may be accessed by number or symbolic names listed in the headings. Columns may be accessed by number or symbolic names listed in the
widget option columns. See `Column Identifiers`_. widget option columns. See `Column Identifiers`_.
Each item is identified by an unique name. The widget will generate item IDs Each item is identified by an unique name. The widget will generate item IDs
if they are not supplied by the caller. There is a distinguished root item, if they are not supplied by the caller. There is a distinguished root item,
named {}. The root item itself is not displayed; its children appear at the named ``{}``. The root item itself is not displayed; its children appear at the
top level of the hierarchy. top level of the hierarchy.
Each item also has a list of tags, which can be used to associate even bindings Each item also has a list of tags, which can be used to associate event bindings
with individual items and control the appearance of the item. with individual items and control the appearance of the item.
The Treeview widget supports horizontal and vertical scrolling, according to The Treeview widget supports horizontal and vertical scrolling, according to
@ -698,7 +698,7 @@ the options described in `Scrollable Widget Options`_ and the methods
Options Options
^^^^^^^ ^^^^^^^
This widget accepts the following specific option: This widget accepts the following specific options:
+----------------+--------------------------------------------------------+ +----------------+--------------------------------------------------------+
| option | description | | option | description |
@ -726,8 +726,8 @@ This widget accepts the following specific option:
| | be changed. | | | be changed. |
| | | | | |
| | Note that the application code and tag bindings can set| | | Note that the application code and tag bindings can set|
| | the selection however they wish, regardless the value | | | the selection however they wish, regardless of the |
| | of this option. | | | value of this option. |
+----------------+--------------------------------------------------------+ +----------------+--------------------------------------------------------+
| show | A list containing zero or more of the following values,| | show | A list containing zero or more of the following values,|
| | specifying which elements of the tree to display. | | | specifying which elements of the tree to display. |
@ -738,7 +738,7 @@ This widget accepts the following specific option:
| | The default is "tree headings", i.e., show all | | | The default is "tree headings", i.e., show all |
| | elements. | | | elements. |
| | | | | |
| | **Note**: Column #0 always refer to the tree column, | | | **Note**: Column #0 always refers to the tree column, |
| | even if show="tree" is not specified. | | | even if show="tree" is not specified. |
+----------------+--------------------------------------------------------+ +----------------+--------------------------------------------------------+
@ -858,11 +858,11 @@ ttk.Treeview
.. method:: set_children(item, *newchildren) .. method:: set_children(item, *newchildren)
Replaces item's child with *newchildren*. Replaces *item*'s child with *newchildren*.
Children present in item that are not present in *newchildren* are Children present in *item* that are not present in *newchildren* are
detached from tree. No items in *newchildren* may be an ancestor of detached from the tree. No items in *newchildren* may be an ancestor of
item. Note that not specifying *newchildren* results in detaching *item*. Note that not specifying *newchildren* results in detaching
*item*'s children. *item*'s children.
@ -877,16 +877,16 @@ ttk.Treeview
The valid options/values are: The valid options/values are:
* id * id
Returns the column name, this is a read-only option. Returns the column name. This is a read-only option.
* anchor: One of the standard Tk anchor values. * anchor: One of the standard Tk anchor values.
Specifies how the text in this column should be aligned with respect Specifies how the text in this column should be aligned with respect
to the cell. to the cell.
* minwidth: width * minwidth: width
The minimum width of the column in pixels. The treeview widget will The minimum width of the column in pixels. The treeview widget will
not make the column any smaller than the specified by this option when not make the column any smaller than specified by this option when
the widget is resized or the user drags a column. the widget is resized or the user drags a column.
* stretch: True/False * stretch: True/False
Specifies wheter or not the column's width should be adjusted when Specifies whether the column's width should be adjusted when
the widget is resized. the widget is resized.
* width: width * width: width
The width of the column in pixels. The width of the column in pixels.
@ -912,8 +912,7 @@ ttk.Treeview
.. method:: exists(item) .. method:: exists(item)
Returns True if the specified *item* is present in the three, Returns True if the specified *item* is present in the tree.
False otherwise.
.. method:: focus([item=None]) .. method:: focus([item=None])
@ -942,7 +941,7 @@ ttk.Treeview
* command: callback * command: callback
A callback to be invoked when the heading label is pressed. A callback to be invoked when the heading label is pressed.
To configure the tree column heading, call this with column = "#0" To configure the tree column heading, call this with column = "#0".
.. method:: identify(component, x, y) .. method:: identify(component, x, y)
@ -985,7 +984,7 @@ ttk.Treeview
.. method:: identify_element(x, y) .. method:: identify_element(x, y)
Returns the element at position x, y. Returns the element at position *x*, *y*.
Availability: Tk 8.6. Availability: Tk 8.6.
@ -997,16 +996,16 @@ ttk.Treeview
.. method:: insert(parent, index[, iid=None[, **kw]]) .. method:: insert(parent, index[, iid=None[, **kw]])
Creates a new item and return the item identifier of the newly created Creates a new item and returns the item identifier of the newly created
item. item.
*parent* is the item ID of the parent item, or the empty string to create *parent* is the item ID of the parent item, or the empty string to create
a new top-level item. *index* is an integer, or the value "end", a new top-level item. *index* is an integer, or the value "end",
specifying where in the list of parent's children to insert the new item. specifying where in the list of parent's children to insert the new item.
If *index* is less than or equal to zero, the new node is inserted at If *index* is less than or equal to zero, the new node is inserted at
the beginning, if *index* is greater than or equal to the current number the beginning; if *index* is greater than or equal to the current number
of children, it is inserted at the end. If *iid* is specified, it is used of children, it is inserted at the end. If *iid* is specified, it is used
as the item identifier, *iid* must not already exist in the tree. as the item identifier; *iid* must not already exist in the tree.
Otherwise, a new unique identifier is generated. Otherwise, a new unique identifier is generated.
See `Item Options`_ for the list of available points. See `Item Options`_ for the list of available points.
@ -1026,9 +1025,9 @@ ttk.Treeview
Moves *item* to position *index* in *parent*'s list of children. Moves *item* to position *index* in *parent*'s list of children.
It is illegal to move an item under one of its descendants. If index is It is illegal to move an item under one of its descendants. If *index* is
less than or equal to zero, item is moved to the beginning, if greater less than or equal to zero, *item* is moved to the beginning; if greater
than or equal to the number of children, it is moved to the end. If item than or equal to the number of children, it is moved to the end. If *item*
was detached it is reattached. was detached it is reattached.
@ -1101,7 +1100,7 @@ ttk.Treeview
.. method:: tag_bind(tagname[, sequence=None[, callback=None]]) .. method:: tag_bind(tagname[, sequence=None[, callback=None]])
Bind a callback for the given event *sequence* to the tag *tagname*. Bind a callback for the given event *sequence* to the tag *tagname*.
When an event is delivered to an item, the *callbacks* for each of the When an event is delivered to an item, the callbacks for each of the
item's tags option are called. item's tags option are called.
@ -1119,7 +1118,7 @@ ttk.Treeview
If *item* is specified, returns 1 or 0 depending on whether the specified If *item* is specified, returns 1 or 0 depending on whether the specified
*item* has the given *tagname*. Otherwise, returns a list of all items *item* has the given *tagname*. Otherwise, returns a list of all items
which have the specified tag. that have the specified tag.
Availability: Tk 8.6 Availability: Tk 8.6
@ -1159,7 +1158,7 @@ option. If you don't know the class name of a widget, use the method
.. method:: configure(style, query_opt=None, **kw) .. method:: configure(style, query_opt=None, **kw)
Query or sets the default value of the specified option(s) in *style*. Query or set the default value of the specified option(s) in *style*.
Each key in *kw* is an option and each value is a string identifying Each key in *kw* is an option and each value is a string identifying
the value for that option. the value for that option.
@ -1185,10 +1184,10 @@ option. If you don't know the class name of a widget, use the method
Query or sets dynamic values of the specified option(s) in *style*. Query or sets dynamic values of the specified option(s) in *style*.
Each key in kw is an option and each value should be a list or a Each key in *kw* is an option and each value should be a list or a
tuple (usually) containing statespecs grouped in tuples, or list, or tuple (usually) containing statespecs grouped in tuples, lists, or
something else of your preference. A statespec is compound of one or more something else of your preference. A statespec is a compound of one
states and then a value. or more states and then a value.
An example may make it more understandable:: An example may make it more understandable::
@ -1208,12 +1207,10 @@ option. If you don't know the class name of a widget, use the method
root.mainloop() root.mainloop()
There is a thing to note in this previous short example: Note that the order of the (states, value) sequences for an option does
matter, if you changed the order to ``[('active', 'blue'), ('pressed',
* The order of the (states, value) sequences for an option does matter, 'red')]`` in the foreground option, for example, you would get a blue
if you changed the order to [('active', 'blue'), ('pressed', 'red')] foreground when the widget were in active or pressed states.
in the foreground option, for example, you would get a blue foreground
when the widget were in active or pressed states.
.. method:: lookup(style, option[, state=None[, default=None]]) .. method:: lookup(style, option[, state=None[, default=None]])
@ -1236,13 +1233,13 @@ option. If you don't know the class name of a widget, use the method
Define the widget layout for given *style*. If *layoutspec* is omitted, Define the widget layout for given *style*. If *layoutspec* is omitted,
return the layout specification for given style. return the layout specification for given style.
*layoutspec*, if specified, is expected to be a list, or some other *layoutspec*, if specified, is expected to be a list or some other
sequence type (excluding string), where each item should be a tuple and sequence type (excluding strings), where each item should be a tuple and
the first item is the layout name and the second item should have the the first item is the layout name and the second item should have the
format described described in `Layouts`_. format described described in `Layouts`_.
To understand the format, check this example below (it is not intended To understand the format, see the following example (it is not
to do anything useful):: intended to do anything useful)::
from tkinter import ttk from tkinter import ttk
import tkinter import tkinter
@ -1268,12 +1265,12 @@ option. If you don't know the class name of a widget, use the method
.. method:: element_create(elementname, etype, *args, **kw) .. method:: element_create(elementname, etype, *args, **kw)
Create a new element in the current theme of given *etype* which is Create a new element in the current theme, of the given *etype* which is
expected to be either "image", "from" or "vsapi". The latter is only expected to be either "image", "from" or "vsapi". The latter is only
available in Tk 8.6a for Windows XP and Vista and is not described here. available in Tk 8.6a for Windows XP and Vista and is not described here.
If "image" is used, *args* should contain the default image name followed If "image" is used, *args* should contain the default image name followed
by statespec/value pairs (this is the imagespec), *kw* may have the by statespec/value pairs (this is the imagespec), and *kw* may have the
following options: following options:
* border=padding * border=padding
@ -1296,11 +1293,12 @@ option. If you don't know the class name of a widget, use the method
Specifies a minimum width for the element. If less than zero, the Specifies a minimum width for the element. If less than zero, the
base image's width is used as a default. base image's width is used as a default.
But if "from" is used, then :meth:`element_create` will clone an existing If "from" is used as the value of *etype*,
element. *args* is expected to contain a themename, which is from where :meth:`element_create` will clone an existing
element. *args* is expected to contain a themename, from which
the element will be cloned, and optionally an element to clone from. the element will be cloned, and optionally an element to clone from.
If this element to clone from is not specified, an empty element will If this element to clone from is not specified, an empty element will
be used. *kw* is discarded here. be used. *kw* is discarded.
.. method:: element_names() .. method:: element_names()
@ -1334,7 +1332,7 @@ option. If you don't know the class name of a widget, use the method
:meth:`Style.configure`, :meth:`Style.map`, :meth:`Style.layout` and :meth:`Style.configure`, :meth:`Style.map`, :meth:`Style.layout` and
:meth:`Style.element_create` respectively. :meth:`Style.element_create` respectively.
As an example, lets change the Combobox for the default theme a bit:: As an example, let's change the Combobox for the default theme a bit::
from tkinter import ttk from tkinter import ttk
import tkinter import tkinter
@ -1367,7 +1365,7 @@ option. If you don't know the class name of a widget, use the method
.. method:: theme_use([themename]) .. method:: theme_use([themename])
If *themename* is not given, returns the theme in use, otherwise, set If *themename* is not given, returns the theme in use. Otherwise, sets
the current theme to *themename*, refreshes all widgets and emits a the current theme to *themename*, refreshes all widgets and emits a
<<ThemeChanged>> event. <<ThemeChanged>> event.
@ -1375,13 +1373,14 @@ option. If you don't know the class name of a widget, use the method
Layouts Layouts
^^^^^^^ ^^^^^^^
A layout can be just None, if takes no options, or a dict of options specifying A layout can be just None, if it takes no options, or a dict of
how to arrange the element. The layout mechanism uses a simplified options specifying how to arrange the element. The layout mechanism
version of the pack geometry manager: given an initial cavity, each element is uses a simplified version of the pack geometry manager: given an
allocated a parcel. Valid options/values are: initial cavity, each element is allocated a parcel. Valid
options/values are:
* side: whichside * side: whichside
Specifies which side of the cavity to place the the element; one of Specifies which side of the cavity to place the element; one of
top, right, bottom or left. If omitted, the element occupies the top, right, bottom or left. If omitted, the element occupies the
entire cavity. entire cavity.

2
Doc/library/urllib.request.rst
View File

@ -40,7 +40,7 @@ The :mod:`urllib.request` module defines the following functions:
commonly used to determine if a redirect was followed commonly used to determine if a redirect was followed
* :meth:`info` --- return the meta-information of the page, such as headers, * :meth:`info` --- return the meta-information of the page, such as headers,
in the form of an ``http.client.HTTPMessage`` instance (see `Quick in the form of an :class:`http.client.HTTPMessage` instance (see `Quick
Reference to HTTP Headers <http://www.cs.tut.fi/~jkorpela/http.html>`_) Reference to HTTP Headers <http://www.cs.tut.fi/~jkorpela/http.html>`_)
Raises :exc:`URLError` on errors. Raises :exc:`URLError` on errors.

4
Doc/library/webbrowser.rst
View File

@ -55,6 +55,10 @@ The following functions are defined:
under many window managers this will occur regardless of the setting of this under many window managers this will occur regardless of the setting of this
variable). variable).
Note that on some platforms, trying to open a filename using this function,
may work and start the operating system's associated program. However, this
is neither supported nor portable.
.. function:: open_new(url) .. function:: open_new(url)

21
Doc/library/winreg.rst
View File

@ -39,8 +39,8 @@ This module offers the following functions:
*key* is the predefined handle to connect to. *key* is the predefined handle to connect to.
The return value is the handle of the opened key. If the function fails, an The return value is the handle of the opened key. If the function fails, a
:exc:`EnvironmentError` exception is raised. :exc:`WindowsError` exception is raised.
.. function:: CreateKey(key, sub_key) .. function:: CreateKey(key, sub_key)
@ -57,8 +57,8 @@ This module offers the following functions:
If the key already exists, this function opens the existing key. If the key already exists, this function opens the existing key.
The return value is the handle of the opened key. If the function fails, an The return value is the handle of the opened key. If the function fails, a
:exc:`EnvironmentError` exception is raised. :exc:`WindowsError` exception is raised.
.. function:: DeleteKey(key, sub_key) .. function:: DeleteKey(key, sub_key)
@ -74,7 +74,7 @@ This module offers the following functions:
*This method can not delete keys with subkeys.* *This method can not delete keys with subkeys.*
If the method succeeds, the entire key, including all of its values, is removed. If the method succeeds, the entire key, including all of its values, is removed.
If the method fails, an :exc:`EnvironmentError` exception is raised. If the method fails, a :exc:`WindowsError` exception is raised.
.. function:: DeleteValue(key, value) .. function:: DeleteValue(key, value)
@ -97,7 +97,7 @@ This module offers the following functions:
*index* is an integer that identifies the index of the key to retrieve. *index* is an integer that identifies the index of the key to retrieve.
The function retrieves the name of one subkey each time it is called. It is The function retrieves the name of one subkey each time it is called. It is
typically called repeatedly until an :exc:`EnvironmentError` exception is typically called repeatedly until a :exc:`WindowsError` exception is
raised, indicating, no more values are available. raised, indicating, no more values are available.
@ -111,7 +111,7 @@ This module offers the following functions:
*index* is an integer that identifies the index of the value to retrieve. *index* is an integer that identifies the index of the value to retrieve.
The function retrieves the name of one subkey each time it is called. It is The function retrieves the name of one subkey each time it is called. It is
typically called repeatedly, until an :exc:`EnvironmentError` exception is typically called repeatedly, until a :exc:`WindowsError` exception is
raised, indicating no more values. raised, indicating no more values.
The result is a tuple of 3 items: The result is a tuple of 3 items:
@ -199,7 +199,7 @@ This module offers the following functions:
The result is a new handle to the specified key. The result is a new handle to the specified key.
If the function fails, :exc:`EnvironmentError` is raised. If the function fails, :exc:`WindowsError` is raised.
.. function:: OpenKeyEx() .. function:: OpenKeyEx()
@ -243,9 +243,10 @@ This module offers the following functions:
associated. If this parameter is ``None`` or empty, the function retrieves the associated. If this parameter is ``None`` or empty, the function retrieves the
value set by the :func:`SetValue` method for the key identified by *key*. value set by the :func:`SetValue` method for the key identified by *key*.
Values in the registry have name, type, and data components. This method Values in the registry have name, type, and data components. This method
retrieves the data for a key's first value that has a NULL name. But the retrieves the data for a key's first value that has a NULL name. But the
underlying API call doesn't return the type, Lame Lame Lame, DO NOT USE THIS!!! underlying API call doesn't return the type, so always use
:func:`QueryValueEx` if possible.
.. function:: QueryValueEx(key, value_name) .. function:: QueryValueEx(key, value_name)

5
Doc/reference/datamodel.rst
View File

@ -59,12 +59,13 @@ Objects are never explicitly destroyed; however, when they become unreachable
they may be garbage-collected. An implementation is allowed to postpone garbage they may be garbage-collected. An implementation is allowed to postpone garbage
collection or omit it altogether --- it is a matter of implementation quality collection or omit it altogether --- it is a matter of implementation quality
how garbage collection is implemented, as long as no objects are collected that how garbage collection is implemented, as long as no objects are collected that
are still reachable. (Implementation note: the current implementation uses a are still reachable. (Implementation note: CPython currently uses a
reference-counting scheme with (optional) delayed detection of cyclically linked reference-counting scheme with (optional) delayed detection of cyclically linked
garbage, which collects most objects as soon as they become unreachable, but is garbage, which collects most objects as soon as they become unreachable, but is
not guaranteed to collect garbage containing circular references. See the not guaranteed to collect garbage containing circular references. See the
documentation of the :mod:`gc` module for information on controlling the documentation of the :mod:`gc` module for information on controlling the
collection of cyclic garbage.) collection of cyclic garbage. Other implementations act differently and CPython
may change.)
Note that the use of the implementation's tracing or debugging facilities may Note that the use of the implementation's tracing or debugging facilities may
keep objects alive that would normally be collectable. Also note that catching keep objects alive that would normally be collectable. Also note that catching

12
Doc/tutorial/datastructures.rst
View File

@ -347,13 +347,11 @@ The reverse operation is also possible::
>>> x, y, z = t >>> x, y, z = t
This is called, appropriately enough, *sequence unpacking*. Sequence unpacking This is called, appropriately enough, *sequence unpacking* and works for any
requires the list of variables on the left to have the same number of elements sequence on the right-hand side. Sequence unpacking requires the list of
as the length of the sequence. Note that multiple assignment is really just a variables on the left to have the same number of elements as the length of the
combination of tuple packing and sequence unpacking! sequence. Note that multiple assignment is really just a combination of tuple
packing and sequence unpacking.
There is a small bit of asymmetry here: packing multiple values always creates
a tuple, and unpacking works for any sequence.
.. XXX Add a bit on the difference between tuples and lists. .. XXX Add a bit on the difference between tuples and lists.

29
Doc/tutorial/introduction.rst
View File

@ -225,10 +225,9 @@ the following::
several lines of text just as you would do in C. several lines of text just as you would do in C.
Note that whitespace at the beginning of the line is significant. Note that whitespace at the beginning of the line is significant.
If we make the string literal a "raw" string, however, the ``\n`` sequences are If we make the string literal a "raw" string, ``\n`` sequences are not converted
not converted to newlines, but the backslash at the end of the line, and the to newlines, but the backslash at the end of the line, and the newline character
newline character in the source, are both included in the string as data. Thus, in the source, are both included in the string as data. Thus, the example::
the example::
hello = r"This is a rather long string containing\n\ hello = r"This is a rather long string containing\n\
several lines of text much as you would do in C." several lines of text much as you would do in C."
@ -240,22 +239,12 @@ would print::
This is a rather long string containing\n\ This is a rather long string containing\n\
several lines of text much as you would do in C. several lines of text much as you would do in C.
Or, strings can be surrounded in a pair of matching triple-quotes: ``"""`` or The interpreter prints the result of string operations in the same way as they
``'''``. End of lines do not need to be escaped when using triple-quotes, but are typed for input: inside quotes, and with quotes and other funny characters
they will be included in the string. :: escaped by backslashes, to show the precise value. The string is enclosed in
double quotes if the string contains a single quote and no double quotes, else
print(""" it's enclosed in single quotes. (The :func:`print` function, described later,
Usage: thingy [OPTIONS] can be used to write strings without quotes or escapes.)
-h Display this usage message
-H hostname Hostname to connect to
""")
produces the following output::
Usage: thingy [OPTIONS]
-h Display this usage message
-H hostname Hostname to connect to
Strings can be concatenated (glued together) with the ``+`` operator, and Strings can be concatenated (glued together) with the ``+`` operator, and
repeated with ``*``:: repeated with ``*``::

4
Doc/whatsnew/2.6.rst
View File

@ -86,8 +86,6 @@ for each change.
.. ======================================================================== .. ========================================================================
.. Large, PEP-level features and changes should be described here. .. Large, PEP-level features and changes should be described here.
.. Should there be a new section here for 3k migration?
.. Or perhaps a more general section describing module changes/deprecation?
.. ======================================================================== .. ========================================================================
Python 3.0 Python 3.0
@ -1678,7 +1676,7 @@ Some smaller changes made to the core Python language are:
:attr:`__self__`, and :attr:`im_func` is also available as :attr:`__func__`. :attr:`__self__`, and :attr:`im_func` is also available as :attr:`__func__`.
The old names are still supported in Python 2.6, but are gone in 3.0. The old names are still supported in Python 2.6, but are gone in 3.0.
* An obscure change: when you use the the :func:`locals` function inside a * An obscure change: when you use the :func:`locals` function inside a
:keyword:`class` statement, the resulting dictionary no longer returns free :keyword:`class` statement, the resulting dictionary no longer returns free
variables. (Free variables, in this case, are variables referenced in the variables. (Free variables, in this case, are variables referenced in the
:keyword:`class` statement that aren't attributes of the class.) :keyword:`class` statement that aren't attributes of the class.)

267
Doc/whatsnew/2.7.rst
View File

@ -6,7 +6,7 @@
:Release: |release| :Release: |release|
:Date: |today| :Date: |today|
.. Fix accents on Kristjan Valur Jonsson, Fuerstenau. .. Fix accents on Kristjan Valur Jonsson, Fuerstenau, Tarek Ziade.
.. $Id$ .. $Id$
Rules for maintenance: Rules for maintenance:
@ -55,12 +55,32 @@ No release schedule has been decided yet for 2.7.
.. Compare with previous release in 2 - 3 sentences here. .. Compare with previous release in 2 - 3 sentences here.
add hyperlink when the documentation becomes available online. add hyperlink when the documentation becomes available online.
Python 3.1
================
Much as Python 2.6 incorporated features from Python 3.0,
version 2.7 is influenced by features from 3.1.
XXX mention importlib; anything else?
One porting change: the :option:`-3` switch now automatically
enables the :option:`-Qwarn` switch that causes warnings
about using classic division with integers and long integers.
.. ======================================================================== .. ========================================================================
.. Large, PEP-level features and changes should be described here. .. Large, PEP-level features and changes should be described here.
.. Should there be a new section here for 3k migration?
.. Or perhaps a more general section describing module changes/deprecation?
.. ======================================================================== .. ========================================================================
PEP 372: Adding an ordered dictionary to collections
====================================================
XXX write this
Several modules will now use :class:`OrderedDict` by default. The
:mod:`ConfigParser` module uses :class:`OrderedDict` for the list
of sections and the options within a section.
The :meth:`namedtuple._asdict` method returns an :class:`OrderedDict`
as well.
Other Language Changes Other Language Changes
@ -85,30 +105,9 @@ Some smaller changes made to the core Python language are:
(Contributed by Fredrik Johansson and Victor Stinner; :issue:`3439`.) (Contributed by Fredrik Johansson and Victor Stinner; :issue:`3439`.)
* The :class:`bytearray` type's :meth:`translate` method will
* Integers are now stored internally either in base 2**15 or in base now accept None as its first argument. (Fixed by Georg Brandl;
2**30, the base being determined at build time. Previously, they :issue:`4759`.)
were always stored in base 2**15. Using base 2**30 gives
significant performance improvements on 64-bit machines, but
benchmark results on 32-bit machines have been mixed. Therefore,
the default is to use base 2**30 on 64-bit machines and base 2**15
on 32-bit machines; on Unix, there's a new configure option
--enable-big-digits that can be used to override this default.
Apart from the performance improvements this change should be
invisible to end users, with one exception: for testing and
debugging purposes there's a new structseq ``sys.long_info`` that
provides information about the internal format, giving the number of
bits per digit and the size in bytes of the C type used to store
each digit::
>>> import sys
>>> sys.long_info
sys.long_info(bits_per_digit=30, sizeof_digit=4)
(Contributed by Mark Dickinson; :issue:`4258`.)
.. ====================================================================== .. ======================================================================
@ -116,7 +115,13 @@ Some smaller changes made to the core Python language are:
Optimizations Optimizations
------------- -------------
A few performance enhancements have been added: Several performance enhancements have been added:
.. * A new :program:`configure` option, :option:`--with-computed-gotos`,
compiles the main bytecode interpreter loop using a new dispatch
mechanism that gives speedups of up to 20%, depending on the system
and benchmark. The new mechanism is only supported on certain
compilers, such as gcc, SunPro, and icc.
* The garbage collector now performs better when many objects are * The garbage collector now performs better when many objects are
being allocated without deallocating any. A full garbage collection being allocated without deallocating any. A full garbage collection
@ -129,18 +134,57 @@ A few performance enhancements have been added:
(Suggested by Martin von Loewis and implemented by Antoine Pitrou; (Suggested by Martin von Loewis and implemented by Antoine Pitrou;
:issue:`4074`.) :issue:`4074`.)
* The garbage collector tries to avoid tracking simple containers which * The garbage collector tries to avoid tracking simple containers
can't be part of a cycle. As of now, this is true for tuples and dicts which can't be part of a cycle. In Python 2.7, this is now true for
containing atomic types (such as ints, strings, etc.). Transitively, a dict tuples and dicts containing atomic types (such as ints, strings,
containing tuples of atomic types won't be tracked either. This helps bring etc.). Transitively, a dict containing tuples of atomic types won't
down the individual cost of each garbage collection, since it decreases the be tracked either. This helps reduce the cost of each
number of objects to be considered and traversed by the collector. garbage collection by decreasing the number of objects to be
considered and traversed by the collector.
To help diagnosing this optimization, a new function in the :mod:`gc`
module, :func:`is_tracked`, returns True if a given instance is tracked
by the garbage collector, False otherwise.
(Contributed by Antoine Pitrou; :issue:`4688`.) (Contributed by Antoine Pitrou; :issue:`4688`.)
* Integers are now stored internally either in base 2**15 or in base
2**30, the base being determined at build time. Previously, they
were always stored in base 2**15. Using base 2**30 gives
significant performance improvements on 64-bit machines, but
benchmark results on 32-bit machines have been mixed. Therefore,
the default is to use base 2**30 on 64-bit machines and base 2**15
on 32-bit machines; on Unix, there's a new configure option
:option:`--enable-big-digits` that can be used to override this default.
Apart from the performance improvements this change should be
invisible to end users, with one exception: for testing and
debugging purposes there's a new structseq ``sys.long_info`` that
provides information about the internal format, giving the number of
bits per digit and the size in bytes of the C type used to store
each digit::
>>> import sys
>>> sys.long_info
sys.long_info(bits_per_digit=30, sizeof_digit=4)
(Contributed by Mark Dickinson; :issue:`4258`.)
Another set of changes made long objects a few bytes smaller: 2 bytes
smaller on 32-bit systems and 6 bytes on 64-bit.
(Contributed by Mark Dickinson; :issue:`5260`.)
* The division algorithm for long integers has been made faster
by tightening the inner loop, doing shifts instead of multiplications,
and fixing an unnecessary extra iteration.
Various benchmarks show speedups of between 50% and 150% for long
integer divisions and modulo operations.
(Contributed by Mark Dickinson; :issue:`5512`.)
* The implementation of ``%`` checks for the left-side operand being
a Python string and special-cases it; this results in a 1-3%
performance increase for applications that frequently use ``%``
with strings, such as templating libraries.
(Implemented by Collin Winter; :issue:`5176`.)
* List comprehensions with an ``if`` condition are compiled into
faster bytecode. (Patch by Antoine Pitrou, back-ported to 2.7
by Jeffrey Yasskin; :issue:`4715`.)
.. ====================================================================== .. ======================================================================
@ -153,15 +197,6 @@ changes, sorted alphabetically by module name. Consult the
:file:`Misc/NEWS` file in the source tree for a more complete list of :file:`Misc/NEWS` file in the source tree for a more complete list of
changes, or look through the Subversion logs for all the details. changes, or look through the Subversion logs for all the details.
* In Distutils, distutils.sdist.add_defaults now uses package_dir and data_files
to feed MANIFEST.
* It is not mandatory anymore to store clear text passwords in the
:file:`.pypirc` file when registering and uploading packages to PyPI. As long
as the username is present in that file, the :mod:`distutils` package will
prompt for the password if not present. (Added by tarek, with the initial
contribution of Nathan Van Gheem; :issue:`4394`.)
* The :mod:`bz2` module's :class:`BZ2File` now supports the context * The :mod:`bz2` module's :class:`BZ2File` now supports the context
management protocol, so you can write ``with bz2.BZ2File(...) as f: ...``. management protocol, so you can write ``with bz2.BZ2File(...) as f: ...``.
(Contributed by Hagen Fuerstenau; :issue:`3860`.) (Contributed by Hagen Fuerstenau; :issue:`3860`.)
@ -200,21 +235,100 @@ changes, or look through the Subversion logs for all the details.
Contributed by Raymond Hettinger; :issue:`1696199`. Contributed by Raymond Hettinger; :issue:`1696199`.
The :class:`namedtuple` class now has an optional *rename* parameter.
If *rename* is True, field names that are invalid because they've
been repeated or that aren't legal Python identifiers will be
renamed to legal names that are derived from the field's
position within the list of fields:
>>> T=namedtuple('T', ['field1', '$illegal', 'for', 'field2'], rename=True)
>>> T._fields
('field1', '_1', '_2', 'field2')
(Added by Raymond Hettinger; :issue:`1818`.)
* In Distutils, :func:`distutils.sdist.add_defaults` now uses
*package_dir* and *data_files* to create the MANIFEST file.
It is no longer mandatory to store clear-text passwords in the
:file:`.pypirc` file when registering and uploading packages to PyPI. As long
as the username is present in that file, the :mod:`distutils` package will
prompt for the password if not present. (Added by Tarek Ziade,
based on an initial contribution by Nathan Van Gheem; :issue:`4394`.)
* New method: the :class:`Decimal` class gained a
:meth:`from_float` class method that performs an exact conversion
of a floating-point number to a :class:`Decimal`.
Note that this is an **exact** conversion that strives for the
closest decimal approximation to the floating-point representation's value;
the resulting decimal value will therefore still include the inaccuracy,
if any.
For example, ``Decimal.from_float(0.1)`` returns
``Decimal('0.1000000000000000055511151231257827021181583404541015625')``.
(Implemented by Raymond Hettinger; :issue:`4796`.)
* A new function in the :mod:`gc` module, :func:`is_tracked`, returns
True if a given instance is tracked by the garbage collector, False
otherwise. (Contributed by Antoine Pitrou; :issue:`4688`.)
* The :mod:`gzip` module's :class:`GzipFile` now supports the context * The :mod:`gzip` module's :class:`GzipFile` now supports the context
management protocol, so you can write ``with gzip.GzipFile(...) as f: ...``. management protocol, so you can write ``with gzip.GzipFile(...) as f: ...``.
(Contributed by Hagen Fuerstenau; :issue:`3860`.) (Contributed by Hagen Fuerstenau; :issue:`3860`.)
It's now possible to override the modification time
recorded in a gzipped file by providing an optional timestamp to
the constructor. (Contributed by Jacques Frechet; :issue:`4272`.)
* The :class:`io.FileIO` class now raises an :exc:`OSError` when passed * The :class:`io.FileIO` class now raises an :exc:`OSError` when passed
an invalid file descriptor. (Implemented by Benjamin Peterson; an invalid file descriptor. (Implemented by Benjamin Peterson;
:issue:`4991`.) :issue:`4991`.)
* New function: ``itertools.compress(*data*, *selectors*)`` takes two
iterators. Elements of *data* are returned if the corresponding
value in *selectors* is True::
itertools.compress('ABCDEF', [1,0,1,0,1,1]) =>
A, C, E, F
New function: ``itertools.combinations_with_replacement(*iter*, *r*)``
returns all the possible *r*-length combinations of elements from the
iterable *iter*. Unlike :func:`combinations`, individual elements
can be repeated in the generated combinations::
itertools.combinations_with_replacement('abc', 2) =>
('a', 'a'), ('a', 'b'), ('a', 'c'),
('b', 'b'), ('b', 'c'), ('c', 'c')
Note that elements are treated as unique depending on their position
in the input, not their actual values.
The :class:`itertools.count` function now has a *step* argument that
allows incrementing by values other than 1. :func:`count` also
now allows keyword arguments, and using non-integer values such as
floats or :class:`Decimal` instances. (Implemented by Raymond
Hettinger; :issue:`5032`.)
:func:`itertools.combinations` and :func:`itertools.product` were
previously raising :exc:`ValueError` for values of *r* larger than
the input iterable. This was deemed a specification error, so they
now return an empty iterator. (Fixed by Raymond Hettinger; :issue:`4816`.)
* The :mod:`json` module was upgraded to version 2.0.9 of the
simplejson package, which includes a C extension that makes
encoding and decoding faster.
(Contributed by Bob Ippolito; :issue:`4136`.)
To support the new :class:`OrderedDict` type, :func:`json.load`
now has an optional *object_pairs_hook* parameter that will be called
with any object literal that decodes to a list of pairs.
(Contributed by Raymond Hettinger; :issue:`5381`.)
* The :mod:`pydoc` module now has help for the various symbols that Python * The :mod:`pydoc` module now has help for the various symbols that Python
uses. You can now do ``help('<<')`` or ``help('@')``, for example. uses. You can now do ``help('<<')`` or ``help('@')``, for example.
(Contributed by David Laban; :issue:`4739`.) (Contributed by David Laban; :issue:`4739`.)
* A new function in the :mod:`subprocess` module, * A new function in the :mod:`subprocess` module,
:func:`check_output`, runs a command with a specified set of arguments :func:`check_output`, runs a command with a specified set of arguments
and returns the command's output as a string if the command runs without and returns the command's output as a string when the command runs without
error, or raises a :exc:`CalledProcessError` exception otherwise. error, or raises a :exc:`CalledProcessError` exception otherwise.
:: ::
@ -229,13 +343,41 @@ changes, or look through the Subversion logs for all the details.
(Contributed by Gregory P. Smith.) (Contributed by Gregory P. Smith.)
* The ``sys.version_info`` value is now a named tuple, with attributes
named ``major``, ``minor``, ``micro``, ``releaselevel``, and ``serial``.
(Contributed by Ross Light; :issue:`4285`.)
* The :mod:`unittest` module was enhanced in several ways.
Test cases can raise the :exc:`SkipTest` exception to skip a test.
(:issue:`1034053`.)
It will now use 'x' for expected failures
and 'u' for unexpected successes when run in its verbose mode.
(Contributed by Benjamin Peterson.)
The :meth:`assertRaises` and :meth:`failUnlessRaises` methods now
return a context handler when called without providing a callable
object to run. For example, you can write this::
with self.assertRaises(KeyError):
raise ValueError
(Implemented by Antoine Pitrou; :issue:`4444`.)
* The :func:`is_zipfile` function in the :mod:`zipfile` module will now * The :func:`is_zipfile` function in the :mod:`zipfile` module will now
accept a file object, in addition to the path names accepted in earlier accept a file object, in addition to the path names accepted in earlier
versions. (Contributed by Gabriel Genellina; :issue:`4756`.) versions. (Contributed by Gabriel Genellina; :issue:`4756`.)
:mod:`zipfile` now supports archiving empty directories and
extracts them correctly. (Fixed by Kuba Wieczorek; :issue:`4710`.)
.. ====================================================================== .. ======================================================================
.. whole new modules get described in subsections here .. whole new modules get described in subsections here
importlib: Importing Modules
------------------------------
XXX write this
ttk: Themed Widgets for Tk ttk: Themed Widgets for Tk
-------------------------- --------------------------
@ -266,11 +408,16 @@ Changes to Python's build process and to the C API include:
debugged doesn't hold the GIL; the macro will now acquire it before printing. debugged doesn't hold the GIL; the macro will now acquire it before printing.
(Contributed by Victor Stinner; :issue:`3632`.) (Contributed by Victor Stinner; :issue:`3632`.)
* :cfunc:`Py_AddPendingCall` is now thread safe, letting any * :cfunc:`Py_AddPendingCall` is now thread-safe, letting any
worker thread submit notifications to the main Python thread. This worker thread submit notifications to the main Python thread. This
is particularly useful for asynchronous IO operations. is particularly useful for asynchronous IO operations.
(Contributed by Kristjan Valur Jonsson; :issue:`4293`.) (Contributed by Kristjan Valur Jonsson; :issue:`4293`.)
* The :program:`configure` script now checks for floating-point rounding bugs
on certain 32-bit Intel chips and defines a :cmacro:`X87_DOUBLE_ROUNDING`
preprocessor definition. No code currently uses this definition,
but it's available if anyone wishes to use it.
(Added by Mark Dickinson; :issue:`2937`.)
.. ====================================================================== .. ======================================================================
@ -293,6 +440,28 @@ Port-Specific Changes: Windows
Port-Specific Changes: Mac OS X Port-Specific Changes: Mac OS X
----------------------------------- -----------------------------------
* The ``/Library/Python/2.7/site-packages`` is now appended to
``sys.path``, in order to share added packages between the system
installation and a user-installed copy of the same version.
(Changed by Ronald Oussoren; :issue:`4865`.)
Other Changes and Fixes
=======================
* When importing a module from a :file:`.pyc` or :file:`.pyo` file
with an existing :file:`.py` counterpart, the :attr:`co_filename`
attributes of all code objects if the original filename is obsolete,
which can happen if the file has been renamed, moved, or is accessed
through different paths. (Patch by Ziga Seilnacht and Jean-Paul
Calderone; :issue:`1180193`.)
* The :file:`regrtest.py` script now takes a :option:`--randseed=`
switch that takes an integer that will be used as the random seed
for the :option:`-r` option that executes tests in random order.
The :option:`-r` option also now reports the seed that was used
(Added by Collin Winter.)
.. ====================================================================== .. ======================================================================

3
Lib/distutils/cmd.py
View File

@ -333,7 +333,8 @@ class Command:
# -- External world manipulation ----------------------------------- # -- External world manipulation -----------------------------------
def warn(self, msg): def warn(self, msg):
log.warn("warning: %s: %s\n" % (self.get_command_name(), msg)) log.warn("warning: %s: %s\n" %
(self.get_command_name(), msg))
def execute(self, func, args, msg=None, level=1): def execute(self, func, args, msg=None, level=1):
util.execute(func, args, msg, dry_run=self.dry_run) util.execute(func, args, msg, dry_run=self.dry_run)

13
Lib/distutils/log.py
View File

@ -18,13 +18,14 @@ class Log:
def _log(self, level, msg, args): def _log(self, level, msg, args):
if level >= self.threshold: if level >= self.threshold:
if not args: if args:
# msg may contain a '%'. If args is empty, msg = msg % args
# don't even try to string-format if level in (WARN, ERROR, FATAL):
print(msg) stream = sys.stderr
else: else:
print(msg % args) stream = sys.stdout
sys.stdout.flush() stream.write('%s\n' % msg)
stream.flush()
def log(self, level, msg, *args): def log(self, level, msg, *args):
self._log(level, msg, args) self._log(level, msg, args)

4
Lib/ftplib.py
View File

@ -223,7 +223,7 @@ class FTP:
def voidresp(self): def voidresp(self):
"""Expect a response beginning with '2'.""" """Expect a response beginning with '2'."""
resp = self.getresp() resp = self.getresp()
if resp[0] != '2': if resp[:1] != '2':
raise error_reply(resp) raise error_reply(resp)
return resp return resp
@ -522,8 +522,6 @@ class FTP:
resp = self.sendcmd('DELE ' + filename) resp = self.sendcmd('DELE ' + filename)
if resp[:3] in ('250', '200'): if resp[:3] in ('250', '200'):
return resp return resp
elif resp[:1] == '5':
raise error_perm(resp)
else: else:
raise error_reply(resp) raise error_reply(resp)

2
Lib/glob.py
View File

@ -16,7 +16,7 @@ def glob(pathname):
return list(iglob(pathname)) return list(iglob(pathname))
def iglob(pathname): def iglob(pathname):
"""Return a list of paths matching a pathname pattern. """Return an iterator which yields the paths matching a pathname pattern.
The pattern may contain simple shell-style wildcards a la fnmatch. The pattern may contain simple shell-style wildcards a la fnmatch.

1
Lib/optparse.py
View File

@ -11,6 +11,7 @@ For support, use the optik-users@lists.sourceforge.net mailing list
__version__ = "1.5.3" __version__ = "1.5.3"
__all__ = ['Option', __all__ = ['Option',
'make_option',
'SUPPRESS_HELP', 'SUPPRESS_HELP',
'SUPPRESS_USAGE', 'SUPPRESS_USAGE',
'Values', 'Values',

47
Lib/pdb.py
View File

@ -95,10 +95,14 @@ class Pdb(bdb.Bdb, cmd.Cmd):
rcFile.close() rcFile.close()
self.commands = {} # associates a command list to breakpoint numbers self.commands = {} # associates a command list to breakpoint numbers
self.commands_doprompt = {} # for each bp num, tells if the prompt must be disp. after execing the cmd list self.commands_doprompt = {} # for each bp num, tells if the prompt
self.commands_silent = {} # for each bp num, tells if the stack trace must be disp. after execing the cmd list # must be disp. after execing the cmd list
self.commands_defining = False # True while in the process of defining a command list self.commands_silent = {} # for each bp num, tells if the stack trace
self.commands_bnum = None # The breakpoint number for which we are defining a list # must be disp. after execing the cmd list
self.commands_defining = False # True while in the process of defining
# a command list
self.commands_bnum = None # The breakpoint number for which we are
# defining a list
def reset(self): def reset(self):
bdb.Bdb.reset(self) bdb.Bdb.reset(self)
@ -114,6 +118,10 @@ class Pdb(bdb.Bdb, cmd.Cmd):
self.forget() self.forget()
self.stack, self.curindex = self.get_stack(f, t) self.stack, self.curindex = self.get_stack(f, t)
self.curframe = self.stack[self.curindex][0] self.curframe = self.stack[self.curindex][0]
# The f_locals dictionary is updated from the actual frame
# locals whenever the .f_locals accessor is called, so we
# cache it here to ensure that modifications are not overwritten.
self.curframe_locals = self.curframe.f_locals
self.execRcLines() self.execRcLines()
# Can be executed earlier than 'setup' if desired # Can be executed earlier than 'setup' if desired
@ -192,21 +200,30 @@ class Pdb(bdb.Bdb, cmd.Cmd):
self.cmdloop() self.cmdloop()
self.forget() self.forget()
def displayhook(self, obj):
"""Custom displayhook for the exec in default(), which prevents
assignment of the _ variable in the builtins.
"""
print(repr(obj))
def default(self, line): def default(self, line):
if line[:1] == '!': line = line[1:] if line[:1] == '!': line = line[1:]
locals = self.curframe.f_locals locals = self.curframe_locals
globals = self.curframe.f_globals globals = self.curframe.f_globals
try: try:
code = compile(line + '\n', '<stdin>', 'single') code = compile(line + '\n', '<stdin>', 'single')
save_stdout = sys.stdout save_stdout = sys.stdout
save_stdin = sys.stdin save_stdin = sys.stdin
save_displayhook = sys.displayhook
try: try:
sys.stdin = self.stdin sys.stdin = self.stdin
sys.stdout = self.stdout sys.stdout = self.stdout
sys.displayhook = self.displayhook
exec(code, globals, locals) exec(code, globals, locals)
finally: finally:
sys.stdout = save_stdout sys.stdout = save_stdout
sys.stdin = save_stdin sys.stdin = save_stdin
sys.displayhook = save_displayhook
except: except:
t, v = sys.exc_info()[:2] t, v = sys.exc_info()[:2]
if type(t) == type(''): if type(t) == type(''):
@ -349,7 +366,7 @@ class Pdb(bdb.Bdb, cmd.Cmd):
try: try:
func = eval(arg, func = eval(arg,
self.curframe.f_globals, self.curframe.f_globals,
self.curframe.f_locals) self.curframe_locals)
except: except:
func = arg func = arg
try: try:
@ -597,6 +614,7 @@ class Pdb(bdb.Bdb, cmd.Cmd):
else: else:
self.curindex = self.curindex - 1 self.curindex = self.curindex - 1
self.curframe = self.stack[self.curindex][0] self.curframe = self.stack[self.curindex][0]
self.curframe_locals = self.curframe.f_locals
self.print_stack_entry(self.stack[self.curindex]) self.print_stack_entry(self.stack[self.curindex])
self.lineno = None self.lineno = None
do_u = do_up do_u = do_up
@ -607,6 +625,7 @@ class Pdb(bdb.Bdb, cmd.Cmd):
else: else:
self.curindex = self.curindex + 1 self.curindex = self.curindex + 1
self.curframe = self.stack[self.curindex][0] self.curframe = self.stack[self.curindex][0]
self.curframe_locals = self.curframe.f_locals
self.print_stack_entry(self.stack[self.curindex]) self.print_stack_entry(self.stack[self.curindex])
self.lineno = None self.lineno = None
do_d = do_down do_d = do_down
@ -670,7 +689,7 @@ class Pdb(bdb.Bdb, cmd.Cmd):
def do_debug(self, arg): def do_debug(self, arg):
sys.settrace(None) sys.settrace(None)
globals = self.curframe.f_globals globals = self.curframe.f_globals
locals = self.curframe.f_locals locals = self.curframe_locals
p = Pdb(self.completekey, self.stdin, self.stdout) p = Pdb(self.completekey, self.stdin, self.stdout)
p.prompt = "(%s) " % self.prompt.strip() p.prompt = "(%s) " % self.prompt.strip()
print("ENTERING RECURSIVE DEBUGGER", file=self.stdout) print("ENTERING RECURSIVE DEBUGGER", file=self.stdout)
@ -694,9 +713,8 @@ class Pdb(bdb.Bdb, cmd.Cmd):
return 1 return 1
def do_args(self, arg): def do_args(self, arg):
f = self.curframe co = self.curframe.f_code
co = f.f_code dict = self.curframe_locals
dict = f.f_locals
n = co.co_argcount n = co.co_argcount
if co.co_flags & 4: n = n+1 if co.co_flags & 4: n = n+1
if co.co_flags & 8: n = n+1 if co.co_flags & 8: n = n+1
@ -708,16 +726,15 @@ class Pdb(bdb.Bdb, cmd.Cmd):
do_a = do_args do_a = do_args
def do_retval(self, arg): def do_retval(self, arg):
if '__return__' in self.curframe.f_locals: if '__return__' in self.curframe_locals:
print(self.curframe.f_locals['__return__'], file=self.stdout) print(self.curframe_locals['__return__'], file=self.stdout)
else: else:
print('*** Not yet returned!', file=self.stdout) print('*** Not yet returned!', file=self.stdout)
do_rv = do_retval do_rv = do_retval
def _getval(self, arg): def _getval(self, arg):
try: try:
return eval(arg, self.curframe.f_globals, return eval(arg, self.curframe.f_globals, self.curframe_locals)
self.curframe.f_locals)
except: except:
t, v = sys.exc_info()[:2] t, v = sys.exc_info()[:2]
if isinstance(t, str): if isinstance(t, str):
@ -788,7 +805,7 @@ class Pdb(bdb.Bdb, cmd.Cmd):
def do_whatis(self, arg): def do_whatis(self, arg):
try: try:
value = eval(arg, self.curframe.f_globals, value = eval(arg, self.curframe.f_globals,
self.curframe.f_locals) self.curframe_locals)
except: except:
t, v = sys.exc_info()[:2] t, v = sys.exc_info()[:2]
if type(t) == type(''): if type(t) == type(''):

411
Lib/test/README
View File

@ -1,411 +0,0 @@
+++++++++++++++++++++++++++++++
Writing Python Regression Tests
+++++++++++++++++++++++++++++++
:Author: Skip Montanaro
:Contact: skip@pobox.com
Introduction
============
If you add a new module to Python or modify the functionality of an existing
module, you should write one or more test cases to exercise that new
functionality. There are different ways to do this within the regression
testing facility provided with Python; any particular test should use only
one of these options. Each option requires writing a test module using the
conventions of the selected option:
- unittest_ based tests
- doctest_ based tests
- "traditional" Python test modules
Regardless of the mechanics of the testing approach you choose,
you will be writing unit tests (isolated tests of functions and objects
defined by the module) using white box techniques. Unlike black box
testing, where you only have the external interfaces to guide your test case
writing, in white box testing you can see the code being tested and tailor
your test cases to exercise it more completely. In particular, you will be
able to refer to the C and Python code in the CVS repository when writing
your regression test cases.
.. _unittest: http://www.python.org/doc/current/lib/module-unittest.html
.. _doctest: http://www.python.org/doc/current/lib/module-doctest.html
unittest-based tests
------------------
The unittest_ framework is based on the ideas of unit testing as espoused
by Kent Beck and the `Extreme Programming`_ (XP) movement. The specific
interface provided by the framework is tightly based on the JUnit_
Java implementation of Beck's original SmallTalk test framework. Please
see the documentation of the unittest_ module for detailed information on
the interface and general guidelines on writing unittest-based tests.
The test_support helper module provides a function for use by
unittest-based tests in the Python regression testing framework,
``run_unittest()``. This is the primary way of running tests in the
standard library. You can pass it any number of the following:
- classes derived from or instances of ``unittest.TestCase`` or
``unittest.TestSuite``. These will be handed off to unittest for
converting into a proper TestSuite instance.
- a string; this must be a key in sys.modules. The module associated with
that string will be scanned by ``unittest.TestLoader.loadTestsFromModule``.
This is usually seen as ``test_support.run_unittest(__name__)`` in a test
module's ``test_main()`` function. This has the advantage of picking up
new tests automatically, without you having to add each new test case
manually.
All test methods in the Python regression framework have names that
start with "``test_``" and use lower-case names with words separated with
underscores.
Test methods should *not* have docstrings! The unittest module prints
the docstring if there is one, but otherwise prints the function name
and the full class name. When there's a problem with a test, the
latter information makes it easier to find the source for the test
than the docstring.
All unittest-based tests in the Python test suite use boilerplate that
looks like this (with minor variations)::
import unittest
from test import test_support
class MyTestCase1(unittest.TestCase):
# Define setUp and tearDown only if needed
def setUp(self):
unittest.TestCase.setUp(self)
... additional initialization...
def tearDown(self):
... additional finalization...
unittest.TestCase.tearDown(self)
def test_feature_one(self):
# Testing feature one
...unit test for feature one...
def test_feature_two(self):
# Testing feature two
...unit test for feature two...
...etc...
class MyTestCase2(unittest.TestCase):
...same structure as MyTestCase1...
...etc...
def test_main():
test_support.run_unittest(__name__)
if __name__ == "__main__":
test_main()
This has the advantage that it allows the unittest module to be used
as a script to run individual tests as well as working well with the
regrtest framework.
.. _Extreme Programming: http://www.extremeprogramming.org/
.. _JUnit: http://www.junit.org/
doctest based tests
-------------------
Tests written to use doctest_ are actually part of the docstrings for
the module being tested. Each test is written as a display of an
interactive session, including the Python prompts, statements that would
be typed by the user, and the output of those statements (including
tracebacks, although only the exception msg needs to be retained then).
The module in the test package is simply a wrapper that causes doctest
to run over the tests in the module. The test for the difflib module
provides a convenient example::
import difflib
from test import test_support
test_support.run_doctest(difflib)
If the test is successful, nothing is written to stdout (so you should not
create a corresponding output/test_difflib file), but running regrtest
with -v will give a detailed report, the same as if passing -v to doctest.
A second argument can be passed to run_doctest to tell doctest to search
``sys.argv`` for -v instead of using test_support's idea of verbosity. This
is useful for writing doctest-based tests that aren't simply running a
doctest'ed Lib module, but contain the doctests themselves. Then at
times you may want to run such a test directly as a doctest, independent
of the regrtest framework. The tail end of test_descrtut.py is a good
example::
def test_main(verbose=None):
from test import test_support, test_descrtut
test_support.run_doctest(test_descrtut, verbose)
if __name__ == "__main__":
test_main(1)
If run via regrtest, ``test_main()`` is called (by regrtest) without
specifying verbose, and then test_support's idea of verbosity is used. But
when run directly, ``test_main(1)`` is called, and then doctest's idea of
verbosity is used.
See the documentation for the doctest module for information on
writing tests using the doctest framework.
"traditional" Python test modules
---------------------------------
The mechanics of how the "traditional" test system operates are fairly
straightforward. When a test case is run, the output is compared with the
expected output that is stored in .../Lib/test/output. If the test runs to
completion and the actual and expected outputs match, the test succeeds, if
not, it fails. If an ``ImportError`` or ``test_support.TestSkipped`` error
is raised, the test is not run.
Executing Test Cases
====================
If you are writing test cases for module spam, you need to create a file
in .../Lib/test named test_spam.py. In addition, if the tests are expected
to write to stdout during a successful run, you also need to create an
expected output file in .../Lib/test/output named test_spam ("..."
represents the top-level directory in the Python source tree, the directory
containing the configure script). If needed, generate the initial version
of the test output file by executing::
./python Lib/test/regrtest.py -g test_spam.py
from the top-level directory.
Any time you modify test_spam.py you need to generate a new expected
output file. Don't forget to desk check the generated output to make sure
it's really what you expected to find! All in all it's usually better
not to have an expected-out file (note that doctest- and unittest-based
tests do not).
To run a single test after modifying a module, simply run regrtest.py
without the -g flag::
./python Lib/test/regrtest.py test_spam.py
While debugging a regression test, you can of course execute it
independently of the regression testing framework and see what it prints::
./python Lib/test/test_spam.py
To run the entire test suite:
- [UNIX, + other platforms where "make" works] Make the "test" target at the
top level::
make test
- [WINDOWS] Run rt.bat from your PCBuild directory. Read the comments at
the top of rt.bat for the use of special -d, -O and -q options processed
by rt.bat.
- [OTHER] You can simply execute the two runs of regrtest (optimized and
non-optimized) directly::
./python Lib/test/regrtest.py
./python -O Lib/test/regrtest.py
But note that this way picks up whatever .pyc and .pyo files happen to be
around. The makefile and rt.bat ways run the tests twice, the first time
removing all .pyc and .pyo files from the subtree rooted at Lib/.
Test cases generate output based upon values computed by the test code.
When executed, regrtest.py compares the actual output generated by executing
the test case with the expected output and reports success or failure. It
stands to reason that if the actual and expected outputs are to match, they
must not contain any machine dependencies. This means your test cases
should not print out absolute machine addresses (e.g. the return value of
the id() builtin function) or floating point numbers with large numbers of
significant digits (unless you understand what you are doing!).
Test Case Writing Tips
======================
Writing good test cases is a skilled task and is too complex to discuss in
detail in this short document. Many books have been written on the subject.
I'll show my age by suggesting that Glenford Myers' `"The Art of Software
Testing"`_, published in 1979, is still the best introduction to the subject
available. It is short (177 pages), easy to read, and discusses the major
elements of software testing, though its publication predates the
object-oriented software revolution, so doesn't cover that subject at all.
Unfortunately, it is very expensive (about $100 new). If you can borrow it
or find it used (around $20), I strongly urge you to pick up a copy.
The most important goal when writing test cases is to break things. A test
case that doesn't uncover a bug is much less valuable than one that does.
In designing test cases you should pay attention to the following:
* Your test cases should exercise all the functions and objects defined
in the module, not just the ones meant to be called by users of your
module. This may require you to write test code that uses the module
in ways you don't expect (explicitly calling internal functions, for
example - see test_atexit.py).
* You should consider any boundary values that may tickle exceptional
conditions (e.g. if you were writing regression tests for division,
you might well want to generate tests with numerators and denominators
at the limits of floating point and integer numbers on the machine
performing the tests as well as a denominator of zero).
* You should exercise as many paths through the code as possible. This
may not always be possible, but is a goal to strive for. In
particular, when considering if statements (or their equivalent), you
want to create test cases that exercise both the true and false
branches. For loops, you should create test cases that exercise the
loop zero, one and multiple times.
* You should test with obviously invalid input. If you know that a
function requires an integer input, try calling it with other types of
objects to see how it responds.
* You should test with obviously out-of-range input. If the domain of a
function is only defined for positive integers, try calling it with a
negative integer.
* If you are going to fix a bug that wasn't uncovered by an existing
test, try to write a test case that exposes the bug (preferably before
fixing it).
* If you need to create a temporary file, you can use the filename in
``test_support.TESTFN`` to do so. It is important to remove the file
when done; other tests should be able to use the name without cleaning
up after your test.
.. _"The Art of Software Testing":
http://www.amazon.com/exec/obidos/ISBN=0471043281
Regression Test Writing Rules
=============================
Each test case is different. There is no "standard" form for a Python
regression test case, though there are some general rules (note that
these mostly apply only to the "classic" tests; unittest_- and doctest_-
based tests should follow the conventions natural to those frameworks)::
* If your test case detects a failure, raise ``TestFailed`` (found in
``test.test_support``).
* Import everything you'll need as early as possible.
* If you'll be importing objects from a module that is at least
partially platform-dependent, only import those objects you need for
the current test case to avoid spurious ``ImportError`` exceptions
that prevent the test from running to completion.
* Print all your test case results using the ``print`` statement. For
non-fatal errors, print an error message (or omit a successful
completion print) to indicate the failure, but proceed instead of
raising ``TestFailed``.
* Use ``assert`` sparingly, if at all. It's usually better to just print
what you got, and rely on regrtest's got-vs-expected comparison to
catch deviations from what you expect. ``assert`` statements aren't
executed at all when regrtest is run in -O mode; and, because they
cause the test to stop immediately, can lead to a long & tedious
test-fix, test-fix, test-fix, ... cycle when things are badly broken
(and note that "badly broken" often includes running the test suite
for the first time on new platforms or under new implementations of
the language).
Miscellaneous
=============
There is a test_support module in the test package you can import for
your test case. Import this module using either::
import test.test_support
or::
from test import test_support
test_support provides the following useful objects:
* ``TestFailed`` - raise this exception when your regression test detects
a failure.
* ``TestSkipped`` - raise this if the test could not be run because the
platform doesn't offer all the required facilities (like large
file support), even if all the required modules are available.
* ``ResourceDenied`` - this is raised when a test requires a resource that
is not available. Primarily used by 'requires'.
* ``verbose`` - you can use this variable to control print output. Many
modules use it. Search for "verbose" in the test_*.py files to see
lots of examples.
* ``forget(module_name)`` - attempts to cause Python to "forget" that it
loaded a module and erase any PYC files.
* ``is_resource_enabled(resource)`` - Returns a boolean based on whether
the resource is enabled or not.
* ``requires(resource [, msg])`` - if the required resource is not
available the ResourceDenied exception is raised.
* ``verify(condition, reason='test failed')``. Use this instead of::
assert condition[, reason]
``verify()`` has two advantages over ``assert``: it works even in -O
mode, and it raises ``TestFailed`` on failure instead of
``AssertionError``.
* ``is_jython`` - true if the interpreter is Jython, false otherwise.
* ``TESTFN`` - a string that should always be used as the filename when
you need to create a temp file. Also use ``try``/``finally`` to
ensure that your temp files are deleted before your test completes.
Note that you cannot unlink an open file on all operating systems, so
also be sure to close temp files before trying to unlink them.
* ``sortdict(dict)`` - acts like ``repr(dict.items())``, but sorts the
items first. This is important when printing a dict value, because
the order of items produced by ``dict.items()`` is not defined by the
language.
* ``findfile(file)`` - you can call this function to locate a file
somewhere along sys.path or in the Lib/test tree - see
test_ossaudiodev.py for an example of its use.
* ``fcmp(x,y)`` - you can call this function to compare two floating
point numbers when you expect them to only be approximately equal
withing a fuzz factor (``test_support.FUZZ``, which defaults to 1e-6).
* ``check_syntax_error(testcase, statement)`` - make sure that the
statement is *not* correct Python syntax.
Some Non-Obvious regrtest Features
==================================
* Automagic test detection: When you create a new test file
test_spam.py, you do not need to modify regrtest (or anything else)
to advertise its existence. regrtest searches for and runs all
modules in the test directory with names of the form test_xxx.py.
* Miranda output: If, when running test_spam.py, regrtest does not
find an expected-output file test/output/test_spam, regrtest
pretends that it did find one, containing the single line
test_spam
This allows new tests that don't expect to print anything to stdout
to not bother creating expected-output files.
* Two-stage testing: To run test_spam.py, regrtest imports test_spam
as a module. Most tests run to completion as a side-effect of
getting imported. After importing test_spam, regrtest also executes
``test_spam.test_main()``, if test_spam has a ``test_main`` attribute.
This is rarely required with the "traditional" Python tests, and
you shouldn't create a module global with name test_main unless
you're specifically exploiting this gimmick. This usage does
prove useful with unittest-based tests as well, however; defining
a ``test_main()`` which is run by regrtest and a script-stub in the
test module ("``if __name__ == '__main__': test_main()``") allows
the test to be used like any other Python test and also work
with the unittest.py-as-a-script approach, allowing a developer
to run specific tests from the command line.

4
Lib/test/test_pprint.py
View File

@ -115,10 +115,10 @@ class QueryTestCase(unittest.TestCase):
{}, dict2(), dict3(), {}, dict2(), dict3(),
verify, pprint, verify, pprint,
-6, -6, -6-6j, -1.5, "x", b"x", (3,), [3], {3: 6}, -6, -6, -6-6j, -1.5, "x", b"x", (3,), [3], {3: 6},
(1,2), [3,4], {5: 6, 7: 8}, (1,2), [3,4], {5: 6},
tuple2((1,2)), tuple3((1,2)), tuple3(range(100)), tuple2((1,2)), tuple3((1,2)), tuple3(range(100)),
[3,4], list2([3,4]), list3([3,4]), list3(range(100)), [3,4], list2([3,4]), list3([3,4]), list3(range(100)),
{5: 6, 7: 8}, dict2({5: 6}), dict3({5: 6}), dict2({5: 6}), dict3({5: 6}),
range(10, -11, -1) range(10, -11, -1)
): ):
native = repr(simple) native = repr(simple)

5
Lib/test/test_sys.py
View File

@ -225,6 +225,11 @@ class SysModuleTest(unittest.TestCase):
sys.setdlopenflags(oldflags) sys.setdlopenflags(oldflags)
def test_refcount(self): def test_refcount(self):
# n here must be a global in order for this test to pass while
# tracing with a python function. Tracing calls PyFrame_FastToLocals
# which will add a copy of any locals to the frame object, causing
# the reference count to increase by 2 instead of 1.
global n
self.assertRaises(TypeError, sys.getrefcount) self.assertRaises(TypeError, sys.getrefcount)
c = sys.getrefcount(None) c = sys.getrefcount(None)
n = None n = None

16
Lib/test/test_threading.py
View File

@ -84,11 +84,24 @@ class ThreadTests(unittest.TestCase):
t.join(NUMTASKS) t.join(NUMTASKS)
self.assert_(not t.is_alive()) self.assert_(not t.is_alive())
self.failIfEqual(t.ident, 0) self.failIfEqual(t.ident, 0)
self.assertFalse(t.ident is None)
self.assert_(re.match('<TestThread\(.*, \w+ -?\d+\)>', repr(t))) self.assert_(re.match('<TestThread\(.*, \w+ -?\d+\)>', repr(t)))
if verbose: if verbose:
print('all tasks done') print('all tasks done')
self.assertEqual(numrunning.get(), 0) self.assertEqual(numrunning.get(), 0)
def test_ident_of_no_threading_threads(self):
# The ident still must work for the main thread and dummy threads.
self.assertFalse(threading.currentThread().ident is None)
def f():
ident.append(threading.currentThread().ident)
done.set()
done = threading.Event()
ident = []
_thread.start_new_thread(f, ())
done.wait()
self.assertFalse(ident[0] is None)
# run with a small(ish) thread stack size (256kB) # run with a small(ish) thread stack size (256kB)
def test_various_ops_small_stack(self): def test_various_ops_small_stack(self):
if verbose: if verbose:
@ -187,7 +200,8 @@ class ThreadTests(unittest.TestCase):
# Now raise an exception in the worker thread. # Now raise an exception in the worker thread.
if verbose: if verbose:
print(" waiting for worker thread to get started") print(" waiting for worker thread to get started")
worker_started.wait() ret = worker_started.wait()
self.assertTrue(ret)
if verbose: if verbose:
print(" verifying worker hasn't exited") print(" verifying worker hasn't exited")
self.assert_(not t.finished) self.assert_(not t.finished)

42
Lib/threading.py
View File

@ -375,6 +375,7 @@ class _Event(_Verbose):
try: try:
if not self._flag: if not self._flag:
self._cond.wait(timeout) self._cond.wait(timeout)
return self._flag
finally: finally:
self._cond.release() self._cond.release()
@ -450,9 +451,8 @@ class Thread(_Verbose):
raise RuntimeError("thread already started") raise RuntimeError("thread already started")
if __debug__: if __debug__:
self._note("%s.start(): starting thread", self) self._note("%s.start(): starting thread", self)
_active_limbo_lock.acquire() with _active_limbo_lock:
_limbo[self] = self _limbo[self] = self
_active_limbo_lock.release()
_start_new_thread(self._bootstrap, ()) _start_new_thread(self._bootstrap, ())
self._started.wait() self._started.wait()
@ -485,14 +485,16 @@ class Thread(_Verbose):
return return
raise raise
def _set_ident(self):
self._ident = _get_ident()
def _bootstrap_inner(self): def _bootstrap_inner(self):
try: try:
self._ident = _get_ident() self._set_ident()
self._started.set() self._started.set()
_active_limbo_lock.acquire() with _active_limbo_lock:
_active[self._ident] = self _active[self._ident] = self
del _limbo[self] del _limbo[self]
_active_limbo_lock.release()
if __debug__: if __debug__:
self._note("%s._bootstrap(): thread started", self) self._note("%s._bootstrap(): thread started", self)
@ -721,9 +723,9 @@ class _MainThread(Thread):
def __init__(self): def __init__(self):
Thread.__init__(self, name="MainThread") Thread.__init__(self, name="MainThread")
self._started.set() self._started.set()
_active_limbo_lock.acquire() self._set_ident()
_active[_get_ident()] = self with _active_limbo_lock:
_active_limbo_lock.release() _active[self._ident] = self
def _set_daemon(self): def _set_daemon(self):
return False return False
@ -768,9 +770,9 @@ class _DummyThread(Thread):
self._started.set() self._started.set()
_active_limbo_lock.acquire() self._set_ident()
_active[_get_ident()] = self with _active_limbo_lock:
_active_limbo_lock.release() _active[self._ident] = self
def _set_daemon(self): def _set_daemon(self):
return True return True
@ -791,18 +793,14 @@ def current_thread():
currentThread = current_thread currentThread = current_thread
def active_count(): def active_count():
_active_limbo_lock.acquire() with _active_limbo_lock:
count = len(_active) + len(_limbo) return len(_active) + len(_limbo)
_active_limbo_lock.release()
return count
activeCount = active_count activeCount = active_count
def enumerate(): def enumerate():
_active_limbo_lock.acquire() with _active_limbo_lock:
active = list(_active.values()) + list(_limbo.values()) return list(_active.values()) + list(_limbo.values())
_active_limbo_lock.release()
return active
from _thread import stack_size from _thread import stack_size

1
Misc/ACKS
View File

@ -392,6 +392,7 @@ Pat Knight
Greg Kochanski Greg Kochanski
Damon Kohler Damon Kohler
Joseph Koshy Joseph Koshy
Maksim Kozyarchuk
Bob Kras Bob Kras
Holger Krekel Holger Krekel
Michael Kremer Michael Kremer

21
Misc/developers.txt
View File

@ -17,6 +17,18 @@ the format to accommodate documentation needs as they arise.
Permissions History Permissions History
------------------- -------------------
- Paul Kippes was given commit privileges at PyCon 2009 by BAC to work on 3to2.
- Ron DuPlain was given commit privileges at PyCon 2009 by BAC to work on 3to2.
- Several developers of alternative Python implementations where
given access for test suite and library adaptions by MvL:
Allison Randal (Parrot), Michael Foord (IronPython),
Jim Baker, Philip Jenvey, and Frank Wierzbicki (all Jython).
- R. David Murray was given SVN access on March 30 2009 by MvL, after
recommendation by BAC.
- Chris Withers was given SVN access on March 8 2009 by MvL, - Chris Withers was given SVN access on March 8 2009 by MvL,
after recommendation by GvR. after recommendation by GvR.
@ -244,10 +256,11 @@ Permissions Dropped after Loss of Contact
Initials of Project Admins Initials of Project Admins
-------------------------- --------------------------
GvR: Guido van Rossum
NCN: Neal Norwitz
RDH: Raymond Hettinger
TGP: Tim Peters TGP: Tim Peters
GFB: Georg Brandl
BAC: Brett Cannon
NCN: Neal Norwitz
DJG: David Goodger DJG: David Goodger
MvL: Martin v. Loewis MvL: Martin v. Loewis
GFB: Georg Brandl GvR: Guido van Rossum
RDH: Raymond Hettinger

2
Objects/genobject.c
View File

@ -304,7 +304,7 @@ PyDoc_STRVAR(gen__name__doc__,
"Return the name of the generator's associated code object."); "Return the name of the generator's associated code object.");
static PyGetSetDef gen_getsetlist[] = { static PyGetSetDef gen_getsetlist[] = {
{"__name__", (getter)gen_get_name, NULL, NULL, gen__name__doc__}, {"__name__", (getter)gen_get_name, NULL, gen__name__doc__},
{NULL} {NULL}
}; };

7
configure vendored
View File

@ -1,5 +1,5 @@
#! /bin/sh #! /bin/sh
# From configure.in Revision: 70459 . # From configure.in Revision: 70732 .
# Guess values for system-dependent variables and create Makefiles. # Guess values for system-dependent variables and create Makefiles.
# Generated by GNU Autoconf 2.61 for python 3.1. # Generated by GNU Autoconf 2.61 for python 3.1.
# #
@ -1804,6 +1804,11 @@ ac_config_headers="$ac_config_headers pyconfig.h"
if test "$prefix" != "/"; then
prefix=`echo "$prefix" | sed -e 's/\/$//g'`
fi

9
configure.in
View File

@ -12,6 +12,15 @@ AC_INIT(python, PYTHON_VERSION, http://www.python.org/python-bugs)
AC_CONFIG_SRCDIR([Include/object.h]) AC_CONFIG_SRCDIR([Include/object.h])
AC_CONFIG_HEADER(pyconfig.h) AC_CONFIG_HEADER(pyconfig.h)
dnl Ensure that if prefix is specified, it does not end in a slash. If
dnl it does, we get path names containing '//' which is both ugly and
dnl can cause trouble.
dnl Last slash shouldn't be stripped if prefix=/
if test "$prefix" != "/"; then
prefix=`echo "$prefix" | sed -e 's/\/$//g'`
fi
dnl This is for stuff that absolutely must end up in pyconfig.h. dnl This is for stuff that absolutely must end up in pyconfig.h.
dnl Please use pyport.h instead, if possible. dnl Please use pyport.h instead, if possible.
AH_TOP([ AH_TOP([