diff options
Diffstat (limited to 'Doc/c-api')
-rw-r--r-- | Doc/c-api/init.rst | 40 | ||||
-rw-r--r-- | Doc/c-api/object.rst | 73 | ||||
-rw-r--r-- | Doc/c-api/slice.rst | 37 | ||||
-rw-r--r-- | Doc/c-api/typeobj.rst | 10 | ||||
-rw-r--r-- | Doc/c-api/unicode.rst | 13 |
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) |