gh-149611: Explain return values for `Path.write_text()` and `Path.write_bytes()...

specify return explanation

Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index 2867015042ee16249d58f205c254016bbbb12964..923cd4a2c4c1f1ec65097baa8b416aa0af3669bc 100644 (file)
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -1266,6 +1266,8 @@ Reading and writing files
       >>> p.read_text()
       'Text file contents'
 
+   Return the number of characters written.
+
    An existing file of the same name is overwritten. The optional parameters
    have the same meaning as in :func:`open`.
 
@@ -1286,6 +1288,8 @@ Reading and writing files
       >>> p.read_bytes()
       b'Binary file contents'
 
+   Return the number of bytes written.
+
    An existing file of the same name is overwritten.
 
    .. versionadded:: 3.5

diff --git a/Lib/pathlib/__init__.py b/Lib/pathlib/__init__.py
index a32e4b5320ff6dd61d5f2ef05862a64286067224..295f633824a6ef219361240088f6728b9436eb26 100644 (file)
--- a/Lib/pathlib/__init__.py
+++ b/Lib/pathlib/__init__.py
@@ -989,6 +989,7 @@ class Path(PurePath):
     def write_bytes(self, data):
         """
         Open the file in bytes mode, write to it, and close the file.
+        Return the number of bytes written.
         """
         # type-check for the buffer interface before truncating the file
         view = memoryview(data)
@@ -998,6 +999,7 @@ class Path(PurePath):
     def write_text(self, data, encoding=None, errors=None, newline=None):
         """
         Open the file in text mode, write to it, and close the file.
+        Return the number of characters written.
         """
         # Call io.text_encoding() here to ensure any warning is raised at an
         # appropriate stack level.

diff --git a/Lib/pathlib/types.py b/Lib/pathlib/types.py
index f21ce0774548f8705c84ae058c52d3d3ac793794..bb4a521223da04d2fcda118ba4012a20812fe884 100644 (file)
--- a/Lib/pathlib/types.py
+++ b/Lib/pathlib/types.py
@@ -431,6 +431,7 @@ class _WritablePath(_JoinablePath):
     def write_bytes(self, data):
         """
         Open the file in bytes mode, write to it, and close the file.
+        Return the number of bytes written.
         """
         # type-check for the buffer interface before truncating the file
         view = memoryview(data)
@@ -440,6 +441,7 @@ class _WritablePath(_JoinablePath):
     def write_text(self, data, encoding=None, errors=None, newline=None):
         """
         Open the file in text mode, write to it, and close the file.
+        Return the number of characters written.
         """
         # Call io.text_encoding() here to ensure any warning is raised at an
         # appropriate stack level.