From 885ec0ea0d0dedb01a4777f101bec0685aab473e Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 13:31:08 +0200 Subject: [PATCH 01/10] gh-107801: Document SEEK_HOLE and SEEK_DATA --- Doc/library/os.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 9735baa5bc0f3a..bf83be2cceba4c 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1180,8 +1180,27 @@ as internal buffering of data. respectively. .. versionadded:: 3.3 - Some operating systems could support additional values, like - :const:`os.SEEK_HOLE` or :const:`os.SEEK_DATA`. + +.. data:: SEEK_HOLE + SEEK_DATA + + Parameters to the :func:`lseek` function and the :meth:`~io.IOBase.seek` + method on file objects, for seeking file data and holes. + + :data:`!SEEK_DATA` + Adjust the file offset to the next location in the file containing data. + + :data:`!SEEK_HOLE` + Adjust the file offset to the next hole in the file. + A hole is defined as a sequence of zeros. + + .. note:: + + These operations only make sense for filesystems that support them. + + .. availability: Linux >= 3.1, macOS, Unix + + .. versionadded:: 3.1 .. function:: open(path, flags, mode=0o777, *, dir_fd=None) From 9985609b531780a87698cc83d48d0e3288457d9b Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 13:34:33 +0200 Subject: [PATCH 02/10] syntax --- 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 bf83be2cceba4c..e0ba3471c9d45c 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1198,7 +1198,7 @@ as internal buffering of data. These operations only make sense for filesystems that support them. - .. availability: Linux >= 3.1, macOS, Unix + .. availability:: Linux >= 3.1, macOS, Unix .. versionadded:: 3.1 From 27796954f2e2d719275e416ce86787faf5b99fb3 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 22:05:27 +0200 Subject: [PATCH 03/10] It was 3.3 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 e0ba3471c9d45c..48b931dda1ff2a 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1200,7 +1200,7 @@ as internal buffering of data. .. availability:: Linux >= 3.1, macOS, Unix - .. versionadded:: 3.1 + .. versionadded:: 3.3 .. function:: open(path, flags, mode=0o777, *, dir_fd=None) From 32eadec12fc1213dbf17c08564ffd59e8c205fa7 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 22:09:52 +0200 Subject: [PATCH 04/10] Update Doc/library/os.rst --- Doc/library/os.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 48b931dda1ff2a..e68ed1f09aa5a7 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1179,8 +1179,6 @@ as internal buffering of data. Parameters to the :func:`lseek` function. Their values are 0, 1, and 2, respectively. - .. versionadded:: 3.3 - .. data:: SEEK_HOLE SEEK_DATA From e120082962b46913525d330b3126e957904819c5 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 22:13:06 +0200 Subject: [PATCH 05/10] Add back a newline --- Doc/library/os.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index e68ed1f09aa5a7..a2babadcfee88a 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1179,6 +1179,7 @@ as internal buffering of data. Parameters to the :func:`lseek` function. Their values are 0, 1, and 2, respectively. + .. data:: SEEK_HOLE SEEK_DATA From 7dd2cefe02fe644da4376a6bd6c40324030a565a Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 14 Aug 2023 22:14:32 +0200 Subject: [PATCH 06/10] Add Antoine's suggestion --- Doc/library/os.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index a2babadcfee88a..90e2d5e3ea17c1 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1184,7 +1184,8 @@ as internal buffering of data. SEEK_DATA Parameters to the :func:`lseek` function and the :meth:`~io.IOBase.seek` - method on file objects, for seeking file data and holes. + method on file objects, for seeking file data and holes on sparsely + allocated files. :data:`!SEEK_DATA` Adjust the file offset to the next location in the file containing data. From fa3ee1d44e84c22a8a7cccb59284e217373842d3 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 15 Aug 2023 10:11:27 +0200 Subject: [PATCH 07/10] Add back 'versionadded' --- Doc/library/os.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 90e2d5e3ea17c1..71f72ce6ff4113 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1171,6 +1171,10 @@ as internal buffering of data. 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. +.. versionadded:: 3.3 + + Add support for :const:`SEEK_HOLE` and :const:`SEEK_DATA`. + .. data:: SEEK_SET SEEK_CUR From ecb16d7ebee11951cf43db12b78cec59b71d7672 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 15 Aug 2023 12:37:24 +0200 Subject: [PATCH 08/10] Fix indentation --- Doc/library/os.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 71f72ce6ff4113..9bc5fd4da63bb9 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1171,9 +1171,9 @@ as internal buffering of data. 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. -.. versionadded:: 3.3 + .. versionadded:: 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 From e580a687ceba12d26fb4e6b0848fe8ed5a76a7e6 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 15 Aug 2023 20:51:31 +0200 Subject: [PATCH 09/10] Address review: mention how the 'next location' relates to the seek position --- Doc/library/os.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 9bc5fd4da63bb9..df5321b2ad8b33 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1192,10 +1192,12 @@ as internal buffering of data. allocated files. :data:`!SEEK_DATA` - Adjust the file offset to the next location in the file containing data. + Adjust the file offset to the next location containing data, + relative to the seek position. :data:`!SEEK_HOLE` - Adjust the file offset to the next hole in the file. + Adjust the file offset to the next location containing a hole, + relative to the seek position. A hole is defined as a sequence of zeros. .. note:: From 5f516e64511d96e9c0fe4642975950492c717dc2 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 15 Aug 2023 22:39:27 +0200 Subject: [PATCH 10/10] Use versionchanged iso. verisonadded --- 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 df5321b2ad8b33..94b76e4052b94b 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1171,7 +1171,7 @@ as internal buffering of data. 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. - .. versionadded:: 3.3 + .. versionchanged:: 3.3 Add support for :const:`SEEK_HOLE` and :const:`SEEK_DATA`.