Changeset 391 for python/trunk/Doc/whatsnew/2.5.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/whatsnew/2.5.rst (modified) (21 diffs)

python/trunk/Doc/whatsnew/2.5.rst

@@ -871 +871 @@
 ========================================
 
-A wide-ranging change to Python's C API, using a new  :ctype:`Py_ssize_t` type
-definition instead of :ctype:`int`,  will permit the interpreter to handle more
+A wide-ranging change to Python's C API, using a new  :c:type:`Py_ssize_t` type
+definition instead of :c:type:`int`,  will permit the interpreter to handle more
 data on 64-bit platforms. This change doesn't affect Python's capacity on 32-bit
 platforms.
 
-Various pieces of the Python interpreter used C's :ctype:`int` type to store
+Various pieces of the Python interpreter used C's :c:type:`int` type to store
 sizes or counts; for example, the number of items in a list or tuple were stored
-in an :ctype:`int`.  The C compilers for most 64-bit platforms still define
-:ctype:`int` as a 32-bit type, so that meant that lists could only hold up to
+in an :c:type:`int`.  The C compilers for most 64-bit platforms still define
+:c:type:`int` as a 32-bit type, so that meant that lists could only hold up to
 ``2**31 - 1`` = 2147483647 items. (There are actually a few different
 programming models that 64-bit C compilers can use -- see
 http://www.unix.org/version2/whatsnew/lp64_wp.html for a discussion -- but the
-most commonly available model leaves :ctype:`int` as 32 bits.)
+most commonly available model leaves :c:type:`int` as 32 bits.)
 
 A limit of 2147483647 items doesn't really matter on a 32-bit platform because
 you'll run out of memory before hitting the length limit. Each list item
 requires space for a pointer, which is 4 bytes, plus space for a
-:ctype:`PyObject` representing the item.  2147483647\*4 is already more bytes
+:c:type:`PyObject` representing the item.  2147483647\*4 is already more bytes
 than a 32-bit address space can contain.
 
@@ -895 +895 @@
 unreasonable that Python programmers might construct lists that large.
 Therefore, the Python interpreter had to be changed to use some type other than
-:ctype:`int`, and this will be a 64-bit type on 64-bit platforms.  The change
+:c:type:`int`, and this will be a 64-bit type on 64-bit platforms.  The change
 will cause incompatibilities on 64-bit machines, so it was deemed worth making
 the transition now, while the number of 64-bit users is still relatively small.
@@ -903 +903 @@
 This change most strongly affects authors of C extension modules.   Python
 strings and container types such as lists and tuples  now use
-:ctype:`Py_ssize_t` to store their size.   Functions such as
-:cfunc:`PyList_Size`  now return :ctype:`Py_ssize_t`.  Code in extension modules
-may therefore need to have some variables changed to :ctype:`Py_ssize_t`.
-
-The :cfunc:`PyArg_ParseTuple` and :cfunc:`Py_BuildValue` functions have a new
-conversion code, ``n``, for :ctype:`Py_ssize_t`.   :cfunc:`PyArg_ParseTuple`'s
-``s#`` and ``t#`` still output :ctype:`int` by default, but you can define the
-macro  :cmacro:`PY_SSIZE_T_CLEAN` before including :file:`Python.h`  to make
-them return :ctype:`Py_ssize_t`.
+:c:type:`Py_ssize_t` to store their size.   Functions such as
+:c:func:`PyList_Size`  now return :c:type:`Py_ssize_t`.  Code in extension modules
+may therefore need to have some variables changed to :c:type:`Py_ssize_t`.
+
+The :c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` functions have a new
+conversion code, ``n``, for :c:type:`Py_ssize_t`.   :c:func:`PyArg_ParseTuple`'s
+``s#`` and ``t#`` still output :c:type:`int` by default, but you can define the
+macro  :c:macro:`PY_SSIZE_T_CLEAN` before including :file:`Python.h`  to make
+them return :c:type:`Py_ssize_t`.
 
 :pep:`353` has a section on conversion guidelines that  extension authors should
@@ -955 +955 @@
 
 A corresponding :attr:`nb_index` slot was added to the C-level
-:ctype:`PyNumberMethods` structure to let C extensions implement this protocol.
-:cfunc:`PyNumber_Index(obj)` can be used in extension code to call the
+:c:type:`PyNumberMethods` structure to let C extensions implement this protocol.
+:c:func:`PyNumber_Index(obj)` can be used in extension code to call the
 :meth:`__index__` function and retrieve its result.
 
@@ -1180 +1180 @@
 
 * The :mod:`re` module got a 1 or 2% speedup by switching to  Python's allocator
-  functions instead of the system's  :cfunc:`malloc` and :cfunc:`free`.
+  functions instead of the system's  :c:func:`malloc` and :c:func:`free`.
   (Contributed by Jack Diederich at the NeedForSpeed sprint.)
 
@@ -1204 +1204 @@
 
 * Importing now caches the paths tried, recording whether  they exist or not so
-  that the interpreter makes fewer  :cfunc:`open` and :cfunc:`stat` calls on
+  that the interpreter makes fewer  :c:func:`open` and :c:func:`stat` calls on
   startup. (Contributed by Martin von Löwis and Georg Brandl.)
 
@@ -1339 +1339 @@
   .. XXX need to provide some more detail here
 
+  .. index::
+     single: universal newlines; What's new
+
 * The :mod:`fileinput` module was made more flexible. Unicode filenames are now
   supported, and a *mode* parameter that defaults to ``"r"`` was added to the
-  :func:`input` function to allow opening files in binary or universal-newline
-  mode.  Another new parameter, *openhook*, lets you use a function other than
-  :func:`open`  to open the input files.  Once you're iterating over  the set of
-  files, the :class:`FileInput` object's new :meth:`fileno` returns the file
-  descriptor for the currently opened file. (Contributed by Georg Brandl.)
+  :func:`input` function to allow opening files in binary or :term:`universal
+  newlines` mode.  Another new parameter, *openhook*, lets you use a function
+  other than :func:`open`  to open the input files.  Once you're iterating over
+  the set of files, the :class:`FileInput` object's new :meth:`fileno` returns
+  the file descriptor for the currently opened file. (Contributed by Georg
+  Brandl.)
 
 * In the :mod:`gc` module, the new :func:`get_count` function returns a 3-tuple
@@ -1460 +1464 @@
   On FreeBSD, the :func:`os.stat` function now returns  times with nanosecond
   resolution, and the returned object now has :attr:`st_gen` and
-  :attr:`st_birthtime`. The :attr:`st_flags` member is also available, if the
+  :attr:`st_birthtime`. The :attr:`st_flags` attribute is also available, if the
   platform supports it. (Contributed by Antti Louko and  Diego Pettenò.)
 
@@ -1569 +1573 @@
 
   This information is also available to C extensions via the
-  :cfunc:`Py_GetBuildInfo` function that returns a  string of build information
+  :c:func:`Py_GetBuildInfo` function that returns a  string of build information
   like this: ``"trunk:45355:45356M, Apr 13 2006, 07:42:19"``.   (Contributed by
   Barry Warsaw.)
@@ -1691 +1695 @@
 
 Type constructors for the various C types are provided: :func:`c_int`,
-:func:`c_float`, :func:`c_double`, :func:`c_char_p` (equivalent to :ctype:`char
+:func:`c_float`, :func:`c_double`, :func:`c_char_p` (equivalent to :c:type:`char
 \*`), and so forth.  Unlike Python's types, the C versions are all mutable; you
 can assign to their :attr:`value` attribute to change the wrapped value.  Python
@@ -1721 +1725 @@
 interpreter lock before calling a function, because the lock must be held when
 calling into the interpreter's code.   There's a :class:`py_object()` type
-constructor that will create a  :ctype:`PyObject \*` pointer.  A simple usage::
+constructor that will create a  :c:type:`PyObject \*` pointer.  A simple usage::
 
    import ctypes
@@ -1766 +1770 @@
 
 ElementTree represents an XML document as a tree of element nodes. The text
-content of the document is stored as the :attr:`.text` and :attr:`.tail`
+content of the document is stored as the :attr:`text` and :attr:`tail`
 attributes of  (This is one of the major differences between ElementTree and
 the Document Object Model; in the DOM there are many different types of node,
@@ -2088 +2092 @@
 
 * The largest change to the C API came from :pep:`353`, which modifies the
-  interpreter to use a :ctype:`Py_ssize_t` type definition instead of
-  :ctype:`int`.  See the earlier section :ref:`pep-353` for a discussion of this
+  interpreter to use a :c:type:`Py_ssize_t` type definition instead of
+  :c:type:`int`.  See the earlier section :ref:`pep-353` for a discussion of this
   change.
 
@@ -2114 +2118 @@
   the various AST nodes in :file:`Parser/Python.asdl`.  A Python script reads this
   file and generates a set of C structure definitions in
-  :file:`Include/Python-ast.h`.  The :cfunc:`PyParser_ASTFromString` and
-  :cfunc:`PyParser_ASTFromFile`, defined in :file:`Include/pythonrun.h`, take
+  :file:`Include/Python-ast.h`.  The :c:func:`PyParser_ASTFromString` and
+  :c:func:`PyParser_ASTFromFile`, defined in :file:`Include/pythonrun.h`, take
   Python source as input and return the root of an AST representing the contents.
-  This AST can then be turned into a code object by :cfunc:`PyAST_Compile`.  For
+  This AST can then be turned into a code object by :c:func:`PyAST_Compile`.  For
   more information, read the source code, and then ask questions on python-dev.
 
@@ -2139 +2143 @@
   Note that this change means extension modules must be more careful when
   allocating memory.  Python's API has many different functions for allocating
-  memory that are grouped into families.  For example, :cfunc:`PyMem_Malloc`,
-  :cfunc:`PyMem_Realloc`, and :cfunc:`PyMem_Free` are one family that allocates
-  raw memory, while :cfunc:`PyObject_Malloc`, :cfunc:`PyObject_Realloc`, and
-  :cfunc:`PyObject_Free` are another family that's supposed to be used for
+  memory that are grouped into families.  For example, :c:func:`PyMem_Malloc`,
+  :c:func:`PyMem_Realloc`, and :c:func:`PyMem_Free` are one family that allocates
+  raw memory, while :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc`, and
+  :c:func:`PyObject_Free` are another family that's supposed to be used for
   creating Python objects.
 
   Previously these different families all reduced to the platform's
-  :cfunc:`malloc` and :cfunc:`free` functions.  This meant  it didn't matter if
-  you got things wrong and allocated memory with the :cfunc:`PyMem` function but
-  freed it with the :cfunc:`PyObject` function.  With 2.5's changes to obmalloc,
+  :c:func:`malloc` and :c:func:`free` functions.  This meant  it didn't matter if
+  you got things wrong and allocated memory with the :c:func:`PyMem` function but
+  freed it with the :c:func:`PyObject` function.  With 2.5's changes to obmalloc,
   these families now do different things and mismatches will probably result in a
   segfault.  You should carefully test your C extension modules with Python 2.5.
 
-* The built-in set types now have an official C API.  Call :cfunc:`PySet_New`
-  and :cfunc:`PyFrozenSet_New` to create a new set, :cfunc:`PySet_Add` and
-  :cfunc:`PySet_Discard` to add and remove elements, and :cfunc:`PySet_Contains`
-  and :cfunc:`PySet_Size` to examine the set's state. (Contributed by Raymond
+* The built-in set types now have an official C API.  Call :c:func:`PySet_New`
+  and :c:func:`PyFrozenSet_New` to create a new set, :c:func:`PySet_Add` and
+  :c:func:`PySet_Discard` to add and remove elements, and :c:func:`PySet_Contains`
+  and :c:func:`PySet_Size` to examine the set's state. (Contributed by Raymond
   Hettinger.)
 
 * C code can now obtain information about the exact revision of the Python
-  interpreter by calling the  :cfunc:`Py_GetBuildInfo` function that returns a
+  interpreter by calling the  :c:func:`Py_GetBuildInfo` function that returns a
   string of build information like this: ``"trunk:45355:45356M, Apr 13 2006,
   07:42:19"``.   (Contributed by Barry Warsaw.)
@@ -2165 +2169 @@
 * Two new macros can be used to indicate C functions that are local to the
   current file so that a faster calling convention can be used.
-  :cfunc:`Py_LOCAL(type)` declares the function as returning a value of the
+  :c:func:`Py_LOCAL(type)` declares the function as returning a value of the
   specified *type* and uses a fast-calling qualifier.
-  :cfunc:`Py_LOCAL_INLINE(type)` does the same thing and also requests the
-  function be inlined.  If :cfunc:`PY_LOCAL_AGGRESSIVE` is defined before
+  :c:func:`Py_LOCAL_INLINE(type)` does the same thing and also requests the
+  function be inlined.  If :c:func:`PY_LOCAL_AGGRESSIVE` is defined before
   :file:`python.h` is included, a set of more aggressive optimizations are enabled
   for the module; you should benchmark the results to find out if these
@@ -2174 +2178 @@
   the NeedForSpeed sprint.)
 
-* :cfunc:`PyErr_NewException(name, base, dict)` can now accept a tuple of base
+* :c:func:`PyErr_NewException(name, base, dict)` can now accept a tuple of base
   classes as its *base* argument.  (Contributed by Georg Brandl.)
 
-* The :cfunc:`PyErr_Warn` function for issuing warnings is now deprecated in
-  favour of :cfunc:`PyErr_WarnEx(category, message, stacklevel)` which lets you
+* The :c:func:`PyErr_Warn` function for issuing warnings is now deprecated in
+  favour of :c:func:`PyErr_WarnEx(category, message, stacklevel)` which lets you
   specify the number of stack frames separating this function and the caller.  A
-  *stacklevel* of 1 is the function calling :cfunc:`PyErr_WarnEx`, 2 is the
+  *stacklevel* of 1 is the function calling :c:func:`PyErr_WarnEx`, 2 is the
   function above that, and so forth.  (Added by Neal Norwitz.)
 
@@ -2187 +2191 @@
   Martin von Löwis, Skip Montanaro.)
 
-* The :cfunc:`PyRange_New` function was removed.  It was never documented, never
+* The :c:func:`PyRange_New` function was removed.  It was never documented, never
   used in the core code, and had dangerously lax error checking.  In the unlikely
   case that your extensions were using it, you can replace it by something like
@@ -2204 +2208 @@
 
 * MacOS X (10.3 and higher): dynamic loading of modules now uses the
-  :cfunc:`dlopen` function instead of MacOS-specific functions.
+  :c:func:`dlopen` function instead of MacOS-specific functions.
 
 * MacOS X: an :option:`--enable-universalsdk` switch was added to the
@@ -2260 +2264 @@
   checking.
 
-* C API: Many functions now use :ctype:`Py_ssize_t`  instead of :ctype:`int` to
+* C API: Many functions now use :c:type:`Py_ssize_t`  instead of :c:type:`int` to
   allow processing more data on 64-bit machines.  Extension code may need to make
   the same change to avoid warnings and to support 64-bit machines.  See the
@@ -2266 +2270 @@
 
 * C API:  The obmalloc changes mean that  you must be careful to not mix usage
-  of the :cfunc:`PyMem_\*` and :cfunc:`PyObject_\*` families of functions. Memory
-  allocated with  one family's :cfunc:`\*_Malloc` must be  freed with the
-  corresponding family's :cfunc:`\*_Free` function.
+  of the :c:func:`PyMem_\*` and :c:func:`PyObject_\*` families of functions. Memory
+  allocated with  one family's :c:func:`\*_Malloc` must be  freed with the
+  corresponding family's :c:func:`\*_Free` function.
 
 .. ======================================================================