From befa8ba1d53bc7c3119f34a966ce34230f45e992 Mon Sep 17 00:00:00 2001
From: Andrew Kuchling <amk@amk.ca>
Date: Tue, 6 Mar 2018 19:27:41 -0500
Subject: [PATCH 1/3] bpo-8840: Improve docstrings for truncate()

---
 Lib/_pyio.py                    | 24 +++++++++++++++++-------
 Modules/_io/bytesio.c           | 10 ++++++----
 Modules/_io/clinic/bytesio.c.h  | 10 ++++++----
 Modules/_io/clinic/fileio.c.h   | 10 ++++++----
 Modules/_io/clinic/stringio.c.h | 11 ++++++-----
 Modules/_io/fileio.c            | 10 ++++++----
 Modules/_io/iobase.c            |  8 +++++---
 Modules/_io/stringio.c          | 11 ++++++-----
 8 files changed, 58 insertions(+), 36 deletions(-)

diff --git a/Lib/_pyio.py b/Lib/_pyio.py
index c91a647a2f67b0d..e3f7024ac100a10 100644
--- a/Lib/_pyio.py
+++ b/Lib/_pyio.py
@@ -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.
 
-        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.
         """
         self._unsupported("truncate")
 
@@ -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 'pos' 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()
@@ -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):
diff --git a/Modules/_io/bytesio.c b/Modules/_io/bytesio.c
index ba33f8c50d6aade..4454092220c5397 100644
--- a/Modules/_io/bytesio.c
+++ b/Modules/_io/bytesio.c
@@ -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=5f56a5c3b3d91e9d]*/
 {
     CHECK_CLOSED(self);
     CHECK_EXPORTS(self);
diff --git a/Modules/_io/clinic/bytesio.c.h b/Modules/_io/clinic/bytesio.c.h
index 5c155cb3066e3b5..e9a7deaf606aaa0 100644
--- a/Modules/_io/clinic/bytesio.c.h
+++ b/Modules/_io/clinic/bytesio.c.h
@@ -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__},
@@ -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=605eed15d8c98b4a input=a9049054013a1b77]*/
diff --git a/Modules/_io/clinic/fileio.c.h b/Modules/_io/clinic/fileio.c.h
index 8a9958aaecf0de9..db4a17ebbcb997c 100644
--- a/Modules/_io/clinic/fileio.c.h
+++ b/Modules/_io/clinic/fileio.c.h
@@ -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__},
@@ -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=c0e670a6d39d67fb input=a9049054013a1b77]*/
diff --git a/Modules/_io/clinic/stringio.c.h b/Modules/_io/clinic/stringio.c.h
index 72b2540d47aab98..1bbf30ce7e0b55d 100644
--- a/Modules/_io/clinic/stringio.c.h
+++ b/Modules/_io/clinic/stringio.c.h
@@ -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__},
@@ -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]*/
diff --git a/Modules/_io/fileio.c b/Modules/_io/fileio.c
index 0d5bf3b22114e5e..af96abcdfbda47b 100644
--- a/Modules/_io/fileio.c
+++ b/Modules/_io/fileio.c
@@ -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=1957520f803e9c07]*/
 {
     Py_off_t pos;
     int ret;
diff --git a/Modules/_io/iobase.c b/Modules/_io/iobase.c
index 0c329bff840bd3c..1437da59619cc4b 100644
--- a/Modules/_io/iobase.c
+++ b/Modules/_io/iobase.c
@@ -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)
diff --git a/Modules/_io/stringio.c b/Modules/_io/stringio.c
index 718b1ac1d82db2b..9a7483e744a8d0c 100644
--- a/Modules/_io/stringio.c
+++ b/Modules/_io/stringio.c
@@ -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);

From 3c18ae188cca1d4e5723768b30cd1779d99ae7e8 Mon Sep 17 00:00:00 2001
From: Andrew Kuchling <amk@amk.ca>
Date: Thu, 29 Mar 2018 07:18:29 -0400
Subject: [PATCH 2/3] bpo-8840: use correct parameter name

---
 Lib/_pyio.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Lib/_pyio.py b/Lib/_pyio.py
index e3f7024ac100a10..350d70061d4624e 100644
--- a/Lib/_pyio.py
+++ b/Lib/_pyio.py
@@ -1672,7 +1672,7 @@ def tell(self):
         return os.lseek(self._fd, 0, SEEK_CUR)
 
     def truncate(self, size=None):
-        """Resize stream to at most 'pos' bytes.
+        """Resize stream to at most 'size' bytes.
 
         The position in the stream is left unchanged.  The size
         defaults to the current IO position as reported by tell().  If

From 2d0a5d45423f45ffa9bf31274eebdb20849ff9ef Mon Sep 17 00:00:00 2001
From: Andrew Kuchling <amk@amk.ca>
Date: Thu, 29 Mar 2018 07:33:58 -0400
Subject: [PATCH 3/3] bpo-8840: Consistently use single-quotes around parameter
 name

---
 Modules/_io/bytesio.c          | 4 ++--
 Modules/_io/clinic/bytesio.c.h | 4 ++--
 Modules/_io/clinic/fileio.c.h  | 4 ++--
 Modules/_io/fileio.c           | 4 ++--
 Modules/_io/iobase.c           | 2 +-
 5 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Modules/_io/bytesio.c b/Modules/_io/bytesio.c
index 4454092220c5397..a52979357d2530b 100644
--- a/Modules/_io/bytesio.c
+++ b/Modules/_io/bytesio.c
@@ -552,7 +552,7 @@ _io.BytesIO.truncate
     size: Py_ssize_t(accept={int, NoneType}, c_default="self->pos") = None
     /
 
-Resize stream to at most size bytes.
+Resize stream to at most 'size' bytes.
 
 Position in the stream is left unchanged.  Size defaults to
 the current IO position as reported by tell().  If the stream's
@@ -562,7 +562,7 @@ undetermined.  Returns the new size.
 
 static PyObject *
 _io_BytesIO_truncate_impl(bytesio *self, Py_ssize_t size)
-/*[clinic end generated code: output=9ad17650c15fa09b input=5f56a5c3b3d91e9d]*/
+/*[clinic end generated code: output=9ad17650c15fa09b input=0f69785dcc22737e]*/
 {
     CHECK_CLOSED(self);
     CHECK_EXPORTS(self);
diff --git a/Modules/_io/clinic/bytesio.c.h b/Modules/_io/clinic/bytesio.c.h
index e9a7deaf606aaa0..f31e34551b63e47 100644
--- a/Modules/_io/clinic/bytesio.c.h
+++ b/Modules/_io/clinic/bytesio.c.h
@@ -314,7 +314,7 @@ PyDoc_STRVAR(_io_BytesIO_truncate__doc__,
 "truncate($self, size=None, /)\n"
 "--\n"
 "\n"
-"Resize stream to at most size bytes.\n"
+"Resize stream to at most \'size\' bytes.\n"
 "\n"
 "Position in the stream is left unchanged.  Size defaults to\n"
 "the current IO position as reported by tell().  If the stream\'s\n"
@@ -446,4 +446,4 @@ _io_BytesIO___init__(PyObject *self, PyObject *args, PyObject *kwargs)
 exit:
     return return_value;
 }
-/*[clinic end generated code: output=605eed15d8c98b4a input=a9049054013a1b77]*/
+/*[clinic end generated code: output=934f685bde756d6d input=a9049054013a1b77]*/
diff --git a/Modules/_io/clinic/fileio.c.h b/Modules/_io/clinic/fileio.c.h
index db4a17ebbcb997c..048fa8716d5c198 100644
--- a/Modules/_io/clinic/fileio.c.h
+++ b/Modules/_io/clinic/fileio.c.h
@@ -322,7 +322,7 @@ PyDoc_STRVAR(_io_FileIO_truncate__doc__,
 "truncate($self, size=None, /)\n"
 "--\n"
 "\n"
-"Resize stream to at most size bytes.\n"
+"Resize stream to at most \'size\' bytes.\n"
 "\n"
 "Position in the stream is left unchanged.  Size defaults to\n"
 "the current IO position as reported by tell().  If the stream\'s\n"
@@ -375,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=c0e670a6d39d67fb input=a9049054013a1b77]*/
+/*[clinic end generated code: output=b0ef426afce9a6c3 input=a9049054013a1b77]*/
diff --git a/Modules/_io/fileio.c b/Modules/_io/fileio.c
index af96abcdfbda47b..427c1b59bb64385 100644
--- a/Modules/_io/fileio.c
+++ b/Modules/_io/fileio.c
@@ -979,7 +979,7 @@ _io.FileIO.truncate
     size as posobj: object = NULL
     /
 
-Resize stream to at most size bytes.
+Resize stream to at most 'size' bytes.
 
 Position in the stream is left unchanged.  Size defaults to
 the current IO position as reported by tell().  If the stream's
@@ -989,7 +989,7 @@ undetermined.  Returns the new size.
 
 static PyObject *
 _io_FileIO_truncate_impl(fileio *self, PyObject *posobj)
-/*[clinic end generated code: output=e49ca7a916c176fa input=1957520f803e9c07]*/
+/*[clinic end generated code: output=e49ca7a916c176fa input=b60ed73a8ce11d96]*/
 {
     Py_off_t pos;
     int ret;
diff --git a/Modules/_io/iobase.c b/Modules/_io/iobase.c
index 1437da59619cc4b..b696290444ca05d 100644
--- a/Modules/_io/iobase.c
+++ b/Modules/_io/iobase.c
@@ -118,7 +118,7 @@ _io__IOBase_tell_impl(PyObject *self)
 }
 
 PyDoc_STRVAR(iobase_truncate_doc,
-    "Resize stream to at most size bytes.\n"
+    "Resize stream to at most 'size' bytes.\n"
     "\n"
     "Position in the stream is left unchanged.  Size defaults to\n"
     "the current IO position as reported by tell().  If the stream's\n"