cpython/Doc/c-api
Stan Ulbrych 3402e133ef
gh-82045: Correct and deduplicate "isprintable" docs; add test. (GH-130118)
We had the definition of what makes a character "printable" documented in three places, giving two different definitions.
The definition in the comment on `_PyUnicode_IsPrintable` was inverted; correct that.

With that correction, the two definitions turn out to be equivalent -- but to confirm that, you have to go look up, or happen to know, that those are the only five "Other" categories and only three "Separator" categories in the Unicode character database.  That makes it hard for the reader to tell whether they really are the same, or if there's some subtle difference in the intended semantics.

Fix that by cutting the C API docs' and the C comment's copies of the subtle details, in favor of referring to the Python-level docs. That ensures it's explicit that these are all meant to agree, and also lets us concentrate improvements to the wording in one place.

Speaking of which, borrow some ideas from the C comment, along with other tweaks, to hopefully add a bit more clarity to that one newly-centralized copy in the docs.

Also add a thorough test that the implementation agrees with this definition.

Author:    Greg Price <gnprice@gmail.com>

Co-authored-by: Greg Price <gnprice@gmail.com>
2025-02-14 18:16:47 +01:00
..
abstract.rst gh-85275: Remove old buffer APIs (#105137) 2023-06-02 01:12:40 +00:00
allocation.rst Doc: C API: Delete claim that PyObject_Init is GC-aware (#126418) 2024-11-05 15:18:46 +05:30
apiabiversion.rst gh-128629: Add Py_PACK_VERSION and Py_PACK_FULL_VERSION (GH-128630) 2025-01-09 11:10:28 +01:00
arg.rst gh-90241: Clarify documentation for PyUnicode_FSConverter and PyUnicode_FSDecoder (GH-128451) 2025-01-06 13:28:50 +01:00
bool.rst gh-110481, doc: Add "immortal" term to the glossary (#112180) 2023-11-17 15:09:19 +01:00
buffer.rst gh-123609: Clarify usage of standalone PyBUF_FORMAT (GH-123778) 2024-09-10 15:05:28 +02:00
bytearray.rst Python 3.14.0a5 2025-02-11 19:16:29 +02:00
bytes.rst gh-121645: Fix typo in PyBytes_Join() doc (#123783) 2024-09-06 16:08:17 +02:00
call.rst Add a version added note for PY_VECTORCALL_ARGUMENTS_OFFSET (#110963) 2023-10-23 19:00:52 +03:00
capsule.rst gh-107298: Fix yet more Sphinx warnings in the C API doc (GH-107345) 2023-07-27 18:44:32 +03:00
cell.rst gh-121533: Improve PyCell_[Get,Set] docs: mention the exceptions (#121534) 2024-07-09 18:47:35 +03:00
code.rst gh-70870: Clarify dual usage of 'free variable' (#122545) 2024-10-08 07:52:12 +00:00
codec.rst gh-107298: Fix doc references to undocumented modules (#107300) 2023-07-26 18:59:06 +02:00
complex.rst gh-69639: Add mixed-mode rules for complex arithmetic (C-like) (GH-124829) 2024-11-26 17:57:39 +02:00
concrete.rst GH-97950: Use new-style index directive ('object') (#104158) 2023-05-04 13:04:41 +03:00
contextvars.rst gh-124872: Replace enter/exit events with "switched" (#125532) 2024-10-16 13:53:21 +02:00
conversion.rst gh-120026: soft deprecate Py_HUGE_VAL macro (#120027) 2024-11-01 22:04:31 +00:00
coro.rst bpo-42528: Improve the docs of most Py*_Check{,Exact} API calls (GH-23602) 2021-01-06 12:38:26 +01:00
datetime.rst gh-123517: Remove unnecessary `:meth:` parentheses (#123518) 2024-09-01 05:59:42 +01:00
descriptor.rst bpo-40170: Convert PyDescr_IsData() to static inline function (GH-24535) 2021-02-16 08:50:00 +01:00
dict.rst Fix phrasing in paragraphs with leading "similar" (#121135) 2024-07-01 17:36:27 -07:00
exceptions.rst gh-123378: Ensure results of PyUnicode*Error_Get{Start,End} are clamped (GH-123380) 2024-12-04 14:13:52 +01:00
file.rst gh-115172: Fix explicit index extries for the C API (GH-115173) 2024-02-11 12:23:30 +02:00
float.rst gh-121905: Consistently use "floating-point" instead of "floating point" (GH-121907) 2024-07-19 08:06:02 +00:00
frame.rst gh-118915: C API: Document frame locals proxies. (#127720) 2024-12-11 17:28:44 +01:00
function.rst gh-101100: Further improve docs on function attributes (#113001) 2023-12-12 20:21:12 +00:00
gcsupport.rst gh-101100: Fix sphinx warnings in c-api/gcsupport.rst (#114786) 2024-02-10 15:59:23 -07:00
gen.rst bpo-42528: Improve the docs of most Py*_Check{,Exact} API calls (GH-23602) 2021-01-06 12:38:26 +01:00
hash.rst gh-122854: Add Py_HashBuffer() function (#122855) 2024-08-30 15:42:27 +00:00
import.rst gh-128911: Add PyImport_ImportModuleAttr() function (#128912) 2025-01-30 11:17:29 +00:00
index.rst gh-111997: C-API for signalling monitoring events (#116413) 2024-05-04 08:23:50 +00:00
init.rst gh-101100: Docs: Fix some typos in the document (#129988) 2025-02-11 13:06:32 +02:00
init_config.rst Add Configuration Options table to PyInitConfig API doc (#129062) 2025-01-20 15:46:45 +01:00
intro.rst gh-115172: Fix explicit index extries for the C API (GH-115173) 2024-02-11 12:23:30 +02:00
iter.rst gh-105201: Add PyIter_NextItem() (#122331) 2024-08-08 00:47:15 +02:00
iterator.rst gh-107298: Fix Sphinx warnings in the C API doc (#107302) 2023-07-27 01:41:15 +02:00
list.rst gh-121403: Add notes for PyList_GetXXX APIs about the need for init (gh-121626) 2024-07-16 10:16:41 +09:00
long.rst gh-102471: Change PyLongWriter_Discard(NULL) to do nothing (#129339) 2025-01-27 10:51:16 +00:00
mapping.rst gh-108511: Add C API functions which do not silently ignore errors (GH-109025) 2023-09-17 14:23:31 +03:00
marshal.rst gh-125063: marshal: Add version 5, improve documentation (GH-126829) 2024-11-15 13:48:57 +01:00
memory.rst gh-119802: Update memory management docs for free-threaded build (gh-124006) 2024-09-13 15:15:44 +00:00
memoryview.rst gh-101100: Fix sphinx warnings in Doc/c-api/memoryview.rst (GH-114669) 2024-01-29 11:56:11 +02:00
method.rst gh-107091: Fix the use of some C domain roles (#107092) 2023-07-23 12:27:05 +02:00
module.rst gh-101944: Clarify PyModule_AddObjectRef() documentation (#129433) 2025-02-03 12:55:22 +01:00
monitoring.rst GH-122548: Implement branch taken and not taken events for sys.monitoring (GH-122564) 2024-12-19 16:59:51 +00:00
none.rst gh-110481, doc: Add "immortal" term to the glossary (#112180) 2023-11-17 15:09:19 +01:00
number.rst gh-121905: Consistently use "floating-point" instead of "floating point" (GH-121907) 2024-07-19 08:06:02 +00:00
object.rst Python 3.14.0a5 2025-02-11 19:16:29 +02:00
objimpl.rst Doc: Replace the deprecated highlightlang directive by highlight. (#13377) 2019-05-17 15:25:34 +05:30
perfmaps.rst gh-103295: expose API for writing perf map files (#103546) 2023-05-21 11:12:24 +01:00
refcounting.rst Use pep role instead of url (#121611) 2024-09-17 16:02:14 +03:00
reflection.rst gh-118934: Fix PyEval_GetLocals docs (PEP 667) (#119932) 2024-06-02 04:44:29 +00:00
sequence.rst gh-127896: Add missing documentation of PySequence_In (GH-127979) 2024-12-16 14:56:04 +01:00
set.rst gh-101100: Fix Sphinx reference warnings (GH-112416) 2023-11-25 15:40:19 -08:00
slice.rst gh-121567: Improve slice C-API docs by mentioning exceptions (#121568) 2024-07-10 13:56:44 +03:00
stable.rst gh-127253: Note that Stable ABI is about ABI stability (GH-127254) 2024-12-03 13:30:27 +01:00
structures.rst gh-123465: Allow Py_RELATIVE_OFFSET for __*offset__ members (GH-123474) 2024-09-05 14:14:05 +02:00
sys.rst Python 3.14.0a4 2025-01-14 13:52:58 +02:00
time.rst GH-109975: Copyedit 3.13 What's New: C API (#124313) 2024-09-23 14:28:17 +01:00
tuple.rst gh-124182: Explain naming rules for struct sequence types (#124335) 2024-10-07 19:52:34 +02:00
type.rst Docs: Fix incorrect indents in c-api/type.rst (#127449) 2024-11-30 15:01:15 +00:00
typehints.rst gh-107298: Fix Sphinx warnings in the C API doc (#107302) 2023-07-27 01:41:15 +02:00
typeobj.rst gh-129912: Fix references to Py_TPFLAGS_MANAGED_DICT (gh-130044) 2025-02-12 17:48:14 -05:00
unicode.rst gh-82045: Correct and deduplicate "isprintable" docs; add test. (GH-130118) 2025-02-14 18:16:47 +01:00
utilities.rst gh-110850: Add PyTime_t C API (GH-115215) 2024-02-12 18:13:10 +01:00
veryhigh.rst gh-118915: C API: Document compiler flag macros (GH-129028) 2025-01-20 17:45:08 +01:00
weakref.rst gh-128008: Add PyWeakref_IsDead() (GH-128009) 2024-12-19 16:17:15 +01:00