From d049ec098362feeec990626a77a1a1c1b45b8613 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 19 Oct 2026 12:55:04 -0400 Subject: [PATCH 1/2] Document Py_UniversalNewlineFgets() --- Doc/c-api/file.rst | 25 ++++++++++++++++++++++++ Tools/check-c-api-docs/ignored_c_api.txt | 2 -- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index dcafefdc0458722..abb31b17784f2ee 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -60,6 +60,31 @@ 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``. + If it is not ``NULL``, nothing is read, :c:data:`errno` is set to + :c:macro:`!ENXIO` and ``NULL`` is returned. + + .. 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 af7b2772ef5e085..ec82a47f293d4ea 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -33,8 +33,6 @@ PyCFunction_GET_CLASS PyDescr_NAME PyDescr_TYPE PyWrapperFlag_KEYWORDS -# cpython/fileobject.h -Py_UniversalNewlineFgets # cpython/pylifecycle.h Py_FrozenMain # cpython/objimpl.h From 2b56d93ef1ef51e0136f76fb33e9c46492a8fba8 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 19 Oct 2026 17:44:21 -0400 Subject: [PATCH 2/2] Update Doc/c-api/file.rst Co-authored-by: Petr Viktorin --- Doc/c-api/file.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index abb31b17784f2ee..45f2d1a6f53c697 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -81,8 +81,6 @@ the :mod:`io` APIs instead. file and a read error, and it does not set an exception. *fobj* exists only for backward compatibility and must be ``NULL``. - If it is not ``NULL``, nothing is read, :c:data:`errno` is set to - :c:macro:`!ENXIO` and ``NULL`` is returned. .. c:function:: int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)