Autodoc displays `enum.Flag` member unions poorly when they are class attributes

Author: brockdyer03Created Sep 16, 2026Updated Sep 16, 2026

Labelstype:bug

Describe the bug

When a class attribute is set to a union of enum.Flag members the value shown is the integer value of the union, and does not show/include the actual names of members in the enum. Furthermore, the display is different for class attributes versus function defaults, which also seems like poor behavior.

How to Reproduce

example.py

python

from enum import Flag, auto

class Result(Flag):
    VAL1 = auto()
    VAL2 = auto()
    VAL3 = auto()


def function(arg: Result = Result.VAL1 | Result.VAL2) -> None:
    """docstring"""


class Class:
    """docstring"""

    #: docstring
    attribute: Result = Result.VAL1 | Result.VAL2

conf.py

python

import os
import sys

sys.path.insert(0, os.path.abspath('.'))
extensions = ['sphinx.ext.autodoc']

index.rst

restructuredtext

.. automodule:: example
   :members:

This produces the following output:

Environment Information

Platform:              linux; (Linux-7.2.5-200.fc44.x86_64-x86_64-with-glibc2.43)
Python version:        3.14.6 (main, Jun 11 2026, 04:03:53) [Clang 22.1.3 ])
Python implementation: CPython
Sphinx version:        9.1.0
Docutils version:      0.22.4
Jinja2 version:        3.1.6
Pygments version:      2.21.0

Sphinx extensions

python

Additional context

No response

Source: sphinx-doc/sphinx

View original on GitHub View discussion on GitHub