testing: Add Path.read_text() and Path.read_bytes()

To migrate pathlib.Path in future, compatibile methods are needed
for our Path class.

CHANGES

@@ -27,6 +27,8 @@ Deprecated
 ----------
 
 * ``sphinx.domains.std.StandardDomain.add_object()``
+* ``sphinx.testing.path.Path.text()``
+* ``sphinx.testing.path.Path.bytes()``
 
 Features added
 --------------

doc/extdev/deprecated.rst

@@ -31,6 +31,16 @@ The following is a list of deprecated interfaces.
      - 5.0
      - ``sphinx.domains.std.StandardDomain.note_object()``
 
+   * - ``sphinx.testing.path.Path.text()``
+     - 3.0
+     - 5.0
+     - ``sphinx.testing.path.Path.read_text()``
+
+   * - ``sphinx.testing.path.Path.bytes()``
+     - 3.0
+     - 5.0
+     - ``sphinx.testing.path.Path.read_bytes()``
+
    * - ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()``
      - 2.4
      - 4.0

sphinx/testing/path.py

@@ -10,8 +10,11 @@ import builtins
 import os
 import shutil
 import sys
+import warnings
 from typing import Any, Callable, IO, List
 
+from sphinx.deprecation import RemovedInSphinx50Warning
+
 
 FILESYSTEMENCODING = sys.getfilesystemencoding() or sys.getdefaultencoding()
 
@@ -135,6 +138,14 @@ class path(str):
             f.write(text)
 
     def text(self, encoding: str = 'utf-8', **kwargs: Any) -> str:
+        """
+        Returns the text in the file.
+        """
+        warnings.warn('Path.text() is deprecated.  Please use read_text() instead.',
+                      RemovedInSphinx50Warning, stacklevel=2)
+        return self.read_text(encoding, **kwargs)
+
+    def read_text(self, encoding: str = 'utf-8', **kwargs: Any) -> str:
         """
         Returns the text in the file.
         """
@@ -142,6 +153,14 @@ class path(str):
             return f.read()
 
     def bytes(self) -> builtins.bytes:
+        """
+        Returns the bytes in the file.
+        """
+        warnings.warn('Path.bytes() is deprecated.  Please use read_bytes() instead.',
+                      RemovedInSphinx50Warning, stacklevel=2)
+        return self.read_bytes()
+
+    def read_bytes(self) -> builtins.bytes:
         """
         Returns the bytes in the file.
         """