manager: deprecate register(None)

changelog/790.removal.rst

@@ -0,0 +1 @@
+:func:`PluginManager.register(None) <pluggy.PluginManager.register>` is deprecated: the call is still ignored, but now emits a :class:`DeprecationWarning`. It will become an error in a future version.

src/pluggy/_manager.py

@@ -194,11 +194,20 @@ def register(self, plugin: _Plugin, name: str | None = None) -> str | None:
             ``None``.
 
         If the plugin is already registered, raises a :exc:`ValueError`.
+
+        Passing ``None`` as the plugin is deprecated. The call is ignored and
+        emits a :class:`DeprecationWarning`. A future version will raise an
+        error.
         """
         if plugin is None:
-            # Registering a `None` plugin causes problems (#731). However, some
-            # users are doing it, so can't error out (#749). Just ignore
-            # instead.
+            # #731: registering None misbehaves. #749: callers still pass it,
+            # so ignore it for now. #790: warn until a later version errors.
+            warnings.warn(
+                "Passing None to PluginManager.register() is deprecated and will "
+                "become an error in a future version; it is currently ignored.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
             return None
 
         plugin_name = name or self.get_canonical_name(plugin)

testing/test_pluginmanager.py

@@ -30,8 +30,17 @@ def test_plugin_double_register(pm: PluginManager) -> None:
 
 
 def test_register_ignores_none(pm: PluginManager) -> None:
-    """``None`` collides with the blocked-name sentinel and must be ignored."""
-    assert pm.register(None) is None
+    """``None`` is ignored, and the caller sees a ``DeprecationWarning``."""
+    with pytest.warns(
+        DeprecationWarning,
+        match=(
+            r"Passing None to PluginManager\.register\(\) is deprecated and "
+            r"will become an error in a future version; it is currently ignored\."
+        ),
+    ) as record:
+        assert pm.register(None) is None
+    assert len(record) == 1
+    assert record[0].filename == __file__
     assert pm.get_plugins() == set()
     assert not pm.is_registered(None)