Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

bpo-29918: Add missed "const" modifiers in C API documentation. (#846)

This commit is contained in:
Serhiy Storchaka 2017-03-30 10:01:03 +03:00 committed by GitHub
parent 576def096e
commit 84b8e92e46
12 changed files with 84 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
Doc/c-api/arg.rst
View File

@ -138,7 +138,7 @@ which disallows mutable objects such as :class:`bytearray`.
attempting any conversion. Raises :exc:`TypeError` if the object is not
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
``u`` (:class:`str`) [Py_UNICODE \*]
``u`` (:class:`str`) [const Py_UNICODE \*]
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
Unicode characters. You must pass the address of a :c:type:`Py_UNICODE`
pointer variable, which will be filled with the pointer to an existing
@ -151,16 +151,16 @@ which disallows mutable objects such as :class:`bytearray`.
Previously, :exc:`TypeError` was raised when embedded null code points
were encountered in the Python string.
``u#`` (:class:`str`) [Py_UNICODE \*, int]
``u#`` (:class:`str`) [const Py_UNICODE \*, int]
This variant on ``u`` stores into two C variables, the first one a pointer to a
Unicode data buffer, the second one its length. This variant allows
null code points.
``Z`` (:class:`str` or ``None``) [Py_UNICODE \*]
``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*]
Like ``u``, but the Python object may also be ``None``, in which case the
:c:type:`Py_UNICODE` pointer is set to *NULL*.
``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int]
``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int]
Like ``u#``, but the Python object may also be ``None``, in which case the
:c:type:`Py_UNICODE` pointer is set to *NULL*.
@ -529,42 +529,42 @@ Building values
not within format units such as ``s#``). This can be used to make long format
strings a tad more readable.
``s`` (:class:`str` or ``None``) [char \*]
``s`` (:class:`str` or ``None``) [const char \*]
Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
encoding. If the C string pointer is *NULL*, ``None`` is used.
``s#`` (:class:`str` or ``None``) [char \*, int]
``s#`` (:class:`str` or ``None``) [const char \*, int]
Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
encoding. If the C string pointer is *NULL*, the length is ignored and
``None`` is returned.
``y`` (:class:`bytes`) [char \*]
``y`` (:class:`bytes`) [const char \*]
This converts a C string to a Python :class:`bytes` object. If the C
string pointer is *NULL*, ``None`` is returned.
``y#`` (:class:`bytes`) [char \*, int]
``y#`` (:class:`bytes`) [const char \*, int]
This converts a C string and its lengths to a Python object. If the C
string pointer is *NULL*, ``None`` is returned.
``z`` (:class:`str` or ``None``) [char \*]
``z`` (:class:`str` or ``None``) [const char \*]
Same as ``s``.
``z#`` (:class:`str` or ``None``) [char \*, int]
``z#`` (:class:`str` or ``None``) [const char \*, int]
Same as ``s#``.
``u`` (:class:`str`) [Py_UNICODE \*]
``u`` (:class:`str`) [const Py_UNICODE \*]
Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is returned.
``u#`` (:class:`str`) [Py_UNICODE \*, int]
``u#`` (:class:`str`) [const Py_UNICODE \*, int]
Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored
and ``None`` is returned.
``U`` (:class:`str` or ``None``) [char \*]
``U`` (:class:`str` or ``None``) [const char \*]
Same as ``s``.
``U#`` (:class:`str` or ``None``) [char \*, int]
``U#`` (:class:`str` or ``None``) [const char \*, int]
Same as ``s#``.
``i`` (:class:`int`) [int]

4
Doc/c-api/bytes.rst
View File

@ -96,10 +96,10 @@ called with a non-bytes parameter.
| :attr:`%x` | int | Exactly equivalent to |
| | | ``printf("%x")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%s` | char\* | A null-terminated C character |
| :attr:`%s` | const char\* | A null-terminated C character |
| | | array. |
+-------------------+---------------+--------------------------------+
| :attr:`%p` | void\* | The hex representation of a C |
| :attr:`%p` | const void\* | The hex representation of a C |
| | | pointer. Mostly equivalent to |
| | | ``printf("%p")`` except that |
| | | it is guaranteed to start with |

4
Doc/c-api/dict.rst
View File

@ -72,7 +72,7 @@ Dictionary Objects
.. index:: single: PyUnicode_FromString()
Insert *value* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`char\*`. The key object is created using
be a :c:type:`const char\*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure.
@ -107,7 +107,7 @@ Dictionary Objects
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
:c:type:`char\*`, rather than a :c:type:`PyObject\*`.
:c:type:`const char\*`, rather than a :c:type:`PyObject\*`.
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default)

11
Doc/c-api/import.rst
View File

@ -231,11 +231,6 @@ Importing Modules
Finalize the import mechanism. For internal use only.
.. c:function:: PyObject* _PyImport_FindExtension(char *, char *)
For internal use only.
.. c:function:: int PyImport_ImportFrozenModuleObject(PyObject *name)
Load a frozen module named *name*. Return ``1`` for success, ``0`` if the
@ -266,8 +261,8 @@ Importing Modules
is::
struct _frozen {
char *name;
unsigned char *code;
const char *name;
const unsigned char *code;
int size;
};
@ -300,7 +295,7 @@ Importing Modules
The structure is defined in :file:`Include/import.h` as::
struct _inittab {
char *name; /* ASCII encoded string */
const char *name; /* ASCII encoded string */
PyObject* (*initfunc)(void);
};

8
Doc/c-api/module.rst
View File

@ -80,7 +80,7 @@ Module Objects
.. versionadded:: 3.3
.. c:function:: char* PyModule_GetName(PyObject *module)
.. c:function:: const char* PyModule_GetName(PyObject *module)
Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
``'utf-8'``.
@ -112,7 +112,7 @@ Module Objects
.. versionadded:: 3.2
.. c:function:: char* PyModule_GetFilename(PyObject *module)
.. c:function:: const char* PyModule_GetFilename(PyObject *module)
Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
encoded to 'utf-8'.
@ -146,11 +146,11 @@ or request "multi-phase initialization" by returning the definition struct itsel
Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
.. c:member:: char* m_name
.. c:member:: const char *m_name
Name for the new module.
.. c:member:: char* m_doc
.. c:member:: const char *m_doc
Docstring for the module; usually a docstring variable created with
:c:func:`PyDoc_STRVAR` is used.

68
Doc/c-api/structures.rst
View File

@ -125,20 +125,20 @@ the definition of all other Python objects.
Structure used to describe a method of an extension type. This structure has
four fields:
+------------------+-------------+-------------------------------+
| Field | C Type | Meaning |
+==================+=============+===============================+
| :attr:`ml_name` | char \* | name of the method |
+------------------+-------------+-------------------------------+
| :attr:`ml_meth` | PyCFunction | pointer to the C |
| | | implementation |
+------------------+-------------+-------------------------------+
| :attr:`ml_flags` | int | flag bits indicating how the |
| | | call should be constructed |
+------------------+-------------+-------------------------------+
| :attr:`ml_doc` | char \* | points to the contents of the |
| | | docstring |
+------------------+-------------+-------------------------------+
+------------------+---------------+-------------------------------+
| Field | C Type | Meaning |
+==================+===============+===============================+
| :attr:`ml_name` | const char \* | name of the method |
+------------------+---------------+-------------------------------+
| :attr:`ml_meth` | PyCFunction | pointer to the C |
| | | implementation |
+------------------+---------------+-------------------------------+
| :attr:`ml_flags` | int | flag bits indicating how the |
| | | call should be constructed |
+------------------+---------------+-------------------------------+
| :attr:`ml_doc` | const char \* | points to the contents of the |
| | | docstring |
+------------------+---------------+-------------------------------+
The :attr:`ml_meth` is a C function pointer. The functions may be of different
types, but they always return :c:type:`PyObject\*`. If the function is not of
@ -236,25 +236,25 @@ definition with the same method name.
Structure which describes an attribute of a type which corresponds to a C
struct member. Its fields are:
+------------------+-------------+-------------------------------+
| Field | C Type | Meaning |
+==================+=============+===============================+
| :attr:`name` | char \* | name of the member |
+------------------+-------------+-------------------------------+
| :attr:`!type` | int | the type of the member in the |
| | | C struct |
+------------------+-------------+-------------------------------+
| :attr:`offset` | Py_ssize_t | the offset in bytes that the |
| | | member is located on the |
| | | type's object struct |
+------------------+-------------+-------------------------------+
| :attr:`flags` | int | flag bits indicating if the |
| | | field should be read-only or |
| | | writable |
+------------------+-------------+-------------------------------+
| :attr:`doc` | char \* | points to the contents of the |
| | | docstring |
+------------------+-------------+-------------------------------+
+------------------+---------------+-------------------------------+
| Field | C Type | Meaning |
+==================+===============+===============================+
| :attr:`name` | const char \* | name of the member |
+------------------+---------------+-------------------------------+
| :attr:`!type` | int | the type of the member in the |
| | | C struct |
+------------------+---------------+-------------------------------+
| :attr:`offset` | Py_ssize_t | the offset in bytes that the |
| | | member is located on the |
| | | type's object struct |
+------------------+---------------+-------------------------------+
| :attr:`flags` | int | flag bits indicating if the |
| | | field should be read-only or |
| | | writable |
+------------------+---------------+-------------------------------+
| :attr:`doc` | const char \* | points to the contents of the |
| | | docstring |
+------------------+---------------+-------------------------------+
:attr:`!type` can be one of many ``T_`` macros corresponding to various C
types. When the member is accessed in Python, it will be converted to the
@ -268,7 +268,7 @@ definition with the same method name.
T_LONG long
T_FLOAT float
T_DOUBLE double
T_STRING char \*
T_STRING const char \*
T_OBJECT PyObject \*
T_OBJECT_EX PyObject \*
T_CHAR char

4
Doc/c-api/sys.rst
View File

@ -136,7 +136,7 @@ accessible to C code. They all work with the current interpreter thread's
Reset :data:`sys.warnoptions` to an empty list.
.. c:function:: void PySys_AddWarnOption(wchar_t *s)
.. c:function:: void PySys_AddWarnOption(const wchar_t *s)
Append *s* to :data:`sys.warnoptions`.
@ -144,7 +144,7 @@ accessible to C code. They all work with the current interpreter thread's
Append *unicode* to :data:`sys.warnoptions`.
.. c:function:: void PySys_SetPath(wchar_t *path)
.. c:function:: void PySys_SetPath(const wchar_t *path)
Set :data:`sys.path` to a list object of paths found in *path* which should
be a list of paths separated with the platform's search path delimiter

24
Doc/c-api/tuple.rst
View File

@ -144,9 +144,9 @@ type.
+-------------------+------------------------------+------------------------------------+
| Field | C Type | Meaning |
+===================+==============================+====================================+
| ``name`` | ``char *`` | name of the struct sequence type |
| ``name`` | ``const char *`` | name of the struct sequence type |
+-------------------+------------------------------+------------------------------------+
| ``doc`` | ``char *`` | pointer to docstring for the type |
| ``doc`` | ``const char *`` | pointer to docstring for the type |
| | | or NULL to omit |
+-------------------+------------------------------+------------------------------------+
| ``fields`` | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array |
@ -164,16 +164,16 @@ type.
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
field of the struct sequence is described.
+-----------+---------------+--------------------------------------+
| Field | C Type | Meaning |
+===========+===============+======================================+
| ``name`` | ``char *`` | name for the field or *NULL* to end |
| | | the list of named fields, set to |
| | | PyStructSequence_UnnamedField to |
| | | leave unnamed |
+-----------+---------------+--------------------------------------+
| ``doc`` | ``char *`` | field docstring or *NULL* to omit |
+-----------+---------------+--------------------------------------+
+-----------+------------------+--------------------------------------+
| Field | C Type | Meaning |
+===========+==================+======================================+
| ``name`` | ``const char *`` | name for the field or *NULL* to end |
| | | the list of named fields, set to |
| | | PyStructSequence_UnnamedField to |
| | | leave unnamed |
+-----------+------------------+--------------------------------------+
| ``doc`` | ``const char *`` | field docstring or *NULL* to omit |
+-----------+------------------+--------------------------------------+
.. c:var:: char* PyStructSequence_UnnamedField

8
Doc/c-api/unicode.rst
View File

@ -490,10 +490,10 @@ APIs:
| :attr:`%x` | int | Exactly equivalent to |
| | | ``printf("%x")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%s` | char\* | A null-terminated C character |
| :attr:`%s` | const char\* | A null-terminated C character |
| | | array. |
+-------------------+---------------------+--------------------------------+
| :attr:`%p` | void\* | The hex representation of a C |
| :attr:`%p` | const void\* | The hex representation of a C |
| | | pointer. Mostly equivalent to |
| | | ``printf("%p")`` except that |
| | | it is guaranteed to start with |
@ -506,8 +506,8 @@ APIs:
+-------------------+---------------------+--------------------------------+
| :attr:`%U` | PyObject\* | A unicode object. |
+-------------------+---------------------+--------------------------------+
| :attr:`%V` | PyObject\*, char \* | A unicode object (which may be |
| | | *NULL*) and a null-terminated |
| :attr:`%V` | PyObject\*, | A unicode object (which may be |
| | const char\* | *NULL*) and a null-terminated |
| | | C character array as a second |
| | | parameter (which will be used, |
| | | if the first parameter is |

6
Doc/extending/extending.rst
View File

@ -727,9 +727,9 @@ Philbrick (philbrick@hks.com)::
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
{
int voltage;
char *state = "a stiff";
char *action = "voom";
char *type = "Norwegian Blue";
const char *state = "a stiff";
const char *action = "voom";
const char *type = "Norwegian Blue";
static char *kwlist[] = {"voltage", "state", "action", "type", NULL};

6
Doc/extending/newtypes.rst
View File

@ -1361,9 +1361,9 @@ Here is a desultory example of the implementation of the call function. ::
newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *other)
{
PyObject *result;
char *arg1;
char *arg2;
char *arg3;
const char *arg1;
const char *arg2;
const char *arg3;
if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
return NULL;

2
Doc/howto/clinic.rst
View File

@ -1050,7 +1050,7 @@ Currently Argument Clinic supports only a few return converters:
DecodeFSDefault
None of these take parameters. For the first three, return -1 to indicate
error. For ``DecodeFSDefault``, the return type is ``char *``; return a NULL
error. For ``DecodeFSDefault``, the return type is ``const char *``; return a NULL
pointer to indicate an error.
(There's also an experimental ``NoneType`` converter, which lets you