not all members have is_package/is_module

[ixje]

Description of the bug

From the documentation I get that one way of navigating through a module is via its members property. As I'm playing around to see if it can replace my forked API generator (that has some issues) I tried to simply print the modules and subpackages in my package using

    import griffe
    mamba = griffe.load("neo3")
    for member in mamba.members.values():
        # if member.is_alias or member.is_attribute:
        #    continue
        if member.is_subpackage:
            print(f"package: {member.name}")
        elif member.is_module:
            print(f"module: {member.name}")

However it seems that not all member types have the is_subpackage or is_module properties i.e. Alias lacks at least is_subpackage and is_module and Attribute lacks is_subpackage.

I'm not sure if this is intentional or not.

To Reproduce

pip install neo-mamba

run example code from description

Full traceback

Full traceback

Traceback (most recent call last):
  File "/home/erik/PycharmProjects/griffletest/venv/lib/python3.11/site-packages/griffe/dataclasses.py", line 1183, in _resolve_target
    resolved = self.modules_collection.get_member(self.target_path)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/erik/PycharmProjects/griffletest/venv/lib/python3.11/site-packages/griffe/mixins.py", line 77, in get_member
    return self.members[parts[0]]  # type: ignore[attr-defined]
           ~~~~~~~~~~~~^^^^^^^^^^
KeyError: 'logging'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/erik/PycharmProjects/griffletest/main.py", line 14, in <module>
    main()
  File "/home/erik/PycharmProjects/griffletest/main.py", line 8, in main
    if member.is_subpackage:
       ^^^^^^^^^^^^^^^^^^^^
  File "/home/erik/PycharmProjects/griffletest/venv/lib/python3.11/site-packages/griffe/dataclasses.py", line 1049, in is_subpackage
    return cast(Module, self.final_target).is_subpackage
                        ^^^^^^^^^^^^^^^^^
  File "/home/erik/PycharmProjects/griffletest/venv/lib/python3.11/site-packages/griffe/dataclasses.py", line 1149, in final_target
    target = target.target  # type: ignore[assignment]
             ^^^^^^^^^^^^^
  File "/home/erik/PycharmProjects/griffletest/venv/lib/python3.11/site-packages/griffe/dataclasses.py", line 1118, in target
    self.resolve_target()
  File "/home/erik/PycharmProjects/griffletest/venv/lib/python3.11/site-packages/griffe/dataclasses.py", line 1177, in resolve_target
    self._resolve_target()
  File "/home/erik/PycharmProjects/griffletest/venv/lib/python3.11/site-packages/griffe/dataclasses.py", line 1185, in _resolve_target
    raise AliasResolutionError(self) from error
griffe.exceptions.AliasResolutionError: Could not resolve alias neo3.logging pointing at logging (in venv/lib/python3.11/site-packages/neo3/__init__.py:1)

Expected behavior

I expected to easily test each member if it matches the type I want to filter on using is_subpackage and/or is_module without errors.

Environment information

griffe --debug-info  # | xclip -selection clipboard

• System: Linux-6.5.0-13-generic-x86_64-with-glibc2.38
• Python: cpython 3.11.6
• Environment variables:
• Installed packages:
• griffe v0.38.0

[pawamoy]

Thanks for the report!

The error in the traceback can be avoided with your commented line: if member.is_alias: continue.

However you're right that the module-kind properties are not exposed in the other kinds of objects (attribute, function, class), namely:

• is_init_module
• is_package
• is_subpackage
• is_namespace_package
• is_namespace_subpackage

The Alias class does have all these properties, though they do not appear in the API reference, true.

I thought it made sense to have these properties on the Module class only. It requires to check is_module first though, but I think it's an acceptable trade-off?

import griffe
mamba = griffe.load("neo3")
for member in mamba.members.values():
    if member.is_alias:
       continue
    if member.is_module and member.is_subpackage:
        print(f"package: {member.name}")
    elif member.is_module:
        print(f"module: {member.name}")

Well, if all objects have an is_module property, it would make sense to have all the other module-related properties too... I'll expose them in the attribute, function and class methods, and add the missing objects in the API reference 🙂

[ixje]

I thought it made sense to have these properties on the Module class only. It requires to check is_module first though, but I think it's an acceptable trade-off?

It's all how you envisioned the API. I saw the is_xxx properties while inspecting the result of load() and that triggered me to try and filter based on those properties.

I believe the problem might be with my mental model where I define a module as anything ending in a .py and a package as a folder containing a __init__.py and 0 or more .py modules. Under that mental model I was trying to filter using is_module and is_package/is_subpackage. Now after looking at the Python docs I realise my mental model was wrong as it states

It’s important to keep in mind that all packages are modules, but not all modules are packages. Or put another way, packages are just a special kind of module. Specifically, any module that contains a __path__ attribute is considered a package.

So I believe the correct way would become

import griffe
mamba = griffe.load("neo3")
for member in mamba.members.values():
    if isinstance(member, griffe.Module):
       if member.is_subpackage:
          print(f"package: {member.name}")
       else:
          print(f"module: {member.name}")

and the Alias documentation is all that could perhaps use a little polishing by means of description all properties it has.

Feel free to close the issue if you plan to keep it as is or want to track it in another issue.

[pawamoy]

The mental model to adopt when using Griffe is the one of a user of the Python code. griffe and griffe.dataclasses show no difference in usage from the user point of view: you can import them, or import from them. That's why I went with only a Module class and no Package class.

I think I'll still copy the Module-specific properties to the generic Object class, where they'll always return False. And yeah I'll add everything to the API reference 🙂