Explicit note that tmpdir fixture is discouraged in favour of tmp_path …

…#9937 (#10138)

Co-authored-by: Bruno Oliveira <nicoddemus@gmail.com>
Co-authored-by: kevin.hierro-ext <kevin.hierro-ext@clarity.ai>
Co-authored-by: Dani Sancas <lord.sancas@gmail.com>

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
@@ -328,6 +330,7 @@ Taneli Hukkinen
 Tanvi Mehta
 Tarcisio Fischer
 Tareq Alayan
+Tatiana Ovary
 Ted Xiao
 Terje Runde
 Thomas Grainger
@@ -346,6 +349,7 @@ Tyler Goodlet
 Tzu-ping Chung
 Vasily Kuznetsov
 Victor Maryama
+Victor Rodriguez
 Victor Uriarte
 Vidar T. Fauske
 Virgil Dupras

changelog/9937.doc.rst

@@ -0,0 +1 @@
+Explicit note that :fixture:`tmpdir` fixture is discouraged in favour of :fixture:`tmp_path`.

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 <tmpdir>` :fixture:`tmpdir_factory <tmpdir_factory>`
 API for details.

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<tmpdir and tmpdir_factory>`.
+
+    """
 
     _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<tmpdir and tmpdir_factory>`.
+
         .. _legacy_path: https://py.readthedocs.io/en/latest/path.html
         """
         return legacy_path(tmp_path)