doc: intersphinx: add py, use it for py.path.local

doc/en/builtin.rst

@@ -144,10 +144,8 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
         Return a temporary directory path object
         which is unique to each test function invocation,
         created as a sub directory of the base temporary
-        directory.  The returned object is a `py.path.local`_
-        path object.
-
-        .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html
+        directory.  The returned object is a :class:`py.path.local`
+        object.
 
     tmp_path
         Return a temporary directory path object

doc/en/conf.py

@@ -346,6 +346,7 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     "pluggy": ("https://pluggy.readthedocs.io/en/latest", None),
+    "py": ("https://py.readthedocs.io/en/latest/", None),
     "python": ("https://docs.python.org/3", None),
 }
 

doc/en/example/attic.rst

@@ -76,8 +76,7 @@ ignorant of how/where the function argument is provided -
 in our example from a `conftest plugin`_.
 
 sidenote: the temporary directory used here are instances of
-the `py.path.local`_ class which provides many of the os.path
+the :class:`py.path.local` class which provides many of the os.path
 methods in a convenient way.
 
-.. _`py.path.local`: ../path.html#local
 .. _`conftest plugin`: customize.html#conftestplugin

doc/en/fixture.rst

@@ -102,8 +102,6 @@ for reference:
         directory which is unique to each test function;
         replaced by :fixture:`tmp_path`.
 
-        .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html
-
    :fixture:`tmpdir_factory`
         Make session-scoped temporary directories and return
         :class:`py.path.local` objects;

doc/en/reference.rst

@@ -895,6 +895,26 @@ Result used within :ref:`hook wrappers <hookwrapper>`.
 .. automethod:: pluggy.callers._Result.get_result
 .. automethod:: pluggy.callers._Result.force_result
 
+py.path.local
+~~~~~~~~~~~~~
+
+`py.path.local` instances are a legacy provided via the ``py`` library as
+instances of ``py._path.local.LocalPath``.
+
+.. note::
+
+    While they are used in many places (especially with hooks) still,
+    they are meant to be deprecated in favor of using pathlib Path instances
+    in the long run.
+
+.. currentmodule:: py.path
+.. class:: local
+
+.. autoclass:: py._path.local.LocalPath
+   :members:
+   :member-order: groupwise
+
+
 Special Variables
 -----------------
 

doc/en/tmpdir.rst

@@ -89,7 +89,7 @@ You can use the ``tmpdir`` fixture which will
 provide a temporary directory unique to the test invocation,
 created in the `base temporary directory`_.
 
-``tmpdir`` is a `py.path.local`_ object which offers ``os.path`` methods
+``tmpdir`` is a :class:`py.path.local` object which offers ``os.path`` methods
 and more.  Here is an example test usage:
 
 .. code-block:: python
@@ -191,5 +191,3 @@ You can override the default temporary directory setting like this:
 When distributing tests on the local machine, ``pytest`` takes care to
 configure a basetemp directory for the sub processes such that all temporary
 data lands below a single per-test run basetemp directory.
-
-.. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html

src/_pytest/hookspec.py

@@ -215,7 +215,7 @@ def pytest_ignore_collect(
 
         return (True, "collect_ignore")
 
-    :param path: a :py:class:`py.path.local` - the path to analyze
+    :param py.path.local path: the path to analyze
     :param _pytest.config.Config config: pytest config object
     """
 
@@ -226,15 +226,15 @@ def pytest_collect_directory(path, parent):
 
     Stops at first non-None result, see :ref:`firstresult`
 
-    :param path: a :py:class:`py.path.local` - the path to analyze
+    :param py.path.local path: the path to analyze
     """
 
 
 def pytest_collect_file(path, parent):
     """ return collection Node or None for the given path. Any new node
     needs to have the specified ``parent`` as a parent.
 
-    :param path: a :py:class:`py.path.local` - the path to collect
+    :param py.path.local path: the path to collect
     """
 
 
@@ -278,7 +278,7 @@ def pytest_pycollect_makemodule(path, parent):
 
     Stops at first non-None result, see :ref:`firstresult`
 
-    :param path: a :py:class:`py.path.local` - the path of module to collect
+    :param py.path.local path: the path of the module to collect
     """
 
 
@@ -540,7 +540,7 @@ def pytest_report_header(config, startdir):
     """ return a string or list of strings to be displayed as header info for terminal reporting.
 
     :param _pytest.config.Config config: pytest config object
-    :param startdir: py.path object with the starting dir
+    :param py.path.local startdir: object with the starting dir
 
     .. note::
 
@@ -559,7 +559,7 @@ def pytest_report_collectionfinish(config, startdir, items):
     This strings will be displayed after the standard "collected X items" message.
 
     :param _pytest.config.Config config: pytest config object
-    :param startdir: py.path object with the starting dir
+    :param startdir: :ref:`py.path.local <py:local>` object with the starting dir
     :param items: list of pytest items that are going to be executed; this list should not be modified.
     """
 

src/_pytest/pytester/__init__.py

@@ -901,7 +901,7 @@ def getnode(self, config, arg):
            :py:meth:`parseconfig` and :py:meth:`parseconfigure` to create the
            configuration
 
-        :param arg: a :py:class:`py.path.local` instance of the file
+        :param arg: a :ref:`py.path.local <py:local>` instance of the file
 
         """
         session = Session.from_config(config)
@@ -918,7 +918,7 @@ def getpathnode(self, path):
         This is like :py:meth:`getnode` but uses :py:meth:`parseconfigure` to
         create the (configured) pytest Config instance.
 
-        :param path: a :py:class:`py.path.local` instance of the file
+        :param py.path.local path: the file
 
         """
         config = self.parseconfigure(path)

src/_pytest/tmpdir.py

@@ -154,14 +154,12 @@ def _mk_tmp(request: FixtureRequest, factory: TempPathFactory) -> Path:
 
 
 @pytest.fixture
-def tmpdir(tmp_path):
+def tmpdir(tmp_path) -> py.path.local:
     """Return a temporary directory path object
     which is unique to each test function invocation,
     created as a sub directory of the base temporary
-    directory.  The returned object is a `py.path.local`_
-    path object.
-
-    .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html
+    directory.  The returned object is a :class:`py.path.local`
+    object.
     """
     return py.path.local(tmp_path)