Merge pull request #14129 from bluetech/fixtures-docs

docs: a few tweaks

Author: bluetech

.github/PULL_REQUEST_TEMPLATE.md

@@ -13,7 +13,7 @@ If this change fixes an issue, please:
 
 Unless your change is trivial or a small documentation fix (e.g., a typo or reword of a small section) please:
 
-- [ ] Create a new changelog file in the `changelog` folder, with a name like `<ISSUE NUMBER>.<TYPE>.rst`. See [changelog/README.rst](https://github.com/pytest-dev/pytest/blob/main/changelog/README.rst) for details.
+- [ ] Create a new changelog file in the `changelog` directory, with a name like `<ISSUE NUMBER>.<TYPE>.rst`. See [changelog/README.rst](https://github.com/pytest-dev/pytest/blob/main/changelog/README.rst) for details.
 
   Write sentences in the **past or present tense**, examples:
 

doc/en/changelog.rst

@@ -16,7 +16,7 @@ with advance notice in the **Deprecations** section of releases.
     fix problems like typo corrections or such.
     To add a new change log entry, please see
     https://pip.pypa.io/en/latest/development/contributing/#news-entries
-    we named the news folder changelog
+    but note that in pytest the "news/" directory is named "changelog/".
 
 
 .. only:: not is_release

doc/en/explanation/fixtures.rst

@@ -152,7 +152,7 @@ If you want to make test data from files available to your tests, a good way
 to do this is by loading these data in a fixture for use by your tests.
 This makes use of the automatic caching mechanisms of pytest.
 
-Another good approach is by adding the data files in the ``tests`` folder.
+Another good approach is by adding the data files in the ``tests`` directory.
 There are also community plugins available to help to manage this aspect of
 testing, e.g. :pypi:`pytest-datadir` and :pypi:`pytest-datafiles`.
 

doc/en/explanation/goodpractices.rst

@@ -240,7 +240,7 @@ This results in a drawback compared to the import mode ``importlib``:
 your test files must have **unique names**.
 
 If you need to have test modules with the same name,
-as a workaround you might add ``__init__.py`` files to your ``tests`` folder and subfolders,
+as a workaround you might add ``__init__.py`` files to your ``tests`` directory and subdirectories,
 changing them to packages:
 
 .. code-block:: text

doc/en/explanation/pythonpath.rst

@@ -143,8 +143,8 @@ When executing:
     pytest root/
 
 pytest will find ``foo/bar/tests/test_foo.py`` and realize it is part of a package given that
-there's an ``__init__.py`` file in the same folder. It will then search upwards until it can find the
-last folder which still contains an ``__init__.py`` file in order to find the package *root* (in
+there's an ``__init__.py`` file in the same directory. It will then search upwards until it can find the
+last directory which still contains an ``__init__.py`` file in order to find the package *root* (in
 this case ``foo/``). To load the module, it will insert ``root/``  to the front of
 :py:data:`sys.path` (if not there already) in order to load
 ``test_foo.py`` as the *module* ``foo.bar.tests.test_foo``.
@@ -175,7 +175,7 @@ When executing:
     pytest root/
 
 pytest will find ``foo/bar/tests/test_foo.py`` and realize it is NOT part of a package given that
-there's no ``__init__.py`` file in the same folder. It will then add ``root/foo/bar/tests`` to
+there's no ``__init__.py`` file in the same directory. It will then add ``root/foo/bar/tests`` to
 :py:data:`sys.path` in order to import ``test_foo.py`` as the *module* ``test_foo``. The same is done
 with the ``conftest.py`` file by adding ``root/foo`` to :py:data:`sys.path` to import it as ``conftest``.
 

doc/en/how-to/fixtures.rst

@@ -1746,27 +1746,25 @@ into a configuration file:
 
 .. warning::
 
-    Note this mark has no effect in **fixture functions**. For example,
-    this **will not work as expected**:
+    ``@pytest.mark.usefixtures`` cannot be used on **fixture functions**. For example,
+    this is an error:
 
     .. code-block:: python
 
         @pytest.mark.usefixtures("my_other_fixture")
         @pytest.fixture
         def my_fixture_that_sadly_wont_use_my_other_fixture(): ...
 
-    This generates a deprecation warning, and will become an error in Pytest 8.
-
 .. _`override fixtures`:
 
 Overriding fixtures on various levels
 -------------------------------------
 
-In relatively large test suite, you most likely need to ``override`` a ``global`` or ``root`` fixture with a ``locally``
-defined one, keeping the test code readable and maintainable.
+In relatively large test suite, you may want to *override* a fixture, to augment
+or change its behavior inside of certain test modules or directories.
 
-Override a fixture on a folder (conftest) level
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Override a fixture on a directory (conftest) level
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Given the tests file structure is:
 
@@ -1786,21 +1784,21 @@ Given the tests file structure is:
             def test_username(username):
                 assert username == 'username'
 
-        subfolder/
+        subdir/
             conftest.py
-                # content of tests/subfolder/conftest.py
+                # content of tests/subdir/conftest.py
                 import pytest
 
                 @pytest.fixture
                 def username(username):
                     return 'overridden-' + username
 
             test_something_else.py
-                # content of tests/subfolder/test_something_else.py
+                # content of tests/subdir/test_something_else.py
                 def test_username(username):
                     assert username == 'overridden-username'
 
-As you can see, a fixture with the same name can be overridden for certain test folder level.
+As you can see, a fixture with the same name can be overridden for certain test directory level.
 Note that the ``base`` or ``super`` fixture can be accessed from the ``overriding``
 fixture easily - used in the example above.
 
@@ -1929,7 +1927,7 @@ Given the tests file structure is:
 
 In the example above, a parametrized fixture is overridden with a non-parametrized version, and
 a non-parametrized fixture is overridden with a parametrized version for certain test module.
-The same applies for the test folder level obviously.
+The same applies for the test directory level obviously.
 
 
 Using fixtures from other projects

doc/en/reference/customize.rst

@@ -272,7 +272,7 @@ check for configuration files as follows:
 
     Custom pytest plugin commandline arguments may include a path, as in
     ``pytest --log-output ../../test.log args``. Then ``args`` is mandatory,
-    otherwise pytest uses the folder of test.log for rootdir determination
+    otherwise pytest uses the directory of test.log for rootdir determination
     (see also :issue:`1435`).
     A dot ``.`` for referencing to the current working directory is also
     possible.

src/_pytest/pathlib.py

@@ -225,7 +225,7 @@ def _force_symlink(root: Path, target: str | PurePath, link_to: str | Path) -> N
 def make_numbered_dir(root: Path, prefix: str, mode: int = 0o700) -> Path:
     """Create a directory with an increased number as suffix for the given prefix."""
     for i in range(10):
-        # try up to 10 times to create the folder
+        # try up to 10 times to create the directory
         max_existing = max(map(parse_num, find_suffixes(root, prefix)), default=-1)
         new_number = max_existing + 1
         new_path = root.joinpath(f"{prefix}{new_number}")
@@ -244,7 +244,7 @@ def make_numbered_dir(root: Path, prefix: str, mode: int = 0o700) -> Path:
 
 
 def create_cleanup_lock(p: Path) -> Path:
-    """Create a lock to prevent premature folder cleanup."""
+    """Create a lock to prevent premature directory cleanup."""
     lock_path = get_lock_path(p)
     try:
         fd = os.open(str(lock_path), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
@@ -294,7 +294,7 @@ def maybe_delete_a_numbered_dir(path: Path) -> None:
     except OSError:
         #  known races:
         #  * other process did a cleanup at the same time
-        #  * deletable folder was found
+        #  * deletable directory was found
         #  * process cwd (Windows)
         return
     finally:
@@ -336,7 +336,7 @@ def ensure_deletable(path: Path, consider_lock_dead_if_created_before: float) ->
 
 
 def try_cleanup(path: Path, consider_lock_dead_if_created_before: float) -> None:
-    """Try to cleanup a folder if we can ensure it's deletable."""
+    """Try to cleanup a directory if we can ensure it's deletable."""
     if ensure_deletable(path, consider_lock_dead_if_created_before):
         maybe_delete_a_numbered_dir(path)
 

testing/example_scripts/README.rst

@@ -2,7 +2,7 @@ Example test scripts
 =====================
 
 
-The files in this folder are not direct tests, but rather example test suites that demonstrate certain issues/behaviours.
+The files in this directory are not direct tests, but rather example test suites that demonstrate certain issues/behaviours.
 
 In the future we will move part of the content of the acceptance tests here in order to have directly testable code instead of writing out things and then running them in nested pytest sessions/subprocesses.
 

testing/plugins_integration/README.rst

@@ -1,4 +1,4 @@
-This folder contains tests and support files for smoke testing popular plugins against the current pytest version.
+This directory contains tests and support files for smoke testing popular plugins against the current pytest version.
 
 The objective is to gauge if any intentional or unintentional changes in pytest break plugins.