From 300015645d08289a97a344f5d4447cb7d6750c93 Mon Sep 17 00:00:00 2001 From: "kevin.hierro-ext" Date: Fri, 15 Jul 2022 10:25:11 +0100 Subject: [PATCH] Improve tmp_path documentation #9937 on-behalf-of: @clarityai-eng Add changelog entry on-behalf-of: @clarityai-eng Added mob programming authors on-behalf-of: @clarityai-eng --- AUTHORS | 4 ++++ changelog/9937.doc.rst | 1 + doc/en/how-to/tmp_path.rst | 6 ++++-- src/_pytest/legacypath.py | 14 +++++++++++++- 4 files changed, 22 insertions(+), 3 deletions(-) create mode 100644 changelog/9937.doc.rst diff --git a/AUTHORS b/AUTHORS index 09fe12e004f..3698b1d272b 100644 --- a/AUTHORS +++ b/AUTHORS @@ -87,6 +87,7 @@ Damian Skrzypczak Daniel Grana Daniel Hahler Daniel Nuri +Daniel Sánchez Castelló Daniel Wandschneider Daniele Procida Danielle Jenkins @@ -190,6 +191,7 @@ Katerina Koukiou Keri Volans Kevin C Kevin Cox +Kevin Hierro Carrasco Kevin J. Foley Kian Eliasi Kian-Meng Ang @@ -327,6 +329,7 @@ Taneli Hukkinen Tanvi Mehta Tarcisio Fischer Tareq Alayan +Tatiana Ovary Ted Xiao Terje Runde Thomas Grainger @@ -345,6 +348,7 @@ Tyler Goodlet Tzu-ping Chung Vasily Kuznetsov Victor Maryama +Victor Rodriguez Victor Uriarte Vidar T. Fauske Virgil Dupras diff --git a/changelog/9937.doc.rst b/changelog/9937.doc.rst new file mode 100644 index 00000000000..43be61397cf --- /dev/null +++ b/changelog/9937.doc.rst @@ -0,0 +1 @@ +Explicit note that ``tmpdir`` fixture is discouraged in favour of ``tmp_path``. diff --git a/doc/en/how-to/tmp_path.rst b/doc/en/how-to/tmp_path.rst index b261a55637e..99e9e55367a 100644 --- a/doc/en/how-to/tmp_path.rst +++ b/doc/en/how-to/tmp_path.rst @@ -104,8 +104,10 @@ The ``tmpdir`` and ``tmpdir_factory`` fixtures The ``tmpdir`` and ``tmpdir_factory`` fixtures are similar to ``tmp_path`` and ``tmp_path_factory``, but use/return legacy `py.path.local`_ objects -rather than standard :class:`pathlib.Path` objects. These days, prefer to -use ``tmp_path`` and ``tmp_path_factory``. +rather than standard :class:`pathlib.Path` objects. + +.. note:: + These days, it is preferred to use ``tmp_path`` and ``tmp_path_factory``. See :fixture:`tmpdir ` :fixture:`tmpdir_factory ` API for details. diff --git a/src/_pytest/legacypath.py b/src/_pytest/legacypath.py index 49149311a7d..f71e7e96ead 100644 --- a/src/_pytest/legacypath.py +++ b/src/_pytest/legacypath.py @@ -271,7 +271,14 @@ def testdir(pytester: Pytester) -> Testdir: @attr.s(init=False, auto_attribs=True) class TempdirFactory: """Backward compatibility wrapper that implements :class:`py.path.local` - for :class:`TempPathFactory`.""" + for :class:`TempPathFactory`. + + .. note:: + These days, it is preferred to use ``tmp_path_factory``. + + :ref:`About the tmpdir and tmpdir_factory fixtures`. + + """ _tmppath_factory: TempPathFactory @@ -312,6 +319,11 @@ def tmpdir(tmp_path: Path) -> LEGACY_PATH: The returned object is a `legacy_path`_ object. + .. note:: + These days, it is preferred to use ``tmp_path``. + + :ref:`About the tmpdir and tmpdir_factory fixtures`. + .. _legacy_path: https://py.readthedocs.io/en/latest/path.html """ return legacy_path(tmp_path)