Skip to content

gh-107801: Improve io.*.seek docs and docstrings #107899

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
erlend-aasland wants to merge 3 commits into from
Closed

gh-107801: Improve io.*.seek docs and docstrings #107899

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d087aaf
gh-107801: Improve io.*.seek docs and docstrings
erlend-aasland Aug 12, 2023
8bd646f
offset is int
erlend-aasland Aug 12, 2023
4fc2095
Use C default 0; we cannot guarantee what SEEK_SET is on C level
erlend-aasland Aug 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Use C default 0; we cannot guarantee what SEEK_SET is on C level
  • Loading branch information
@erlend-aasland
erlend-aasland committed Aug 13, 2023
commit 4fc20957ca8e65ef8be0393432651e1a202521ca
4 changes: 2 additions & 2 deletions Modules/_io/bufferedio.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1285,13 +1285,13 @@ _io__Buffered_tell_impl(buffered *self)
/*[clinic input]
_io._Buffered.seek
offset as targetobj: object
whence: int(c_default='SEEK_SET') = io.SEEK_SET
whence: int(c_default='0') = io.SEEK_SET
/
[clinic start generated code]*/

static PyObject *
_io__Buffered_seek_impl(buffered *self, PyObject *targetobj, int whence)
/*[clinic end generated code: output=7ae0e8dc46efdefb input=51b4741b1f355115]*/
/*[clinic end generated code: output=7ae0e8dc46efdefb input=d9ac57b8f178bc05]*/
{
Py_off_t target, n;
PyObject *res = NULL;
Expand Down
4 changes: 2 additions & 2 deletions Modules/_io/bytesio.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -637,7 +637,7 @@ bytesio_iternext(bytesio *self)
/*[clinic input]
_io.BytesIO.seek
offset as pos: Py_ssize_t
whence: int(c_default='SEEK_SET') = io.SEEK_SET
whence: int(c_default='0') = io.SEEK_SET
/

Change stream position and return the new absolute position.
Expand All @@ -647,7 +647,7 @@ Set the byte offset 'offset', relative to position indicated by 'whence':

static PyObject *
_io_BytesIO_seek_impl(bytesio *self, Py_ssize_t pos, int whence)
/*[clinic end generated code: output=c26204a68e9190e4 input=2dd44abb89ad75fb]*/
/*[clinic end generated code: output=c26204a68e9190e4 input=dbeeba9f5f031b6e]*/
{
CHECK_CLOSED(self);

Expand Down
4 changes: 2 additions & 2 deletions Modules/_io/clinic/bufferedio.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Modules/_io/clinic/bytesio.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Modules/_io/clinic/iobase.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Modules/_io/clinic/stringio.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Modules/_io/clinic/textio.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Modules/_io/iobase.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ _io._IOBase.seek
offset: int(unused=True)
Offset as byte count.
Relative to the position given by 'whence'.
whence: int(unused=True, c_default='SEEK_SET') = io.SEEK_SET
whence: int(unused=True, c_default='0') = io.SEEK_SET
Relative position, used by 'offset'. Valid values are:
* io.SEEK_SET -- Start of stream (the default)
* io.SEEK_CUR -- Current position
Expand All @@ -107,7 +107,7 @@ Note that not all file objects are seekable.
static PyObject *
_io__IOBase_seek_impl(PyObject *self, PyTypeObject *cls,
int Py_UNUSED(offset), int Py_UNUSED(whence))
/*[clinic end generated code: output=8bd74ea6538ded53 input=d7bfaaec026b9090]*/
/*[clinic end generated code: output=8bd74ea6538ded53 input=bcdff2c6dd398df8]*/
{
_PyIO_State *state = get_io_state_by_cls(cls);
return iobase_unsupported(state, "seek");
Expand Down
4 changes: 2 additions & 2 deletions Modules/_io/stringio.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -464,7 +464,7 @@ _io_StringIO_truncate_impl(stringio *self, Py_ssize_t size)
/*[clinic input]
_io.StringIO.seek
offset as pos: Py_ssize_t
whence: int(c_default='SEEK_SET') = io.SEEK_SET
whence: int(c_default='0') = io.SEEK_SET
Comment on lines +466 to +467
Copy link
Copy Markdown
Member

@serhiy-storchaka serhiy-storchaka Aug 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should also copy parameter docstrings. Otherwise the function docstring will look incomplete.

Copy link
Copy Markdown
Contributor Author

@erlend-aasland erlend-aasland Aug 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The param docstrings are rendered to be a part of the docstring during clinic input parsing. It will be part of the whole docstring after make clinic. The subclasses will inherit this, unless they override the docstring explicitly.

Copy link
Copy Markdown
Member

@serhiy-storchaka serhiy-storchaka Aug 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. Subclasses "inherit" docstrings only if they do not have their own docstrings.

I put "inherit" in quotes because actually they do not do this. It is pydoc who falls back to looking up docstrings in the parent classes.

Look at the Argument Clinic generated docstrings and you will see that they are incomplete.

Copy link
Copy Markdown
Contributor Author

@erlend-aasland erlend-aasland Aug 14, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docstrings as of this PR:

Details 
Seek docs for <class '_io.BufferedRWPair'>:
BufferedRWPair.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

BufferedRWPair.__doc__:
 Change the stream position and return the new absolute position.

  offset
    Offset as byte count.
    Relative to the position given by 'whence'.
  whence
    Relative position, used by 'offset'. Valid values are:
    * io.SEEK_SET -- Start of stream (the default)
    * io.SEEK_CUR -- Current position
    * io.SEEK_END -- End of stream

Offsets relative to the start of the stream are usually zero or
positive, offsets relative to the current stream position may be
zero, positive or negative, and offsets relative to the end of the
stream are usually zero or negative.

Some platforms allow seeking beyond the end of a file.

Note that not all file objects are seekable.

Seek docs for <class '_io.BufferedRandom'>:
BufferedRandom.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

BufferedRandom.__doc__:
 None

Seek docs for <class '_io.BufferedReader'>:
BufferedReader.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

BufferedReader.__doc__:
 None

Seek docs for <class '_io.BufferedWriter'>:
BufferedWriter.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

BufferedWriter.__doc__:
 None

Seek docs for <class '_io.BytesIO'>:
BytesIO.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

BytesIO.__doc__:
 Change stream position and return the new absolute position.

Set the byte offset 'offset', relative to position indicated by 'whence':

Seek docs for <class '_io.FileIO'>:
FileIO.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

FileIO.__doc__:
 None

Seek docs for <class '_io.StringIO'>:
StringIO.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

StringIO.__doc__:
 Change the stream position and return the new absolute position.

Offsets relative to the start of the stream are usually zero or positive.
Offsets relative to the current and end of file positions must zero;
any other values are unsupported, and will raise OSError.

Some platforms allow seeking beyond the end of a file.

Note that not all file objects are seekable.

Seek docs for <class '_io.TextIOWrapper'>:
TextIOWrapper.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

TextIOWrapper.__doc__:
 Change the file position and return the new absolute position.

Offsets relative to the start of the file are usually zero or positive.
Offsets relative to the current and end of file positions must zero;
any other values are unsupported, and will raise the
io.UnsupportedOperation exception.

Some platforms allow seeking beyond the end of a file.

Note that not all file objects are seekable.

Seek docs for <class '_io._BufferedIOBase'>:
_BufferedIOBase.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

_BufferedIOBase.__doc__:
 Change the stream position and return the new absolute position.

  offset
    Offset as byte count.
    Relative to the position given by 'whence'.
  whence
    Relative position, used by 'offset'. Valid values are:
    * io.SEEK_SET -- Start of stream (the default)
    * io.SEEK_CUR -- Current position
    * io.SEEK_END -- End of stream

Offsets relative to the start of the stream are usually zero or
positive, offsets relative to the current stream position may be
zero, positive or negative, and offsets relative to the end of the
stream are usually zero or negative.

Some platforms allow seeking beyond the end of a file.

Note that not all file objects are seekable.

Seek docs for <class '_io._IOBase'>:
_IOBase.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

_IOBase.__doc__:
 Change the stream position and return the new absolute position.

  offset
    Offset as byte count.
    Relative to the position given by 'whence'.
  whence
    Relative position, used by 'offset'. Valid values are:
    * io.SEEK_SET -- Start of stream (the default)
    * io.SEEK_CUR -- Current position
    * io.SEEK_END -- End of stream

Offsets relative to the start of the stream are usually zero or
positive, offsets relative to the current stream position may be
zero, positive or negative, and offsets relative to the end of the
stream are usually zero or negative.

Some platforms allow seeking beyond the end of a file.

Note that not all file objects are seekable.

Seek docs for <class '_io._RawIOBase'>:
_RawIOBase.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

_RawIOBase.__doc__:
 Change the stream position and return the new absolute position.

  offset
    Offset as byte count.
    Relative to the position given by 'whence'.
  whence
    Relative position, used by 'offset'. Valid values are:
    * io.SEEK_SET -- Start of stream (the default)
    * io.SEEK_CUR -- Current position
    * io.SEEK_END -- End of stream

Offsets relative to the start of the stream are usually zero or
positive, offsets relative to the current stream position may be
zero, positive or negative, and offsets relative to the end of the
stream are usually zero or negative.

Some platforms allow seeking beyond the end of a file.

Note that not all file objects are seekable.

Seek docs for <class '_io._TextIOBase'>:
_TextIOBase.__text_signature__:
($self, offset, whence=io.SEEK_SET, /)

_TextIOBase.__doc__:
 Change the stream position and return the new absolute position.

  offset
    Offset as byte count.
    Relative to the position given by 'whence'.
  whence
    Relative position, used by 'offset'. Valid values are:
    * io.SEEK_SET -- Start of stream (the default)
    * io.SEEK_CUR -- Current position
    * io.SEEK_END -- End of stream

Offsets relative to the start of the stream are usually zero or
positive, offsets relative to the current stream position may be
zero, positive or negative, and offsets relative to the end of the
stream are usually zero or negative.

Some platforms allow seeking beyond the end of a file.

Note that not all file objects are seekable.

Copy link
Copy Markdown
Contributor Author

@erlend-aasland erlend-aasland Aug 14, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Look at the Argument Clinic generated docstrings and you will see that they are incomplete.

Of course. Only the _IOBase docstring will be generated completely with param docstrings inlined, as the PR stands now.

Copy link
Copy Markdown
Contributor Author

@erlend-aasland erlend-aasland Aug 14, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps param docstrings are not a good fit for these functions, though.

Copy link
Copy Markdown
Member

@serhiy-storchaka serhiy-storchaka Aug 14, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All docstrings should be complete. If possible, make them empty, then pydoc will show the docstring from the parent class. Perhaps you only need two docstrings: for binary and text streams.

/

Change the stream position and return the new absolute position.
Expand All @@ -480,7 +480,7 @@ Note that not all file objects are seekable.

static PyObject *
_io_StringIO_seek_impl(stringio *self, Py_ssize_t pos, int whence)
/*[clinic end generated code: output=e9e0ac9a8ae71c25 input=40a33f8f64ddc34e]*/
/*[clinic end generated code: output=e9e0ac9a8ae71c25 input=50823fbdc8782825]*/
{
CHECK_INITIALIZED(self);
CHECK_CLOSED(self);
Expand Down
4 changes: 2 additions & 2 deletions Modules/_io/textio.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2428,7 +2428,7 @@ _textiowrapper_encoder_setstate(textio *self, cookie_type *cookie)
/*[clinic input]
_io.TextIOWrapper.seek
offset as cookieObj: object
whence: int(c_default='SEEK_SET') = io.SEEK_SET
whence: int(c_default='0') = io.SEEK_SET
/

Change the file position and return the new absolute position.
Expand All @@ -2445,7 +2445,7 @@ Note that not all file objects are seekable.

static PyObject *
_io_TextIOWrapper_seek_impl(textio *self, PyObject *cookieObj, int whence)
/*[clinic end generated code: output=0a15679764e2d04d input=0e4b087bfcf07780]*/
/*[clinic end generated code: output=0a15679764e2d04d input=35d7e7156afb3e56]*/
{
PyObject *posobj;
cookie_type cookie;
Expand Down