feat: Add wildcard_imported boolean attribute to aliases, deprecate on_wildcard_expansion event

Extensions can now hook onto `on_alias` instead, and check the `wildcard_imported` property of aliases.

Author: pawamoy

docs/guide/users/extending.md

@@ -208,10 +208,6 @@ There are also specific **load events** for each object kind:
 - [`on_alias`][griffe.Extension.on_alias]: The "on alias" event is triggered on aliases (imported/inherited objects).
 - [`on_package`][griffe.Extension.on_package]: The "on package" event is triggered on top-level modules (packages) only.
 
-And a special **load event** for wildcard expansion:
-
-- [`on_wildcard_expansion`][griffe.Extension.on_wildcard_expansion]: The "on wildcard expansion" event is triggered for each alias that is created by expanding wildcard imports (`from ... import *`).
-
 #### Analysis events
 
 **Analysis events** are triggered while modules are being scanned (with static or dynamic analysis). Data is incomplete when these events are triggered, so we recommend only hooking onto these events if you know what you are doing. In doubt, prefer using **load events** above.

src/griffe/_internal/extensions/base.py

@@ -50,6 +50,14 @@ def __new__(cls, name: str, bases: tuple[type, ...], attrs: dict[str, Any]) -> _
                     DeprecationWarning,
                     stacklevel=1,
                 )
+        if "on_wildcard_expansion" in attrs:
+            warnings.warn(
+                "The `on_wildcard_expansion` event is deprecated. "
+                "Instead, hook onto the `on_alias` event "
+                "and check for aliases' `wildcard_imported` boolean attribute.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         return super().__new__(cls, name, bases, attrs)
 
 
@@ -465,21 +473,6 @@ def on_package(self, *, pkg: Module, loader: GriffeLoader, **kwargs: Any) -> Non
         if hasattr(self, "on_package_loaded"):
             self.on_package_loaded(pkg=pkg, loader=loader, **kwargs)
 
-    def on_wildcard_expansion(
-        self,
-        *,
-        alias: Alias,
-        loader: GriffeLoader,
-        **kwargs: Any,
-    ) -> None:
-        """Run when wildcard imports are expanded into aliases.
-
-        Parameters:
-            alias: The alias instance.
-            loader: The loader currently in use.
-            **kwargs: For forward-compatibility.
-        """
-
 
 LoadableExtensionType = Union[str, dict[str, Any], Extension, type[Extension]]
 """All the types that can be passed to `load_extensions`."""
@@ -506,6 +499,9 @@ def add(self, *extensions: Extension) -> None:
         for extension in extensions:
             self._extensions.append(extension)
 
+    def _noop(self, **kwargs: Any) -> None:
+        """No-op method for extension hooks."""
+
     def call(self, event: str, **kwargs: Any) -> None:
         """Call the extension hook for the given event.
 
@@ -519,7 +515,7 @@ def call(self, event: str, **kwargs: Any) -> None:
                 with suppress(TypeError):
                     getattr(extension, event)(**kwargs)
             else:
-                getattr(extension, event)(**kwargs)
+                getattr(extension, event, self._noop)(**kwargs)
 
 
 builtin_extensions: set[str] = {

src/griffe/_internal/loader.py

@@ -417,6 +417,7 @@ def expand_wildcards(
                     lineno=alias_lineno,
                     endlineno=alias_endlineno,
                     parent=obj,  # type: ignore[arg-type]
+                    wildcard_imported=True,
                 )
                 # Special case: we avoid overwriting a submodule with an alias.
                 # Griffe suffers from this limitation where an object cannot store both
@@ -431,6 +432,7 @@ def expand_wildcards(
 
                 # Everything went right (supposedly), we add the alias as a member of the current object.
                 obj.set_member(new_member.name, alias)
+                # YORE: Bump 2: Remove line.
                 self.extensions.call("on_wildcard_expansion", alias=alias, loader=self)
 
     def resolve_module_aliases(

src/griffe/_internal/models.py

@@ -1292,6 +1292,7 @@ def __init__(
         runtime: bool = True,
         parent: Module | Class | Alias | None = None,
         inherited: bool = False,
+        wildcard_imported: bool = False,
     ) -> None:
         """Initialize the alias.
 
@@ -1304,6 +1305,7 @@ def __init__(
             runtime: Whether this alias is present at runtime or not.
             parent: The alias parent.
             inherited: Whether this alias wraps an inherited member.
+            wildcard_imported: Whether this alias was created using a wildcard import.
         """
         self.name: str = name
         """The alias name."""
@@ -1320,6 +1322,9 @@ def __init__(
         self.inherited: bool = inherited
         """Whether this alias represents an inherited member."""
 
+        self.wildcard_imported: bool = wildcard_imported
+        """Whether this alias was created using a wildcard import."""
+
         self.public: bool | None = None
         """Whether this alias is public."""
 

tests/test_extensions.py

@@ -252,3 +252,23 @@ def on_package_loaded(self, *, pkg: Module, loader: GriffeLoader, **kwargs: Any)
     with temporary_visited_package("pkg", {}, extensions=load_extensions(extension)):
         assert extension.records == ["called as on_package"]
 
+
+# YORE: Bump 2: Remove block.
+def test_deprecated_on_wildcard_expansion_event() -> None:
+    """Hook still runs, a deprecation warning is emitted when the class is declared."""
+    with pytest.warns(DeprecationWarning, match="`on_wildcard_expansion` event is deprecated"):
+
+        class Ext(Extension):
+            def __init__(self) -> None:
+                self.records: list[str] = []
+
+            def on_wildcard_expansion(self, *, alias: Alias, loader: GriffeLoader, **kwargs: Any) -> None:  # noqa: ARG002
+                self.records.append("called as on_wildcard_expansion")
+
+    extension = Ext()
+    with temporary_visited_package(
+        "pkg",
+        {"__init__.py": "from pkg.module import *", "module.py": "def func(): ..."},
+        extensions=load_extensions(extension),
+    ):
+        assert extension.records == ["called as on_wildcard_expansion"]