mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-03 08:34:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

Remove many "versionchanged" items that didn't use the official markup,

Browse source 
but just some text embedded in the docs.

Also remove paragraph about implicit relative imports from tutorial.
This commit is contained in:
Georg Brandl 2008-05-12 18:05:20 +00:00
parent c73728373c
commit e6bcc9145e
52 changed files with 147 additions and 469 deletions
Download patch file Download diff file Expand all files Collapse all files

6
Doc/c-api/dict.rst
View file

@ -153,9 +153,9 @@ Dictionary Objects
...
}
The dictionary *p* should not be mutated during iteration. It is safe (since
Python 2.1) to modify the values of the keys as you iterate over the dictionary,
but only so long as the set of keys does not change. For example::
The dictionary *p* should not be mutated during iteration. It is safe to
modify the values of the keys as you iterate over the dictionary, but only so
long as the set of keys does not change. For example::
PyObject *key, *value;
Py_ssize_t pos = 0;

1
Doc/c-api/exceptions.rst
View file

@ -147,7 +147,6 @@ in various ways. There is a separate error indicator for each thread.
.. % The descriptions for %zd and %zu are wrong, but the truth is complicated
.. % because not all compilers support the %z width modifier -- we fake it
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
.. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+-------------------+---------------+--------------------------------+
| Format Characters | Type | Comment |

23
Doc/c-api/import.rst
View file

@ -22,10 +22,8 @@ Importing Modules
be the case. (Unfortunately, this has an additional side effect when *name* in
fact specifies a subpackage instead of a submodule: the submodules specified in
the package's ``__all__`` variable are loaded.) Return a new reference to the
imported module, or *NULL* with an exception set on failure. Before Python 2.4,
the module may still be created in the failure case --- examine ``sys.modules``
to find out. Starting with Python 2.4, a failing import of a module no longer
leaves the module in ``sys.modules``.
imported module, or *NULL* with an exception set on failure. A failing
import of a module doesn't leave the module in :data:`sys.modules`.
.. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
@ -47,11 +45,11 @@ Importing Modules
function :func:`__import__`, as the standard :func:`__import__` function calls
this function directly.
The return value is a new reference to the imported module or top-level package,
or *NULL* with an exception set on failure (before Python 2.4, the module may
still be created in this case). Like for :func:`__import__`, the return value
when a submodule of a package was requested is normally the top-level package,
unless a non-empty *fromlist* was given.
The return value is a new reference to the imported module or top-level
package, or *NULL* with an exception set on failure. Like for
:func:`__import__`, the return value when a submodule of a package was
requested is normally the top-level package, unless a non-empty *fromlist*
was given.
Failing imports remove incomplete module objects, like with
:cfunc:`PyImport_ImportModule`.
@ -106,9 +104,8 @@ Importing Modules
Given a module name (possibly of the form ``package.module``) and a code object
read from a Python bytecode file or obtained from the built-in function
:func:`compile`, load the module. Return a new reference to the module object,
or *NULL* with an exception set if an error occurred. Before Python 2.4, the
module could still be created in error cases. Starting with Python 2.4, *name*
is removed from :attr:`sys.modules` in error cases, and even if *name* was already
or *NULL* with an exception set if an error occurred. *name*
is removed from :attr:`sys.modules` in error cases, even if *name* was already
in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`. Leaving
incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
such modules have no way to know that the module object is an unknown (and
@ -144,8 +141,6 @@ Importing Modules
Cache the result in :data:`sys.path_importer_cache`. Return a new reference
to the importer object.
.. versionadded:: 2.6
.. cfunction:: void _PyImport_Init()

24
Doc/c-api/init.rst
View file

@ -273,14 +273,14 @@ Initialization, Finalization, and Threads
Return the version of this Python interpreter. This is a string that looks
something like ::
"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"
.. index:: single: version (in module sys)
The first word (up to the first space character) is the current Python version;
the first three characters are the major and minor version separated by a
period. The returned string points into static storage; the caller should not
modify its value. The value is available to Python code as ``sys.version``.
modify its value. The value is available to Python code as :data:`sys.version`.
.. cfunction:: const char* Py_GetBuildNumber()
@ -479,9 +479,9 @@ the lock, and finally storing their thread state pointer, before they can start
using the Python/C API. When they are done, they should reset the thread state
pointer, release the lock, and finally free their thread state data structure.
Beginning with version 2.3, threads can now take advantage of the
:cfunc:`PyGILState_\*` functions to do all of the above automatically. The
typical idiom for calling into Python from a C thread is now::
Threads can take advantage of the :cfunc:`PyGILState_\*` functions to do all of
the above automatically. The typical idiom for calling into Python from a C
thread is now::
PyGILState_STATE gstate;
gstate = PyGILState_Ensure();
@ -777,14 +777,12 @@ The Python interpreter provides some low-level support for attaching profiling
and execution tracing facilities. These are used for profiling, debugging, and
coverage analysis tools.
Starting with Python 2.2, the implementation of this facility was substantially
revised, and an interface from C was added. This C interface allows the
profiling or tracing code to avoid the overhead of calling through Python-level
callable objects, making a direct C function call instead. The essential
attributes of the facility have not changed; the interface allows trace
functions to be installed per-thread, and the basic events reported to the trace
function are the same as had been reported to the Python-level trace functions
in previous versions.
This C interface allows the profiling or tracing code to avoid the overhead of
calling through Python-level callable objects, making a direct C function call
instead. The essential attributes of the facility have not changed; the
interface allows trace functions to be installed per-thread, and the basic
events reported to the trace function are the same as had been reported to the
Python-level trace functions in previous versions.
.. ctype:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

6
Doc/c-api/marshal.rst
View file

@ -13,9 +13,9 @@ back. Files used to store marshalled data must be opened in binary mode.
Numeric values are stored with the least significant byte first.
The module supports two versions of the data format: version 0 is the historical
version, version 1 (new in Python 2.4) shares interned strings in the file, and
upon unmarshalling. *Py_MARSHAL_VERSION* indicates the current file format
(currently 1).
version, version 1 shares interned strings in the file, and upon unmarshalling.
Version 2 uses a binary format for floating point numbers.
*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)

2
Doc/c-api/number.rst
View file

@ -267,8 +267,6 @@ Number Protocol
base. If *n* is not an int object, it is converted with
:cfunc:`PyNumber_Index` first.
.. versionadded:: 2.6
.. cfunction:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)

18
Doc/c-api/set.rst
View file

@ -93,10 +93,6 @@ the constructor functions work with any iterable Python object.
set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is
not actually iterable.
.. versionchanged:: 2.6
Now guaranteed to return a brand-new :class:`frozenset`. Formerly,
frozensets of zero-length were a singleton. This got in the way of
building-up new frozensets with :meth:`PySet_Add`.
The following functions and macros are available for instances of :class:`set`
or :class:`frozenset` or instances of their subtypes.
@ -127,16 +123,14 @@ or :class:`frozenset` or instances of their subtypes.
.. cfunction:: int PySet_Add(PyObject *set, PyObject *key)
Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset`
instances. Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if
the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its
Add *key* to a :class:`set` instance. Also works with :class:`frozenset`
instances (like :cfunc:`PyTuple_SetItem` it can be used to fill-in the values
of brand new frozensets before they are exposed to other code). Return 0 on
success or -1 on failure. Raise a :exc:`TypeError` if the *key* is
unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a
:exc:`SystemError` if *set* is an not an instance of :class:`set` or its
subtype.
.. versionchanged:: 2.6
Now works with instances of :class:`frozenset` or its subtypes.
Like :cfunc:`PyTuple_SetItem` in that it can be used to fill-in the
values of brand new frozensets before they are exposed to other code.
The following functions are available for instances of :class:`set` or its
subtypes but not for instances of :class:`frozenset` or its subtypes.

5
Doc/c-api/slice.rst
View file

@ -38,10 +38,7 @@ Slice Objects
indices was not :const:`None` and failed to be converted to an integer, in which
case -1 is returned with an exception set).
You probably do not want to use this function. If you want to use slice objects
in versions of Python prior to 2.3, you would probably do well to incorporate
the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of
your extension.
You probably do not want to use this function.
.. cfunction:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)

1
Doc/c-api/string.rst
View file

@ -63,7 +63,6 @@ called with a non-string parameter.
.. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated
.. % because not all compilers support the %z width modifier -- we fake it
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
.. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+-------------------+---------------+--------------------------------+
| Format Characters | Type | Comment |

138
Doc/c-api/typeobj.rst
View file

@ -80,12 +80,10 @@ type objects) *must* have the :attr:`ob_size` field.
This should be done before any instances of the type are created.
:cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,
initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1
and later it is initialized to the :attr:`ob_type` field of the base class.
initializes it to the :attr:`ob_type` field of the base class.
:cfunc:`PyType_Ready` will not change this field if it is non-zero.
In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3
and beyond, it is inherited by subtypes.
This field is inherited by subtypes.
.. cmember:: Py_ssize_t PyVarObject.ob_size
@ -150,8 +148,7 @@ type objects) *must* have the :attr:`ob_size` field.
:attr:`_ob_next` fields if they are present. This means that the only correct
way to get an initializer for the :attr:`tp_basicsize` is to use the
``sizeof`` operator on the struct used to declare the instance layout.
The basic size does not include the GC header size (this is new in Python 2.2;
in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`).
The basic size does not include the GC header size.
These fields are inherited separately by subtypes. If the base type has a
non-zero :attr:`tp_itemsize`, it is generally not safe to set
@ -415,9 +412,8 @@ type objects) *must* have the :attr:`ob_size` field.
structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the
:const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
:attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as
indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL*
values.
:attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist and have
*NULL* values.
The following bit masks are currently defined; these can be ORed together using
the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro
@ -425,68 +421,6 @@ type objects) *must* have the :attr:`ob_size` field.
checks whether ``tp->tp_flags & f`` is non-zero.
.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
If this bit is set, the :ctype:`PyBufferProcs` struct referenced by
:attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field.
.. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN
If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
:attr:`tp_as_sequence` has the :attr:`sq_contains` field.
.. data:: Py_TPFLAGS_GC
This bit is obsolete. The bit it used to name is no longer in use. The symbol
is now defined as zero.
.. data:: Py_TPFLAGS_HAVE_INPLACEOPS
If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
:attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by
:attr:`tp_as_number` contain the fields for in-place operators. In particular,
this means that the :ctype:`PyNumberMethods` structure has the fields
:attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,
:attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,
:attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,
:attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,
:attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the
:ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and
:attr:`sq_inplace_repeat`.
.. data:: Py_TPFLAGS_HAVE_RICHCOMPARE
If this bit is set, the type object has the :attr:`tp_richcompare` field, as
well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields.
.. data:: Py_TPFLAGS_HAVE_WEAKREFS
If this bit is set, the :attr:`tp_weaklistoffset` field is defined. Instances
of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field
has a value greater than zero.
.. data:: Py_TPFLAGS_HAVE_ITER
If this bit is set, the type object has the :attr:`tp_iter` and
:attr:`tp_iternext` fields.
.. data:: Py_TPFLAGS_HAVE_CLASS
If this bit is set, the type object has several new fields defined starting in
Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`,
:attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`,
:attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`,
:attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`,
:attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`.
.. data:: Py_TPFLAGS_HEAPTYPE
This bit is set when the type object itself is allocated on the heap. In this
@ -523,19 +457,15 @@ type objects) *must* have the :attr:`ob_size` field.
destroyed using :cfunc:`PyObject_GC_Del`. More information in section
:ref:`supporting-cycle-detection`. This bit also implies that the
GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in
the type object; but those fields also exist when
:const:`Py_TPFLAGS_HAVE_GC` is clear but
:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set.
the type object.
.. data:: Py_TPFLAGS_DEFAULT
This is a bitmask of all the bits that pertain to the existence of certain
fields in the type object and its extension structures. Currently, it includes
the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`,
:const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`,
:const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`,
:const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`.
the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`,
:const:`Py_TPFLAGS_HAVE_VERSION_TAG`.
.. cmember:: char* PyTypeObject.tp_doc
@ -546,9 +476,6 @@ type objects) *must* have the :attr:`ob_size` field.
This field is *not* inherited by subtypes.
The following three fields only exist if the
:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.
.. cmember:: traverseproc PyTypeObject.tp_traverse
@ -587,8 +514,7 @@ The following three fields only exist if the
This field is inherited by subtypes together with :attr:`tp_clear` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
:attr:`tp_clear` are all inherited from the base type if they are all zero in
the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
bit set.
the subtype.
.. cmember:: inquiry PyTypeObject.tp_clear
@ -643,8 +569,7 @@ The following three fields only exist if the
This field is inherited by subtypes together with :attr:`tp_traverse` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
:attr:`tp_clear` are all inherited from the base type if they are all zero in
the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
bit set.
the subtype.
.. cmember:: richcmpfunc PyTypeObject.tp_richcompare
@ -688,9 +613,6 @@ The following three fields only exist if the
+----------------+------------+
The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
set.
.. cmember:: long PyTypeObject.tp_weaklistoffset
If the instances of this type are weakly referenceable, this field is greater
@ -722,9 +644,6 @@ set.
:attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its
base type.
The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is
set.
.. cmember:: getiterfunc PyTypeObject.tp_iter
@ -753,9 +672,6 @@ set.
This field is inherited by subtypes.
The next fields, up to and including :attr:`tp_weaklist`, only exist if the
:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.
.. cmember:: struct PyMethodDef* PyTypeObject.tp_methods
@ -933,10 +849,7 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the
has returned an instance of the type. If the :attr:`tp_new` function returns an
instance of some other type that is not a subtype of the original type, no
:attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a
subtype of the original type, the subtype's :attr:`tp_init` is called. (VERSION
NOTE: described here is what is implemented in Python 2.2.1 and later. In
Python 2.2, the :attr:`tp_init` of the type of the object returned by
:attr:`tp_new` was always called, if not *NULL*.)
subtype of the original type, the subtype's :attr:`tp_init` is called.
This field is inherited by subtypes.
@ -995,26 +908,17 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the
deferred to :attr:`tp_init`.
This field is inherited by subtypes, except it is not inherited by static types
whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``. The latter exception
is a precaution so that old extension types don't become callable simply by
being linked with Python 2.2.
whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``.
.. cmember:: destructor PyTypeObject.tp_free
An optional pointer to an instance deallocation function.
The signature of this function has changed slightly: in Python 2.2 and 2.2.1,
its signature is :ctype:`destructor`::
void tp_free(PyObject *)
In Python 2.3 and beyond, its signature is :ctype:`freefunc`::
An optional pointer to an instance deallocation function. Its signature is
:ctype:`freefunc`::
void tp_free(void *)
The only initializer that is compatible with both versions is ``PyObject_Free``,
whose definition has suitably adapted in Python 2.3.
An initializer that is compatible with this signature is :cfunc:`PyObject_Free`.
This field is inherited by static subtypes, but not by dynamic subtypes
(subtypes created by a class statement); in the latter, this field is set to a
@ -1040,8 +944,7 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the
:cdata:`PyType_Type`, defines this function to distinguish between statically
and dynamically allocated types.)
This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not
inherited. It is inherited in 2.2.1 and later versions.)
This field is inherited by subtypes.
.. cmember:: PyObject* PyTypeObject.tp_bases
@ -1309,7 +1212,7 @@ member in the :ctype:`PyTypeObject` structure should be *NULL*. Otherwise, the
did not have this member, so a new Python interpreter using an old extension
needs to be able to test for its presence before using it.
.. XXX out of date!
.. ctype:: PyBufferProcs
Structure used to hold the function pointers which define an implementation of
@ -1352,13 +1255,6 @@ member in the :ctype:`PyTypeObject` structure should be *NULL*. Otherwise, the
characters present.
.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
Flag bit set in the type structure to indicate that the :attr:`bf_getcharbuffer`
slot is known. This being set does not indicate that the object supports the
buffer interface or that the :attr:`bf_getcharbuffer` slot is non-*NULL*.
.. ctype:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
Return a pointer to a readable segment of the buffer in ``*ptrptr``. This