refactor: Be more consistent regarding not overriding submodules with aliases

Our documentation states that a submodule will always get precedence over an alias of the same name. But the code only avoided replacing a submodule when the alias was pointing to the module.

With this change, we avoid replacing the submodule with *any* alias of the same name, not just aliases that point to the submodule.

The reason we do this is that Griffe suffers from a limitation where a module cannot store both a submodule and anoter member of the same name. We previously decided not to lift this limitation, because we consider this kind of name-shadowing bad practice. We document it in our "Recommendations / Python code" page.

Author: pawamoy

src/_griffe/loader.py

@@ -397,19 +397,16 @@ def expand_wildcards(
                     endlineno=alias_endlineno,
                     parent=obj,  # type: ignore[arg-type]
                 )
-                # Special case: we avoid overwriting a submodule with an alias pointing to it.
-                # Griffe suffers from this design flaw where an object cannot store both
+                # Special case: we avoid overwriting a submodule with an alias.
+                # Griffe suffers from this limitation where an object cannot store both
                 # a submodule and a member of the same name, while this poses (almost) no issue in Python.
-                # We at least prevent this case where a submodule is overwritten by an imported version of itself.
+                # We always give precedence to the submodule.
+                # See the "avoid member-submodule name shadowing" section in the "Python code" docs page.
                 if already_present:
                     prev_member = obj.get_member(new_member.name)
                     with suppress(AliasResolutionError, CyclicAliasError):
                         if prev_member.is_module:
-                            if prev_member.is_alias:
-                                prev_member = prev_member.final_target
-                            if alias.final_target is prev_member:
-                                # Alias named after the module it targets: skip to avoid cyclic aliases.
-                                continue
+                            continue
 
                 # Everything went right (supposedly), we add the alias as a member of the current object.
                 obj.set_member(new_member.name, alias)

tests/test_loader.py

@@ -489,3 +489,22 @@ def test_not_calling_package_loaded_hook_on_something_else_than_package() -> Non
         alias: Alias = loader.load("pkg.L")  # type: ignore[assignment]
         assert alias.is_alias
         assert not alias.resolved
+
+
+def test_not_overriding_module_with_alias_from_wildcard_import() -> None:
+    """Do not override a submodule with an imported object with the same name."""
+    with temporary_visited_package(
+        "pkg",
+        {
+            "__init__.py": "",
+            "a/__init__.py": "from .m import *",
+            "a/m.py": "def m(): pass",
+            "b/__init__.py": "from .m import *",
+            "b/m.py": "from pkg.a.m import m",
+        },
+        resolve_aliases=True,
+    ) as pkg:
+        assert pkg["a.m"].is_module
+        assert pkg["a.m.m"].is_function
+        assert pkg["b.m"].is_module
+        assert pkg["b.m.m"].is_alias