Merge pull request #8043 from tk0miya/refactor_autodoc

refactor autodoc: Documenter.filter_members()

CHANGES

@@ -10,6 +10,7 @@ Incompatible changes
 Deprecated
 ----------
 
+* ``sphinx.ext.autodoc.members_set_option()``
 * ``sphinx.ext.autodoc.merge_special_members_option()``
 * ``sphinx.writers.texinfo.TexinfoWriter.desc``
 * C, parsing of pre-v3 style type directives and roles, along with the options

doc/extdev/deprecated.rst

@@ -26,6 +26,11 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - ``sphinx.ext.autodoc.members_set_option()``
+     - 3.2
+     - 5.0
+     - N/A
+
    * - ``sphinx.ext.autodoc.merge_special_members_option()``
      - 3.2
      - 5.0

sphinx/ext/autodoc/__init__.py

@@ -61,13 +61,29 @@
            (?:\s* -> \s* (.*))?  #           return annotation
           )? $                   # and nothing more
           ''', re.VERBOSE)
+special_member_re = re.compile(r'^__\S+__$')
 
 
 def identity(x: Any) -> Any:
     return x
 
 
-ALL = object()
+class _All:
+    """A special value for :*-members: that matches to any member."""
+
+    def __contains__(self, item: Any) -> bool:
+        return True
+
+
+class _Empty:
+    """A special value for :exclude-members: that never matches to any member."""
+
+    def __contains__(self, item: Any) -> bool:
+        return False
+
+
+ALL = _All()
+EMPTY = _Empty()
 UNINITIALIZED_ATTR = object()
 INSTANCEATTR = object()
 SLOTSATTR = object()
@@ -82,11 +98,20 @@ def members_option(arg: Any) -> Union[object, List[str]]:
 
 def members_set_option(arg: Any) -> Union[object, Set[str]]:
     """Used to convert the :members: option to auto directives."""
+    warnings.warn("members_set_option() is deprecated.",
+                  RemovedInSphinx50Warning, stacklevel=2)
     if arg is None:
         return ALL
     return {x.strip() for x in arg.split(',') if x.strip()}
 
 
+def exclude_members_option(arg: Any) -> Union[object, Set[str]]:
+    """Used to convert the :exclude-members: option."""
+    if arg is None:
+        return EMPTY
+    return {x.strip() for x in arg.split(',') if x.strip()}
+
+
 def inherited_members_option(arg: Any) -> Union[object, Set[str]]:
     """Used to convert the :members: option to auto directives."""
     if arg is None:
@@ -647,29 +672,24 @@ def is_filtered_inherited_member(name: str) -> bool:
             if safe_getattr(member, '__sphinx_mock__', False):
                 # mocked module or object
                 pass
-            elif (self.options.exclude_members not in (None, ALL) and
-                  membername in self.options.exclude_members):
+            elif self.options.exclude_members and membername in self.options.exclude_members:
                 # remove members given by exclude-members
                 keep = False
-            elif want_all and membername.startswith('__') and \
-                    membername.endswith('__') and len(membername) > 4:
+            elif want_all and special_member_re.match(membername):
                 # special __methods__
-                if self.options.special_members is ALL:
+                if self.options.special_members and membername in self.options.special_members:
                     if membername == '__doc__':
                         keep = False
                     elif is_filtered_inherited_member(membername):
                         keep = False
                     else:
                         keep = has_doc or self.options.undoc_members
-                elif self.options.special_members:
-                    if membername in self.options.special_members:
-                        keep = has_doc or self.options.undoc_members
+                else:
+                    keep = False
             elif (namespace, membername) in attr_docs:
                 if want_all and isprivate:
                     if self.options.private_members is None:
                         keep = False
-                    elif self.options.private_members is ALL:
-                        keep = True
                     else:
                         keep = membername in self.options.private_members
                 else:
@@ -680,8 +700,6 @@ def is_filtered_inherited_member(name: str) -> bool:
                 if has_doc or self.options.undoc_members:
                     if self.options.private_members is None:
                         keep = False
-                    elif self.options.private_members is ALL:
-                        keep = True
                     elif is_filtered_inherited_member(membername):
                         keep = False
                     else:
@@ -888,7 +906,7 @@ class ModuleDocumenter(Documenter):
         'noindex': bool_option, 'inherited-members': inherited_members_option,
         'show-inheritance': bool_option, 'synopsis': identity,
         'platform': identity, 'deprecated': bool_option,
-        'member-order': member_order_option, 'exclude-members': members_set_option,
+        'member-order': member_order_option, 'exclude-members': exclude_members_option,
         'private-members': members_option, 'special-members': members_option,
         'imported-members': bool_option, 'ignore-module-all': bool_option
     }  # type: Dict[str, Callable]
@@ -1308,7 +1326,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         'members': members_option, 'undoc-members': bool_option,
         'noindex': bool_option, 'inherited-members': inherited_members_option,
         'show-inheritance': bool_option, 'member-order': member_order_option,
-        'exclude-members': members_set_option,
+        'exclude-members': exclude_members_option,
         'private-members': members_option, 'special-members': members_option,
     }  # type: Dict[str, Callable]