From 384bfa68c7722608649997cec6f45d274cdb53e0 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 19 Oct 2026 17:55:48 -0400 Subject: [PATCH] gh-141004: Document `Py_UniversalNewlineFgets` (GH-159713) (cherry picked from commit 6297f8dc5167c49a62a9416cb840f3e116fb29e4) Co-authored-by: Peter Bierma --- Doc/c-api/file.rst | 23 +++++++++++++++++++++++ Tools/check-c-api-docs/ignored_c_api.txt | 2 -- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index dcafefdc0458722..45f2d1a6f53c697 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -60,6 +60,29 @@ the :mod:`io` APIs instead. raised if the end of the file is reached immediately. +.. c:function:: char* Py_UniversalNewlineFgets(char *buf, int n, FILE *stream, PyObject *fobj) + + Read a line from the C stream *stream* into the buffer *buf*, like the + C standard library function :c:func:`!fgets`, but treating all of ``\n``, + ``\r`` and ``\r\n`` as line endings (see :term:`universal newlines`). + Any ``\r`` or ``\r\n`` read from the stream is stored in *buf* as a + single ``\n``. + + At most ``n - 1`` characters are stored in *buf*; reading stops after a + newline has been stored or when the end of the file is reached. + The result is always null-terminated. + *stream* should be opened in binary mode, so that the C library does not + perform its own newline translation. + + Return *buf* on success. + Return ``NULL`` if no characters could be read, because *stream* is at + end of file, a read error occurred, or *n* is less than 2. + Like :c:func:`!fgets`, this function does not distinguish between end of + file and a read error, and it does not set an exception. + + *fobj* exists only for backward compatibility and must be ``NULL``. + + .. c:function:: int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler) Overrides the normal behavior of :func:`io.open_code` to pass its parameter diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index 3c8400a9b3c75a7..55d72b8574825ac 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -56,8 +56,6 @@ PyDescr_COMMON PyDescr_NAME PyDescr_TYPE PyWrapperFlag_KEYWORDS -# cpython/fileobject.h -Py_UniversalNewlineFgets # cpython/pylifecycle.h Py_FrozenMain # cpython/objimpl.h