Bad computation of enum superclass in sphinx.ext.autodoc.importer.get_class_members()

[alxroyer]

Describe the bug

The computation for the super-class in sphinx.ext.autodoc.importer.get_class_members() is:

superclass = subject.__mro__[1]

The version above does not check the super-class taken into account is actually the expected base enum type.

As a consequence, when the super-class is wrong:

• the method does not filter out a couple of members it's used to filter-out for enums: _generate_next_value_, __weakref__, _member_names_, _member_map_, _member_type_, _value2member_map_
• the method filters out other members it should not: __str__() for instance.

The computation below fixes the thing:

superclass = list(filter(sphinx.util.inspect.isenumclass, subject.__mro__))[1]

How to Reproduce

git clone https://github.com/alxroyer/scenario/
cd scenario/
python -m sphinx -T -E -b html -D language=en ./tools/conf/sphinx/ ./doc/html/

The problem occurs for the StrEnum class.

Environment Information

Sphinx version in use: 5.3.0, but the wrong line is still the same with 6.1.3.

Sphinx extensions

Base `sphinx.ext.autodoc` should be enough.

Additional context

No response

[AA-Turner]

Please provide a minimal reproducer, ideally a single module file, a single index.rst file, and a single conf.py file.

A

[alxroyer]

3 files, in the same directory:

• 'conf.py':

  extensions = ["sphinx.ext.autodoc"]
• 'index.rst':

  .. automodule:: strenum
     :members:
     :undoc-members:
     :private-members:
• strenum.py

  import enum
  
  
  class RegularEnum(enum.Enum):
      """
      Regular enum.
  
      ``enum.Enum`` inherited attributes are filtered-out.
      """
  
  
  class StrEnum(str, enum.Enum):
      """
      Inspired from ``enum.IntEnum``.
  
      ``enum.Enum`` inherited attributes are not filtered-out.
      """
      def __str__(self):
          return self.value

Build command, from the same directory:

python -m sphinx -b html . out/html

Output:

Hope that helps. Let me know.

[picnixz]

The computation below fixes the thing:
superclass = list(filter(sphinx.util.inspect.isenumclass, subject.__mro__))[1]

An enumeration is instantiated as¹:

EnumName([mixin_type, ...] [data_type,] enum_type)

Instead, it is better to use superclass = subject.__mro__[-2] because this would always target the correct enumeration type. Also, enumerations cannot be extended with other enumerations, unless the enumeration super class has no members:²

class EnumMixin(enum.Enum):
    pass

class MyEnum(EnumMixin, Enum):
    a = 1

class Invalid(MyEnum, Enum):  # failure
    b = 1 

The reason why __str__ is not included is because it is first a special member. I agree that there is an issue. This is not due to

sphinx/sphinx/ext/autodoc/importer.py

Lines 228 to 231 in 776d01e

	for name in obj_dict:
	if name not in superclass.__dict__:
	value = safe_getattr(subject, name)
	members[name] = ObjectMember(name, value, class_=subject)

but due to

sphinx/sphinx/ext/autodoc/importer.py

Lines 245 to 259 in 776d01e

	# other members
	for name in dir(subject):
	try:
	value = attrgetter(subject, name)
	if ismock(value):
	value = undecorate(value)
	unmangled = unmangle(subject, name)
	if unmangled and unmangled not in members:
	if name in obj_dict:
	members[unmangled] = ObjectMember(unmangled, value, class_=subject)
	else:
	members[unmangled] = ObjectMember(unmangled, value)
	except AttributeError:
	continue

Enumerations override __dir__ and only return public members and some pre-defined special methods. In particular, __str__ is not part of the public API for enumerations and Sphinx will never be able to find it. This is not the case for regular classes since __str__ will be found when using dir(subject).

As such, I suggest one of the following:

• Either you document the behaviour of what __str__ in the enumeration docstring directly (which would probably be more readable in general).
• Or we entirely change the logic of finding members for an enumeration (this would also affect

  sphinx/sphinx/ext/autodoc/importer.py

  Lines 146 to 153 in 776d01e

  	def get_object_members(
  	subject: Any,
  	objpath: list[str],
  	attrgetter: Callable,
  	analyzer: ModuleAnalyzer | None = None
  	) -> dict[str, Attribute]:
  	"""Get members and attributes of target object."""
  	from sphinx.ext.autodoc import INSTANCEATTR

  where enumerations are handled differently as well.

Footnotes

1. https://github.com/python/cpython/blob/9fbb614c4ed0b9181db1c1b858dfb93587662d6b/Lib/enum.py#L955-L957 ↩

2. https://github.com/python/cpython/blob/9fbb614c4ed0b9181db1c1b858dfb93587662d6b/Lib/enum.py#L929-L937 ↩

[alxroyer]

Thanks a lot @picnixz for the explanation.