Skip to content

bpo-8840: Improve docstrings for truncate() #6011

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
akuchling wants to merge 3 commits into from
Closed

bpo-8840: Improve docstrings for truncate() #6011

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
befa8ba
bpo-8840: Improve docstrings for truncate()
akuchling Mar 7, 2018
3c18ae1
bpo-8840: use correct parameter name
akuchling Mar 29, 2018
2d0a5d4
bpo-8840: Consistently use single-quotes around parameter name
akuchling Mar 29, 2018
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
24 changes: 17 additions & 7 deletions Lib/_pyio.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -342,10 +342,12 @@ def tell(self):
return self.seek(0, 1)

def truncate(self, pos=None):
"""Truncate file to size bytes.
"""Resize stream to at most 'pos' bytes.
Copy link
Copy Markdown
Member

@vadmium vadmium Oct 13, 2018

Choose a reason for hiding this comment

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

For most truncate methods, I don’t think the “at most” wording should be added. It should also be okay to remove it from FileIO.truncate. These methods are supposed to either resize to exactly the specified size, or raise an exception.

The odd one out is be BytesIO.truncate, which currently does not expand the size (https://bugs.python.org/issue27261).


Size defaults to the current IO position as reported by tell(). Return
the new size.
The position in the stream is left unchanged. The size
defaults to the current IO position as reported by tell(). If
the stream's size is increased, the contents of the new file
area are undetermined. Returns the new size.
Copy link
Copy Markdown
Member

@vadmium vadmium Oct 13, 2018

Choose a reason for hiding this comment

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

The contents depend on the platform according to the main RST documentation.

IMO it is okay to leave out this level of detail from docstrings.

"""
self._unsupported("truncate")

Expand Down Expand Up @@ -1670,10 +1672,12 @@ def tell(self):
return os.lseek(self._fd, 0, SEEK_CUR)

def truncate(self, size=None):
"""Truncate the file to at most size bytes.
"""Resize stream to at most 'size' bytes.

Size defaults to the current file position, as returned by tell().
The current file position is changed to the value of size.
The position in the stream is left unchanged. The size
defaults to the current IO position as reported by tell(). If
the stream's size is increased, the contents of the new file
area are undetermined. Returns the new size.
"""
self._checkClosed()
self._checkWritable()
Expand Down Expand Up @@ -1778,7 +1782,13 @@ def write(self, s):
self._unsupported("write")

def truncate(self, pos=None):
"""Truncate size to pos, where pos is an int."""
"""Resize stream to at most 'pos' characters.

The position in the stream is left unchanged. The size
defaults to the current IO position as reported by tell(). If
the stream's size is increased, the contents of the new file
area are undetermined. Returns the new size.
"""
self._unsupported("truncate")

def readline(self):
Expand Down
10 changes: 6 additions & 4 deletions Modules/_io/bytesio.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -552,15 +552,17 @@ _io.BytesIO.truncate
size: Py_ssize_t(accept={int, NoneType}, c_default="self->pos") = None
/

Truncate the file to at most size bytes.
Resize stream to at most 'size' bytes.

Size defaults to the current file position, as returned by tell().
The current file position is unchanged. Returns the new size.
Position in the stream is left unchanged. Size defaults to
the current IO position as reported by tell(). If the stream's
size is increased, the contents of the new file area are
undetermined. Returns the new size.
[clinic start generated code]*/

static PyObject *
_io_BytesIO_truncate_impl(bytesio *self, Py_ssize_t size)
/*[clinic end generated code: output=9ad17650c15fa09b input=423759dd42d2f7c1]*/
/*[clinic end generated code: output=9ad17650c15fa09b input=0f69785dcc22737e]*/
{
CHECK_CLOSED(self);
CHECK_EXPORTS(self);
Expand Down
10 changes: 6 additions & 4 deletions Modules/_io/clinic/bytesio.c.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -314,10 +314,12 @@ PyDoc_STRVAR(_io_BytesIO_truncate__doc__,
"truncate($self, size=None, /)\n"
"--\n"
"\n"
"Truncate the file to at most size bytes.\n"
"Resize stream to at most \'size\' bytes.\n"
"\n"
"Size defaults to the current file position, as returned by tell().\n"
"The current file position is unchanged. Returns the new size.");
"Position in the stream is left unchanged. Size defaults to\n"
"the current IO position as reported by tell(). If the stream\'s\n"
"size is increased, the contents of the new file area are\n"
"undetermined. Returns the new size.");

#define _IO_BYTESIO_TRUNCATE_METHODDEF \
{"truncate", (PyCFunction)_io_BytesIO_truncate, METH_FASTCALL, _io_BytesIO_truncate__doc__},
Expand Down Expand Up @@ -444,4 +446,4 @@ _io_BytesIO___init__(PyObject *self, PyObject *args, PyObject *kwargs)
exit:
return return_value;
}
/*[clinic end generated code: output=9ba9a68c8c5669e7 input=a9049054013a1b77]*/
/*[clinic end generated code: output=934f685bde756d6d input=a9049054013a1b77]*/
10 changes: 6 additions & 4 deletions Modules/_io/clinic/fileio.c.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -322,10 +322,12 @@ PyDoc_STRVAR(_io_FileIO_truncate__doc__,
"truncate($self, size=None, /)\n"
"--\n"
"\n"
"Truncate the file to at most size bytes and return the truncated size.\n"
"Resize stream to at most \'size\' bytes.\n"
"\n"
"Size defaults to the current file position, as returned by tell().\n"
"The current file position is changed to the value of size.");
"Position in the stream is left unchanged. Size defaults to\n"
"the current IO position as reported by tell(). If the stream\'s\n"
"size is increased, the contents of the new file area are\n"
"undetermined. Returns the new size.");

#define _IO_FILEIO_TRUNCATE_METHODDEF \
{"truncate", (PyCFunction)_io_FileIO_truncate, METH_FASTCALL, _io_FileIO_truncate__doc__},
Expand Down Expand Up @@ -373,4 +375,4 @@ _io_FileIO_isatty(fileio *self, PyObject *Py_UNUSED(ignored))
#ifndef _IO_FILEIO_TRUNCATE_METHODDEF
#define _IO_FILEIO_TRUNCATE_METHODDEF
#endif /* !defined(_IO_FILEIO_TRUNCATE_METHODDEF) */
/*[clinic end generated code: output=a8796438c8b7c49a input=a9049054013a1b77]*/
/*[clinic end generated code: output=b0ef426afce9a6c3 input=a9049054013a1b77]*/
11 changes: 6 additions & 5 deletions Modules/_io/clinic/stringio.c.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,11 +103,12 @@ PyDoc_STRVAR(_io_StringIO_truncate__doc__,
"truncate($self, pos=None, /)\n"
"--\n"
"\n"
"Truncate size to pos.\n"
"Resize stream to at most \'pos\' characters.\n"
"\n"
"The pos argument defaults to the current file position, as\n"
"returned by tell(). The current file position is unchanged.\n"
"Returns the new absolute position.");
"The position in the stream is left unchanged. The size defaults to\n"
"the current IO position as reported by tell(). If the stream\'s size\n"
"is increased, the contents of the new file area are undetermined.\n"
"Returns the new size.");

#define _IO_STRINGIO_TRUNCATE_METHODDEF \
{"truncate", (PyCFunction)_io_StringIO_truncate, METH_FASTCALL, _io_StringIO_truncate__doc__},
Expand Down Expand Up @@ -286,4 +287,4 @@ _io_StringIO_seekable(stringio *self, PyObject *Py_UNUSED(ignored))
{
return _io_StringIO_seekable_impl(self);
}
/*[clinic end generated code: output=73c4d6e5cc3b1a58 input=a9049054013a1b77]*/
/*[clinic end generated code: output=64a903b7c3c45564 input=a9049054013a1b77]*/
10 changes: 6 additions & 4 deletions Modules/_io/fileio.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -979,15 +979,17 @@ _io.FileIO.truncate
size as posobj: object = NULL
/

Truncate the file to at most size bytes and return the truncated size.
Resize stream to at most 'size' bytes.

Size defaults to the current file position, as returned by tell().
The current file position is changed to the value of size.
Position in the stream is left unchanged. Size defaults to
the current IO position as reported by tell(). If the stream's
size is increased, the contents of the new file area are
undetermined. Returns the new size.
[clinic start generated code]*/

static PyObject *
_io_FileIO_truncate_impl(fileio *self, PyObject *posobj)
/*[clinic end generated code: output=e49ca7a916c176fa input=9026af44686b7318]*/
/*[clinic end generated code: output=e49ca7a916c176fa input=b60ed73a8ce11d96]*/
{
Py_off_t pos;
int ret;
Expand Down
8 changes: 5 additions & 3 deletions Modules/_io/iobase.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,10 +118,12 @@ _io__IOBase_tell_impl(PyObject *self)
}

PyDoc_STRVAR(iobase_truncate_doc,
"Truncate file to size bytes.\n"
"Resize stream to at most 'size' bytes.\n"
"\n"
"File pointer is left unchanged. Size defaults to the current IO\n"
"position as reported by tell(). Returns the new size.");
"Position in the stream is left unchanged. Size defaults to\n"
"the current IO position as reported by tell(). If the stream's\n"
"size is increased, the contents of the new file area are undetermined.\n"
"Returns the new size.");

static PyObject *
iobase_truncate(PyObject *self, PyObject *args)
Expand Down
11 changes: 6 additions & 5 deletions Modules/_io/stringio.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -435,16 +435,17 @@ _io.StringIO.truncate
pos as size: Py_ssize_t(accept={int, NoneType}, c_default="self->pos") = None
/

Truncate size to pos.
Resize stream to at most 'pos' characters.

The pos argument defaults to the current file position, as
returned by tell(). The current file position is unchanged.
Returns the new absolute position.
The position in the stream is left unchanged. The size defaults to
the current IO position as reported by tell(). If the stream's size
is increased, the contents of the new file area are undetermined.
Returns the new size.
[clinic start generated code]*/

static PyObject *
_io_StringIO_truncate_impl(stringio *self, Py_ssize_t size)
/*[clinic end generated code: output=eb3aef8e06701365 input=5505cff90ca48b96]*/
/*[clinic end generated code: output=eb3aef8e06701365 input=f2b6a674a34b14a5]*/
{
CHECK_INITIALIZED(self);
CHECK_CLOSED(self);
Expand Down