summaryrefslogtreecommitdiffstats
path: root/Doc/c-api
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/c-api')
-rw-r--r--Doc/c-api/dict.rst9
-rw-r--r--Doc/c-api/exceptions.rst36
-rw-r--r--Doc/c-api/init.rst20
-rw-r--r--Doc/c-api/memory.rst171
-rw-r--r--Doc/c-api/module.rst11
-rw-r--r--Doc/c-api/object.rst19
-rw-r--r--Doc/c-api/typeobj.rst49
-rw-r--r--Doc/c-api/unicode.rst11
-rw-r--r--Doc/c-api/veryhigh.rst40
9 files changed, 343 insertions, 23 deletions
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index 6bacc32..1f599fe 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -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/init.rst b/Doc/c-api/init.rst
index 705509f..9ed2a3a 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -329,7 +329,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 +661,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/memory.rst b/Doc/c-api/memory.rst
index 8afa56a..e4a759b 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_Malloc` and :c:func:`PyMem_Realloc` 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 a47183c..791cdbb 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -240,7 +240,7 @@ 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 @@ 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 @@ 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 @@ 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 118fa50..8e8af24 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 6cc8cce..216088e 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 499eb3e..eef7951 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -144,6 +144,29 @@ 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 *, 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.
+
+
.. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start)
This is a simplified interface to
@@ -235,16 +258,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 +274,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 +367,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`.
-