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

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

Lib/pathlib/__init__.py

@@ -989,6 +989,7 @@ def read_text(self, encoding=None, errors=None, newline=None):
     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 @@ def write_bytes(self, data):
     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.

Lib/pathlib/types.py

@@ -431,6 +431,7 @@ def __open_writer__(self, mode):
     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 @@ def write_bytes(self, data):
     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.