Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
serhiy-storchaka merged 2 commits into from
Mar 30, 2017
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
956b432
bpo-29918: Add missed "const" modifiers in C API documentation.
serhiy-storchaka Mar 27, 2017
82ddf2e
Merge remote-tracking branch 'upstream/master' into doc-c-api-const-m…
serhiy-storchaka Mar 30, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions Doc/c-api/arg.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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*.

Expand Down Expand Up @@ -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]
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/bytes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/dict.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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)
Expand Down
11 changes: 3 additions & 8 deletions Doc/c-api/import.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -266,8 +261,8 @@ Importing Modules
is::

struct _frozen {
char *name;
unsigned char *code;
const char *name;
const unsigned char *code;
int size;
};

Expand Down Expand Up @@ -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);
};

Expand Down
8 changes: 4 additions & 4 deletions Doc/c-api/module.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'``.
Expand Down Expand Up @@ -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'.
Expand Down Expand Up @@ -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.
Expand Down
68 changes: 34 additions & 34 deletions Doc/c-api/structures.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/sys.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,15 +136,15 @@ 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`.

.. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode)

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
Expand Down
24 changes: 12 additions & 12 deletions Doc/c-api/tuple.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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
Expand Down
8 changes: 4 additions & 4 deletions Doc/c-api/unicode.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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 |
Expand Down
6 changes: 3 additions & 3 deletions Doc/extending/extending.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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};

Expand Down
6 changes: 3 additions & 3 deletions Doc/extending/newtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion Doc/howto/clinic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down