Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 84b8e92

Browse files
serhiy-storchakaserhiy-storchaka
authored
bpo-29918: Add missed "const" modifiers in C API documentation. (#846)
1 parent 576def0 commit 84b8e92

12 files changed

Lines changed: 84 additions & 89 deletions

File tree

‎Doc/c-api/arg.rst‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@ which disallows mutable objects such as :class:`bytearray`.
138138
attempting any conversion. Raises :exc:`TypeError` if the object is not
139139
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
140140

141-
``u`` (:class:`str`) [Py_UNICODE \*]
141+
``u`` (:class:`str`) [const Py_UNICODE \*]
142142
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
143143
Unicode characters. You must pass the address of a :c:type:`Py_UNICODE`
144144
pointer variable, which will be filled with the pointer to an existing
@@ -151,16 +151,16 @@ which disallows mutable objects such as :class:`bytearray`.
151151
Previously, :exc:`TypeError` was raised when embedded null code points
152152
were encountered in the Python string.
153153

154-
``u#`` (:class:`str`) [Py_UNICODE \*, int]
154+
``u#`` (:class:`str`) [const Py_UNICODE \*, int]
155155
This variant on ``u`` stores into two C variables, the first one a pointer to a
156156
Unicode data buffer, the second one its length. This variant allows
157157
null code points.
158158

159-
``Z`` (:class:`str` or ``None``) [Py_UNICODE \*]
159+
``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*]
160160
Like ``u``, but the Python object may also be ``None``, in which case the
161161
:c:type:`Py_UNICODE` pointer is set to *NULL*.
162162

163-
``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int]
163+
``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int]
164164
Like ``u#``, but the Python object may also be ``None``, in which case the
165165
:c:type:`Py_UNICODE` pointer is set to *NULL*.
166166

@@ -529,42 +529,42 @@ Building values
529529
not within format units such as ``s#``). This can be used to make long format
530530
strings a tad more readable.
531531
532-
``s`` (:class:`str` or ``None``) [char \*]
532+
``s`` (:class:`str` or ``None``) [const char \*]
533533
Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
534534
encoding. If the C string pointer is *NULL*, ``None`` is used.
535535
536-
``s#`` (:class:`str` or ``None``) [char \*, int]
536+
``s#`` (:class:`str` or ``None``) [const char \*, int]
537537
Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
538538
encoding. If the C string pointer is *NULL*, the length is ignored and
539539
``None`` is returned.
540540
541-
``y`` (:class:`bytes`) [char \*]
541+
``y`` (:class:`bytes`) [const char \*]
542542
This converts a C string to a Python :class:`bytes` object. If the C
543543
string pointer is *NULL*, ``None`` is returned.
544544
545-
``y#`` (:class:`bytes`) [char \*, int]
545+
``y#`` (:class:`bytes`) [const char \*, int]
546546
This converts a C string and its lengths to a Python object. If the C
547547
string pointer is *NULL*, ``None`` is returned.
548548
549-
``z`` (:class:`str` or ``None``) [char \*]
549+
``z`` (:class:`str` or ``None``) [const char \*]
550550
Same as ``s``.
551551
552-
``z#`` (:class:`str` or ``None``) [char \*, int]
552+
``z#`` (:class:`str` or ``None``) [const char \*, int]
553553
Same as ``s#``.
554554
555-
``u`` (:class:`str`) [Py_UNICODE \*]
555+
``u`` (:class:`str`) [const Py_UNICODE \*]
556556
Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
557557
Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is returned.
558558
559-
``u#`` (:class:`str`) [Py_UNICODE \*, int]
559+
``u#`` (:class:`str`) [const Py_UNICODE \*, int]
560560
Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
561561
Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored
562562
and ``None`` is returned.
563563
564-
``U`` (:class:`str` or ``None``) [char \*]
564+
``U`` (:class:`str` or ``None``) [const char \*]
565565
Same as ``s``.
566566
567-
``U#`` (:class:`str` or ``None``) [char \*, int]
567+
``U#`` (:class:`str` or ``None``) [const char \*, int]
568568
Same as ``s#``.
569569
570570
``i`` (:class:`int`) [int]

‎Doc/c-api/bytes.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,10 +96,10 @@ called with a non-bytes parameter.
9696
| :attr:`%x` | int | Exactly equivalent to |
9797
| | | ``printf("%x")``. |
9898
+-------------------+---------------+--------------------------------+
99-
| :attr:`%s` | char\* | A null-terminated C character |
99+
| :attr:`%s` | const char\* | A null-terminated C character |
100100
| | | array. |
101101
+-------------------+---------------+--------------------------------+
102-
| :attr:`%p` | void\* | The hex representation of a C |
102+
| :attr:`%p` | const void\* | The hex representation of a C |
103103
| | | pointer. Mostly equivalent to |
104104
| | | ``printf("%p")`` except that |
105105
| | | it is guaranteed to start with |

‎Doc/c-api/dict.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ Dictionary Objects
7272
.. index:: single: PyUnicode_FromString()
7373
7474
Insert *value* into the dictionary *p* using *key* as a key. *key* should
75-
be a :c:type:`char\*`. The key object is created using
75+
be a :c:type:`const char\*`. The key object is created using
7676
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
7777
failure.
7878
@@ -107,7 +107,7 @@ Dictionary Objects
107107
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
108108
109109
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
110-
:c:type:`char\*`, rather than a :c:type:`PyObject\*`.
110+
:c:type:`const char\*`, rather than a :c:type:`PyObject\*`.
111111
112112
113113
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default)

‎Doc/c-api/import.rst‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -231,11 +231,6 @@ Importing Modules
231231
Finalize the import mechanism. For internal use only.
232232
233233
234-
.. c:function:: PyObject* _PyImport_FindExtension(char *, char *)
235-
236-
For internal use only.
237-
238-
239234
.. c:function:: int PyImport_ImportFrozenModuleObject(PyObject *name)
240235
241236
Load a frozen module named *name*. Return ``1`` for success, ``0`` if the
@@ -266,8 +261,8 @@ Importing Modules
266261
is::
267262
268263
struct _frozen {
269-
char *name;
270-
unsigned char *code;
264+
const char *name;
265+
const unsigned char *code;
271266
int size;
272267
};
273268
@@ -300,7 +295,7 @@ Importing Modules
300295
The structure is defined in :file:`Include/import.h` as::
301296
302297
struct _inittab {
303-
char *name; /* ASCII encoded string */
298+
const char *name; /* ASCII encoded string */
304299
PyObject* (*initfunc)(void);
305300
};
306301

‎Doc/c-api/module.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ Module Objects
8080
.. versionadded:: 3.3
8181
8282
83-
.. c:function:: char* PyModule_GetName(PyObject *module)
83+
.. c:function:: const char* PyModule_GetName(PyObject *module)
8484
8585
Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
8686
``'utf-8'``.
@@ -112,7 +112,7 @@ Module Objects
112112
.. versionadded:: 3.2
113113
114114
115-
.. c:function:: char* PyModule_GetFilename(PyObject *module)
115+
.. c:function:: const char* PyModule_GetFilename(PyObject *module)
116116
117117
Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
118118
encoded to 'utf-8'.
@@ -146,11 +146,11 @@ or request "multi-phase initialization" by returning the definition struct itsel
146146
147147
Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
148148
149-
.. c:member:: char* m_name
149+
.. c:member:: const char *m_name
150150
151151
Name for the new module.
152152
153-
.. c:member:: char* m_doc
153+
.. c:member:: const char *m_doc
154154
155155
Docstring for the module; usually a docstring variable created with
156156
:c:func:`PyDoc_STRVAR` is used.

‎Doc/c-api/structures.rst‎

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -125,20 +125,20 @@ the definition of all other Python objects.
125125
Structure used to describe a method of an extension type. This structure has
126126
four fields:
127127

128-
+------------------+-------------+-------------------------------+
129-
| Field | C Type | Meaning |
130-
+==================+=============+===============================+
131-
| :attr:`ml_name` | char \* | name of the method |
132-
+------------------+-------------+-------------------------------+
133-
| :attr:`ml_meth` | PyCFunction | pointer to the C |
134-
| | | implementation |
135-
+------------------+-------------+-------------------------------+
136-
| :attr:`ml_flags` | int | flag bits indicating how the |
137-
| | | call should be constructed |
138-
+------------------+-------------+-------------------------------+
139-
| :attr:`ml_doc` | char \* | points to the contents of the |
140-
| | | docstring |
141-
+------------------+-------------+-------------------------------+
128+
+------------------+---------------+-------------------------------+
129+
| Field | C Type | Meaning |
130+
+==================+===============+===============================+
131+
| :attr:`ml_name` | const char \* | name of the method |
132+
+------------------+---------------+-------------------------------+
133+
| :attr:`ml_meth` | PyCFunction | pointer to the C |
134+
| | | implementation |
135+
+------------------+---------------+-------------------------------+
136+
| :attr:`ml_flags` | int | flag bits indicating how the |
137+
| | | call should be constructed |
138+
+------------------+---------------+-------------------------------+
139+
| :attr:`ml_doc` | const char \* | points to the contents of the |
140+
| | | docstring |
141+
+------------------+---------------+-------------------------------+
142142

143143
The :attr:`ml_meth` is a C function pointer. The functions may be of different
144144
types, but they always return :c:type:`PyObject\*`. If the function is not of
@@ -236,25 +236,25 @@ definition with the same method name.
236236
Structure which describes an attribute of a type which corresponds to a C
237237
struct member. Its fields are:
238238

239-
+------------------+-------------+-------------------------------+
240-
| Field | C Type | Meaning |
241-
+==================+=============+===============================+
242-
| :attr:`name` | char \* | name of the member |
243-
+------------------+-------------+-------------------------------+
244-
| :attr:`!type` | int | the type of the member in the |
245-
| | | C struct |
246-
+------------------+-------------+-------------------------------+
247-
| :attr:`offset` | Py_ssize_t | the offset in bytes that the |
248-
| | | member is located on the |
249-
| | | type's object struct |
250-
+------------------+-------------+-------------------------------+
251-
| :attr:`flags` | int | flag bits indicating if the |
252-
| | | field should be read-only or |
253-
| | | writable |
254-
+------------------+-------------+-------------------------------+
255-
| :attr:`doc` | char \* | points to the contents of the |
256-
| | | docstring |
257-
+------------------+-------------+-------------------------------+
239+
+------------------+---------------+-------------------------------+
240+
| Field | C Type | Meaning |
241+
+==================+===============+===============================+
242+
| :attr:`name` | const char \* | name of the member |
243+
+------------------+---------------+-------------------------------+
244+
| :attr:`!type` | int | the type of the member in the |
245+
| | | C struct |
246+
+------------------+---------------+-------------------------------+
247+
| :attr:`offset` | Py_ssize_t | the offset in bytes that the |
248+
| | | member is located on the |
249+
| | | type's object struct |
250+
+------------------+---------------+-------------------------------+
251+
| :attr:`flags` | int | flag bits indicating if the |
252+
| | | field should be read-only or |
253+
| | | writable |
254+
+------------------+---------------+-------------------------------+
255+
| :attr:`doc` | const char \* | points to the contents of the |
256+
| | | docstring |
257+
+------------------+---------------+-------------------------------+
258258

259259
:attr:`!type` can be one of many ``T_`` macros corresponding to various C
260260
types. When the member is accessed in Python, it will be converted to the
@@ -268,7 +268,7 @@ definition with the same method name.
268268
T_LONG long
269269
T_FLOAT float
270270
T_DOUBLE double
271-
T_STRING char \*
271+
T_STRING const char \*
272272
T_OBJECT PyObject \*
273273
T_OBJECT_EX PyObject \*
274274
T_CHAR char

‎Doc/c-api/sys.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -136,15 +136,15 @@ accessible to C code. They all work with the current interpreter thread's
136136
137137
Reset :data:`sys.warnoptions` to an empty list.
138138
139-
.. c:function:: void PySys_AddWarnOption(wchar_t *s)
139+
.. c:function:: void PySys_AddWarnOption(const wchar_t *s)
140140
141141
Append *s* to :data:`sys.warnoptions`.
142142
143143
.. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode)
144144
145145
Append *unicode* to :data:`sys.warnoptions`.
146146
147-
.. c:function:: void PySys_SetPath(wchar_t *path)
147+
.. c:function:: void PySys_SetPath(const wchar_t *path)
148148
149149
Set :data:`sys.path` to a list object of paths found in *path* which should
150150
be a list of paths separated with the platform's search path delimiter

‎Doc/c-api/tuple.rst‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -144,9 +144,9 @@ type.
144144
+-------------------+------------------------------+------------------------------------+
145145
| Field | C Type | Meaning |
146146
+===================+==============================+====================================+
147-
| ``name`` | ``char *`` | name of the struct sequence type |
147+
| ``name`` | ``const char *`` | name of the struct sequence type |
148148
+-------------------+------------------------------+------------------------------------+
149-
| ``doc`` | ``char *`` | pointer to docstring for the type |
149+
| ``doc`` | ``const char *`` | pointer to docstring for the type |
150150
| | | or NULL to omit |
151151
+-------------------+------------------------------+------------------------------------+
152152
| ``fields`` | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array |
@@ -164,16 +164,16 @@ type.
164164
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
165165
field of the struct sequence is described.
166166
167-
+-----------+---------------+--------------------------------------+
168-
| Field | C Type | Meaning |
169-
+===========+===============+======================================+
170-
| ``name`` | ``char *`` | name for the field or *NULL* to end |
171-
| | | the list of named fields, set to |
172-
| | | PyStructSequence_UnnamedField to |
173-
| | | leave unnamed |
174-
+-----------+---------------+--------------------------------------+
175-
| ``doc`` | ``char *`` | field docstring or *NULL* to omit |
176-
+-----------+---------------+--------------------------------------+
167+
+-----------+------------------+--------------------------------------+
168+
| Field | C Type | Meaning |
169+
+===========+==================+======================================+
170+
| ``name`` | ``const char *`` | name for the field or *NULL* to end |
171+
| | | the list of named fields, set to |
172+
| | | PyStructSequence_UnnamedField to |
173+
| | | leave unnamed |
174+
+-----------+------------------+--------------------------------------+
175+
| ``doc`` | ``const char *`` | field docstring or *NULL* to omit |
176+
+-----------+------------------+--------------------------------------+
177177
178178
179179
.. c:var:: char* PyStructSequence_UnnamedField

‎Doc/c-api/unicode.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -490,10 +490,10 @@ APIs:
490490
| :attr:`%x` | int | Exactly equivalent to |
491491
| | | ``printf("%x")``. |
492492
+-------------------+---------------------+--------------------------------+
493-
| :attr:`%s` | char\* | A null-terminated C character |
493+
| :attr:`%s` | const char\* | A null-terminated C character |
494494
| | | array. |
495495
+-------------------+---------------------+--------------------------------+
496-
| :attr:`%p` | void\* | The hex representation of a C |
496+
| :attr:`%p` | const void\* | The hex representation of a C |
497497
| | | pointer. Mostly equivalent to |
498498
| | | ``printf("%p")`` except that |
499499
| | | it is guaranteed to start with |
@@ -506,8 +506,8 @@ APIs:
506506
+-------------------+---------------------+--------------------------------+
507507
| :attr:`%U` | PyObject\* | A unicode object. |
508508
+-------------------+---------------------+--------------------------------+
509-
| :attr:`%V` | PyObject\*, char \* | A unicode object (which may be |
510-
| | | *NULL*) and a null-terminated |
509+
| :attr:`%V` | PyObject\*, | A unicode object (which may be |
510+
| | const char\* | *NULL*) and a null-terminated |
511511
| | | C character array as a second |
512512
| | | parameter (which will be used, |
513513
| | | if the first parameter is |

‎Doc/extending/extending.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -727,9 +727,9 @@ Philbrick ([email protected])::
727727
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
728728
{
729729
int voltage;
730-
char *state = "a stiff";
731-
char *action = "voom";
732-
char *type = "Norwegian Blue";
730+
const char *state = "a stiff";
731+
const char *action = "voom";
732+
const char *type = "Norwegian Blue";
733733

734734
static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
735735

0 commit comments

Comments
 (0)