floraachy
/
pytest2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs: clean up various documentation pages (#12451) 

* Change Contribution doc title to match sidebar

* Rearrange sentence for clarity

* Update backwards-compatibility.rst

some minor grammar changes

* Update pythonpath.rst

fixed some gramatical errors

* Update AUTHORS

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update doc/en/explanation/pythonpath.rst

From a quick overview it looks like lowercase is more consistent, although some pages do use `pytest` in code blocks

Co-authored-by: Bruno Oliveira <bruno@soliv.dev>

---------

Co-authored-by: Mackerello <82668740+Mackerello@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Bruno Oliveira <bruno@soliv.dev>
This commit is contained in:
neutraljump 2024-06-13 21:39:02 +09:30 committed by GitHub
parent ff75980135
commit 2effd8cb2c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 24 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
AUTHORS
View File

@ -259,6 +259,7 @@ Marc Bresson
Marco Gorelli Marco Gorelli
Mark Abramowitz Mark Abramowitz
Mark Dickinson Mark Dickinson
Mark Vong
Marko Pacak Marko Pacak
Markus Unterwaditzer Markus Unterwaditzer
Martijn Faassen Martijn Faassen
@ -301,6 +302,7 @@ Nicholas Devenish
Nicholas Murphy Nicholas Murphy
Niclas Olofsson Niclas Olofsson
Nicolas Delaby Nicolas Delaby
Nico Vidal
Nikolay Kondratyev Nikolay Kondratyev
Nipunn Koorapati Nipunn Koorapati
Oleg Pidsadnyi Oleg Pidsadnyi

4
CONTRIBUTING.rst
View File

@ -1,5 +1,5 @@
============================ ============================
Contribution getting started Contributing
============================ ============================
Contributions are highly welcomed and appreciated. Every little bit of help counts, Contributions are highly welcomed and appreciated. Every little bit of help counts,
@ -124,7 +124,7 @@ For example:
Submitting Plugins to pytest-dev Submitting Plugins to pytest-dev
-------------------------------- --------------------------------
Pytest development of the core, some plugins and support code happens Development of the pytest core, support code, and some plugins happens
in repositories living under the ``pytest-dev`` organisations: in repositories living under the ``pytest-dev`` organisations:
- `pytest-dev on GitHub <https://github.com/pytest-dev>`_ - `pytest-dev on GitHub <https://github.com/pytest-dev>`_

28
doc/en/backwards-compatibility.rst
View File

@ -5,30 +5,26 @@ Backwards Compatibility Policy
.. versionadded: 6.0 .. versionadded: 6.0
pytest is actively evolving and is a project that has been decades in the making, Pytest is an actively evolving project that has been decades in the making.
we keep learning about new and better structures to express different details about testing. We keep learning about new and better structures to express different details about testing.
While we implement those modifications we try to ensure an easy transition and don't want to impose unnecessary churn on our users and community/plugin authors. While we implement those modifications, we try to ensure an easy transition and don't want to impose unnecessary churn on our users and community/plugin authors.
As of now, pytest considers multiple types of backward compatibility transitions: As of now, pytest considers multiple types of backward compatibility transitions:
a) trivial: APIs which trivially translate to the new mechanism, a) trivial: APIs that trivially translate to the new mechanism and do not cause problematic changes.
and do not cause problematic changes.
We try to support those indefinitely while encouraging users to switch to newer/better mechanisms through documentation. We try to support those indefinitely while encouraging users to switch to newer or better mechanisms through documentation.
b) transitional: the old and new API don't conflict b) transitional: the old and new APIs don't conflict, and we can help users transition by using warnings while supporting both for a prolonged period of time.
and we can help users transition by using warnings, while supporting both for a prolonged time.
We will only start the removal of deprecated functionality in major releases (e.g. if we deprecate something in 3.0 we will start to remove it in 4.0), and keep it around for at least two minor releases (e.g. if we deprecate something in 3.9 and 4.0 is the next release, we start to remove it in 5.0, not in 4.0). We will only start the removal of deprecated functionality in major releases (e.g., if we deprecate something in 3.0, we will start to remove it in 4.0), and keep it around for at least two minor releases (e.g., if we deprecate something in 3.9 and 4.0 is the next release, we start to remove it in 5.0, not in 4.0).
A deprecated feature scheduled to be removed in major version X will use the warning class `PytestRemovedInXWarning` (a subclass of :class:`~pytest.PytestDeprecationWarning`). A deprecated feature scheduled to be removed in major version X will use the warning class `PytestRemovedInXWarning` (a subclass of :class:`~pytest.PytestDeprecationWarning`).
When the deprecation expires (e.g. 4.0 is released), we won't remove the deprecated functionality immediately, but will use the standard warning filters to turn `PytestRemovedInXWarning` (e.g. `PytestRemovedIn4Warning`) into **errors** by default. This approach makes it explicit that removal is imminent, and still gives you time to turn the deprecated feature into a warning instead of an error so it can be dealt with in your own time. In the next minor release (e.g. 4.1), the feature will be effectively removed. When the deprecation expires (e.g., 4.0 is released), we won't remove the deprecated functionality immediately but will use the standard warning filters to turn `PytestRemovedInXWarning` (e.g., `PytestRemovedIn4Warning`) into **errors** by default. This approach makes it explicit that removal is imminent and still gives you time to turn the deprecated feature into a warning instead of an error so it can be dealt with in your own time. In the next minor release (e.g., 4.1), the feature will be effectively removed.
c) True breakage should only be considered when a normal transition is unreasonably unsustainable and would offset important developments or features by years. In addition, they should be limited to APIs where the number of actual users is very small (for example, only impacting some plugins) and can be coordinated with the community in advance.
c) true breakage: should only be considered when normal transition is unreasonably unsustainable and would offset important development/features by years.
In addition, they should be limited to APIs where the number of actual users is very small (for example only impacting some plugins), and can be coordinated with the community in advance.
Examples for such upcoming changes: Examples for such upcoming changes:
@ -62,11 +58,11 @@ Focus primary on smooth transition - stance (pre 6.0)
Keeping backwards compatibility has a very high priority in the pytest project. Although we have deprecated functionality over the years, most of it is still supported. All deprecations in pytest were done because simpler or more efficient ways of accomplishing the same tasks have emerged, making the old way of doing things unnecessary. Keeping backwards compatibility has a very high priority in the pytest project. Although we have deprecated functionality over the years, most of it is still supported. All deprecations in pytest were done because simpler or more efficient ways of accomplishing the same tasks have emerged, making the old way of doing things unnecessary.
With the pytest 3.0 release we introduced a clear communication scheme for when we will actually remove the old busted joint and politely ask you to use the new hotness instead, while giving you enough time to adjust your tests or raise concerns if there are valid reasons to keep deprecated functionality around. With the pytest 3.0 release, we introduced a clear communication scheme for when we will actually remove the old busted joint and politely ask you to use the new hotness instead, while giving you enough time to adjust your tests or raise concerns if there are valid reasons to keep deprecated functionality around.
To communicate changes we issue deprecation warnings using a custom warning hierarchy (see :ref:`internal-warnings`). These warnings may be suppressed using the standard means: ``-W`` command-line flag or ``filterwarnings`` ini options (see :ref:`warnings`), but we suggest to use these sparingly and temporarily, and heed the warnings when possible. To communicate changes, we issue deprecation warnings using a custom warning hierarchy (see :ref:`internal-warnings`). These warnings may be suppressed using the standard means: ``-W`` command-line flag or ``filterwarnings`` ini options (see :ref:`warnings`), but we suggest to use these sparingly and temporarily, and heed the warnings when possible.
We will only start the removal of deprecated functionality in major releases (e.g. if we deprecate something in 3.0 we will start to remove it in 4.0), and keep it around for at least two minor releases (e.g. if we deprecate something in 3.9 and 4.0 is the next release, we start to remove it in 5.0, not in 4.0). We will only start the removal of deprecated functionality in major releases (e.g. if we deprecate something in 3.0, we will start to remove it in 4.0), and keep it around for at least two minor releases (e.g. if we deprecate something in 3.9 and 4.0 is the next release, we start to remove it in 5.0, not in 4.0).
When the deprecation expires (e.g. 4.0 is released), we won't remove the deprecated functionality immediately, but will use the standard warning filters to turn them into **errors** by default. This approach makes it explicit that removal is imminent, and still gives you time to turn the deprecated feature into a warning instead of an error so it can be dealt with in your own time. In the next minor release (e.g. 4.1), the feature will be effectively removed. When the deprecation expires (e.g. 4.0 is released), we won't remove the deprecated functionality immediately, but will use the standard warning filters to turn them into **errors** by default. This approach makes it explicit that removal is imminent, and still gives you time to turn the deprecated feature into a warning instead of an error so it can be dealt with in your own time. In the next minor release (e.g. 4.1), the feature will be effectively removed.

16
doc/en/explanation/pythonpath.rst
View File

@ -8,15 +8,15 @@ pytest import mechanisms and ``sys.path``/``PYTHONPATH``
Import modes Import modes
------------ ------------
pytest as a testing framework needs to import test modules and ``conftest.py`` files for execution. pytest as a testing framework that needs to import test modules and ``conftest.py`` files for execution.
Importing files in Python is a non-trivial processes, so aspects of the Importing files in Python is a non-trivial process, so aspects of the
import process can be controlled through the ``--import-mode`` command-line flag, which can assume import process can be controlled through the ``--import-mode`` command-line flag, which can assume
these values: these values:
.. _`import-mode-prepend`: .. _`import-mode-prepend`:
* ``prepend`` (default): the directory path containing each module will be inserted into the *beginning* * ``prepend`` (default): The directory path containing each module will be inserted into the *beginning*
of :py:data:`sys.path` if not already there, and then imported with of :py:data:`sys.path` if not already there, and then imported with
the :func:`importlib.import_module <importlib.import_module>` function. the :func:`importlib.import_module <importlib.import_module>` function.
@ -34,7 +34,7 @@ these values:
* ``append``: the directory containing each module is appended to the end of :py:data:`sys.path` if not already * ``append``: the directory containing each module is appended to the end of :py:data:`sys.path` if not already
there, and imported with :func:`importlib.import_module <importlib.import_module>`. there, and imported with :func:`importlib.import_module <importlib.import_module>`.
This better allows to run test modules against installed versions of a package even if the This better allows users to run test modules against installed versions of a package even if the
package under test has the same import root. For example: package under test has the same import root. For example:
:: ::
@ -45,7 +45,7 @@ these values:
the tests will run against the installed version the tests will run against the installed version
of ``pkg_under_test`` when ``--import-mode=append`` is used whereas of ``pkg_under_test`` when ``--import-mode=append`` is used whereas
with ``prepend`` they would pick up the local version. This kind of confusion is why with ``prepend``, they would pick up the local version. This kind of confusion is why
we advocate for using :ref:`src-layouts <src-layout>`. we advocate for using :ref:`src-layouts <src-layout>`.
Same as ``prepend``, requires test module names to be unique when the test directory tree is Same as ``prepend``, requires test module names to be unique when the test directory tree is
@ -67,7 +67,7 @@ these values:
are not importable. The recommendation in this case it to place testing utility modules together with the application/library are not importable. The recommendation in this case it to place testing utility modules together with the application/library
code, for example ``app.testing.helpers``. code, for example ``app.testing.helpers``.
Important: by "test utility modules" we mean functions/classes which are imported by Important: by "test utility modules", we mean functions/classes which are imported by
other tests directly; this does not include fixtures, which should be placed in ``conftest.py`` files, along other tests directly; this does not include fixtures, which should be placed in ``conftest.py`` files, along
with the test modules, and are discovered automatically by pytest. with the test modules, and are discovered automatically by pytest.
@ -76,8 +76,8 @@ these values:
1. Given a certain module path, for example ``tests/core/test_models.py``, derives a canonical name 1. Given a certain module path, for example ``tests/core/test_models.py``, derives a canonical name
like ``tests.core.test_models`` and tries to import it. like ``tests.core.test_models`` and tries to import it.
For non-test modules this will work if they are accessible via :py:data:`sys.path`, so For non-test modules, this will work if they are accessible via :py:data:`sys.path`. So
for example ``.env/lib/site-packages/app/core.py`` will be importable as ``app.core``. for example, ``.env/lib/site-packages/app/core.py`` will be importable as ``app.core``.
This is happens when plugins import non-test modules (for example doctesting). This is happens when plugins import non-test modules (for example doctesting).
If this step succeeds, the module is returned. If this step succeeds, the module is returned.