https://github.com/python/cpython/commit/6297f8dc5167c49a62a9416cb840f3e116fb29e4
commit: 6297f8dc5167c49a62a9416cb840f3e116fb29e4
branch: main
author: Peter Bierma <[email protected]>
committer: encukou <[email protected]>
date: 2026-10-19T21:55:48Z
summary:
gh-141004: Document `Py_UniversalNewlineFgets` (GH-159713)
files:
M Doc/c-api/file.rst
M Tools/check-c-api-docs/ignored_c_api.txt
diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index dcafefdc045872..45f2d1a6f53c69 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 1eb6806b83d5cd..754b8959b2e5d5 100644
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -32,8 +32,6 @@ PyCFunction_GET_CLASS
PyDescr_NAME
PyDescr_TYPE
PyWrapperFlag_KEYWORDS
-# cpython/fileobject.h
-Py_UniversalNewlineFgets
# cpython/pylifecycle.h
Py_FrozenMain
# cpython/objimpl.h
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
