Add and use HideReason enum

Author: robtaylor

autoapi/_mapper.py

@@ -30,6 +30,7 @@
     PythonData,
     PythonException,
     _trace_visibility,
+    HideReason,
 )
 from .settings import OWN_PAGE_LEVELS, TEMPLATE_DIR
 
@@ -45,12 +46,7 @@ def in_stdlib(module_name: str) -> bool:
 
 
 def _color_info(msg: str) -> None:
-    LOGGER.info(
-        colorize("bold", "[AutoAPI] ")
-        + colorize(
-            "darkgreen", msg
-        )
-    )
+    LOGGER.info(colorize("bold", "[AutoAPI] ") + colorize("darkgreen", msg))
 
 
 def _expand_wildcard_placeholder(original_module, originals_map, placeholder):
@@ -389,13 +385,6 @@ def _output_top_rst(self):
         # Render Top Index
         top_level_index = os.path.join(self.dir_root, "index.rst")
 
-        modules = [obj for obj in self.all_objects.values()
-                   if obj.type == "module" and obj.docstring == ""]
-        if modules and "undoc-members" not in self.app.config.autoapi_options:
-            _color_info("The following modules have no top-level documentation, and so were skipped as undocumented:")
-            for m in modules:
-                _color_info(f"    {m.id}")
-
         pages = [obj for obj in self.objects_to_render.values() if obj.display]
         if not pages:
             msg = (
@@ -507,8 +496,12 @@ def _skip_if_stdlib(self):
                     and not obj["inherited_from"]["is_abstract"]
                     and module not in documented_modules
                 ):
-                    _trace_visibility(self.app, f"Hiding {obj['qual_name']} as determined to be Python standard Library (found as {obj['full_name']})", verbose=2)
-                    obj["hide"] = True
+                    _trace_visibility(
+                        self.app,
+                        f"Hiding {obj['qual_name']} as determined to be Python standard Library (found as {obj['full_name']})",
+                        verbose=2,
+                    )
+                    obj["hide_reason"] = HideReason.STD_LIBRARY
 
     def _resolve_placeholders(self):
         """Resolve objects that have been imported from elsewhere."""
@@ -527,19 +520,27 @@ def _hide_yo_kids(self):
         for module in self.paths.values():
             if module["all"] is not None:
                 all_names = set(module["all"])
-                _trace_visibility(self.app, f"{module['full_name']}: Found __all__ =")
                 for n in all_names:
                     _trace_visibility(self.app, f"    {n}")
                 for child in module["children"]:
                     if child["qual_name"] not in all_names:
-                        _trace_visibility(self.app, f"Hiding {child['full_name']}, as {child['qual_name']} not in __all__")
-                        child["hide"] = True
+                        _trace_visibility(
+                            self.app,
+                            f"Hiding {child['full_name']}, as {child['qual_name']} not in __all__",
+                        )
+                        child["hide_reason"] = HideReason.NOT_IN_ALL
             elif module["type"] == "module":
-                _trace_visibility(self.app, f"Testing if any children of {module['full_name']} have already been documented")
+                _trace_visibility(
+                    self.app,
+                    f"Testing if any children of {module['full_name']} have already been documented",
+                )
                 for child in module["children"]:
                     if "original_path" in child:
-                        _trace_visibility(self.app, f"Hiding {child['full_name']} as documented at {child['original_path']}")
-                        child["hide"] = True
+                        _trace_visibility(
+                            self.app,
+                            f"Hiding {child['full_name']} as it appears to be in your public API at {child['original_path']}",
+                        )
+                        child["hide_reason"] = HideReason.NOT_PUBLIC
 
     def map(self, options=None):
         self._skip_if_stdlib()
@@ -583,17 +584,27 @@ def _render_selection(self):
                 self.objects_to_render[obj.id] = obj
             else:
                 if obj.subpackages or obj.submodules:
-                    _trace_visibility(self.app, f"Not rendering the following as {obj.id} set to not display:", verbose=2)
+                    _trace_visibility(
+                        self.app,
+                        f"Not rendering the following as {obj.id} set to not display because object is {obj.hide_reason}",
+                        verbose=2,
+                    )
                 for module in itertools.chain(obj.subpackages, obj.submodules):
-                    _trace_visibility(self.app, f"    {module.obj['full_name']}", verbose=2)
-                    module.obj["hide"] = True
+                    _trace_visibility(
+                        self.app, f"    {module.obj['full_name']}", verbose=2
+                    )
+                    module.obj["hide_reason"] = HideReason.PARENT_HIDDEN
 
         def _inner(parent):
             for child in parent.children:
                 self.all_objects[child.id] = child
                 if not parent.display:
-                    _trace_visibility(self.app, f"Hiding {child.id} as parent {parent.id} will not be displayed", verbose=2)
-                    child.obj["hide"] = True
+                    _trace_visibility(
+                        self.app,
+                        f"Hiding {child.id} as parent {parent.id} will not be displayed",
+                        verbose=2,
+                    )
+                    child.obj["hide_reason"] = HideReason.PARENT_HIDDEN
 
                 if child.display and child.type in self.own_page_types:
                     self.objects_to_render[child.id] = child
@@ -603,6 +614,18 @@ def _inner(parent):
         for obj in list(self.all_objects.values()):
             _inner(obj)
 
+        modules = [
+            obj
+            for obj in self.all_objects.values()
+            if obj.type == "module" and obj.docstring == ""
+        ]
+        if modules and "undoc-members" not in self.app.config.autoapi_options:
+            _color_info(
+                "The following modules have no top-level documentation, and so were skipped as undocumented:"
+            )
+            for m in modules:
+                _color_info(f"    {m.id}")
+
     def create_class(self, data, options=None):
         """Create a class from the passed in data
 

autoapi/_objects.py

@@ -2,6 +2,13 @@
 
 import functools
 import pathlib
+import sys
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    from backports.strenum import StrEnum
+from typing import List
 
 import sphinx
 import sphinx.util
@@ -13,6 +20,7 @@
 
 LOGGER = sphinx.util.logging.getLogger(__name__)
 
+
 def _trace_visibility(app, msg: str, verbose=1) -> None:
     if app.config.autoapi_verbose_visibility >= verbose:
         LOGGER.info(colorize("bold", f"[AutoAPI] [Visibility] {msg}"))
@@ -35,6 +43,21 @@ def _format_args(args_info, include_annotations=True, ignore_self=None):
     return ", ".join(result)
 
 
+class HideReason(StrEnum):
+    NOT_HIDDEN = "not hidden"
+    UNDOC_MEMBER = "undocumented"
+    PRIVATE_MEMBER = "a private member"
+    SPECIAL_MEMBER = "a special member"
+    IMPORTED_MEMBER = "an imported member"
+    INHERITED_MEMBER = "an inherited member"
+    IS_NEW_OR_INIT = "__new__ or __init__"
+    NOT_IN_ALL = "not in __all__ for module"
+    NOT_PUBLIC = "assumed to not be public API"
+    PARENT_HIDDEN = "parent is hidden"
+    STD_LIBRARY = "part of Python standard library"
+    SKIP_MEMBER = "`autoapi-skip-member` returned false for the object"
+
+
 class PythonObject:
     """A class representing an entity from the parsed source code.
 
@@ -50,7 +73,13 @@ class PythonObject:
     type: str
 
     def __init__(
-        self, obj, jinja_env, app, url_root, options=None, class_content="class"
+        self,
+        obj,
+        jinja_env,
+        app,
+        url_root,
+        options: List[str] = [],
+        class_content="class",
     ):
         self.app = app
         self.obj = obj
@@ -84,8 +113,7 @@ def __init__(
 
         # For later
         self._class_content = class_content
-        self._display_cache: bool | None = None
-        self._skip_reason = None
+        self._display_cache: HideReason | None = None
 
     def __getstate__(self):
         """Obtains serialisable data for pickling."""
@@ -199,22 +227,65 @@ def is_special_member(self) -> bool:
         """Whether this object is a special member (True) or not (False)."""
         return self.short_name.startswith("__") and self.short_name.endswith("__")
 
+    @property
+    def hide_reason(self) -> HideReason:
+        skip_undoc_member = self.is_undoc_member and "undoc-members" not in self.options
+        skip_private_member = (
+            self.is_private_member and "private-members" not in self.options
+        )
+        skip_special_member = (
+            self.is_special_member and "special-members" not in self.options
+        )
+        skip_imported_member = self.imported and "imported-members" not in self.options
+        skip_inherited_member = (
+            self.inherited and "inherited-members" not in self.options
+        )
+
+        reason = HideReason.NOT_HIDDEN
+        if self.obj.get("hide-reason"):
+            reason = self.obj.get("hide-reason")
+        elif skip_undoc_member:
+            reason = HideReason.UNDOC_MEMBER
+        elif skip_private_member:
+            reason = HideReason.UNDOC_MEMBER
+        elif skip_special_member:
+            reason = HideReason.SPECIAL_MEMBER
+        elif skip_imported_member:
+            reason = HideReason.IMPORTED_MEMBER
+        elif skip_inherited_member:
+            reason = HideReason.INHERITED_MEMBER
+
+        # Allow user to override
+        # If we told the api we were skipping already, keep the reason as originally
+        skip = reason != HideReason.NOT_HIDDEN
+        api_says_skip = self.app.emit_firstresult(
+            "autoapi-skip-member", self.type, self.id, self, skip, self.options
+        )
+        if not skip and api_says_skip:
+            reason = HideReason.SKIP_MEMBER
+
+        return reason
+
     @property
     def display(self) -> bool:
         """Whether this object should be displayed in documentation.
 
         This attribute depends on the configuration options given in
         :confval:`autoapi_options` and the result of :event:`autoapi-skip-member`.
         """
-        skip = self._should_skip()
+
         if self._display_cache is None:
-            self._display_cache = not self._ask_ignore(skip)
-            if self._display_cache is False:
-                _trace_visibility(self.app, self._skip_reason)
+            self._display_cache = self.hide_reason
+            if self._display_cache != HideReason.NOT_HIDDEN:
+                _trace_visibility(
+                    self.app, f"Skipping {self.id} due to {self.hide_reason}"
+                )
         else:
-            _trace_visibility(self.app, f"Skipping {self.id} due to cache", verbose=2)
+            _trace_visibility(
+                self.app, f"Skipping {self.id} due to {self.hide_reason}", verbose=2
+            )
 
-        return self._display_cache
+        return self._display_cache == HideReason.NOT_HIDDEN
 
     @property
     def summary(self) -> str:
@@ -230,57 +301,6 @@ def summary(self) -> str:
 
         return ""
 
-    def _should_skip(self) -> bool:
-        skip_undoc_member = self.is_undoc_member and "undoc-members" not in self.options
-        skip_private_member = (
-            self.is_private_member and "private-members" not in self.options
-        )
-        skip_special_member = (
-            self.is_special_member and "special-members" not in self.options
-        )
-        skip_imported_member = self.imported and "imported-members" not in self.options
-        skip_inherited_member = (
-            self.inherited and "inherited-members" not in self.options
-        )
-
-        reason = ""
-        if self.obj.get("hide", False):
-            reason = "marked hidden by mapper"
-        elif skip_undoc_member:
-            reason = "is undocumented"
-        elif skip_private_member:
-            reason = "is a private member"
-        elif skip_special_member:
-            reason = "is a special member"
-        elif skip_imported_member:
-            reason = "is an imported member"
-        elif  skip_inherited_member:
-            reason = "is an inherited member"
-
-        self._skip_reason = f"Skipping {self.id} as {reason}"
-
-        return (
-            self.obj.get("hide", False)
-            or skip_undoc_member
-            or skip_private_member
-            or skip_special_member
-            or skip_imported_member
-            or skip_inherited_member
-        )
-
-    def _ask_ignore(self, skip: bool) -> bool:
-
-        ask_result = self.app.emit_firstresult(
-            "autoapi-skip-member", self.type, self.id, self, skip, self.options
-        )
-
-        if ask_result is not None:
-            reason = f"Skipping as 'autoapi-skip-member' returned {ask_result}"
-            if self._skip_reason:
-                reason += f"Passed skip={skip} to 'autoapi-skip-member' as {self._skip_reason}"
-            self._skip_reason = reason
-        return ask_result if ask_result is not None else skip
-
     def _children_of_type(self, type_: str) -> list[PythonObject]:
         return [child for child in self.children if child.type == type_]
 
@@ -339,14 +359,17 @@ def __init__(self, *args, **kwargs):
         Can be any of: abstractmethod, async, classmethod, property, staticmethod.
         """
 
-    def _should_skip(self) -> bool:
+    @property
+    def hide_reason(self) -> HideReason:
         is_new_or_init = self.name in (
             "__new__",
             "__init__",
         )
-        if not super()._should_skip and is_new_or_init:
-            self._skip_reason = f"Skipping method {self.id} as is __new__ or __init__"
-        return super()._should_skip() or is_new_or_init
+        hide_reason = super().hide_reason
+        if hide_reason != HideReason.NOT_HIDDEN and is_new_or_init:
+            return HideReason.IS_NEW_OR_INIT
+        return hide_reason
+
 
 class PythonProperty(PythonObject):
     """The representation of a property on a class."""