From 3254ff5b4fc12d24991f3c7d0fc90502b3381a5c Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 11:23:02 +0200 Subject: [PATCH 1/5] gh-107801: Improve the accuracy of os.lseek docs - name the last parameter *whence*, like it is for seek() methods on file objects - add param docstrings - structure the valid *whence* values as a list --- Doc/library/os.rst | 13 ++++++++----- Modules/posixmodule.c | 13 +++++++++---- 2 files changed, 17 insertions(+), 9 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 9735baa5bc0f3a..5582a3d7a6e14b 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1163,13 +1163,16 @@ as internal buffering of data. .. versionadded:: 3.11 -.. function:: lseek(fd, pos, how, /) +.. function:: lseek(fd, pos, whence, /) Set the current position of file descriptor *fd* to position *pos*, modified - by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the - beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the - current position; :const:`SEEK_END` or ``2`` to set it relative to the end of - the file. Return the new cursor position in bytes, starting from the beginning. + by *whence*, and return the new position in bytes, relative to + the start of the file. + Valid values for *whence* are: + + * :const:`SEEK_SET` or ``0`` -- set *pos* relative to the beginning of the file + * :const:`SEEK_CUR` or ``1`` -- set *pos* relative to the current file position + * :const:`SEEK_END` or ``2`` -- set *pos* relative to the end of the file .. data:: SEEK_SET diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index a42e41c081e5b7..ae5c5f34e47c66 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -10422,14 +10422,19 @@ os_lockf_impl(PyObject *module, int fd, int command, Py_off_t length) os.lseek -> Py_off_t fd: int + An open file descriptor, as returned by os.open(). position: Py_off_t - how: int + Position, interpreted relative to 'whence'. + whence as how: int + The relative position to seek from. Valid values are: + - SEEK_SET: seek from the start of the file. + - SEEK_CUR: seek from the current file position. + - SEEK_END: seek from the end of the file. / -Set the position of a file descriptor. Return the new position. +Set the position of a file descriptor, and return the new position. -Return the new cursor position in number of bytes -relative to the beginning of the file. +The return value is the number of bytes relative to the beginning of the file. [clinic start generated code]*/ static Py_off_t From 0c57eef01eb9beeacf1aee9818d6bb8b7bc753da Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 13:12:14 +0200 Subject: [PATCH 2/5] Regen clinic --- Modules/clinic/posixmodule.c.h | 19 ++++++++++++++----- Modules/posixmodule.c | 2 +- 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/Modules/clinic/posixmodule.c.h b/Modules/clinic/posixmodule.c.h index 81e3162e679d16..3a89094cff854d 100644 --- a/Modules/clinic/posixmodule.c.h +++ b/Modules/clinic/posixmodule.c.h @@ -6496,13 +6496,22 @@ os_lockf(PyObject *module, PyObject *const *args, Py_ssize_t nargs) #endif /* defined(HAVE_LOCKF) */ PyDoc_STRVAR(os_lseek__doc__, -"lseek($module, fd, position, how, /)\n" +"lseek($module, fd, position, whence, /)\n" "--\n" "\n" -"Set the position of a file descriptor. Return the new position.\n" +"Set the position of a file descriptor, and return the new position.\n" "\n" -"Return the new cursor position in number of bytes\n" -"relative to the beginning of the file."); +" fd\n" +" An open file descriptor, as returned by os.open().\n" +" position\n" +" Position, interpreted relative to \'whence\'.\n" +" whence\n" +" The relative position to seek from. Valid values are:\n" +" - SEEK_SET: seek from the start of the file.\n" +" - SEEK_CUR: seek from the current file position.\n" +" - SEEK_END: seek from the end of the file.\n" +"\n" +"The return value is the number of bytes relative to the beginning of the file."); #define OS_LSEEK_METHODDEF \ {"lseek", _PyCFunction_CAST(os_lseek), METH_FASTCALL, os_lseek__doc__}, @@ -11981,4 +11990,4 @@ os_waitstatus_to_exitcode(PyObject *module, PyObject *const *args, Py_ssize_t na #ifndef OS_WAITSTATUS_TO_EXITCODE_METHODDEF #define OS_WAITSTATUS_TO_EXITCODE_METHODDEF #endif /* !defined(OS_WAITSTATUS_TO_EXITCODE_METHODDEF) */ -/*[clinic end generated code: output=a85a386b212b0631 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=23dfb68866509e02 input=a9049054013a1b77]*/ diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index ae5c5f34e47c66..7792b5b689a92c 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -10439,7 +10439,7 @@ The return value is the number of bytes relative to the beginning of the file. static Py_off_t os_lseek_impl(PyObject *module, int fd, Py_off_t position, int how) -/*[clinic end generated code: output=971e1efb6b30bd2f input=902654ad3f96a6d3]*/ +/*[clinic end generated code: output=971e1efb6b30bd2f input=0642ea3d1c708c40]*/ { Py_off_t result; From 12b0471e29aa9786dd11242b1885e2e4433b85ea Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 23:03:40 +0200 Subject: [PATCH 3/5] Update Doc/library/os.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/os.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 5582a3d7a6e14b..020237a1c44829 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1166,7 +1166,7 @@ as internal buffering of data. .. function:: lseek(fd, pos, whence, /) Set the current position of file descriptor *fd* to position *pos*, modified - by *whence*, and return the new position in bytes, relative to + by *whence*, and return the new position in bytes relative to the start of the file. Valid values for *whence* are: From ca27fca6e967b2cc43d8ad465bc1354515c9fb8e Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 15 Aug 2023 12:30:58 +0200 Subject: [PATCH 4/5] Revert summary line change --- Modules/clinic/posixmodule.c.h | 4 ++-- Modules/posixmodule.c | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Modules/clinic/posixmodule.c.h b/Modules/clinic/posixmodule.c.h index 3a89094cff854d..9b3fa8ded26766 100644 --- a/Modules/clinic/posixmodule.c.h +++ b/Modules/clinic/posixmodule.c.h @@ -6499,7 +6499,7 @@ PyDoc_STRVAR(os_lseek__doc__, "lseek($module, fd, position, whence, /)\n" "--\n" "\n" -"Set the position of a file descriptor, and return the new position.\n" +"Set the position of a file descriptor. Return the new position.\n" "\n" " fd\n" " An open file descriptor, as returned by os.open().\n" @@ -11990,4 +11990,4 @@ os_waitstatus_to_exitcode(PyObject *module, PyObject *const *args, Py_ssize_t na #ifndef OS_WAITSTATUS_TO_EXITCODE_METHODDEF #define OS_WAITSTATUS_TO_EXITCODE_METHODDEF #endif /* !defined(OS_WAITSTATUS_TO_EXITCODE_METHODDEF) */ -/*[clinic end generated code: output=23dfb68866509e02 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=9a5f78bb65470528 input=a9049054013a1b77]*/ diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index 7792b5b689a92c..598efcf0468255 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -10432,14 +10432,14 @@ os.lseek -> Py_off_t - SEEK_END: seek from the end of the file. / -Set the position of a file descriptor, and return the new position. +Set the position of a file descriptor. Return the new position. The return value is the number of bytes relative to the beginning of the file. [clinic start generated code]*/ static Py_off_t os_lseek_impl(PyObject *module, int fd, Py_off_t position, int how) -/*[clinic end generated code: output=971e1efb6b30bd2f input=0642ea3d1c708c40]*/ +/*[clinic end generated code: output=971e1efb6b30bd2f input=f096e754c5367504]*/ { Py_off_t result; From aa568d3c291533cd1f9a6444e86613a7d5b3f872 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 18 Aug 2023 11:25:35 +0200 Subject: [PATCH 5/5] Add short description of HOLE/DATA --- Doc/library/os.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 755a602ebc65e6..7d63ac15027d51 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1173,10 +1173,12 @@ as internal buffering of data. * :const:`SEEK_SET` or ``0`` -- set *pos* relative to the beginning of the file * :const:`SEEK_CUR` or ``1`` -- set *pos* relative to the current file position * :const:`SEEK_END` or ``2`` -- set *pos* relative to the end of the file + * :const:`SEEK_HOLE` -- set *pos* to the next data location, relative to *pos* + * :const:`SEEK_DATA` -- set *pos* to the next data hole, relative to *pos* .. versionchanged:: 3.3 - Add support for :const:`SEEK_HOLE` and :const:`SEEK_DATA`. + Add support for :const:`!SEEK_HOLE` and :const:`!SEEK_DATA`. .. data:: SEEK_SET