doc/tmpdir: significantly reduce space dedicated to tmpdir/tmpdir_factory
Emphasize tmp_path/tmp_path_factory and just note the legacy ones.
This commit is contained in:
Ran Benita
parent
ef1308c23b
commit
ba7bd3d77c
|
|
@ -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 <tmp_path_factory 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 <tmpdir factory api>` for details.
|
||||
See :ref:`tmp_path_factory API <tmp_path_factory 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 <tmpdir>` :fixture:`tmpdir_factory <tmpdir_factory>`
|
||||
API for details.
|
||||
|
||||
|
||||
.. _`base temporary directory`:
|
||||
|
|
|
|||
|
|
@ -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`:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue