How to get the document of an enumeration in python

Question

I have plenty of files formated as follows:

# Content of Enumeration1.py

from enum import IntEnum

class Enumeration1(IntEnum):
    """
    Some documentation.
    """
    key_0 = 0
    key_1 = 1
    key_2 = 2

How can I extract the documentation using python code from another "main.py", i.e.,

path_to_file = "./Enumeration1.py"
doc = get_documentation(path_to_file)  # how does this function works?
print(doc)  # outputs "Some documentation."

Do you expect to get `# Content of Enumeration1.py`, `Some documentation.` or something else? Could you import the containing module and/or load it by path, or are you restricted to extracting the documentation without running the module? Are you aware of [the `__doc__` attribute](https://docs.python.org/3/library/inspect.html#types-and-members)? — MisterMiyagi, Jan 09 '23 at 15:46
Does this answer your question? [Getting the docstring from a function](https://stackoverflow.com/questions/713138/getting-the-docstring-from-a-function) — MisterMiyagi, Jan 09 '23 at 15:50
The `get_documentation` is the function I don't know how to implement — Theophile Champion, Jan 09 '23 at 15:53
@MisterMiyagi: I am expecting to get `Some documentation`. Unfortunately, the "Getting the docstring from a function" does not works for me as I don't know in advance the name of all the enumerations (there may be thousands). — Theophile Champion, Jan 09 '23 at 15:57
I am looking for an automatic way to extract this documentation — Theophile Champion, Jan 09 '23 at 15:57
What exactly are the cases you need covered? [Another comment of yours](https://stackoverflow.com/questions/75059652/how-to-get-the-document-of-an-enumeration-in-python?noredirect=1#comment132457611_75059707) implies you don't know in advance which enumerations are present; what are the searches you expect to happen? Just the top-level? Nested inside classes, nested inside functions? — MisterMiyagi, Jan 09 '23 at 15:58
Don’t cover this in comments/chat, [edit] the question to provide well-defined constraints. — MisterMiyagi, Jan 09 '23 at 16:05

Samathingamajig · Accepted Answer · 2023-01-09T16:31:14.080

import the module based on the path string
get all the variables of the module
restrict it to be only enums (those which are classes, subclasses of the enum classes, but not a builtin enum subclass)
get just the docstrings

from enum import EnumType, EnumMeta, Enum, IntEnum, Flag, IntFlag, ReprEnum
import importlib.util
import inspect

def get_documentation(path_to_file, module_name):
    spec = importlib.util.spec_from_file_location(module_name, path_to_file)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    variables = {
        item: getattr(mod, item) for item in dir(mod) if not item.startswith("__")
    }
    enums = {
        name: value
        for name, value in variables.items()
        if inspect.isclass(value)
        and issubclass(
            value, (EnumType, EnumMeta, Enum, IntEnum, Flag, IntFlag, ReprEnum)
        )
        and value not in (EnumType, EnumMeta, Enum, IntEnum, Flag, IntFlag, ReprEnum)
    }
    docstrings = {name: value.__doc__ for name, value in enums.items()}
    return docstrings

For this example, the output is

{'Enumeration1': '\n    Some documentation.\n    '}

If you want to get rid of the extra whitespace, it's as simple as adding .strip() after .__doc__

@TheophileChampion so you want a list/dict of all the docstrings? — Samathingamajig, Jan 09 '23 at 15:50
Yes. Idealy, if there are many enumerations in the file, I would like to get a dictionary. But the key thing is that, I don't know the name of the enumerations (i.e., there are lots of files and within each file potentially many enumerations) — Theophile Champion, Jan 09 '23 at 15:59

How to get the document of an enumeration in python

1 Answers1