def test_modify_in_place(self):
lines = ['Summary line.', '', 'Args:', ' arg1: arg1 description']
app = mock.Mock()
app.config = Config()
_process_docstring(app, 'class', 'SampleClass', SampleClass,
mock.Mock(), lines)
expected = ['Summary line.', '', ':param arg1: arg1 description', '']
self.assertEqual(expected, lines)
def assertSkip(self, what, member, obj, expect_skip, config_name):
skip = 'default skip'
app = mock.Mock()
app.config = Config()
setattr(app.config, config_name, True)
if expect_skip:
self.assertEqual(
skip, _skip_member(app, what, member, obj, skip, mock.Mock()))
else:
self.assertFalse(
_skip_member(app, what, member, obj, skip, mock.Mock()))
setattr(app.config, config_name, False)
self.assertEqual(
skip, _skip_member(app, what, member, obj, skip, mock.Mock()))
def test_add_config_values(self):
app = mock.Mock(Sphinx)
setup(app)
for name, (default, rebuild) in Config._config_values.items():
has_config = False
for method_name, args, kwargs in app.method_calls:
if (method_name == 'add_config_value' and args[0] == name):
has_config = True
if not has_config:
self.fail('Config value was not added to app %s' % name)
has_process_docstring = False
has_skip_member = False
for method_name, args, kwargs in app.method_calls:
if method_name == 'connect':
if (args[0] == 'autodoc-process-docstring'
and args[1] == _process_docstring):
has_process_docstring = True
elif (args[0] == 'autodoc-skip-member'
and args[1] == _skip_member):
has_skip_member = True
if not has_process_docstring:
self.fail('autodoc-process-docstring never connected')
if not has_skip_member:
self.fail('autodoc-skip-member never connected')
def test_process_doc_handle_table_title():
env = mock.Mock(domaindata={})
table_node = nodes.table(
'',
nodes.title('title text', 'title text'),
)
document = mock.Mock(
nametypes={'testname': True},
nameids={'testname': 'testid'},
ids={'testid': table_node},
)
domain = StandardDomain(env)
if 'testname' in domain.data['labels']:
del domain.data['labels']['testname']
domain.process_doc(env, 'testdoc', document)
assert 'testname' in domain.data['labels']
assert domain.data['labels']['testname'] == ('testdoc', 'testid',
'title text')
def test_process_doc_handle_figure_caption():
env = mock.Mock(domaindata={})
figure_node = nodes.figure(
'',
nodes.caption('caption text', 'caption text'),
)
document = mock.Mock(
nametypes={'testname': True},
nameids={'testname': 'testid'},
ids={'testid': figure_node},
)
domain = StandardDomain(env)
if 'testname' in domain.data['labels']:
del domain.data['labels']['testname']
domain.process_doc(env, 'testdoc', document)
assert 'testname' in domain.data['labels']
assert domain.data['labels']['testname'] == ('testdoc', 'testid',
'caption text')
def test_readfromurl_authed(m_build_opener, m_HTTPPasswordMgrWithDefaultRealm,
m_HTTPBasicAuthHandler):
# read from URL containing basic auth creds
password_mgr = mock.Mock()
m_HTTPPasswordMgrWithDefaultRealm.return_value = password_mgr
url = 'https://*****:*****@domain.com/project/objects.inv'
_read_from_url(url)
m_HTTPPasswordMgrWithDefaultRealm.assert_called_once_with()
password_mgr.add_password.assert_called_with(
None, 'https://domain.com/project/objects.inv', 'user', '12345')
def test_unauthed(self, m_build_opener, m_HTTPPasswordMgrWithDefaultRealm,
m_HTTPBasicAuthHandler):
"""read from URL without auth creds"""
password_mgr = mock.Mock()
m_HTTPPasswordMgrWithDefaultRealm.return_value = password_mgr
url = 'https://domain.com/project/objects.inv'
_read_from_url(url)
# assert password manager not created
self.assertEqual(None, m_HTTPPasswordMgrWithDefaultRealm.call_args)
# assert no password added to the password manager
self.assertEqual(None, password_mgr.add_password.call_args)
def test_readfromurl_unauthed(m_default_opener, m_HTTPPasswordMgrWithDefaultRealm,
m_HTTPBasicAuthHandler):
# read from URL without auth creds
password_mgr = mock.Mock()
m_HTTPPasswordMgrWithDefaultRealm.return_value = password_mgr
url = 'https://domain.com/project/objects.inv'
_read_from_url(url)
# assert password manager not created
assert m_HTTPPasswordMgrWithDefaultRealm.call_args is None
# assert no password added to the password manager
assert password_mgr.add_password.call_args is None
def test_see_also_refs(self):
docstring = """\
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
See Also
--------
some, other, funcs
otherfunc : relationship
"""
actual = str(NumpyDocstring(docstring))
expected = """\
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
.. seealso::
:obj:`some`, :obj:`other`, :obj:`funcs`
\n\
:obj:`otherfunc`
relationship
"""
self.assertEqual(expected, actual)
docstring = """\
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
See Also
--------
some, other, funcs
otherfunc : relationship
"""
config = Config()
app = mock.Mock()
actual = str(NumpyDocstring(docstring, config, app, "method"))
expected = """\
numpy.multivariate_normal(mean, cov, shape=None, spam=None)
.. seealso::
:meth:`some`, :meth:`other`, :meth:`funcs`
\n\
:meth:`otherfunc`
relationship
"""
self.assertEqual(expected, actual)
def test_underscore_in_attribute(self):
docstring = """
Attributes
----------
arg_ : type
some description
"""
expected = """
:ivar arg_: some description
:vartype arg_: type
"""
config = Config(napoleon_use_ivar=True)
app = mock.Mock()
actual = str(NumpyDocstring(docstring, config, app, "class"))
self.assertEqual(expected, actual)
def test_xrefs_in_return_type(self):
docstring = """
Example Function
Returns
-------
:class:`numpy.ndarray`
A :math:`n \\times 2` array containing
a bunch of math items
"""
expected = """
Example Function
:returns: A :math:`n \\times 2` array containing
a bunch of math items
:rtype: :class:`numpy.ndarray`
"""
config = Config()
app = mock.Mock()
actual = str(NumpyDocstring(docstring, config, app, "method"))
self.assertEqual(expected, actual)
def test_colon_in_return_type(self):
docstring = """
Summary
Returns
-------
:py:class:`~my_mod.my_class`
an instance of :py:class:`~my_mod.my_class`
"""
expected = """
Summary
:returns: an instance of :py:class:`~my_mod.my_class`
:rtype: :py:class:`~my_mod.my_class`
"""
config = Config()
app = mock.Mock()
actual = str(NumpyDocstring(docstring, config, app, "method"))
self.assertEqual(expected, actual)
def request_session_head(url, **kwargs):
response = mock.Mock()
response.status_code = 200
response.url = url
return response
def test_raises_types(self):
docstrings = [
("""
Example Function
Raises
------
RuntimeError
A setting wasn't specified, or was invalid.
ValueError
Something something value error.
""", """
Example Function
:raises: * :exc:`RuntimeError` -- A setting wasn't specified, or was invalid.
* :exc:`ValueError` -- Something something value error.
"""),
################################
("""
Example Function
Raises
------
InvalidDimensionsError
""", """
Example Function
:raises: :exc:`InvalidDimensionsError`
"""),
################################
("""
Example Function
Raises
------
Invalid Dimensions Error
""", """
Example Function
:raises: Invalid Dimensions Error
"""),
################################
("""
Example Function
Raises
------
Invalid Dimensions Error
With description
""", """
Example Function
:raises: *Invalid Dimensions Error* -- With description
"""),
################################
("""
Example Function
Raises
------
InvalidDimensionsError
If the dimensions couldn't be parsed.
""", """
Example Function
:raises: :exc:`InvalidDimensionsError` -- If the dimensions couldn't be parsed.
"""),
################################
("""
Example Function
Raises
------
Invalid Dimensions Error
If the dimensions couldn't be parsed.
""", """
Example Function
:raises: *Invalid Dimensions Error* -- If the dimensions couldn't be parsed.
"""),
################################
("""
Example Function
Raises
------
If the dimensions couldn't be parsed.
""", """
Example Function
:raises: If the dimensions couldn't be parsed.
"""),
################################
("""
Example Function
Raises
------
:class:`exc.InvalidDimensionsError`
""", """
Example Function
:raises: :class:`exc.InvalidDimensionsError`
"""),
################################
("""
Example Function
Raises
------
:class:`exc.InvalidDimensionsError`
If the dimensions couldn't be parsed.
""", """
Example Function
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
"""be parsed.
"""),
################################
("""
Example Function
Raises
------
:class:`exc.InvalidDimensionsError`
If the dimensions couldn't be parsed,
then a :class:`exc.InvalidDimensionsError` will be raised.
""", """
Example Function
:raises: :class:`exc.InvalidDimensionsError` -- If the dimensions couldn't """
"""be parsed,
then a :class:`exc.InvalidDimensionsError` will be raised.
"""),
################################
("""
Example Function
Raises
------
:class:`exc.InvalidDimensionsError`
If the dimensions couldn't be parsed.
:class:`exc.InvalidArgumentsError`
If the arguments are invalid.
""", """
Example Function
:raises: * :class:`exc.InvalidDimensionsError` -- If the dimensions """
"""couldn't be parsed.
* :class:`exc.InvalidArgumentsError` -- If the arguments """
"""are invalid.
"""),
################################
("""
Example Function
Raises
------
:class:`exc.InvalidDimensionsError`
:class:`exc.InvalidArgumentsError`
""", """
Example Function
:raises: * :class:`exc.InvalidDimensionsError`
* :class:`exc.InvalidArgumentsError`
""")
]
for docstring, expected in docstrings:
config = Config()
app = mock.Mock()
actual = str(NumpyDocstring(docstring, config, app, "method"))
self.assertEqual(expected, actual)
