From becd8992dbfb45f70644df6166d2b486e5374798 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Mon, 9 Mar 2020 05:40:33 +0100 Subject: [PATCH] doc: intersphinx: add py, use it for py.path.local --- doc/en/builtin.rst | 6 ++---- doc/en/conf.py | 1 + doc/en/example/attic.rst | 3 +-- doc/en/fixture.rst | 2 -- doc/en/reference.rst | 20 ++++++++++++++++++++ doc/en/tmpdir.rst | 4 +--- src/_pytest/hookspec.py | 12 ++++++------ src/_pytest/pytester/__init__.py | 4 ++-- src/_pytest/tmpdir.py | 8 +++----- 9 files changed, 36 insertions(+), 24 deletions(-) diff --git a/doc/en/builtin.rst b/doc/en/builtin.rst index 7b8fd4a5a99..d50683aefe6 100644 --- a/doc/en/builtin.rst +++ b/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 diff --git a/doc/en/conf.py b/doc/en/conf.py index a44e8cd296a..9ce221c4383 100644 --- a/doc/en/conf.py +++ b/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), } diff --git a/doc/en/example/attic.rst b/doc/en/example/attic.rst index 2ea87006204..21a3fc99c45 100644 --- a/doc/en/example/attic.rst +++ b/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 diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index 24d911d3301..53db29985f1 100644 --- a/doc/en/fixture.rst +++ b/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; diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 4eedb8f850a..5b4c39e9703 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -895,6 +895,26 @@ Result used within :ref:`hook wrappers `. .. 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 ----------------- diff --git a/doc/en/tmpdir.rst b/doc/en/tmpdir.rst index b9faef4dc92..fe02c3d7022 100644 --- a/doc/en/tmpdir.rst +++ b/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 diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index 30bc2a91409..fb589fd4a17 100644 --- a/src/_pytest/hookspec.py +++ b/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,7 +226,7 @@ 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 """ @@ -234,7 +234,7 @@ 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 ` object with the starting dir :param items: list of pytest items that are going to be executed; this list should not be modified. """ diff --git a/src/_pytest/pytester/__init__.py b/src/_pytest/pytester/__init__.py index 942966a9b71..21b5d9f466d 100644 --- a/src/_pytest/pytester/__init__.py +++ b/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 ` 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) diff --git a/src/_pytest/tmpdir.py b/src/_pytest/tmpdir.py index 3a7ec4098ff..a918de9f1bf 100644 --- a/src/_pytest/tmpdir.py +++ b/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)