summaryrefslogtreecommitdiff
path: root/Doc/c-api
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/c-api')
-rw-r--r--Doc/c-api/init.rst40
-rw-r--r--Doc/c-api/object.rst73
-rw-r--r--Doc/c-api/slice.rst37
-rw-r--r--Doc/c-api/typeobj.rst10
-rw-r--r--Doc/c-api/unicode.rst13
5 files changed, 99 insertions, 74 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 2965bc931a..7d9eefb1ea 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1147,46 +1147,6 @@ Python-level trace functions in previous versions.
:c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
events.
-.. c:function:: PyObject* PyEval_GetCallStats(PyObject *self)
-
- Return a tuple of function call counts. There are constants defined for the
- positions within the tuple:
-
- +-------------------------------+-------+
- | Name | Value |
- +===============================+=======+
- | :const:`PCALL_ALL` | 0 |
- +-------------------------------+-------+
- | :const:`PCALL_FUNCTION` | 1 |
- +-------------------------------+-------+
- | :const:`PCALL_FAST_FUNCTION` | 2 |
- +-------------------------------+-------+
- | :const:`PCALL_FASTER_FUNCTION`| 3 |
- +-------------------------------+-------+
- | :const:`PCALL_METHOD` | 4 |
- +-------------------------------+-------+
- | :const:`PCALL_BOUND_METHOD` | 5 |
- +-------------------------------+-------+
- | :const:`PCALL_CFUNCTION` | 6 |
- +-------------------------------+-------+
- | :const:`PCALL_TYPE` | 7 |
- +-------------------------------+-------+
- | :const:`PCALL_GENERATOR` | 8 |
- +-------------------------------+-------+
- | :const:`PCALL_OTHER` | 9 |
- +-------------------------------+-------+
- | :const:`PCALL_POP` | 10 |
- +-------------------------------+-------+
-
- :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created.
- :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used.
-
- If there is a method call where the call can be optimized by changing
- the argument tuple and calling the function directly, it gets recorded
- twice.
-
- This function is only present if Python is compiled with :const:`CALL_PROFILE`
- defined.
.. _advanced-debugging:
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index b761c808fc..754dedc1c6 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -244,63 +244,82 @@ Object Protocol
and ``0`` otherwise. This function always succeeds.
-.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
+.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)
- Call a callable Python object *callable_object*, with arguments given by the
- tuple *args*, and named arguments given by the dictionary *kw*. If no named
- arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
- empty tuple if no arguments are needed. Returns the result of the call on
- success, or *NULL* on failure. This is the equivalent of the Python expression
- ``callable_object(*args, **kw)``.
+ Call a callable Python object *callable*, with arguments given by the
+ tuple *args*, and named arguments given by the dictionary *kwargs*.
+ *args* must not be *NULL*, use an empty tuple if no arguments are needed.
+ If no named arguments are needed, *kwargs* can be *NULL*.
-.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
+ Returns the result of the call on success, or *NULL* on failure.
- Call a callable Python object *callable_object*, with arguments given by the
- tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
- the result of the call on success, or *NULL* on failure. This is the equivalent
- of the Python expression ``callable_object(*args)``.
+ This is the equivalent of the Python expression:
+ ``callable(*args, **kwargs)``.
+
+
+.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)
+
+ Call a callable Python object *callable*, with arguments given by the
+ tuple *args*. If no arguments are needed, then *args* can be *NULL*.
+
+ Returns the result of the call on success, or *NULL* on failure.
+
+ This is the equivalent of the Python expression: ``callable(*args)``.
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
Call a callable Python object *callable*, with a variable number of C arguments.
The C arguments are described using a :c:func:`Py_BuildValue` style format
- string. The format may be *NULL*, indicating that no arguments are provided.
- Returns the result of the call on success, or *NULL* on failure. This is the
- equivalent of the Python expression ``callable(*args)``. Note that if you only
- pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallFunctionObjArgs` is a
- faster alternative.
+ string. The format can be *NULL*, indicating that no arguments are provided.
+
+ Returns the result of the call on success, or *NULL* on failure.
+
+ This is the equivalent of the Python expression: ``callable(*args)``.
+
+ Note that if you only pass :c:type:`PyObject \*` args,
+ :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
.. versionchanged:: 3.4
The type of *format* was changed from ``char *``.
-.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, const char *method, const char *format, ...)
+.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)
- Call the method named *method* of object *o* with a variable number of C
+ Call the method named *name* of object *obj* with a variable number of C
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
- string that should produce a tuple. The format may be *NULL*, indicating that
- no arguments are provided. Returns the result of the call on success, or *NULL*
- on failure. This is the equivalent of the Python expression ``o.method(args)``.
+ string that should produce a tuple.
+
+ The format can be *NULL*, indicating that no arguments are provided.
+
+ Returns the result of the call on success, or *NULL* on failure.
+
+ This is the equivalent of the Python expression:
+ ``obj.name(arg1, arg2, ...)``.
+
Note that if you only pass :c:type:`PyObject \*` args,
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
.. versionchanged:: 3.4
- The types of *method* and *format* were changed from ``char *``.
+ The types of *name* and *format* were changed from ``char *``.
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
Call a callable Python object *callable*, with a variable number of
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
- of parameters followed by *NULL*. Returns the result of the call on success, or
- *NULL* on failure.
+ of parameters followed by *NULL*.
+
+ Returns the result of the call on success, or *NULL* on failure.
+
+ This is the equivalent of the Python expression:
+ ``callable(arg1, arg2, ...)``.
-.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
+.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)
- Calls a method of the object *o*, where the name of the method is given as a
+ Calls a method of the Python object *obj*, where the name of the method is given as a
Python string object in *name*. It is called with a variable number of
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*. Returns the result of the call on success, or
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index a825164918..5606ae41a5 100644
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -56,3 +56,40 @@ Slice Objects
.. versionchanged:: 3.2
The parameter type for the *slice* parameter was ``PySliceObject*``
before.
+
+ .. versionchanged:: 3.6.1
+ If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400``
+ and ``0x03060000`` (not including) or ``0x03060100`` or higher
+ :c:func:`!PySlice_GetIndicesEx` is implemented as a macro using
+ :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`.
+ Arguments *start*, *stop* and *step* are evaluated more than once.
+
+ .. deprecated:: 3.6.1
+ If ``Py_LIMITED_API`` is set to the value less than ``0x03050400`` or
+ between ``0x03060000`` and ``0x03060100`` (not including)
+ :c:func:`!PySlice_GetIndicesEx` is a deprecated function.
+
+
+.. c:function:: int PySlice_Unpack(PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
+
+ Extract the start, stop and step data members from a slice object as
+ C integers. Silently reduce values larger than ``PY_SSIZE_T_MAX`` to
+ ``PY_SSIZE_T_MAX``, silently boost the start and stop values less than
+ ``-PY_SSIZE_T_MAX-1`` to ``-PY_SSIZE_T_MAX-1``, and silently boost the step
+ values less than ``-PY_SSIZE_T_MAX`` to ``-PY_SSIZE_T_MAX``.
+
+ Return ``-1`` on error, ``0`` on success.
+
+ .. versionadded:: 3.6.1
+
+
+.. c:function:: Py_ssize_t PySlice_AdjustIndices(Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)
+
+ Adjust start/end slice indices assuming a sequence of the specified length.
+ Out of bounds indices are clipped in a manner consistent with the handling
+ of normal slices.
+
+ Return the length of the slice. Always successful. Doesn't call Python
+ code.
+
+ .. versionadded:: 3.6.1
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index ac6fd0b53f..2f0081aa3d 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -727,11 +727,11 @@ type objects) *must* have the :attr:`ob_size` field.
typedef int (*setter)(PyObject *, PyObject *, void *);
typedef struct PyGetSetDef {
- char *name; /* attribute name */
- getter get; /* C function to get the attribute */
- setter set; /* C function to set or delete the attribute */
- char *doc; /* optional doc string */
- void *closure; /* optional additional data for getter and setter */
+ const char *name; /* attribute name */
+ getter get; /* C function to get the attribute */
+ setter set; /* C function to set or delete the attribute */
+ const char *doc; /* optional doc string */
+ void *closure; /* optional additional data for getter and setter */
} PyGetSetDef;
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 02f7ada7be..bcae44ef49 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -1038,7 +1038,7 @@ These are the UTF-8 codec APIs:
raised by the codec.
-.. c:function:: char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
+.. c:function:: const char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
Return a pointer to the UTF-8 encoding of the Unicode object, and
store the size of the encoded representation (in bytes) in *size*. The
@@ -1055,13 +1055,19 @@ These are the UTF-8 codec APIs:
.. versionadded:: 3.3
+ .. versionchanged:: 3.7
+ The return type is now ``const char *`` rather of ``char *``.
-.. c:function:: char* PyUnicode_AsUTF8(PyObject *unicode)
+
+.. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode)
As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size.
.. versionadded:: 3.3
+ .. versionchanged:: 3.7
+ The return type is now ``const char *`` rather of ``char *``.
+
.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
@@ -1605,6 +1611,9 @@ They all return *NULL* or ``-1`` if an exception occurs.
.. versionadded:: 3.3
+ .. versionchanged:: 3.7
+ *start* and *end* are now adjusted to behave like ``str[start:end]``.
+
.. c:function:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, \
Py_ssize_t start, Py_ssize_t end)
View Lorry Controller Status