diff --git a/CHANGES b/CHANGES index 4e934eb3450..d8a3cb915a7 100644 --- a/CHANGES +++ b/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 diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index d6e87b45923..829bfc32bbc 100644 --- a/doc/extdev/deprecated.rst +++ b/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 diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 2e6e7e632b4..832ee4a9209 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/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]