Doc: define PY_SSIZE_T_CLEAN always (GH-12794)

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 6bb2356f694ead4e4671cf45fac8a2c26ce6fcd2..69aef0da04f3bac11b03c24781e8b6c7c0883299 100644 (file)
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -48,7 +48,8 @@ Include Files
 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 @@ This implies inclusion of the following standard headers: ``<stdio.h>``,
    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 7e4fc19db83b2a6bb54b2f3528d066e810313dc3..13d83b72f82ab695d769d1b14e8e50875b1e96c3 100644 (file)
--- a/Doc/extending/embedding.rst
+++ b/Doc/extending/embedding.rst
@@ -53,6 +53,7 @@ interface. This interface is intended to execute a Python script without needing
 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 9fbd91f6a03475e6bbaf4f7709e0cd4447319de3..433178ab64d8e537437203ef8171c0b6476ee908 100644 (file)
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -55,8 +55,9 @@ called ``spam``, the C file containing its implementation is called
 :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 @@ the module and a copyright notice if you like).
    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 @@ it returns false and raises an appropriate exception.
 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 @@ The function :c:func:`spam_system` is modified in a trivial way::
 
 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 74e1af6ef24de1719f7969d3b833323b7feaa12e..2ad27658705258ed72f4a54bd676e265525f0dcb 100644 (file)
--- a/Doc/faq/extending.rst
+++ b/Doc/faq/extending.rst
@@ -280,6 +280,7 @@ solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error``
 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 @@ complete example using the GNU readline library (you may want to ignore
    #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 fb2c7b2a430e6445e49fb9da66e885581895cba0..13d16f5424ae4de319c58f0ae61aae0a1bd28ea4 100644 (file)
--- 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 51ab4b80d68098064728bdbff214e077603ef23a..6477a19dafed753b07f17a5fc10ff2e45e9a8176 100644 (file)
--- 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 09e87355b91afa2e987f56e1506c2ad667860991..213d0864ce1ca8c13cde37bd1045769dfeadfe9f 100644 (file)
--- 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 0994d8fda0e51fa40257d945e540b82f20743cfd..b0b2906dbdc863913e9d09de1f3edcf4c3839db5 100644 (file)
--- 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 9caf1fdb20104af60af4e275acaa5682e180055f..392f86d65ecc17754f5e0922ed1f0ee2b908408b 100644 (file)
--- 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 376dddfac09c685537c7f012395897dcb918aafa..76ff93948cfd6756abdd95666a5ee4ec5beed745 100644 (file)
--- a/Doc/includes/sublist.c
+++ b/Doc/includes/sublist.c
@@ -1,3 +1,4 @@
+#define PY_SSIZE_T_CLEAN
 #include <Python.h>
 
 typedef struct {