Doc: define PY_SSIZE_T_CLEAN always (GH-12794)
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 6bb2356..69aef0d 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -48,7 +48,8 @@
All function, type and macro definitions needed to use the Python/C API are
included in your code by the following line::
- #include "Python.h"
+ #define PY_SSIZE_T_CLEAN
+ #include <Python.h>
This implies inclusion of the following standard headers: ``<stdio.h>``,
``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib.h>``
@@ -60,6 +61,9 @@
headers on some systems, you *must* include :file:`Python.h` before any standard
headers are included.
+ It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including
+ ``Python.h``. See :ref:`arg-parsing` for a description of this macro.
+
All user visible names defined by Python.h (except those defined by the included
standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning
with ``_Py`` are for internal use by the Python implementation and should not be
diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst
index 7e4fc19..13d83b7 100644
--- a/Doc/extending/embedding.rst
+++ b/Doc/extending/embedding.rst
@@ -53,6 +53,7 @@
to interact with the application directly. This can for example be used to
perform some operation on a file. ::
+ #define PY_SSIZE_T_CLEAN
#include <Python.h>
int
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index 9fbd91f..433178a 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -55,8 +55,9 @@
:file:`spammodule.c`; if the module name is very long, like ``spammify``, the
module name can be just :file:`spammify.c`.)
-The first line of our file can be::
+The first two lines of our file can be::
+ #define PY_SSIZE_T_CLEAN
#include <Python.h>
which pulls in the Python API (you can add a comment describing the purpose of
@@ -68,6 +69,9 @@
headers on some systems, you *must* include :file:`Python.h` before any standard
headers are included.
+ It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including
+ ``Python.h``. See :ref:`parsetuple` for a description of this macro.
+
All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or
``PY``, except those defined in standard header files. For convenience, and
since they are used extensively by the Python interpreter, ``"Python.h"``
@@ -729,7 +733,8 @@
Here is an example module which uses keywords, based on an example by Geoff
Philbrick (philbrick@hks.com)::
- #include "Python.h"
+ #define PY_SSIZE_T_CLEAN /* Make "s#" use Py_ssize_t rather than int. */
+ #include <Python.h>
static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
@@ -1228,7 +1233,7 @@
In the beginning of the module, right after the line ::
- #include "Python.h"
+ #include <Python.h>
two more lines must be added::
diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst
index 74e1af6..2ad2765 100644
--- a/Doc/faq/extending.rst
+++ b/Doc/faq/extending.rst
@@ -280,6 +280,7 @@
equal to ``E_EOF``, which means the input is incomplete. Here's a sample code
fragment, untested, inspired by code from Alex Farber::
+ #define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <node.h>
#include <errcode.h>
@@ -318,6 +319,7 @@
#include <stdio.h>
#include <readline.h>
+ #define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <object.h>
#include <compile.h>
diff --git a/Doc/includes/custom.c b/Doc/includes/custom.c
index fb2c7b2..13d16f5 100644
--- a/Doc/includes/custom.c
+++ b/Doc/includes/custom.c
@@ -1,3 +1,4 @@
+#define PY_SSIZE_T_CLEAN
#include <Python.h>
typedef struct {
diff --git a/Doc/includes/custom2.c b/Doc/includes/custom2.c
index 51ab4b8..6477a19 100644
--- a/Doc/includes/custom2.c
+++ b/Doc/includes/custom2.c
@@ -1,3 +1,4 @@
+#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"
diff --git a/Doc/includes/custom3.c b/Doc/includes/custom3.c
index 09e8735..213d086 100644
--- a/Doc/includes/custom3.c
+++ b/Doc/includes/custom3.c
@@ -1,3 +1,4 @@
+#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"
diff --git a/Doc/includes/custom4.c b/Doc/includes/custom4.c
index 0994d8f..b0b2906 100644
--- a/Doc/includes/custom4.c
+++ b/Doc/includes/custom4.c
@@ -1,3 +1,4 @@
+#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include "structmember.h"
diff --git a/Doc/includes/run-func.c b/Doc/includes/run-func.c
index 9caf1fd..392f86d 100644
--- a/Doc/includes/run-func.c
+++ b/Doc/includes/run-func.c
@@ -1,3 +1,4 @@
+#define PY_SSIZE_T_CLEAN
#include <Python.h>
int
diff --git a/Doc/includes/sublist.c b/Doc/includes/sublist.c
index 376dddf..76ff939 100644
--- a/Doc/includes/sublist.c
+++ b/Doc/includes/sublist.c
@@ -1,3 +1,4 @@
+#define PY_SSIZE_T_CLEAN
#include <Python.h>
typedef struct {