From 871a61b0af30313c289858be1d23dcfab4e4a0f2 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 8 Nov 2025 20:26:26 +0000 Subject: [PATCH 1/3] Docs --- Doc/c-api/conversion.rst | 45 ++++++++++++++++++++++++++++++++++++++++ Doc/library/locale.rst | 4 ++-- Doc/whatsnew/2.7.rst | 18 +++++++--------- 3 files changed, 55 insertions(+), 12 deletions(-) diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst index cc7a3d9d9561a3..882c6ee3977ed6 100644 --- a/Doc/c-api/conversion.rst +++ b/Doc/c-api/conversion.rst @@ -162,3 +162,48 @@ 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 character classification and +conversion. The argument must be a signed or unsigned :c:type:`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 4824391e597452..94fc046d3f3c46 100644 --- a/Doc/library/locale.rst +++ b/Doc/library/locale.rst @@ -524,8 +524,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 09feb185b82ea7..7296296d144803 100644 --- 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 From fa84b5169a5ce174c3b54c73fdbe62c9e5079584 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 8 Nov 2025 20:28:40 +0000 Subject: [PATCH 2/3] Fix ref --- Doc/c-api/conversion.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst index 882c6ee3977ed6..371ba8b03a85e1 100644 --- a/Doc/c-api/conversion.rst +++ b/Doc/c-api/conversion.rst @@ -168,7 +168,7 @@ Character classification and conversion ======================================= The following macros provide locale-independent character classification and -conversion. The argument must be a signed or unsigned :c:type:`char`. +conversion. The argument must be a signed or unsigned :c:expr:`char`. .. c:macro:: Py_ISALNUM(c) From 1f4f8251bbcb723003a987f2bd180f033111b671 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 8 Nov 2025 21:27:03 +0000 Subject: [PATCH 3/3] Review --- Doc/c-api/conversion.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/conversion.rst b/Doc/c-api/conversion.rst index 371ba8b03a85e1..78e27a01d2389a 100644 --- a/Doc/c-api/conversion.rst +++ b/Doc/c-api/conversion.rst @@ -167,43 +167,53 @@ The following functions provide locale-independent string to number conversions. Character classification and conversion ======================================= -The following macros provide locale-independent character classification and -conversion. The argument must be a signed or unsigned :c:expr:`char`. +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*.