Skip to content

C
cpython
Commit 321976b6 authored by Georg Brandl's avatar Georg Brandl
Browse files
Options

Remove versionadded and versionchanged directives, fold information into text where necessary.

parent 2326a79d
Expand all Show whitespace changes
Inline Side-by-side
Showing with 41 additions and 442 deletions
Doc/c-api/abstract.rst
View file @ 321976b6
......@@ -170,10 +170,6 @@ Object Protocol
of the value of that attribute with *cls* will be used to determine the result
of this function.
.. versionadded:: 2.1
.. versionchanged:: 2.2
Support for a tuple as the second argument added.
Subclass determination is done in a fairly straightforward way, but includes a
wrinkle that implementors of extensions to the class system may want to be aware
......@@ -196,11 +192,6 @@ is considered sufficient for this determination.
``0``. If either *derived* or *cls* is not an actual class object (or tuple),
this function uses the generic algorithm described above.
.. versionadded:: 2.1
.. versionchanged:: 2.3
Older versions of Python did not support a tuple as the second argument.
.. cfunction:: int PyCallable_Check(PyObject *o)
......@@ -217,8 +208,6 @@ is considered sufficient for this determination.
success, or *NULL* on failure. This is the equivalent of the Python expression
``callable_object(*args, **kw)``.
.. versionadded:: 2.2
.. cfunction:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
......@@ -257,8 +246,6 @@ is considered sufficient for this determination.
of parameters followed by *NULL*. Returns the result of the call on success, or
*NULL* on failure.
.. versionadded:: 2.2
.. cfunction:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
......@@ -268,8 +255,6 @@ is considered sufficient for this determination.
of parameters followed by *NULL*. Returns the result of the call on success, or
*NULL* on failure.
.. versionadded:: 2.2
.. cfunction:: long PyObject_Hash(PyObject *o)
......@@ -311,8 +296,6 @@ is considered sufficient for this determination.
Return true if the object *o* is of type *type* or a subtype of *type*. Both
parameters must be non-*NULL*.
.. versionadded:: 2.2
.. cfunction:: Py_ssize_t PyObject_Length(PyObject *o)
Py_ssize_t PyObject_Size(PyObject *o)
......@@ -408,8 +391,6 @@ Number Protocol
Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is
equivalent to the "classic" division of integers.
.. versionadded:: 2.2
.. cfunction:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
......@@ -419,8 +400,6 @@ Number Protocol
numbers in base two. This function can return a floating point value when
passed two integers.
.. versionadded:: 2.2
.. cfunction:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
......@@ -536,8 +515,6 @@ Number Protocol
The operation is done *in-place* when *o1* supports it. This is the equivalent
of the Python statement ``o1 //= o2``.
.. versionadded:: 2.2
.. cfunction:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
......@@ -547,8 +524,6 @@ Number Protocol
numbers in base two. This function can return a floating point value when
passed two integers. The operation is done *in-place* when *o1* supports it.
.. versionadded:: 2.2
.. cfunction:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
......@@ -633,8 +608,6 @@ Number Protocol
Returns the *o* converted to a Python int or long on success or *NULL* with a
TypeError exception raised on failure.
.. versionadded:: 2.5
.. cfunction:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
......@@ -646,16 +619,12 @@ Number Protocol
exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
integer or *PY_SSIZE_T_MAX* for a positive integer.
.. versionadded:: 2.5
.. cfunction:: int PyIndex_Check(PyObject *o)
Returns True if *o* is an index integer (has the nb_index slot of the
tp_as_number structure filled in).
.. versionadded:: 2.5
.. _sequence:
......@@ -801,8 +770,6 @@ Sequence Protocol
Return the underlying array of PyObject pointers. Assumes that *o* was returned
by :cfunc:`PySequence_Fast` and *o* is not *NULL*.
.. versionadded:: 2.4
.. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
......@@ -811,8 +778,6 @@ Sequence Protocol
:cfunc:`PySequence_Check(o)` is true and without adjustment for negative
indices.
.. versionadded:: 2.3
.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
......@@ -906,11 +871,8 @@ Mapping Protocol
Iterator Protocol
=================
.. versionadded:: 2.2
There are only a couple of functions specifically for working with iterators.
.. cfunction:: int PyIter_Check(PyObject *o)
Return true if the object *o* supports the iterator protocol.
......@@ -965,8 +927,6 @@ Buffer Protocol
*buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:`TypeError`
on error.
.. versionadded:: 1.6
.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
......@@ -975,16 +935,12 @@ Buffer Protocol
success, returns ``0``, sets *buffer* to the memory location and *buffer_len* to
the buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
.. versionadded:: 1.6
.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
Returns ``1`` if *o* supports the single-segment readable buffer interface.
Otherwise returns ``0``.
.. versionadded:: 2.2
.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
......@@ -993,5 +949,3 @@ Buffer Protocol
``0``, sets *buffer* to the memory location and *buffer_len* to the buffer
length. Returns ``-1`` and sets a :exc:`TypeError` on error.
.. versionadded:: 1.6
Doc/c-api/concrete.rst
View file @ 321976b6
This diff is collapsed.
Doc/c-api/exceptions.rst
View file @ 321976b6
......@@ -257,8 +257,6 @@ in various ways. There is a separate error indicator for each thread.
Similar to :cfunc:`PyErr_SetFromWindowsErr`, with an additional parameter
specifying the exception type to be raised. Availability: Windows.
.. versionadded:: 2.3
.. cfunction:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
......@@ -272,8 +270,6 @@ in various ways. There is a separate error indicator for each thread.
Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional
parameter specifying the exception type to be raised. Availability: Windows.
.. versionadded:: 2.3
.. cfunction:: void PyErr_BadInternalCall()
......@@ -399,7 +395,7 @@ the variables:
+------------------------------------+----------------------------+----------+
| C Name | Python Name | Notes |
+====================================+============================+==========+
| :cdata:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |
| :cdata:`PyExc_BaseException` | :exc:`BaseException` | \(1) |
+------------------------------------+----------------------------+----------+
| :cdata:`PyExc_Exception` | :exc:`Exception` | \(1) |
+------------------------------------+----------------------------+----------+
......@@ -497,19 +493,3 @@ Notes:
(3)
Only defined on Windows; protect code that uses this by testing that the
preprocessor macro ``MS_WINDOWS`` is defined.
(4)
.. versionadded:: 2.5
Deprecation of String Exceptions
================================
.. index:: single: BaseException (built-in exception)
All exceptions built into Python or provided in the standard library are derived
from :exc:`BaseException`.
String exceptions are still supported in the interpreter to allow existing code
to run unmodified, but this will also change in a future release.
Doc/c-api/init.rst
View file @ 321976b6
......@@ -42,8 +42,6 @@ Initialization, Finalization, and Threads
*initsigs* is 0, it skips initialization registration of signal handlers, which
might be useful when Python is embedded.
.. versionadded:: 2.4
.. cfunction:: int Py_IsInitialized()
......@@ -290,8 +288,6 @@ Initialization, Finalization, and Threads
was built from. This number is a string because it may contain a trailing 'M'
if Python was built from a mixed revision source tree.
.. versionadded:: 2.5
.. cfunction:: const char* Py_GetPlatform()
......@@ -570,8 +566,6 @@ supports the creation of additional interpreters (using
avoid calls to the locking API when running single-threaded. This function is
not available when thread support is disabled at compile time.
.. versionadded:: 2.4
.. cfunction:: void PyEval_AcquireLock()
......@@ -719,10 +713,6 @@ created.
is available. If this function returns *NULL*, no exception has been raised and
the caller should assume no current thread state is available.
.. versionchanged:: 2.3
Previously this could only be called when a current thread is active, and *NULL*
meant that an exception was raised.
.. cfunction:: int PyThreadState_SetAsyncExc(long id, PyObject *exc)
......@@ -734,8 +724,6 @@ created.
zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending
exception (if any) for the thread is cleared. This raises no exceptions.
.. versionadded:: 2.3
.. cfunction:: PyGILState_STATE PyGILState_Ensure()
......@@ -758,8 +746,6 @@ created.
When the function returns, the current thread will hold the GIL. Failure is a
fatal error.
.. versionadded:: 2.3
.. cfunction:: void PyGILState_Release(PyGILState_STATE)
......@@ -771,8 +757,6 @@ created.
Every call to :cfunc:`PyGILState_Ensure` must be matched by a call to
:cfunc:`PyGILState_Release` on the same thread.
.. versionadded:: 2.3
.. _profiling:
......@@ -908,29 +892,21 @@ These functions are only intended to be used by advanced debugging tools.
Return the interpreter state object at the head of the list of all such objects.
.. versionadded:: 2.2
.. cfunction:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)
Return the next interpreter state object after *interp* from the list of all
such objects.
.. versionadded:: 2.2
.. cfunction:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)
Return the a pointer to the first :ctype:`PyThreadState` object in the list of
threads associated with the interpreter *interp*.
.. versionadded:: 2.2
.. cfunction:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)
Return the next thread state object after *tstate* from the list of all such
objects belonging to the same :ctype:`PyInterpreterState` object.
.. versionadded:: 2.2
Doc/c-api/newtypes.rst
View file @ 321976b6
......@@ -67,49 +67,41 @@ Allocating Objects on the Heap
.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
Create a new module object based on a name and table of functions, returning the
new module object.
.. versionchanged:: 2.3
Older versions of Python did not support *NULL* as the value for the *methods*
argument.
Create a new module object based on a name and table of functions, returning
the new module object; the *methods* argument can be *NULL* if no methods are
to be defined for the module.
.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
Create a new module object based on a name and table of functions, returning the
new module object. If *doc* is non-*NULL*, it will be used to define the
docstring for the module.
.. versionchanged:: 2.3
Older versions of Python did not support *NULL* as the value for the *methods*
argument.
Create a new module object based on a name and table of functions, returning
the new module object. The *methods* argument can be *NULL* if no methods
are to be defined for the module. If *doc* is non-*NULL*, it will be used to
define the docstring for the module.
.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
Create a new module object based on a name and table of functions, returning the
new module object. If *doc* is non-*NULL*, it will be used to define the
docstring for the module. If *self* is non-*NULL*, it will passed to the
functions of the module as their (otherwise *NULL*) first parameter. (This was
added as an experimental feature, and there are no known uses in the current
version of Python.) For *apiver*, the only value which should be passed is
defined by the constant :const:`PYTHON_API_VERSION`.
Create a new module object based on a name and table of functions, returning
the new module object. The *methods* argument can be *NULL* if no methods
are to be defined for the module. If *doc* is non-*NULL*, it will be used to
define the docstring for the module. If *self* is non-*NULL*, it will passed
to the functions of the module as their (otherwise *NULL*) first parameter.
(This was added as an experimental feature, and there are no known uses in
the current version of Python.) For *apiver*, the only value which should be
passed is defined by the constant :const:`PYTHON_API_VERSION`.
.. note::
Most uses of this function should probably be using the :cfunc:`Py_InitModule3`
instead; only use this if you are sure you need it.
.. versionchanged:: 2.3
Older versions of Python did not support *NULL* as the value for the *methods*
argument.
.. cvar:: PyObject _Py_NoneStruct
Object which is visible in Python as ``None``. This should only be accessed
using the ``Py_None`` macro, which evaluates to a pointer to this object.
using the :cmacro:`Py_None` macro, which evaluates to a pointer to this
object.
.. _common-structs:
......@@ -263,6 +255,7 @@ convention flags can be combined with a binding flag.
:ctype:`PyObject\*` parameter representing the single argument.
.. XXX deprecated, should be removed
.. data:: METH_OLDARGS
This calling convention is deprecated. The method must be of type
......@@ -286,8 +279,6 @@ method.
instance of the type. This is used to create *class methods*, similar to what
is created when using the :func:`classmethod` built-in function.
.. versionadded:: 2.3
.. data:: METH_STATIC
......@@ -297,8 +288,6 @@ method.
of the type. This is used to create *static methods*, similar to what is
created when using the :func:`staticmethod` built-in function.
.. versionadded:: 2.3
One other constant controls whether a method is loaded in place of another
definition with the same method name.
......@@ -314,8 +303,6 @@ definition with the same method name.
object and will co-exist with the slot. This is helpful because calls to
PyCFunctions are optimized more than wrapper object calls.
.. versionadded:: 2.4
.. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)
......@@ -1718,8 +1705,6 @@ must name its arguments exactly *visit* and *arg*:
return 0;
}
.. versionadded:: 2.4
The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if
the object is immutable.
......
Doc/c-api/refcounting.rst
View file @ 321976b6
......@@ -61,12 +61,11 @@ objects.
It is a good idea to use this macro whenever decrementing the value of a
variable that might be traversed during garbage collection.
.. versionadded:: 2.4
The following functions are for runtime dynamic embedding of Python:
``Py_IncRef(PyObject \*o)``, `Py_DecRef(PyObject \*o)``. They are
simply exported function versions of :cfunc:`Py_XINCREF` and
:cfunc:`Py_XDECREF`, respectively.
``Py_IncRef(PyObject \*o)``, `Py_DecRef(PyObject \*o)``. They are simply
exported function versions of :cfunc:`Py_XINCREF` and :cfunc:`Py_XDECREF`,
respectively.
The following functions or macros are only for use within the interpreter core:
:cfunc:`_Py_Dealloc`, :cfunc:`_Py_ForgetReference`, :cfunc:`_Py_NewReference`,
......
Doc/c-api/utilities.rst
View file @ 321976b6
......@@ -121,6 +121,7 @@ Importing Modules
.. index::
single: package variable; __all__
single: __all__ (package variable)
single: modules (in module sys)
This is a simplified interface to :cfunc:`PyImport_ImportModuleEx` below,
leaving the *globals* and *locals* arguments set to *NULL*. When the *name*
......@@ -135,11 +136,6 @@ Importing Modules
to find out. Starting with Python 2.4, a failing import of a module no longer
leaves the module in ``sys.modules``.
.. versionchanged:: 2.4
failing imports remove incomplete module objects.
.. index:: single: modules (in module sys)
.. cfunction:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
......@@ -155,20 +151,16 @@ Importing Modules
when a submodule of a package was requested is normally the top-level package,
unless a non-empty *fromlist* was given.
.. versionchanged:: 2.4
failing imports remove incomplete module objects.
Failing imports remove incomplete module objects, like with
:cfunc:`PyImport_ImportModule`.
.. cfunction:: PyObject* PyImport_Import(PyObject *name)
.. index::
module: rexec
module: ihooks
This is a higher-level interface that calls the current "import hook function".
It invokes the :func:`__import__` function from the ``__builtins__`` of the
current globals. This means that the import is done using whatever import hooks
are installed in the current environment, e.g. by :mod:`rexec` or :mod:`ihooks`.
are installed in the current environment.
.. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)
......@@ -213,9 +205,6 @@ Importing Modules
If *name* points to a dotted name of the form ``package.module``, any package
structures not already created will still not be created.
.. versionchanged:: 2.4
*name* is removed from ``sys.modules`` in error cases.
.. cfunction:: long PyImport_GetMagicNumber()
......@@ -345,25 +334,18 @@ upon unmarshalling. *Py_MARSHAL_VERSION* indicates the current file format
Marshal a :ctype:`long` integer, *value*, to *file*. This will only write the
least-significant 32 bits of *value*; regardless of the size of the native
:ctype:`long` type.
.. versionchanged:: 2.4
*version* indicates the file format.
:ctype:`long` type. *version* indicates the file format.
.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
Marshal a Python object, *value*, to *file*.
.. versionchanged:: 2.4
*version* indicates the file format.
.. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
Return a string object containing the marshalled representation of *value*.
.. versionchanged:: 2.4
*version* indicates the file format.
......@@ -557,8 +539,6 @@ variable(s) whose address should be passed.
Convert a Python integer to a tiny int without overflow checking, stored in a C
:ctype:`unsigned char`.
.. versionadded:: 2.3
``h`` (integer) [short int]
Convert a Python integer to a C :ctype:`short int`.
......@@ -566,8 +546,6 @@ variable(s) whose address should be passed.
Convert a Python integer to a C :ctype:`unsigned short int`, without overflow
checking.
.. versionadded:: 2.3
``i`` (integer) [int]
Convert a Python integer to a plain C :ctype:`int`.
......@@ -575,8 +553,6 @@ variable(s) whose address should be passed.
Convert a Python integer to a C :ctype:`unsigned int`, without overflow
checking.
.. versionadded:: 2.3
``l`` (integer) [long int]
Convert a Python integer to a C :ctype:`long int`.
......@@ -584,8 +560,6 @@ variable(s) whose address should be passed.
Convert a Python integer or long integer to a C :ctype:`unsigned long` without
overflow checking.
.. versionadded:: 2.3
``L`` (integer) [PY_LONG_LONG]
Convert a Python integer to a C :ctype:`long long`. This format is only
available on platforms that support :ctype:`long long` (or :ctype:`_int64` on
......@@ -596,13 +570,9 @@ variable(s) whose address should be passed.
without overflow checking. This format is only available on platforms that
support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on Windows).
.. versionadded:: 2.3
``n`` (integer) [Py_ssize_t]
Convert a Python integer or long integer to a C :ctype:`Py_ssize_t`.
.. versionadded:: 2.5
``c`` (string of length 1) [char]
Convert a Python character, represented as a string of length 1, to a C
:ctype:`char`.
......@@ -677,13 +647,6 @@ variable(s) whose address should be passed.
in *items*. The C arguments must correspond to the individual format units in
*items*. Format units for sequences may be nested.
.. note::
Prior to Python version 1.5.2, this format specifier only accepted a tuple
containing the individual parameters, not an arbitrary sequence. Code which
previously caused :exc:`TypeError` to be raised here may now proceed without an
exception. This is not expected to be a problem for existing code.
It is possible to pass Python long integers where integers are requested;
however no proper range checking is done --- the most significant bits are
silently truncated when the receiving field is too small to receive the value
......@@ -798,8 +761,6 @@ return true, otherwise they return false and raise an appropriate exception.
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
.. versionadded:: 2.2
.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
......@@ -898,8 +859,6 @@ return true, otherwise they return false and raise an appropriate exception.
``n`` (int) [Py_ssize_t]
Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer.
.. versionadded:: 2.5
``c`` (string of length 1) [char]
Convert a C :ctype:`int` representing a character to a Python string of length
1.
......@@ -1010,8 +969,6 @@ The following functions provide locale-independent string to number conversions.
:cfunc:`PyOS_ascii_strtod` should typically be used for reading configuration
files or other non-user input that should be locale independent.
.. versionadded:: 2.4
See the Unix man page :manpage:`strtod(2)` for details.
......@@ -1025,14 +982,10 @@ The following functions provide locale-independent string to number conversions.
The return value is a pointer to *buffer* with the converted string or NULL if
the conversion failed.
.. versionadded:: 2.4
.. cfunction:: double PyOS_ascii_atof(const char *nptr)
Convert a string to a :ctype:`double` in a locale-independent way.
.. versionadded:: 2.4
See the Unix man page :manpage:`atof(2)` for details.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7