[3.14] gh-141004: Document `pyctype.h` macros (GH-141272) (GH-141340)

gh-141004: Document `pyctype.h` macros (GH-141272)
(cherry picked from commit df192616212f80aaa2f672b722b925943dbd3b78)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst
index e9d866c647d9e068213f4e85a989e3b9df410ef5..533e5460da895205c876452e0a4de22ff7e6b2ff 100644 (file)
--- a/Doc/c-api/conversion.rst
+++ b/Doc/c-api/conversion.rst
@@ -172,3 +172,58 @@ The following functions provide locale-independent string to number conversions.
 
    Case insensitive comparison of strings. The function works almost
    identically to :c:func:`!strncmp` except that it ignores the case.
+
+
+Character classification and conversion
+=======================================
+
+The following macros provide locale-independent (unlike the C standard library
+``ctype.h``) character classification and conversion.
+The argument must be a signed or unsigned :c:expr:`char`.
+
+
+.. c:macro:: Py_ISALNUM(c)
+
+   Return true if the character *c* is an alphanumeric character.
+
+
+.. c:macro:: Py_ISALPHA(c)
+
+   Return true if the character *c* is an alphabetic character (``a-z`` and ``A-Z``).
+
+
+.. c:macro:: Py_ISDIGIT(c)
+
+   Return true if the character *c* is a decimal digit (``0-9``).
+
+
+.. c:macro:: Py_ISLOWER(c)
+
+   Return true if the character *c* is a lowercase ASCII letter (``a-z``).
+
+
+.. c:macro:: Py_ISUPPER(c)
+
+   Return true if the character *c* is an uppercase ASCII letter (``A-Z``).
+
+
+.. c:macro:: Py_ISSPACE(c)
+
+   Return true if the character *c* is a whitespace character (space, tab,
+   carriage return, newline, vertical tab, or form feed).
+
+
+.. c:macro:: Py_ISXDIGIT(c)
+
+   Return true if the character *c* is a hexadecimal digit (``0-9``, ``a-f``, and
+   ``A-F``).
+
+
+.. c:macro:: Py_TOLOWER(c)
+
+   Return the lowercase equivalent of the character *c*.
+
+
+.. c:macro:: Py_TOUPPER(c)
+
+   Return the uppercase equivalent of the character *c*.

diff --git a/Doc/library/locale.rst b/Doc/library/locale.rst
index d48ea04077f366fdb6321024f7762579ad40b5ba..790bd3a5836423d10ad4cb65fafd434731fe18a3 100644 (file)
--- a/Doc/library/locale.rst
+++ b/Doc/library/locale.rst
@@ -517,8 +517,8 @@ The :mod:`locale` module defines the following exception and functions:
    SSH connections.
 
    Python doesn't internally use locale-dependent character transformation functions
-   from ``ctype.h``. Instead, an internal ``pyctype.h`` provides locale-independent
-   equivalents like :c:macro:`!Py_TOLOWER`.
+   from ``ctype.h``. Instead, ``pyctype.h`` provides locale-independent
+   equivalents like :c:macro:`Py_TOLOWER`.
 
 
 .. data:: LC_COLLATE

diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
index 09feb185b82ea7b420422cec2b28fc89794675e9..7296296d144803d87dd0d890e0c7e6af6f98be31 100644 (file)
--- a/Doc/whatsnew/2.7.rst
+++ b/Doc/whatsnew/2.7.rst
@@ -2181,14 +2181,14 @@ Changes to Python's build process and to the C API include:
   discussed in :issue:`5753`, and fixed by Antoine Pitrou.
 
 * New macros: the Python header files now define the following macros:
-  :c:macro:`!Py_ISALNUM`,
-  :c:macro:`!Py_ISALPHA`,
-  :c:macro:`!Py_ISDIGIT`,
-  :c:macro:`!Py_ISLOWER`,
-  :c:macro:`!Py_ISSPACE`,
-  :c:macro:`!Py_ISUPPER`,
-  :c:macro:`!Py_ISXDIGIT`,
-  :c:macro:`!Py_TOLOWER`, and :c:macro:`!Py_TOUPPER`.
+  :c:macro:`Py_ISALNUM`,
+  :c:macro:`Py_ISALPHA`,
+  :c:macro:`Py_ISDIGIT`,
+  :c:macro:`Py_ISLOWER`,
+  :c:macro:`Py_ISSPACE`,
+  :c:macro:`Py_ISUPPER`,
+  :c:macro:`Py_ISXDIGIT`,
+  :c:macro:`Py_TOLOWER`, and :c:macro:`Py_TOUPPER`.
   All of these functions are analogous to the C
   standard macros for classifying characters, but ignore the current
   locale setting, because in
@@ -2196,8 +2196,6 @@ Changes to Python's build process and to the C API include:
   locale-independent way.  (Added by Eric Smith;
   :issue:`5793`.)
 
-  .. XXX these macros don't seem to be described in the c-api docs.
-
 * Removed function: :c:func:`!PyEval_CallObject` is now only available
   as a macro.  A function version was being kept around to preserve
   ABI linking compatibility, but that was in 1997; it can certainly be