Merge pull request #6680 from RonnyPfannschmidt/fix-6294-more-docs-for-fromparent

doc: more docs for from_parent

doc/en/deprecations.rst

@@ -29,7 +29,7 @@ Below is a complete list of all pytest features which are considered deprecated.
 Option ``--no-print-logs`` is deprecated and meant to be removed in a future release. If you use ``--no-print-logs``, please try out ``--show-capture`` and
 provide feedback.
 
-``--show-capture`` command-line option was added in ``pytest 3.5.0` and allows to specify how to
+``--show-capture`` command-line option was added in ``pytest 3.5.0`` and allows to specify how to
 display captured output when tests fail: ``no``, ``stdout``, ``stderr``, ``log`` or ``all`` (the default).
 
 
@@ -39,9 +39,28 @@ Node Construction changed to ``Node.from_parent``
 
 .. deprecated:: 5.4
 
-The construction of nodes new should use the named constructor ``from_parent``.
+The construction of nodes now should use the named constructor ``from_parent``.
 This limitation in api surface intends to enable better/simpler refactoring of the collection tree.
 
+This means that instead of :code:`MyItem(name="foo", parent=collector, obj=42)`
+one now has to invoke :code:`MyItem.from_parent(collector, name="foo")`.
+
+Plugins that wish to support older versions of pytest and suppress the warning can use
+`hasattr` to check if `from_parent` exists in that version:
+
+.. code-block:: python
+
+    def pytest_pycollect_makeitem(collector, name, obj):
+        if hasattr(MyItem, "from_parent"):
+            item = MyItem.from_parent(collector, name="foo")
+            item.obj = 42
+            return item
+        else:
+            return MyItem(name="foo", parent=collector, obj=42)
+
+Note that ``from_parent`` should only be called with keyword arguments for the parameters.
+
+
 
 ``junit_family`` default value change to "xunit2"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/_pytest/deprecated.py

@@ -37,7 +37,10 @@ FIXTURE_POSITIONAL_ARGUMENTS = PytestDeprecationWarning(
 
 NODE_USE_FROM_PARENT = UnformattedWarning(
     PytestDeprecationWarning,
-    "direct construction of {name} has been deprecated, please use {name}.from_parent",
+    "Direct construction of {name} has been deprecated, please use {name}.from_parent.\n"
+    "See "
+    "https://docs.pytest.org/en/latest/deprecations.html#node-construction-changed-to-node-from-parent"
+    " for more details.",
 )
 
 JUNIT_XML_DEFAULT_FAMILY = PytestDeprecationWarning(

testing/deprecated_test.py

@@ -100,7 +100,7 @@ def test_node_direct_ctor_warning():
     ms = MockConfig()
     with pytest.warns(
         DeprecationWarning,
-        match="direct construction of .* has been deprecated, please use .*.from_parent",
+        match="Direct construction of .* has been deprecated, please use .*.from_parent.*",
     ) as w:
         nodes.Node(name="test", config=ms, session=ms, nodeid="None")
     assert w[0].lineno == inspect.currentframe().f_lineno - 1