From ba7bd3d77cfdd3a0e959fd525dbf6210691fe8d4 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sat, 13 Mar 2021 19:45:11 +0200 Subject: [PATCH] doc/tmpdir: significantly reduce space dedicated to tmpdir/tmpdir_factory Emphasize tmp_path/tmp_path_factory and just note the legacy ones. --- doc/en/how-to/tmpdir.rst | 98 +++++++--------------------------- doc/en/reference/reference.rst | 8 ++- 2 files changed, 22 insertions(+), 84 deletions(-) diff --git a/doc/en/how-to/tmpdir.rst b/doc/en/how-to/tmpdir.rst index 379c6d84c..1823c8a4e 100644 --- a/doc/en/how-to/tmpdir.rst +++ b/doc/en/how-to/tmpdir.rst @@ -8,14 +8,11 @@ How to use temporary directories and files in tests The ``tmp_path`` fixture ------------------------ - - - You can use the ``tmp_path`` fixture which will provide a temporary directory unique to the test invocation, created in the `base temporary directory`_. -``tmp_path`` is a ``pathlib.Path`` object. Here is an example test usage: +``tmp_path`` is a :class:`pathlib.Path` object. Here is an example test usage: .. code-block:: python @@ -71,82 +68,12 @@ Running this would result in a passed test except for the last The ``tmp_path_factory`` fixture -------------------------------- - - - The ``tmp_path_factory`` is a session-scoped fixture which can be used to create arbitrary temporary directories from any other fixture or test. -It is intended to replace ``tmpdir_factory``, and returns :class:`pathlib.Path` instances. - -See :ref:`tmp_path_factory API ` for details. - - -The 'tmpdir' fixture --------------------- - -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 -and more. Here is an example test usage: - -.. code-block:: python - - # content of test_tmpdir.py - def test_create_file(tmpdir): - p = tmpdir.mkdir("sub").join("hello.txt") - p.write("content") - assert p.read() == "content" - assert len(tmpdir.listdir()) == 1 - assert 0 - -Running this would result in a passed test except for the last -``assert 0`` line which we use to look at values: - -.. code-block:: pytest - - $ pytest test_tmpdir.py - =========================== test session starts ============================ - platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-0.x.y - cachedir: $PYTHON_PREFIX/.pytest_cache - rootdir: $REGENDOC_TMPDIR - collected 1 item - - test_tmpdir.py F [100%] - - ================================= FAILURES ================================= - _____________________________ test_create_file _____________________________ - - tmpdir = local('PYTEST_TMPDIR/test_create_file0') - - def test_create_file(tmpdir): - p = tmpdir.mkdir("sub").join("hello.txt") - p.write("content") - assert p.read() == "content" - assert len(tmpdir.listdir()) == 1 - > assert 0 - E assert 0 - - test_tmpdir.py:6: AssertionError - ========================= short test summary info ========================== - FAILED test_tmpdir.py::test_create_file - assert 0 - ============================ 1 failed in 0.12s ============================= - -.. _`tmpdir factory example`: - -The 'tmpdir_factory' fixture ----------------------------- - - - -The ``tmpdir_factory`` is a session-scoped fixture which can be used -to create arbitrary temporary directories from any other fixture or test. - For example, suppose your test suite needs a large image on disk, which is generated procedurally. Instead of computing the same image for each test -that uses it into its own ``tmpdir``, you can generate it once per-session +that uses it into its own ``tmp_path``, you can generate it once per-session to save time: .. code-block:: python @@ -156,10 +83,10 @@ to save time: @pytest.fixture(scope="session") - def image_file(tmpdir_factory): + def image_file(tmp_path_factory): img = compute_expensive_image() - fn = tmpdir_factory.mktemp("data").join("img.png") - img.save(str(fn)) + fn = tmp_path_factory.mktemp("data") / "img.png" + img.save(fn) return fn @@ -168,7 +95,20 @@ to save time: img = load_image(image_file) # compute and test histogram -See :ref:`tmpdir_factory API ` for details. +See :ref:`tmp_path_factory API ` for details. + +.. _`tmpdir and tmpdir_factory`: + +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``. + +See :fixture:`tmpdir ` :fixture:`tmpdir_factory ` +API for details. .. _`base temporary directory`: diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index d9986336c..a8faa044f 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -582,7 +582,7 @@ tmp_path :no-auto-options: -.. fixture:: _pytest.tmpdir.tmp_path_factory +.. fixture:: tmp_path_factory tmp_path_factory ~~~~~~~~~~~~~~~~ @@ -601,7 +601,7 @@ tmp_path_factory tmpdir ~~~~~~ -:ref:`tmpdir` +:ref:`tmpdir and tmpdir_factory` .. autofunction:: _pytest.tmpdir.tmpdir() :no-auto-options: @@ -612,9 +612,7 @@ tmpdir tmpdir_factory ~~~~~~~~~~~~~~ -:ref:`tmpdir factory example` - -.. _`tmpdir factory api`: +:ref:`tmpdir and tmpdir_factory` ``tmp_path_factory`` is an instance of :class:`~pytest.TempdirFactory`: