https://github.com/python/cpython/commit/22a6215825892214959f67eb5cac8be404de434c commit: 22a6215825892214959f67eb5cac8be404de434c branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: ZeroIntensity <[email protected]> date: 2026-10-19T18:06:10-04:00 summary:
[3.14] gh-141004: Document `Py_UniversalNewlineFgets` (GH-159713) (GH-159798) (cherry picked from commit 6297f8dc5167c49a62a9416cb840f3e116fb29e4) Co-authored-by: Peter Bierma <[email protected]> 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 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 _______________________________________________ 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]
