gh-107801: Document SEEK_HOLE and SEEK_DATA

[erlend-aasland]

• Issue: Docs and docstrings for io.*.seek are inconsistent #107801

---

📚 Documentation preview 📚: https://cpython-previews--107936.org.readthedocs.build/

[erlend-aasland]

I tried to keep this as simple as possible; since this is the reference, digressing deep into the explanation of the file hole/data concept and its use is out of place for a reference.

[AA-Turner]

All good!

A

[erlend-aasland]

Thanks for the reviews, Antoine and Adam; highly appreciated.

[serhiy-storchaka]

It is weird that the semantic of SEEK_HOLE and SEEK_DATA is described here, but the semantic of other three SEEK_* constants is described in other places. The latter in understandable, because it subtly differs for different types of streams. But I think that the documentation for all SEEK_* should be more unified.

1. One way, do not document the semantic here, but only document it in lseek() description, in a single item list (or two similar item lists).

2. Other way, add very general descriptions of traditional SEEK_* constants here (which works for all types of streams), more detailed description of new constants, and in the lseek() documentation and seek() methods documentation only document in details the behavior for traditional SEEK_* constants, and a reference for new SEEK_* constants.

In any case I think that changes in SEEK_* and lseek() documentations should be made in a single PR, because they are not independent.

[erlend-aasland]

I think it is fine to document these in a separate PR. Small and incremental changes are aligns well with the recommendations of the Diátaxis, which we are using.

More important:
We could unify the SEEK_ constant docs, but I think they also make sense grouped like they are now. I'm not sure it matters much. The HOLE/DATA constants are pretty obscure, but then so is the whole tell/seek API.

[AA-Turner]

I think it is fine to document these in a separate PR. Small and incremental changes ...

I agree with this, the previous PR got held up due to doing too much, I think these smaller PRs are easier -- noting that :const:`os.SEEK_HOLE` and :const:`os.SEEK_DATA` are currently referenced in the documentation.

A

[erlend-aasland]

Thanks, @AA-Turner and @pitrou; PTAL.

[erlend-aasland]

It looks to me all remarks have been addressed; I'm landing this later today, @pitrou. If further adjustments are needed, we can easily make a follow-up PR.

[miss-islington]

Thanks @erlend-aasland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

[bedevere-bot]

GH-108086 is a backport of this pull request to the 3.12 branch.

[bedevere-bot]

GH-108087 is a backport of this pull request to the 3.11 branch.