pytest_plugin.py: add deprecation warnings for httpserver_listen_address

emmett-rayes · csernazs · commit 1ca49381cd32 · 2021-02-14T16:14:59.000+01:00
Also add upgrade guide for version 1.0.0.
diff --git a/doc/changes.rst b/doc/changes.rst
@@ -1,2 +1,4 @@
+.. _changes:
+
 .. release-notes:: Release Notes
 
diff --git a/doc/index.rst b/doc/index.rst
@@ -41,3 +41,4 @@ For further details, please read the :doc:`guide` or the :doc:`api`.
     api
     background
     changes
+    upgrade
diff --git a/doc/upgrade.rst b/doc/upgrade.rst
@@ -0,0 +1,73 @@
+.. _upgrade:
+
+Upgrade guides
+==============
+
+The following document describes how to upgrade to a given version of the
+library which introduces breaking changes.
+
+Introducing breaking changes
+----------------------------
+When a breaking change is about to be made in the library, an intermediate
+release is released which generates deprecation warnings when the functionality
+to be removed is used. This does not break any functionality but shows a
+warning instead.
+
+Together with this intermediate release, a new *pre-release* is released to
+*pypi*. This release removes the functionality described by the warning, but
+*pip* does not install this version unless you specify the *--pre* parameter to
+*pip install*.
+
+Once you made the required changes to make your code compatible with the new
+version, you can install the new version by *pip install --pre
+pytest-httpserver*.
+
+After a given time period, a new non-pre release is released, this will be
+installed by pip similar to other releases and it will break your code if you
+have not made the required changes. If this happens, you can still pin the
+version in requirements.txt or other places. Usually specifying the version with
+`==` operator fixes the version, but for more details please read the
+documentation of the tool you are using in manage dependencies.
+
+
+1.0.0
+-----
+
+In pytest-httpserver 1.0.0 the following breaking changes were made.
+
+* The scope of ``httpserver_listen_address`` fixture changed from **function** to **session**
+
+In order to make your code compatible with the new version of pytest-httpserver,
+you need to specify the `session` scope explicitly.
+
+Example
+~~~~~~~
+
+Old code:
+
+.. code-block:: python
+
+    import pytest
+
+    @pytest.fixture
+    def httpserver_listen_address():
+        return ("127.0.0.1", 8888)
+
+New code:
+
+.. code-block:: python
+
+    import pytest
+
+    @pytest.fixture(scope="session")
+    def httpserver_listen_address():
+        return ("127.0.0.1", 8888)
+
+
+As this fixture is now defined with session scope, it will be called only once,
+when it is first referenced by a test or by another fixture.
+
+.. note::
+
+   There were other, non-breaking changes introduced to 1.0.0. For details,
+   please read the :ref:`changes`.
diff --git a/pytest_httpserver/pytest_plugin.py b/pytest_httpserver/pytest_plugin.py
@@ -1,8 +1,9 @@
 
-
 import os
+import warnings
 
 import pytest
+
 from .httpserver import HTTPServer
 
 
@@ -57,3 +58,14 @@ def pytest_sessionfinish(session, exitstatus):  # pylint: disable=unused-argumen
         Plugin.SERVER.clear()
         if Plugin.SERVER.is_running():
             Plugin.SERVER.stop()
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_fixture_setup(fixturedef, request):  # pylint: disable=unused-argument
+    if fixturedef.argname == 'httpserver_listen_address' and fixturedef.scope != 'session':
+        warnings.warn("httpserver_listen_address fixture will be converted to session scope in version 1.0.0. "
+                      "Details: https://pytest-httpserver.readthedocs.io/en/latest/upgrade.html",
+                      DeprecationWarning)
+        yield
+    else:
+        yield

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,4 @@`
	`1`	`+.. _changes:`
	`2`	`+`
`1`	`3`	`.. release-notes:: Release Notes`
`2`	`4`
-Original file line number
+Diff line change
     api
     background
     changes
 +    upgrade