diff options
Diffstat (limited to 'Doc/c-api')
| -rw-r--r-- | Doc/c-api/concrete.rst | 22 | ||||
| -rw-r--r-- | Doc/c-api/dict.rst | 11 | ||||
| -rw-r--r-- | Doc/c-api/exceptions.rst | 36 | ||||
| -rw-r--r-- | Doc/c-api/file.rst | 2 | ||||
| -rw-r--r-- | Doc/c-api/import.rst | 8 | ||||
| -rw-r--r-- | Doc/c-api/init.rst | 50 | ||||
| -rw-r--r-- | Doc/c-api/long.rst | 2 | ||||
| -rw-r--r-- | Doc/c-api/mapping.rst | 6 | ||||
| -rw-r--r-- | Doc/c-api/memory.rst | 171 | ||||
| -rw-r--r-- | Doc/c-api/module.rst | 11 | ||||
| -rw-r--r-- | Doc/c-api/object.rst | 19 | ||||
| -rw-r--r-- | Doc/c-api/typeobj.rst | 49 | ||||
| -rw-r--r-- | Doc/c-api/unicode.rst | 11 | ||||
| -rw-r--r-- | Doc/c-api/veryhigh.rst | 48 |
14 files changed, 406 insertions, 40 deletions
diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index 65904ee..2d56386 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -74,26 +74,35 @@ intrinsic to the Python language. .. _mapobjects: -Mapping Objects -=============== +Container Objects +================= .. index:: object: mapping .. toctree:: dict.rst + set.rst .. _otherobjects: -Other Objects -============= +Function Objects +================ .. toctree:: - set.rst function.rst method.rst + cell.rst + code.rst + + +Other Objects +============= + +.. toctree:: + file.rst module.rst iterator.rst @@ -102,7 +111,6 @@ Other Objects memoryview.rst weakref.rst capsule.rst - cell.rst gen.rst datetime.rst - code.rst + diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst index 6bacc32..5a9dca2 100644 --- a/Doc/c-api/dict.rst +++ b/Doc/c-api/dict.rst @@ -84,7 +84,7 @@ Dictionary Objects on failure. -.. c:function:: int PyDict_DelItemString(PyObject *p, char *key) +.. c:function:: int PyDict_DelItemString(PyObject *p, const char *key) Remove the entry in dictionary *p* which has a key specified by the string *key*. Return ``0`` on success or ``-1`` on failure. @@ -110,6 +110,15 @@ Dictionary Objects :c:type:`char\*`, rather than a :c:type:`PyObject\*`. +.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default) + + This is the same as the Python-level :meth:`dict.setdefault`. If present, it + returns the value corresponding to *key* from the dictionary *p*. If the key + is not in the dict, it is inserted with value *defaultobj* and *defaultobj* + is returned. This function evaluates the hash function of *key* only once, + instead of evaluating it independently for the lookup and the insertion. + + .. c:function:: PyObject* PyDict_Items(PyObject *p) Return a :c:type:`PyListObject` containing all the items from the dictionary. diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index c3d978f..8658a58 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -235,7 +235,7 @@ in various ways. There is a separate error indicator for each thread. Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename is given as a C string. *filename* is decoded from the filesystem encoding - (:func:`sys.getfilesystemencoding`). + (:func:`os.fsdecode`). .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr) @@ -267,7 +267,7 @@ in various ways. There is a separate error indicator for each thread. Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the filename is given as a C string. *filename* is decoded from the filesystem - encoding (:func:`sys.getfilesystemencoding`). Availability: Windows. + encoding (:func:`os.fsdecode`). Availability: Windows. .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename) @@ -293,20 +293,27 @@ in various ways. There is a separate error indicator for each thread. .. versionadded:: 3.3 -.. c:function:: void PyErr_SyntaxLocationEx(char *filename, int lineno, int col_offset) +.. c:function:: void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset) Set file, line, and offset information for the current exception. If the current exception is not a :exc:`SyntaxError`, then it sets additional attributes, which make the exception printing subsystem think the exception - is a :exc:`SyntaxError`. *filename* is decoded from the filesystem encoding - (:func:`sys.getfilesystemencoding`). + is a :exc:`SyntaxError`. - .. versionadded:: 3.2 +.. versionadded:: 3.4 + + +.. c:function:: void PyErr_SyntaxLocationEx(char *filename, int lineno, int col_offset) + + Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string + decoded from the filesystem encoding (:func:`os.fsdecode`). + +.. versionadded:: 3.2 .. c:function:: void PyErr_SyntaxLocation(char *filename, int lineno) - Like :c:func:`PyErr_SyntaxLocationExc`, but the col_offset parameter is + Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is omitted. @@ -355,15 +362,22 @@ in various ways. There is a separate error indicator for each thread. documentation. There is no C API for warning control. -.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry) +.. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry) Issue a warning message with explicit control over all warning attributes. This is a straightforward wrapper around the Python function :func:`warnings.warn_explicit`, see there for more information. The *module* and *registry* arguments may be set to *NULL* to get the default effect - described there. *message* and *module* are UTF-8 encoded strings, - *filename* is decoded from the filesystem encoding - (:func:`sys.getfilesystemencoding`). + described there. + + .. versionadded:: 3.4 + + +.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry) + + Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and + *module* are UTF-8 encoded strings, and *filename* is decoded from the + filesystem encoding (:func:`os.fsdecode`). .. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index cc190c9..6f2ecee 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -17,7 +17,7 @@ error reporting in the interpreter; third-party code is advised to access the :mod:`io` APIs instead. -.. c:function:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *errors, char *newline, int closefd) +.. c:function:: PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd) Create a Python file object from the file descriptor of an already opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline* diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst index 270152e..6cd2b8b 100644 --- a/Doc/c-api/import.rst +++ b/Doc/c-api/import.rst @@ -118,7 +118,7 @@ Importing Modules encoded string instead of a Unicode object. -.. c:function:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co) +.. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co) .. index:: builtin: compile @@ -145,7 +145,7 @@ Importing Modules :c:func:`PyImport_ExecCodeModuleWithPathnames`. -.. c:function:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname) +.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname) Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of the module object is set to *pathname* if it is non-``NULL``. @@ -162,7 +162,7 @@ Importing Modules .. versionadded:: 3.3 -.. c:function:: PyObject* PyImport_ExecCodeModuleWithPathnames(char *name, PyObject *co, char *pathname, char *cpathname) +.. c:function:: PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname) Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and *cpathname* are UTF-8 encoded strings. Attempts are also made to figure out @@ -246,7 +246,7 @@ Importing Modules .. versionadded:: 3.3 -.. c:function:: int PyImport_ImportFrozenModule(char *name) +.. c:function:: int PyImport_ImportFrozenModule(const char *name) Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a UTF-8 encoded string instead of a Unicode object. diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 705509f..6439d7f 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -86,6 +86,36 @@ Process-wide parameters ======================= +.. c:function:: int Py_SetStandardStreamEncoding(char *encoding, char *errors) + + .. index:: + single: Py_Initialize() + single: main() + triple: stdin; stdout; sdterr + + This function should be called before :c:func:`Py_Initialize`, if it is + called at all. It specifies which encoding and error handling to use + with standard IO, with the same meanings as in :func:`str.encode`. + + It overrides :envvar:`PYTHONIOENCODING` values, and allows embedding code + to control IO encoding when the environment variable does not work. + + ``encoding`` and/or ``errors`` may be NULL to use + :envvar:`PYTHONIOENCODING` and/or default values (depending on other + settings). + + Note that :data:`sys.stderr` always uses the "backslashreplace" error + handler, regardless of this (or any other) setting. + + If :c:func:`Py_Finalize` is called, this function will need to be called + again in order to affect subsequent calls to :c:func:`Py_Initialize`. + + Returns 0 if successful, a nonzero value on error (e.g. calling after the + interpreter has already been initialized). + + .. versionadded:: 3.4 + + .. c:function:: void Py_SetProgramName(wchar_t *name) .. index:: @@ -329,7 +359,11 @@ Process-wide parameters .. c:function:: void PySys_SetArgv(int argc, wchar_t **argv) - This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to 1. + This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set + to 1 unless the :program:`python` interpreter was started with the + :option:`-I`. + + .. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`. .. c:function:: void Py_SetPythonHome(wchar_t *home) @@ -657,6 +691,20 @@ with sub-interpreters: made on the main thread. This is mainly a helper/diagnostic function. +.. c:function:: int PyGILState_Check() + + Return 1 if the current thread is holding the GIL and 0 otherwise. + This function can be called from any thread at any time. + Only if it has had its Python thread state initialized and currently is + holding the GIL will it return 1. + This is mainly a helper/diagnostic function. It can be useful + for example in callback contexts or memory allocation functions when + knowing that the GIL is locked can allow the caller to perform sensitive + actions or otherwise behave differently. + + .. versionadded:: 3.4 + + The following macros are normally used without a trailing semicolon; look for example usage in the Python source distribution. diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index d5430fd..b348015 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -80,7 +80,7 @@ All integers are implemented as "long" integer objects of arbitrary size. *NULL* on failure. -.. c:function:: PyObject* PyLong_FromString(char *str, char **pend, int base) +.. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base) Return a new :c:type:`PyLongObject` based on the string value in *str*, which is interpreted according to the radix in *base*. If *pend* is non-*NULL*, diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst index 0ef2961..2803fd0 100644 --- a/Doc/c-api/mapping.rst +++ b/Doc/c-api/mapping.rst @@ -22,7 +22,7 @@ Mapping Protocol expression ``len(o)``. -.. c:function:: int PyMapping_DelItemString(PyObject *o, char *key) +.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key) Remove the mapping for object *key* from the object *o*. Return ``-1`` on failure. This is equivalent to the Python statement ``del o[key]``. @@ -67,13 +67,13 @@ Mapping Protocol the Python expression ``list(o.items())``. -.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, char *key) +.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key) Return element of *o* corresponding to the object *key* or *NULL* on failure. This is the equivalent of the Python expression ``o[key]``. -.. c:function:: int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v) +.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v) Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure. This is the equivalent of the Python statement ``o[key] = v``. diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index 8afa56a..a82e1c2 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -84,6 +84,48 @@ the C library allocator as shown in the previous example, the allocated memory for the I/O buffer escapes completely the Python memory manager. +Raw Memory Interface +==================== + +The following function sets are wrappers to the system allocator. These +functions are thread-safe, the :term:`GIL <global interpreter lock>` does not +need to be held. + +The default raw memory block allocator uses the following functions: +:c:func:`malloc`, :c:func:`realloc` and :c:func:`free`; call ``malloc(1)`` when +requesting zero bytes. + +.. versionadded:: 3.4 + +.. c:function:: void* PyMem_RawMalloc(size_t n) + + Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the + allocated memory, or *NULL* if the request fails. Requesting zero bytes + returns a distinct non-*NULL* pointer if possible, as if + ``PyMem_RawMalloc(1)`` had been called instead. The memory will not have + been initialized in any way. + + +.. c:function:: void* PyMem_RawRealloc(void *p, size_t n) + + Resizes the memory block pointed to by *p* to *n* bytes. The contents will + be unchanged to the minimum of the old and the new sizes. If *p* is *NULL*, + the call is equivalent to ``PyMem_RawMalloc(n)``; else if *n* is equal to + zero, the memory block is resized but is not freed, and the returned pointer + is non-*NULL*. Unless *p* is *NULL*, it must have been returned by a + previous call to :c:func:`PyMem_RawMalloc` or :c:func:`PyMem_RawRealloc`. If + the request fails, :c:func:`PyMem_RawRealloc` returns *NULL* and *p* remains + a valid pointer to the previous memory area. + + +.. c:function:: void PyMem_RawFree(void *p) + + Frees the memory block pointed to by *p*, which must have been returned by a + previous call to :c:func:`PyMem_RawMalloc` or :c:func:`PyMem_RawRealloc`. + Otherwise, or if ``PyMem_Free(p)`` has been called before, undefined + behavior occurs. If *p* is *NULL*, no operation is performed. + + .. _memoryinterface: Memory Interface @@ -91,8 +133,16 @@ Memory Interface The following function sets, modeled after the ANSI C standard, but specifying behavior when requesting zero bytes, are available for allocating and releasing -memory from the Python heap: +memory from the Python heap. + +The default memory block allocator uses the following functions: +:c:func:`malloc`, :c:func:`realloc` and :c:func:`free`; call ``malloc(1)`` when +requesting zero bytes. + +.. warning:: + The :term:`GIL <global interpreter lock>` must be held when using these + functions. .. c:function:: void* PyMem_Malloc(size_t n) @@ -155,6 +205,125 @@ versions and is therefore deprecated in extension modules. :c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`. +Customize Memory Allocators +=========================== + +.. versionadded:: 3.4 + +.. c:type:: PyMemAllocator + + Structure used to describe a memory block allocator. The structure has + four fields: + + +----------------------------------------------------------+---------------------------------------+ + | Field | Meaning | + +==========================================================+=======================================+ + | ``void *ctx`` | user context passed as first argument | + +----------------------------------------------------------+---------------------------------------+ + | ``void* malloc(void *ctx, size_t size)`` | allocate a memory block | + +----------------------------------------------------------+---------------------------------------+ + | ``void* realloc(void *ctx, void *ptr, size_t new_size)`` | allocate or resize a memory block | + +----------------------------------------------------------+---------------------------------------+ + | ``void free(void *ctx, void *ptr)`` | free a memory block | + +----------------------------------------------------------+---------------------------------------+ + +.. c:type:: PyMemAllocatorDomain + + Enum used to identify an allocator domain. Domains: + + * :c:data:`PYMEM_DOMAIN_RAW`: functions :c:func:`PyMem_RawMalloc`, + :c:func:`PyMem_RawRealloc` and :c:func:`PyMem_RawFree` + * :c:data:`PYMEM_DOMAIN_MEM`: functions :c:func:`PyMem_Malloc`, + :c:func:`PyMem_Realloc` and :c:func:`PyMem_Free` + * :c:data:`PYMEM_DOMAIN_OBJ`: functions :c:func:`PyObject_Malloc`, + :c:func:`PyObject_Realloc` and :c:func:`PyObject_Free` + + +.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator) + + Get the memory block allocator of the specified domain. + + +.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator) + + Set the memory block allocator of the specified domain. + + The new allocator must return a distinct non-NULL pointer when requesting + zero bytes. + + For the :c:data:`PYMEM_DOMAIN_RAW` domain, the allocator must be + thread-safe: the :term:`GIL <global interpreter lock>` is not held when the + allocator is called. + + If the new allocator is not a hook (does not call the previous allocator), + the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the + debug hooks on top on the new allocator. + + +.. c:function:: void PyMem_SetupDebugHooks(void) + + Setup hooks to detect bugs in the following Python memory allocator + functions: + + - :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc`, + :c:func:`PyMem_RawFree` + - :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc`, :c:func:`PyMem_Free` + - :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc`, + :c:func:`PyObject_Free` + + Newly allocated memory is filled with the byte ``0xCB``, freed memory is + filled with the byte ``0xDB``. Additionnal checks: + + - detect API violations, ex: :c:func:`PyObject_Free` called on a buffer + allocated by :c:func:`PyMem_Malloc` + - detect write before the start of the buffer (buffer underflow) + - detect write after the end of the buffer (buffer overflow) + + The function does nothing if Python is not compiled is debug mode. + + +Customize PyObject Arena Allocator +================================== + +Python has a *pymalloc* allocator for allocations smaller than 512 bytes. This +allocator is optimized for small objects with a short lifetime. It uses memory +mappings called "arenas" with a fixed size of 256 KB. It falls back to +:c:func:`PyMem_RawMalloc` and :c:func:`PyMem_RawRealloc` for allocations larger +than 512 bytes. *pymalloc* is the default allocator used by +:c:func:`PyObject_Malloc`. + +The default arena allocator uses the following functions: + +* :c:func:`VirtualAlloc` and :c:func:`VirtualFree` on Windows, +* :c:func:`mmap` and :c:func:`munmap` if available, +* :c:func:`malloc` and :c:func:`free` otherwise. + +.. versionadded:: 3.4 + +.. c:type:: PyObjectArenaAllocator + + Structure used to describe an arena allocator. The structure has + three fields: + + +--------------------------------------------------+---------------------------------------+ + | Field | Meaning | + +==================================================+=======================================+ + | ``void *ctx`` | user context passed as first argument | + +--------------------------------------------------+---------------------------------------+ + | ``void* alloc(void *ctx, size_t size)`` | allocate an arena of size bytes | + +--------------------------------------------------+---------------------------------------+ + | ``void free(void *ctx, size_t size, void *ptr)`` | free an arena | + +--------------------------------------------------+---------------------------------------+ + +.. c:function:: PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator) + + Get the arena allocator. + +.. c:function:: PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator) + + Set the arena allocator. + + .. _memoryexamples: Examples diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index e80e0ea..26c4384 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -35,13 +35,20 @@ There are only a few functions special to module objects. single: __name__ (module attribute) single: __doc__ (module attribute) single: __file__ (module attribute) + single: __package__ (module attribute) + single: __loader__ (module attribute) Return a new module object with the :attr:`__name__` attribute set to *name*. - Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in; - the caller is responsible for providing a :attr:`__file__` attribute. + The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and + :attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set + to ``None``); the caller is responsible for providing a :attr:`__file__` + attribute. .. versionadded:: 3.3 + .. versionchanged:: 3.4 + :attr:`__package__` and :attr:`__loader__` are set to ``None``. + .. c:function:: PyObject* PyModule_New(const char *name) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 0aba360..be6d798 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -240,7 +240,7 @@ attribute is considered sufficient for this determination. of the Python expression ``callable_object(*args)``. -.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...) +.. 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 @@ -250,8 +250,11 @@ attribute is considered sufficient for this determination. 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, char *method, char *format, ...) + +.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, const char *method, const char *format, ...) Call the method named *method* of object *o* with a variable number of C arguments. The C arguments are described by a :c:func:`Py_BuildValue` format @@ -261,6 +264,9 @@ attribute is considered sufficient for this determination. 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 *``. + .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL) @@ -342,6 +348,15 @@ attribute is considered sufficient for this determination. returned. This is the equivalent to the Python expression ``len(o)``. +.. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default) + + Return an estimated length for the object *o*. First trying to return its + actual length, then an estimate using ``__length_hint__``, and finally + returning the default value. On error ``-1`` is returned. This is the + equivalent to the Python expression ``operator.length_hint(o, default)``. + + .. versionadded:: 3.4 + .. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key) Return element of *o* corresponding to the object *key* or *NULL* on failure. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index b2b8038..48b13e5 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -465,6 +465,14 @@ type objects) *must* have the :attr:`ob_size` field. :const:`Py_TPFLAGS_HAVE_VERSION_TAG`. + .. data:: Py_TPFLAGS_HAVE_FINALIZE + + This bit is set when the :c:member:`~PyTypeObject.tp_finalize` slot is present in the + type structure. + + .. versionadded:: 3.4 + + .. c:member:: char* PyTypeObject.tp_doc An optional pointer to a NUL-terminated C string giving the docstring for this @@ -968,6 +976,47 @@ type objects) *must* have the :attr:`ob_size` field. This field is not inherited; it is calculated fresh by :c:func:`PyType_Ready`. +.. c:member:: destructor PyTypeObject.tp_finalize + + An optional pointer to an instance finalization function. Its signature is + :c:type:`destructor`:: + + void tp_finalize(PyObject *) + + If :c:member:`~PyTypeObject.tp_finalize` is set, the interpreter calls it once when + finalizing an instance. It is called either from the garbage + collector (if the instance is part of an isolated reference cycle) or + just before the object is deallocated. Either way, it is guaranteed + to be called before attempting to break reference cycles, ensuring + that it finds the object in a sane state. + + :c:member:`~PyTypeObject.tp_finalize` should not mutate the current exception status; + therefore, a recommended way to write a non-trivial finalizer is:: + + static void + local_finalize(PyObject *self) + { + PyObject *error_type, *error_value, *error_traceback; + + /* Save the current exception, if any. */ + PyErr_Fetch(&error_type, &error_value, &error_traceback); + + /* ... */ + + /* Restore the saved exception. */ + PyErr_Restore(error_type, error_value, error_traceback); + } + + For this field to be taken into account (even through inheritance), + you must also set the :const:`Py_TPFLAGS_HAVE_FINALIZE` flags bit. + + This field is inherited by subtypes. + + .. versionadded:: 3.4 + + .. seealso:: "Safe object finalization" (:pep:`442`) + + .. c:member:: PyObject* PyTypeObject.tp_cache Unused. Not inherited. Internal use only. diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 3649cfb..c7ed5e5 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -526,12 +526,23 @@ APIs: The `"%lld"` and `"%llu"` format specifiers are only available when :const:`HAVE_LONG_LONG` is defined. + .. note:: + The width formatter unit is number of characters rather than bytes. + The precision formatter unit is number of bytes for ``"%s"`` and + ``"%V"`` (if the ``PyObject*`` argument is NULL), and a number of + characters for ``"%A"``, ``"%U"``, ``"%S"``, ``"%R"`` and ``"%V"`` + (if the ``PyObject*`` argument is not NULL). + .. versionchanged:: 3.2 Support for ``"%lld"`` and ``"%llu"`` added. .. versionchanged:: 3.3 Support for ``"%li"``, ``"%lli"`` and ``"%zi"`` added. + .. versionchanged:: 3.4 + Support width and precision formatter for ``"%s"``, ``"%A"``, ``"%U"``, + ``"%V"``, ``"%S"``, ``"%R"`` added. + .. c:function:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 14ef8df..9f21b89 100644 --- a/Doc/c-api/veryhigh.rst +++ b/Doc/c-api/veryhigh.rst @@ -144,6 +144,37 @@ the same library that the Python runtime is using. (:func:`sys.getfilesystemencoding`). Returns ``0`` at EOF. +.. c:var:: int (*PyOS_InputHook)(void) + + Can be set to point to a function with the prototype + ``int func(void)``. The function will be called when Python's + interpreter prompt is about to become idle and wait for user input + from the terminal. The return value is ignored. Overriding this + hook can be used to integrate the interpreter's prompt with other + event loops, as done in the :file:`Modules/_tkinter.c` in the + Python source code. + + +.. c:var:: char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *) + + Can be set to point to a function with the prototype + ``char *func(FILE *stdin, FILE *stdout, char *prompt)``, + overriding the default function used to read a single line of input + at the interpreter's prompt. The function is expected to output + the string *prompt* if it's not *NULL*, and then read a line of + input from the provided standard input file, returning the + resulting string. For example, The :mod:`readline` module sets + this hook to provide line-editing and tab-completion features. + + The result must be a string allocated by :c:func:`PyMem_RawMalloc` or + :c:func:`PyMem_RawRealloc`, or *NULL* if an error occurred. + + .. versionchanged:: 3.4 + The result must be allocated by :c:func:`PyMem_RawMalloc` or + :c:func:`PyMem_RawRealloc`, instead of being allocated by + :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. + + .. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start) This is a simplified interface to @@ -235,16 +266,15 @@ the same library that the Python runtime is using. *optimize* set to ``-1``. -.. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize) +.. c:function:: PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize) Parse and compile the Python source code in *str*, returning the resulting code object. The start token is given by *start*; this can be used to constrain the code which can be compiled and should be :const:`Py_eval_input`, :const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by *filename* is used to construct the code object and may appear in tracebacks or - :exc:`SyntaxError` exception messages, it is decoded from the filesystem - encoding (:func:`sys.getfilesystemencoding`). This returns *NULL* if the - code cannot be parsed or compiled. + :exc:`SyntaxError` exception messages. This returns *NULL* if the code + cannot be parsed or compiled. The integer *optimize* specifies the optimization level of the compiler; a value of ``-1`` selects the optimization level of the interpreter as given by @@ -252,8 +282,15 @@ the same library that the Python runtime is using. ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false) or ``2`` (docstrings are removed too). - .. versionadded:: 3.2 + .. versionadded:: 3.4 + + +.. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize) + + Like :c:func:`Py_CompileStringExFlags`, but *filename* is a byte string + decoded from the filesystem encoding (:func:`os.fsdecode`). + .. versionadded:: 3.2 .. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals) @@ -338,4 +375,3 @@ the same library that the Python runtime is using. This bit can be set in *flags* to cause division operator ``/`` to be interpreted as "true division" according to :pep:`238`. - |