def get_motor_attr(motor_class, name, *defargs):
"""If any Motor attributes can't be accessed, grab the equivalent PyMongo
attribute. While we're at it, store some info about each attribute
in the global motor_info dict.
"""
attr = safe_getattr(motor_class, name)
method_class = safe_getattr(attr, "im_class", None)
from_pymongo = not safe_getattr(method_class, "__module__", "").startswith("motor")
# Store some info for process_motor_nodes()
full_name = "%s.%s.%s" % (motor_class.__module__, motor_class.__name__, name)
is_async_method = getattr(attr, "is_async_method", False)
is_cursor_method = getattr(attr, "is_motorcursor_chaining_method", False)
if is_async_method or is_cursor_method:
pymongo_method = getattr(motor_class.__delegate_class__, attr.pymongo_method_name)
else:
pymongo_method = None
is_pymongo_docstring = from_pymongo or is_async_method or is_cursor_method
motor_info[full_name] = {
# These sub-attributes are set in motor.asynchronize()
"is_async_method": is_async_method,
"is_pymongo_docstring": is_pymongo_docstring,
"pymongo_method": pymongo_method,
}
return attr
def get_motor_attr(motor_class, name, *defargs):
"""If any Motor attributes can't be accessed, grab the equivalent PyMongo
attribute. While we're at it, store some info about each attribute
in the global motor_info dict.
"""
attr = safe_getattr(motor_class, name)
method_class = safe_getattr(attr, 'im_class', None)
from_pymongo = not safe_getattr(
method_class, '__module__', '').startswith('motor')
# Store some info for process_motor_nodes()
full_name = '%s.%s.%s' % (
motor_class.__module__, motor_class.__name__, name)
is_async_method = getattr(attr, 'is_async_method', False)
is_cursor_method = getattr(attr, 'is_motorcursor_chaining_method', False)
if is_async_method or is_cursor_method:
pymongo_method = getattr(
motor_class.__delegate_class__, attr.pymongo_method_name)
else:
pymongo_method = None
is_pymongo_docstring = from_pymongo or is_async_method or is_cursor_method
motor_info[full_name] = {
# These sub-attributes are set in motor.asynchronize()
'is_async_method': is_async_method,
'callback_required': getattr(attr, 'callback_required', False),
'is_pymongo_docstring': is_pymongo_docstring,
'pymongo_method': pymongo_method }
return attr
def get_object_members(self, want_all):
if want_all:
# if not hasattr(self.object, '__all__'):
# for implicit module members, check __module__ to avoid
# documenting imported objects
return True, safe_getmembers(self.object)
# else:
# memberlist = self.object.__all__
# # Sometimes __all__ is broken...
# if not isinstance(memberlist, (list, tuple)) or not \
# all(isinstance(entry, string_types) for entry in memberlist):
# self.directive.warn(
# '__all__ should be a list of strings, not %r '
# '(in module %s) -- ignoring __all__' %
# (memberlist, self.fullname))
# # fall back to all members
# return True, safe_getmembers(self.object)
else:
memberlist = self.options.members or []
ret = []
for mname in memberlist:
try:
ret.append((mname, safe_getattr(self.object, mname)))
except AttributeError:
self.directive.warn(
'missing attribute mentioned in :members: or __all__: '
'module %s, attribute %s' % (
safe_getattr(self.object, '__name__', '???'), mname))
return False, ret
def get_members(clazz, obj, typ):
names = set()
items = []
# the default dir
for name in dir(obj):
try:
documenter = get_documenter(safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ and not name.startswith('_'):
if name not in AutoCosmoSummary.exclude:
items.append((clazz,name))
names.add(name) # keep track of method/attribute conflicts
# the delegate dro
for n in obj.dro:
for name in dir(n):
try:
documenter = get_documenter(safe_getattr(n, name), n)
except AttributeError:
continue
# dont do conflicts
if name not in names:
if documenter.objtype == typ and not name.startswith('_'):
if name not in AutoCosmoSummary.exclude:
x = "%s.%s" %(n.__module__, n.__name__)
items.append((x,name))
names.add(name)
return ['~%s.%s' %item for item in sorted(items, key=lambda x: x[1])]
def test_safe_getattr_with_exception():
class Foo:
def __getattr__(self, item):
raise Exception
obj = Foo()
try:
inspect.safe_getattr(obj, 'bar')
except AttributeError as exc:
assert exc.args[0] == 'bar'
else:
pytest.fail('AttributeError not raised')
def test_safe_getattr_with_exception(self):
class Foo(object):
def __getattr__(self, item):
raise Exception
obj = Foo()
try:
inspect.safe_getattr(obj, 'bar')
except AttributeError as exc:
self.assertEqual(exc.args[0], 'bar')
else:
self.fail('AttributeError not raised')
def test_safe_getattr_with_property_exception():
class Foo(object):
@property
def bar(self):
raise Exception
obj = Foo()
try:
inspect.safe_getattr(obj, 'bar')
except AttributeError as exc:
assert exc.args[0] == 'bar'
else:
pytest.fail('AttributeError not raised')
def test_safe_getattr_with___dict___override(self):
class Foo(object):
@property
def __dict__(self):
raise Exception
obj = Foo()
try:
inspect.safe_getattr(obj, 'bar')
except AttributeError as exc:
self.assertEqual(exc.args[0], 'bar')
else:
self.fail('AttributeError not raised')
def test_safe_getattr_with___dict___override():
class Foo:
@property
def __dict__(self):
raise Exception
obj = Foo()
try:
inspect.safe_getattr(obj, 'bar')
except AttributeError as exc:
assert exc.args[0] == 'bar'
else:
pytest.fail('AttributeError not raised')
def get_motor_attr(motor_class, name, *defargs):
"""If any Motor attributes can't be accessed, grab the equivalent PyMongo
attribute. While we're at it, store some info about each attribute
in the global motor_info dict.
"""
attr = safe_getattr(motor_class, name)
# Store some info for process_motor_nodes()
full_name = '%s.%s.%s' % (
motor_class.__module__, motor_class.__name__, name)
full_name_legacy = 'motor.%s.%s.%s' % (
motor_class.__module__, motor_class.__name__, name)
# These sub-attributes are set in motor.asynchronize()
has_coroutine_annotation = getattr(attr, 'coroutine_annotation', False)
is_async_method = getattr(attr, 'is_async_method', False)
is_cursor_method = getattr(attr, 'is_motorcursor_chaining_method', False)
if is_async_method or is_cursor_method:
pymongo_method = getattr(
motor_class.__delegate_class__, attr.pymongo_method_name)
else:
pymongo_method = None
# attr.doc is set by statement like 'error = AsyncRead(doc="OBSOLETE")'.
is_pymongo_doc = pymongo_method and attr.__doc__ == pymongo_method.__doc__
motor_info[full_name] = motor_info[full_name_legacy] = {
'is_async_method': is_async_method or has_coroutine_annotation,
'is_pymongo_docstring': is_pymongo_doc,
'pymongo_method': pymongo_method,
}
return attr
def get_members_class(obj, typ, include_public=[],
include_base=False):
"""
typ = None -> all
include_base -> include attrs that are from a base class
"""
items = []
# using dir gets all of the attributes, including the elements
# from the base class, otherwise use __slots__ or __dict__
if include_base:
names = dir(obj)
else:
if hasattr(obj, '__slots__'):
names = tuple(getattr(obj, '__slots__'))
else:
names = getattr(obj, '__dict__').keys()
for name in names:
try:
documenter = get_documenter(safe_getattr(obj, name),
obj)
except AttributeError:
continue
if typ is None or documenter.objtype == typ:
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_motor_attr(motor_class, name, *defargs):
"""If any Motor attributes can't be accessed, grab the equivalent PyMongo
attribute. While we're at it, store some info about each attribute
in the global motor_info dict.
"""
from_pymongo = False
try:
attr = safe_getattr(motor_class, name, *defargs)
except AttributeError:
# Typically, this means 'name' is refers not to an async method like
# MotorDatabase.command, but to a ReadOnlyProperty, e.g.
# MotorClient.close(). The latter can't be accessed directly, but we
# can get the docstring and method signature from the equivalent
# PyMongo attribute, e.g. pymongo.mongo_client.MongoClient.close().
attr = getattr(motor_class.__delegate_class__, name, *defargs)
from_pymongo = True
# Store some info for process_motor_nodes()
full_name = '%s.%s.%s' % (
motor_class.__module__, motor_class.__name__, name)
is_async_method = getattr(attr, 'is_async_method', False)
motor_info[full_name] = {
# These sub-attributes are set in motor.asynchronize()
'is_async_method': is_async_method,
'callback_required': getattr(attr, 'callback_required', False),
'is_pymongo_docstring': from_pymongo or is_async_method}
return attr
def def_members(obj, typ, include_public=[]):
items = []
try:
obj_dict = safe_getattr(obj, '__dict__')
except AttributeError:
return []
defined = obj_dict.keys()
defined.sort()
for name in defined:
if sys.skip_member(name, obj): continue
try:
documenter = get_documenter(safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public
def test_safe_getattr_with_default():
class Foo:
def __getattr__(self, item):
raise Exception
obj = Foo()
result = inspect.safe_getattr(obj, 'bar', 'baz')
assert result == 'baz'
def add_content(self, more_content, no_docstring=False):
if self.doc_as_attr:
classname = safe_getattr(self.object, '__name__', None)
if classname:
content = ViewList(
[_('alias of :class:`%s`') % classname], source='')
MatModuleLevelDocumenter.add_content(self, content,
no_docstring=True)
else:
MatModuleLevelDocumenter.add_content(self, more_content)
def get_members(obj, typ, include_public=[]):
items = []
for name in dir(obj):
try:
documenter = get_documenter(safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [x for x in items if x in include_public or not x.startswith("_")]
return public, items
def get_object_members(self, want_all):
if want_all:
if not hasattr(self.object, '__all__'):
# for implicit module members, check __module__ to avoid
# documenting imported objects
return True, safe_getmembers(self.object)
else:
memberlist = self.object.__all__
else:
memberlist = self.options.members or []
ret = []
for mname in memberlist:
try:
ret.append((mname, safe_getattr(self.object, mname)))
except AttributeError:
self.directive.warn(
'missing attribute mentioned in :members: or __all__: '
'module %s, attribute %s' % (
safe_getattr(self.object, '__name__', '???'), mname))
return False, ret
def get_motor_attr(motor_class, name, *defargs):
"""If any Motor attributes can't be accessed, grab the equivalent PyMongo
attribute. While we're at it, store some info about each attribute
in the global motor_info dict.
"""
attr = safe_getattr(motor_class, name)
method_class = safe_getattr(attr, 'im_class', None)
from_pymongo = not safe_getattr(
method_class, '__module__', '').startswith('motor')
# Store some info for process_motor_nodes()
full_name = '%s.%s.%s' % (
motor_class.__module__, motor_class.__name__, name)
# TODO: hack! All docstrings should be updated with fully-qualified refs.
full_name_legacy = 'motor.motor_tornado.%s.%s' % (
motor_class.__name__, name)
has_coroutine_annotation = getattr(attr, 'coroutine_annotation', False)
is_async_method = getattr(attr, 'is_async_method', False)
is_cursor_method = getattr(attr, 'is_motorcursor_chaining_method', False)
if is_async_method or is_cursor_method:
pymongo_method = getattr(
motor_class.__delegate_class__, attr.pymongo_method_name)
else:
pymongo_method = None
# attr.doc is set by statement like 'error = AsyncRead(doc="OBSOLETE")'.
is_pymongo_doc = ((from_pymongo or is_async_method or is_cursor_method)
and not getattr(attr, 'doc', None))
motor_info[full_name] = motor_info[full_name_legacy] = {
'has_coroutine_annotation': has_coroutine_annotation,
# These sub-attributes are set in motor.asynchronize()
'is_async_method': is_async_method,
'is_pymongo_docstring': is_pymongo_doc,
'pymongo_method': pymongo_method,
}
return attr
def pywikibot_family_classproperty_getattr(obj, name, *defargs):
"""Custom getattr() to get classproperty instances."""
from sphinx.util.inspect import safe_getattr
from pywikibot.family import Family
from pywikibot.tools import classproperty
if not isinstance(obj, type) or not issubclass(obj, Family):
return safe_getattr(obj, name, *defargs)
for base_class in obj.__mro__:
try:
prop = base_class.__dict__[name]
except KeyError:
continue
if not isinstance(prop, classproperty):
return safe_getattr(obj, name, *defargs)
return prop
else:
return safe_getattr(obj, name, *defargs)
def get_members(app, obj, typ, include_public=None):
if not include_public:
include_public = []
items = []
for name in vars(obj):
try:
documenter = get_documenter(app, safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
items.sort()
public = [x for x in items if x in include_public or not x.startswith('_')]
return public, items
def get_members(obj, typ, include_public=[]):
# type: (Any, unicode, List[unicode]) -> Tuple[List[unicode], List[unicode]]
items = [] # type: List[unicode]
for name in dir(obj):
try:
documenter = get_documenter(safe_getattr(obj, name),
obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_full_modname(modname, attribute):
try:
__import__(modname)
except Exception as error:
if not app.quiet:
app.info(traceback.format_exc().rstrip())
app.warn('viewcode can\'t import %s, failed with error "%s"' %
(modname, error))
return None
module = sys.modules[modname]
try:
# Allow an attribute to have multiple parts and incidentally allow
# repeated .s in the attribute.
attr = attribute.split('.')
value = module
for attr in attribute.split('.'):
if attr:
value = safe_getattr(value, attr)
except AttributeError:
app.warn('Didn\'t find %s in %s' % (attribute, module.__name__))
return None
else:
return safe_getattr(value, '__module__', None)
def get_members(obj, typ, include_public=[], imported=False):
# type: (Any, unicode, List[unicode], bool) -> Tuple[List[unicode], List[unicode]] # NOQA
items = [] # type: List[unicode]
for name in dir(obj):
try:
value = safe_getattr(obj, name)
except AttributeError:
continue
documenter = get_documenter(value, obj)
if documenter.objtype == typ:
if imported or getattr(value, '__module__', None) == obj.__name__:
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_members_mod(obj, typ, include_public=[]):
"""
typ = None -> all
"""
items = []
for name in dir(obj):
try:
documenter = get_documenter(safe_getattr(obj, name),
obj)
except AttributeError:
continue
if typ is None or documenter.objtype == typ:
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_members(obj, typ, include_public=None):
if not include_public:
include_public = []
items = []
for name in sorted(obj.__dict__.keys()): #dir(obj):
try:
documenter = get_documenter(AutoAutoSummary.app,
safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype in typ:
items.append(name)
public = [
x for x in items if x in include_public or not x.startswith('_')
]
return public, items
def get_members_mod(obj, typ, include_public=[]):
"""
typ = None -> all
"""
items = []
for name in dir(obj):
try:
documenter = get_documenter(safe_getattr(obj, name),
obj)
except AttributeError:
continue
if typ is None or documenter.objtype == typ:
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_members(obj, types, include_public=[], imported=True):
# type: (Any, Set[str], List[str], bool) -> Tuple[List[str], List[str]] # NOQA
items = [] # type: List[str]
for name in dir(obj):
try:
value = safe_getattr(obj, name)
except AttributeError:
continue
documenter = get_documenter(app, value, obj)
if documenter.objtype in types:
if imported or getattr(value, '__module__', None) == obj.__name__:
# skip imported members if expected
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_public_members(obj, typ, include_public=[]):
items = []
for name in dir(obj):
attr = None
try:
attr = safe_getattr(obj, name)
documenter = get_documenter(attr, obj)
except AttributeError:
continue
attr_file = get_file(attr)
if ((documenter.objtype == typ)
and ((attr_file == get_file(obj)) or (attr_file is None))
and ((name in include_public) or not name.startswith('_'))):
items.append(name)
return items
def get_members(obj, typ, include_public=[]):
# type: (Any, unicode, List[unicode]) -> Tuple[List[unicode], List[unicode]]
items = [] # type: List[unicode]
for name in dir(obj):
try:
documenter = get_documenter(safe_getattr(obj, name),
obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [
x for x in items
if x in include_public or not x.startswith('_')
]
return public, items
def get_members(obj, typ, include_public=None):
if not include_public:
include_public = []
items = []
for name in vars(obj):
try:
documenter = get_documenter(safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
items.sort()
public = [
x for x in items if x in include_public or not x.startswith('_')
]
return public, items
def get_members_class(obj,
typ,
include_public=[],
include_base=False):
"""
typ = None -> all
include_base -> include attrs that are from a base class
"""
items = []
# using dir gets all of the attributes, including the elements
# from the base class, otherwise use __slots__ or __dict__
if include_base:
names = dir(obj)
else:
# Classes deriving from an ABC using the `abc` module will
# have an empty `__slots__` attribute in Python 3, unless
# other slots were declared along the inheritance chain. If
# the ABC-derived class has empty slots, we'll use the
# class `__dict__` instead.
declares_slots = (hasattr(obj, '__slots__')
and not (type(obj) is abc.ABCMeta
and len(obj.__slots__) == 0))
if declares_slots:
names = tuple(getattr(obj, '__slots__'))
else:
names = getattr(obj, '__dict__').keys()
for name in names:
try:
documenter = get_documenter(app,
safe_getattr(obj,
name), obj)
except AttributeError:
continue
if typ is None or documenter.objtype == typ:
items.append(name)
elif typ == 'attribute' and documenter.objtype == 'property':
# In Sphinx 2.0 and above, properties have a separate
# objtype, but we treat them the same here.
items.append(name)
public = [
x for x in items
if x in include_public or not x.startswith('_')
]
return public, items
def get_members(self, obj, typ, include_public=None):
if not include_public:
include_public = []
items = []
for name in obj.__dict__.keys():
try:
documenter = get_documenter(obj=safe_getattr(obj, name),
parent=obj,
app=self.env.app)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [
x for x in items if x in include_public or not x.startswith('_')
]
return public, items
def get_members(obj, typ, include_public=[]):
items = []
for name in dir(obj):
# skip_member
if exclude_member(obj, name):
continue
try:
documenter = get_documenter(safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
elif typ=='function' and documenter.objtype=='boundmethod':
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_members(obj, typ, include_public=[], imported=False):
# type: (Any, unicode, List[unicode], bool) -> Tuple[List[unicode], List[unicode]] # NOQA
items = [] # type: List[unicode]
for name in dir(obj):
try:
value = safe_getattr(obj, name)
except AttributeError:
continue
documenter = get_documenter(value, obj)
if documenter.objtype == typ:
if imported or getattr(value, '__module__',
None) == obj.__name__:
items.append(name)
public = [
x for x in items
if x in include_public or not x.startswith('_')
]
return public, items
def get_members(obj, typ, include_public=None):
if not include_public:
include_public = []
items = []
members = dir(obj)
members.sort(key=AutoAutoSummary._customSort)
for name in members:
try:
documenter = get_documenter(safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [
x for x in items if x in include_public or not x.startswith('_')
]
return public, items
def get_members(obj, typ, include_public=list()):
items = list()
for name in dir(obj):
# skip_member
if exclude_member(obj, name):
continue
try:
documenter = get_documenter(safe_getattr(obj, name),
obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
elif typ == 'function' and documenter.objtype == 'boundmethod':
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_type_hints(obj: Any, globalns: Dict = None, localns: Dict = None) -> Dict[str, Any]:
"""Return a dictionary containing type hints for a function, method, module or class object.
This is a simple wrapper of `typing.get_type_hints()` that does not raise an error on
runtime.
"""
from sphinx.util.inspect import safe_getattr # lazy loading
try:
return typing.get_type_hints(obj, None, localns)
except NameError:
# Failed to evaluate ForwardRef (maybe TYPE_CHECKING)
return safe_getattr(obj, '__annotations__', {})
except TypeError:
return {}
except KeyError:
# a broken class found (refs: https://github.com/sphinx-doc/sphinx/issues/8084)
return {}
def get_members(doc,
obj,
typ,
include_public=None,
signal=False,
enum=False):
try:
if not include_public:
include_public = []
items = []
for name in dir(obj):
if name not in obj.__dict__.keys():
continue
try:
chobj = safe_getattr(obj, name)
documenter = get_documenter(doc.settings.env.app, chobj,
obj)
#cl = get_class_that_defined_method(chobj)
#print(name, chobj.__qualname__, type(chobj), issubclass(chobj, Enum), documenter.objtype)
if documenter.objtype == typ:
if typ == 'attribute':
if signal and type(
chobj) != PyQt5.QtCore.pyqtSignal:
continue
if not signal and type(
chobj) == PyQt5.QtCore.pyqtSignal:
continue
elif typ == 'class':
if enum and not issubclass(chobj, Enum):
continue
if not enum and issubclass(chobj, Enum):
continue
items.append(name)
except AttributeError:
continue
public = [
x for x in items
if x in include_public or not x.startswith('_')
]
return public, items
except BaseException as e:
print(str(e))
raise e
def get_members(obj, typ, include_public=[]):
items = []
want_all = (self.options.inherited_members or
self.options.members is ALL)
members = zip(*self.get_object_members(want_all)[1])[0]
if self.options.exclude_members:
members = [m for m in members if
m not in self.options.exclude_members]
for name in members:
try:
documenter = get_documenter(
safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def insert_element(self, name, obj):
# See function build_py_coverage() in sphinx/sphinx/ext/coverage.py file
# from sphinx github repository
if name[0] == '_':
# starts with an underscore, ignore it
return
if name in _exclude:
return
try:
attr = safe_getattr(self.class_, name)
if inspect.isfunction(attr):
if _is_deprecated(obj):
self.deprecated_methods[name] = obj
else:
self.methods[name] = obj
else:
self.attrs[name] = obj
except AttributeError:
pass
def ismock(subject: Any) -> bool:
"""Check if the object is mocked."""
# check the object has '__sphinx_mock__' attribute
if not hasattr(subject, '__sphinx_mock__'):
return False
# check the object is mocked module
if isinstance(subject, _MockModule):
return True
try:
# check the object is mocked object
__mro__ = safe_getattr(type(subject), '__mro__', [])
if len(__mro__) > 2 and __mro__[1] is _MockObject:
return True
except AttributeError:
pass
return False
def get_members(obj, typ, include_public=[]):
items = []
for name in dir(obj):
try:
documenter = get_documenter(
app, safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
if hasattr(obj, "__all__"):
public = [x for x in items
if x in obj.__all__]
else:
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_module_members(module: Any) -> List[Tuple[str, Any]]:
"""Get members of target module."""
from sphinx.ext.autodoc import INSTANCEATTR
members = {} # type: Dict[str, Tuple[str, Any]]
for name in dir(module):
try:
value = safe_getattr(module, name, None)
members[name] = (name, value)
except AttributeError:
continue
# annotation only member (ex. attr: int)
if hasattr(module, '__annotations__'):
for name in module.__annotations__:
if name not in members:
members[name] = (name, INSTANCEATTR)
return sorted(list(members.values()))
def insert_element(self, name, obj):
# See function build_py_coverage() in sphinx/sphinx/ext/coverage.py file
# from sphinx github repository
if name[0] == '_':
# starts with an underscore, ignore it
return
if name in _exclude:
return
try:
attr = safe_getattr(self.class_, name)
if inspect.isfunction(attr):
if _is_deprecated(obj):
self.deprecated_methods[name] = obj
else:
self.methods[name] = obj
else:
self.attrs[name] = obj
except AttributeError:
pass
def get_members(obj, typ, include_public=[]):
items = []
want_all = self.options.inherited_members or \
self.options.members is ALL
members = zip(*self.get_object_members(want_all)[1])[0]
if self.options.exclude_members:
members = [m for m in members if
m not in self.options.exclude_members]
for name in members:
try:
documenter = get_documenter(safe_getattr(obj, name),
obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def add_directive_header(self, sig: str) -> None: # pragma: no cover (<Py37)
"""
Add the directive header and options to the generated content.
"""
super().add_directive_header(sig)
sourcename = self.get_sourcename()
if not self.options.annotation:
# obtain annotation for this data
try:
annotations = get_type_hints(self.parent)
except NameError:
# Failed to evaluate ForwardRef (maybe TYPE_CHECKING)
annotations = safe_getattr(self.parent, "__annotations__", {})
except TypeError:
annotations = {}
except KeyError:
# a broken class found (refs: https://github.com/sphinx-doc/sphinx/issues/8084)
annotations = {}
except AttributeError:
# AttributeError is raised on 3.5.2 (fixed by 3.5.3)
annotations = {}
if self.objpath[-1] in annotations:
objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
self.add_line(" :type: " + objrepr, sourcename)
else:
key = ('.'.join(self.objpath[:-1]), self.objpath[-1])
if self.analyzer and key in self.analyzer.annotations:
self.add_line(" :type: " + self.analyzer.annotations[key], sourcename)
try:
if self.object is UNINITIALIZED_ATTR:
pass
else:
objrepr = object_description(self.object)
self.add_line(" :value: " + objrepr, sourcename)
except ValueError:
pass
elif self.options.annotation is SUPPRESS:
pass
else:
self.add_line(" :annotation: %s" % self.options.annotation, sourcename)
def get_members(obj, typ, include_public=[]):
items = []
for name in dir(obj):
if sys.skip_member(name, obj):
continue
if typ in ["class", "function"]:
c = getattr(obj, name)
if inspect.isclass(c) or inspect.isfunction(c):
if c.__module__ != obj.__name__ + ".base" and c.__module__ != obj.__name__:
continue
try:
documenter = get_documenter(safe_getattr(obj, name), obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [x for x in items if x in include_public or not x.startswith("_")]
return public, items
def process_overload_signature(self, overload: Signature) -> Signature:
"""
Processes the signature of the given overloaded implementation.
:param overload:
:rtype:
.. latex:clearpage::
"""
__globals__ = safe_getattr(self.object, "__globals__", {})
overload = evaluate_signature(overload, __globals__)
if not inspect.isstaticmethod(
self.object, cls=self.parent, name=self.object_name):
overload = overload.replace(
parameters=list(overload.parameters.values())[1:])
return super().process_overload_signature(overload)
def get_members(obj, typ, include_public=[], imported=False):
items = []
for name in dir(obj):
try:
obj_name = safe_getattr(obj, name)
documenter = get_documenter(obj_name, obj)
except AttributeError:
continue
if documenter.objtype == typ:
try:
cond = (
imported or
obj_name.__module__ == obj.__name__
)
except AttributeError:
cond = True
if cond:
items.append(name)
public = [x for x in items
if x in include_public or not x.startswith('_')]
return public, items
def get_members(obj, typ, include_public=[], imported=False):
items = []
for name in dir(obj):
try:
obj_name = safe_getattr(obj, name)
documenter = get_documenter(obj_name, obj)
except AttributeError:
continue
if documenter.objtype == typ:
try:
cond = (imported
or obj_name.__module__ == obj.__name__)
except AttributeError:
cond = True
if cond:
items.append(name)
public = [
x for x in items
if x in include_public or not x.startswith('_')
]
return public, items
def get_module_members(module: Any) -> List[Tuple[str, Any]]:
"""Get members of target module."""
from sphinx.ext.autodoc import INSTANCEATTR
warnings.warn('sphinx.ext.autodoc.importer.get_module_members() is deprecated.',
RemovedInSphinx50Warning)
members: Dict[str, Tuple[str, Any]] = {}
for name in dir(module):
try:
value = safe_getattr(module, name, None)
members[name] = (name, value)
except AttributeError:
continue
# annotation only member (ex. attr: int)
for name in getannotations(module):
if name not in members:
members[name] = (name, INSTANCEATTR)
return sorted(list(members.values()))
def get_motor_attr(motor_class, name, *defargs):
"""If any Motor attributes can't be accessed, grab the equivalent PyMongo
attribute. While we're at it, store some info about each attribute
in the global motor_info dict.
"""
attr = safe_getattr(motor_class, name)
# Store some info for process_motor_nodes()
full_name = '%s.%s.%s' % (
motor_class.__module__, motor_class.__name__, name)
full_name_legacy = 'motor.%s.%s.%s' % (
motor_class.__module__, motor_class.__name__, name)
# These sub-attributes are set in motor.asynchronize()
has_coroutine_annotation = getattr(attr, 'coroutine_annotation', False)
is_async_method = getattr(attr, 'is_async_method', False)
coroutine_has_callback = has_coroutine_annotation or is_async_method
if has_coroutine_annotation:
coroutine_has_callback = getattr(attr, 'coroutine_has_callback', True)
is_cursor_method = getattr(attr, 'is_motorcursor_chaining_method', False)
if is_async_method or is_cursor_method:
pymongo_method = getattr(
motor_class.__delegate_class__, attr.pymongo_method_name)
else:
pymongo_method = None
# attr.doc is set by statement like 'error = AsyncRead(doc="OBSOLETE")'.
is_pymongo_doc = pymongo_method and attr.__doc__ == pymongo_method.__doc__
motor_info[full_name] = motor_info[full_name_legacy] = {
'is_async_method': is_async_method or has_coroutine_annotation,
'coroutine_has_callback': coroutine_has_callback,
'is_pymongo_docstring': is_pymongo_doc,
'pymongo_method': pymongo_method,
}
return attr
def split_full_qualified_name(name: str) -> Tuple[str, str]:
"""Split full qualified name to a pair of modname and qualname.
A qualname is an abbreviation for "Qualified name" introduced at PEP-3155
(https://www.python.org/dev/peps/pep-3155/). It is a dotted path name
from the module top-level.
A "full" qualified name means a string containing both module name and
qualified name.
.. note:: This function imports module actually to check the exisitence.
Therefore you need to mock 3rd party modules if needed before
calling this function.
"""
from sphinx.util import inspect
parts = name.split('.')
for i, part in enumerate(parts, 1):
try:
modname = ".".join(parts[:i])
module = import_module(modname)
# check the module has a member named as attrname
#
# Note: This is needed to detect the attribute having the same name
# as the module.
# ref: https://github.com/sphinx-doc/sphinx/issues/7812
attrname = parts[i]
if hasattr(module, attrname):
value = inspect.safe_getattr(module, attrname)
if not inspect.ismodule(value):
return ".".join(parts[:i]), ".".join(parts[i:])
except ImportError:
return ".".join(parts[:i - 1]), ".".join(parts[i - 1:])
except IndexError:
pass
return name, ""
def get_members(obj, typ, include_public=[]):
items = []
for name in dir(obj):
if sys.skip_member(name, obj): continue
if typ in ['class', 'function']:
c = getattr(obj, name)
if inspect.isclass(c) or inspect.isfunction(c):
if (c.__module__ != obj.__name__ + ".base"
and c.__module__ != obj.__name__):
continue
try:
documenter = get_documenter(safe_getattr(obj, name),
obj)
except AttributeError:
continue
if documenter.objtype == typ:
items.append(name)
public = [
x for x in items
if x in include_public or not x.startswith('_')
]
return public, items
def process_docstring(app, what, name, obj, options, lines):
"""Use the docstring of the parent if it is not defined."""
if not inspect.isfunction(obj):
return
if lines:
return
cls_name, func_name = name.split(".")[-2:]
self = obj.__globals__.get(cls_name)
if not self:
return
for base in self.mro()[1:]:
try:
base_method = sphinx_inspect.safe_getattr(base, func_name)
except AttributeError:
pass
else:
if not base.__module__.startswith("argus"):
continue
docstring = getattr(base_method, '__doc__', None)
if docstring:
lines[:] = prepare_docstring(docstring)
return
def emit(
self,
name: str,
*args: Any,
allowed_exceptions: Tuple["Type[Exception]", ...] = ()
) -> List:
"""Emit a Sphinx event."""
try:
logger.debug('[app] emitting event: %r%s', name, repr(args)[:100])
except Exception:
# not every object likes to be repr()'d (think
# random stuff coming via autodoc)
pass
results = []
listeners = sorted(self.listeners[name], key=attrgetter("priority"))
for listener in listeners:
try:
if self.app is None:
# for compatibility; RemovedInSphinx40Warning
results.append(listener.handler(*args))
else:
results.append(listener.handler(self.app, *args))
except allowed_exceptions:
# pass through the errors specified as *allowed_exceptions*
raise
except SphinxError:
raise
except Exception as exc:
modname = safe_getattr(listener.handler, '__module__', None)
raise ExtensionError(
__("Handler %r for event %r threw an exception") %
(listener.handler, name),
exc,
modname=modname) from exc
return results
def get_object_members(self, want_all):
if want_all:
if not hasattr(self.object, '__all__'):
# for implicit module members, check __module__ to avoid
# documenting imported objects
return True, self.object.safe_getmembers()
else:
memberlist = self.object.__all__
else:
memberlist = self.options.members or []
ret = []
for mname in memberlist:
try:
attr = self.get_attr(self.object, mname, None)
if attr:
ret.append((mname, attr))
else:
raise AttributeError
except AttributeError:
self.directive.warn(
'missing attribute mentioned in :members: or __all__: '
'module %s, attribute %s' %
(safe_getattr(self.object, '__name__', '???'), mname))
return False, ret
def _get_members(self, class_obj, member_type, include_in_public=None):
"""
Return class members of the specified type.
class_obj: Class object.
member_type: Member type ('method' or 'attribute').
include_in_public: set/list/tuple with member names that should be
included in public members in addition to the public names (those
starting without underscore).
Returns:
tuple(public_members, all_members): Names of the class members of
the specified member type (public / all).
"""
try:
app = self.state.document.settings.env.app
except AttributeError:
app = None
if not include_in_public:
include_in_public = []
all_members = []
for member_name in dir(class_obj):
try:
documenter = get_documenter(
app, safe_getattr(class_obj, member_name), class_obj)
except AttributeError:
continue
if documenter.objtype == member_type:
all_members.append(member_name)
public_members = [
x for x in all_members
if x in include_in_public or not x.startswith('_')
]
return public_members, all_members
def build_py_coverage(self):
# type: () -> None
objects = self.env.domaindata['py']['objects']
modules = self.env.domaindata['py']['modules']
skip_undoc = self.config.coverage_skip_undoc_in_source
for mod_name in modules:
ignore = False
for exp in self.mod_ignorexps:
if exp.match(mod_name):
ignore = True
break
if ignore:
continue
try:
mod = __import__(mod_name, fromlist=['foo'])
except ImportError as err:
logger.warning(__('module %s could not be imported: %s'),
mod_name, err)
self.py_undoc[mod_name] = {'error': err}
continue
funcs = []
classes = {} # type: Dict[str, List[str]]
for name, obj in inspect.getmembers(mod):
# diverse module attributes are ignored:
if name[0] == '_':
# begins in an underscore
continue
if not hasattr(obj, '__module__'):
# cannot be attributed to a module
continue
if obj.__module__ != mod_name:
# is not defined in this module
continue
full_name = '%s.%s' % (mod_name, name)
if inspect.isfunction(obj):
if full_name not in objects:
for exp in self.fun_ignorexps:
if exp.match(name):
break
else:
if skip_undoc and not obj.__doc__:
continue
funcs.append(name)
elif inspect.isclass(obj):
for exp in self.cls_ignorexps:
if exp.match(name):
break
else:
if full_name not in objects:
if skip_undoc and not obj.__doc__:
continue
# not documented at all
classes[name] = []
continue
attrs = [] # type: List[str]
for attr_name in dir(obj):
if attr_name not in obj.__dict__:
continue
try:
attr = safe_getattr(obj, attr_name)
except AttributeError:
continue
if not (inspect.ismethod(attr)
or inspect.isfunction(attr)):
continue
if attr_name[0] == '_':
# starts with an underscore, ignore it
continue
if skip_undoc and not attr.__doc__:
# skip methods without docstring if wished
continue
full_attr_name = '%s.%s' % (full_name, attr_name)
if full_attr_name not in objects:
attrs.append(attr_name)
if attrs:
# some attributes are undocumented
classes[name] = attrs
self.py_undoc[mod_name] = {'funcs': funcs, 'classes': classes}
def inspect_class(obj):
methods = defaultdict(list)
attributes = defaultdict(list)
mro = obj.__mro__
def get_full_class_name(c):
if c.__module__ == '__builtin__':
return c.__name__
else:
return c.__module__ + '.' + c.__name__
def get_class(m):
for c in mro:
if m in getattr(c, '__dict__', []):
return c
return None
# this is pretty lame, should do better
for c in mro:
if not '_sphinx_documented_attributes' in c.__dict__:
format_docstring(c, dont_recurse=True)
# sorted(dir(obj), key=lambda x: '|' + x if x.startswith('_') else x):
for k in dir(obj):
try:
o = safe_getattr(obj, k)
is_method = isinstance(
o, (MethodType, FunctionType, builtin_function_or_method,
method_descriptor))
if k.startswith('_') and not is_method:
continue
if k == '__init__':
continue
if k.startswith('_') and not k.endswith('__'):
continue
if k.startswith('__') and k.endswith('__') and not o.__doc__:
continue
class_ = get_class(k)
assert class_ is not None
class_name = getattr(class_, '__name__', '')
if k.startswith('_' + class_name + '__'):
k = k.split('_' + class_name)[-1]
if k in MEMBER_BLACKLIST:
continue
if is_method:
documenting_class = class_
if not o.__doc__:
for c in mro:
if k in c.__dict__:
try:
supero = safe_getattr(c, k)
if supero.__doc__:
documenting_class = c
break
except AttributeError:
pass
methods[class_].append((k, documenting_class))
else:
documenting_class = class_
if k not in obj._sphinx_documented_attributes:
for c in mro:
if k in c.__dict__.get('_sphinx_documented_attributes',
[]):
documenting_class = c
break
attributes[class_].append((k, documenting_class))
except AttributeError:
pass
key_func = lambda x: '|' + x[0].lower() if x[0].startswith('_') else x[
0].lower()
methods = {
k: [
':meth:`~{}.{}`'.format(get_full_class_name(c), n)
for n, c in sorted(v, key=key_func)
]
for k, v in methods.items()
}
rows = [(':class:`~{}`'.format(get_full_class_name(c)),
', '.join(methods[c])) for c in mro
if c is not object and c in methods]
if rows:
im = ['.. admonition:: Methods', '']
im.extend(indent(table(rows)))
im.append('')
else:
im = []
all_attributes = {x[0] for v in attributes.values() for x in v}
for c in mro:
for a in c.__dict__.get('_sphinx_documented_attributes', []):
if not a in all_attributes:
attributes[c].append((a, c))
attributes = {
k: [
':attr:`~{}.{}`'.format(get_full_class_name(c), n)
for n, c in sorted(v, key=key_func)
]
for k, v in attributes.items()
}
rows = [(':class:`~{}`'.format(get_full_class_name(c)),
', '.join(attributes[c])) for c in mro
if c is not object and c in attributes]
if rows:
ia = ['.. admonition:: Attributes', '']
ia.extend(indent(table(rows)))
ia.append('')
else:
ia = []
return im, ia
