def test_fetchIntersphinxInventories_content():
"""
Download and parse intersphinx inventories for each configured
intersphix.
"""
options, _ = parse_args([])
options.intersphinx = [
'http://sphinx/objects.inv',
'file:///twisted/index.inv',
]
url_content = {
'http://sphinx/objects.inv': zlib.compress(
'sphinx.module py:module -1 sp.html -'),
'file:///twisted/index.inv': zlib.compress(
'twisted.package py:module -1 tm.html -'),
}
sut = model.System(options=options)
log = []
sut.msg = lambda part, msg: log.append((part, msg))
# Patch url getter to avoid touching the network.
sut.intersphinx._getURL = lambda url: url_content[url]
sut.fetchIntersphinxInventories()
assert [] == log
assert (
'http://sphinx/sp.html' ==
sut.intersphinx.getLink('sphinx.module')
)
assert (
'file:///twisted/tm.html' ==
sut.intersphinx.getLink('twisted.package')
)
def test_more_aliasing():
def addsrc(system):
src_a = """
class A:
pass
"""
src_b = """
from a import A as B
"""
src_c = """
from b import B as C
"""
src_d = """
from c import C
class D(C):
pass
"""
fromText(src_a, "a", system)
fromText(src_b, "b", system)
fromText(src_c, "c", system)
fromText(src_d, "d", system)
system = model.System()
addsrc(system)
assert system.allobjects["d.D"].bases == ["a.A"]
def test_EpydocLinker_resolve_identifier_xref_intersphinx_link_not_found(capsys: CapSys) -> None:
"""
A message is sent to stdout when no link could be found for the reference,
while returning the reference name without an A link tag.
The message contains the full name under which the reference was resolved.
FIXME: Use a proper logging system instead of capturing stdout. https://github.com/twisted/pydoctor/issues/112
"""
system = model.System()
target = model.Module(system, 'ignore-name')
# Here we set up the target module as it would have this import.
# from ext_package import ext_module
ext_package = model.Module(system, 'ext_package')
target.contents['ext_module'] = model.Module(
system, 'ext_module', parent=ext_package)
sut = epydoc2stan._EpydocLinker(target)
# This is called for the L{ext_module} markup.
assert sut.resolve_identifier('ext_module') is None
assert not capsys.readouterr().out
with raises(LookupError):
sut._resolve_identifier_xref('ext_module', 0)
captured = capsys.readouterr().out
expected = (
'ignore-name:???: Cannot find link target for "ext_package.ext_module", '
'resolved from "ext_module" '
'(you can link to external docs with --intersphinx)\n'
)
assert expected == captured
def test_EpydocLinker_translate_identifier_xref_intersphinx_link_not_found():
"""
A message is sent to stdout when no link could be found for the reference,
while returning the reference name without an A link tag.
The message contains the full name under which the reference was resolved.
"""
system = model.System()
target = model.Module(system, "ignore-name", "ignore-docstring")
# Here we set up the target module as it would have this import.
# from ext_package import ext_module
ext_package = model.Module(system, "ext_package", "ignore-docstring")
target.contents["ext_module"] = model.Module(system,
"ext_module",
"ignore-docstring",
parent=ext_package)
stdout = BytesIO()
sut = epydoc2stan._EpydocLinker(target)
try:
# FIXME: https://github.com/twisted/pydoctor/issues/112
# We no have this ugly hack to capture stdout.
previousStdout = sys.stdout
sys.stdout = stdout
# This is called for the L{ext_module} markup.
result = sut.translate_identifier_xref(fullID="ext_module",
prettyID="ext_module")
finally:
sys.stdout = previousStdout
assert "<code>ext_module</code>" == result
expected = ("ignore-name:0 invalid ref to 'ext_module' "
"resolved as 'ext_package.ext_module'\n")
assert expected == stdout.getvalue()
def test_xref_not_found_restructured(capsys: CapSys) -> None:
"""
When a link in an reStructedText docstring cannot be resolved, the reference
and the line number of the link should be reported.
However, currently the best we can do is report the starting line of the
docstring instead.
"""
system = model.System()
system.options.docformat = 'restructuredtext'
mod = fromText('''
"""
A test module.
Link to limbo: `NoSuchName`.
"""
''', modname='test', system=system)
epydoc2stan.format_docstring(mod)
captured = capsys.readouterr().out
# TODO: Should actually be line 5, but I can't get docutils to fill in
# the line number when it calls visit_title_reference().
# https://github.com/twisted/pydoctor/issues/237
assert captured == 'test:3: Cannot find link target for "NoSuchName"\n'
def test_EpydocLinker_translate_identifier_xref_intersphinx_relative_id():
"""
Return the link from inventory using short names, by resolving them based
on the imports done in the module.
"""
system = model.System()
inventory = SphinxInventory(system.msg, "some-project")
inventory._links["ext_package.ext_module"] = ("http://tm.tld", "some.html")
system.intersphinx = inventory
target = model.Module(system, "ignore-name", "ignore-docstring")
# Here we set up the target module as it would have this import.
# from ext_package import ext_module
ext_package = model.Module(system, "ext_package", "ignore-docstring")
target.contents["ext_module"] = model.Module(system,
"ext_module",
"ignore-docstring",
parent=ext_package)
sut = epydoc2stan._EpydocLinker(target)
# This is called for the L{ext_module<Pretty Text>} markup.
result = sut.translate_identifier_xref("ext_module", "Pretty Text")
expected = '<a href="http://tm.tld/some.html"><code>Pretty Text</code></a>'
assert expected == result
def test_introspection_extension() -> None:
"""Find docstrings from this test using introspection of an extension."""
try:
import cython_test_exception_raiser.raiser
except ImportError:
pytest.skip("cython_test_exception_raiser not installed")
system = model.System()
system.introspectModule(Path(cython_test_exception_raiser.raiser.__file__),
'cython_test_exception_raiser.raiser')
module = system.objForFullName('cython_test_exception_raiser.raiser')
assert module is not None
assert module.docstring is not None
assert module.docstring.strip().split(
'\n')[0] == "A trivial extension that just raises an exception."
cls = module.contents['RaiserException']
assert cls.docstring is not None
assert cls.docstring.strip(
) == "A speficic exception only used to be identified in tests."
func = module.contents['raiseException']
assert func.docstring is not None
assert func.docstring.strip() == "Raise L{RaiserException}."
def test_package_sourceHref() -> None:
"""
A package reports its __init__.py location as its source link.
"""
project_dir = Path("/foo/bar/ProjectName")
options = FakeOptions()
options.projectbasedirectory = project_dir
system = model.System()
system.ensurePackage('pkg')
system.sourcebase = "https://git.example.org/proj/main"
system.options = cast(Values, options)
mod_init = fromText('''
"""Docstring."""
''',
modname='__init__',
parent_name='pkg',
system=system)
system.setSourceHref(mod_init, project_dir / 'src' / 'pkg' / '__init__.py')
package = system.objForFullName('pkg')
assert isinstance(package, model.Package)
assert package.sourceHref == "https://git.example.org/proj/main/src/pkg/__init__.py"
def test_more_aliasing():
def addsrc(system):
src_a = '''
class A:
pass
'''
src_b = '''
from a import A as B
'''
src_c = '''
from b import B as C
'''
src_d = '''
from c import C
class D(C):
pass
'''
fromText(src_a, 'a', system)
fromText(src_b, 'b', system)
fromText(src_c, 'c', system)
fromText(src_d, 'd', system)
system = model.System()
addsrc(system)
assert system.allobjects['d.D'].bases == ['a.A']
def test_EpydocLinker_resolve_identifier_xref_intersphinx_relative_id(
) -> None:
"""
Return the link from inventory using short names, by resolving them based
on the imports done in the module.
"""
system = model.System()
inventory = SphinxInventory(system.msg)
inventory._links['ext_package.ext_module'] = ('http://tm.tld', 'some.html')
system.intersphinx = inventory
target = model.Module(system, 'ignore-name')
# Here we set up the target module as it would have this import.
# from ext_package import ext_module
ext_package = model.Module(system, 'ext_package')
target.contents['ext_module'] = model.Module(system,
'ext_module',
parent=ext_package)
sut = epydoc2stan._EpydocLinker(target)
# This is called for the L{ext_module<Pretty Text>} markup.
url = sut.resolve_identifier('ext_module')
url_xref = sut.resolve_identifier_xref('ext_module', 0)
assert "http://tm.tld/some.html" == url
assert "http://tm.tld/some.html" == url_xref
def test_initialization_options():
"""
Can be initialized with options.
"""
options = object()
sut = model.System(options=options)
assert options is sut.options
def test_initialization_default():
"""
When initialized without options, will use default options and default
verbosity.
"""
sut = model.System()
assert None is sut.options.projectname
assert 3 == sut.options.verbosity
def test_initialization_options() -> None:
"""
Can be initialized with options.
"""
options = cast(Values, object())
sut = model.System(options=options)
assert options is sut.options
def test_rest_support() -> None:
system = model.System()
system.options.docformat = 'restructuredtext'
system.options.verbosity = 4
src = '''
def f():
"""This is a docstring for f."""
'''
mod = fromText(src, system=system)
html = getHTMLOf(mod.contents['f'])
assert "<pre>" not in html
def test_aliasing_recursion():
system = model.System()
src = """
class C:
pass
from mod import C
class D(C):
pass
"""
mod = fromText(src, "mod", system)
assert mod.contents["D"].bases == ["mod.C"], mod.contents["D"].bases
def test_EpydocLinker_look_for_intersphinx_no_link() -> None:
"""
Return None if inventory had no link for our markup.
"""
system = model.System()
target = model.Module(system, 'ignore-name')
sut = epydoc2stan._EpydocLinker(target)
result = sut.look_for_intersphinx('base.module')
assert None is result
def test_aliasing_recursion():
system = model.System()
src = '''
class C:
pass
from mod import C
class D(C):
pass
'''
mod = fromText(src, 'mod', system)
assert mod.contents['D'].bases == ['mod.C'], mod.contents['D'].bases
def test_moresystems():
system = processPackage("basic")
system2 = model.System()
system2.moresystems.append(system)
mod = test_astbuilder.fromText("""
from basic import mod
class E(mod.C):
pass
""",
system=system2)
E = mod.contents["E"]
assert E.baseobjects[0] is not None
def test_fetchIntersphinxInventories_empty():
"""
Convert option to empty dict.
"""
options, _ = parse_args([])
options.intersphinx = []
sut = model.System(options=options)
sut.fetchIntersphinxInventories()
# Use internal state since I don't know how else to
# check for SphinxInventory state.
assert {} == sut.intersphinx._links
def test_EpydocLinker_look_for_intersphinx_hit() -> None:
"""
Return the link from inventory based on first package name.
"""
system = model.System()
inventory = SphinxInventory(system.msg)
inventory._links['base.module.other'] = ('http://tm.tld', 'some.html')
system.intersphinx = inventory
target = model.Module(system, 'ignore-name')
sut = epydoc2stan._EpydocLinker(target)
result = sut.look_for_intersphinx('base.module.other')
assert 'http://tm.tld/some.html' == result
def test_EpydocLinker_look_for_intersphinx_hit():
"""
Return the link from inventory based on first package name.
"""
system = model.System()
inventory = SphinxInventory(system.msg, "some-project")
inventory._links["base.module.other"] = ("http://tm.tld", "some.html")
system.intersphinx = inventory
target = model.Module(system, "ignore-name", "ignore-docstring")
sut = epydoc2stan._EpydocLinker(target)
result = sut.look_for_intersphinx("base.module.other")
assert "http://tm.tld/some.html" == result
def test_introspection():
"""Find docstrings from this test using introspection."""
system = model.System()
py_mod = sys.modules[__name__]
system.introspectModule(py_mod, __name__)
module = system.objForFullName(__name__)
assert module.docstring == __doc__
func = module.contents['test_introspection']
assert func.docstring == "Find docstrings from this test using introspection."
method = system.objForFullName(__name__ + '.Dummy.crash')
assert method.docstring == "Mmm"
def test_introspection_python() -> None:
"""Find docstrings from this test using introspection on pure Python."""
system = model.System()
system.introspectModule(Path(__file__), __name__)
module = system.objForFullName(__name__)
assert module is not None
assert module.docstring == __doc__
func = module.contents['test_introspection_python']
assert func.docstring == "Find docstrings from this test using introspection on pure Python."
method = system.objForFullName(__name__ + '.Dummy.crash')
assert method is not None
assert method.docstring == "Mmm"
def test_EpydocLinker_resolve_identifier_xref_intersphinx_absolute_id():
"""
Returns the link from Sphinx inventory based on a cross reference
ID specified in absolute dotted path and with a custom pretty text for the
URL.
"""
system = model.System()
inventory = SphinxInventory(system.msg)
inventory._links['base.module.other'] = ('http://tm.tld', 'some.html')
system.intersphinx = inventory
target = model.Module(system, 'ignore-name')
sut = epydoc2stan._EpydocLinker(target)
url = sut.resolve_identifier_xref('base.module.other')
assert "http://tm.tld/some.html" == url
def test_setSourceHrefOption(projectBaseDir: Path) -> None:
"""
Test that the projectbasedirectory option sets the model.sourceHref
properly.
"""
mod = cast(model.Module, FakeDocumentable())
options = FakeOptions()
options.projectbasedirectory = projectBaseDir
system = model.System()
system.sourcebase = "http://example.org/trac/browser/trunk"
system.options = cast(Values, options)
mod.system = system
system.setSourceHref(mod, projectBaseDir / "package" / "module.py")
assert mod.sourceHref == "http://example.org/trac/browser/trunk/package/module.py"
def test_EpydocLinker_translate_identifier_xref_intersphinx_absolute_id():
"""
Returns the link from Sphinx inventory based on a cross reference
ID specified in absolute dotted path and with a custom pretty text for the
URL.
"""
system = model.System()
inventory = SphinxInventory(system.msg, "some-project")
inventory._links["base.module.other"] = ("http://tm.tld", "some.html")
system.intersphinx = inventory
target = model.Module(system, "ignore-name", "ignore-docstring")
sut = epydoc2stan._EpydocLinker(target)
result = sut.translate_identifier_xref("base.module.other",
"base.module.pretty")
expected = '<a href="http://tm.tld/some.html"><code>base.module.pretty</code></a>'
assert expected == result
def test_generateContent():
"""
Return a string with inventory for all targeted objects, recursive.
"""
sut = make_SphinxInventory()
system = model.System()
root1 = model.Package(system, "package1", "docstring1")
root2 = model.Package(system, "package2", "docstring2")
child1 = model.Package(system, "child1", "docstring3", parent=root2)
system.addObject(child1)
subjects = [root1, root2]
result = sut._generateContent(subjects)
expected_result = ("package1 py:module -1 package1.html -\n"
"package2 py:module -1 package2.html -\n"
"package2.child1 py:module -1 package2.child1.html -\n")
assert expected_result == result
def test_EpydocLinker_translate_identifier_xref_intersphinx():
"""
Return the link from inventory.
"""
system = model.System()
inventory = SphinxInventory(system.msg, 'some-project')
inventory._links['base.module.other'] = ('http://tm.tld', 'some.html')
system.intersphinx = inventory
target = model.Module(system, 'ignore-name', 'ignore-docstring')
sut = epydoc2stan._EpydocLinker(target)
result = sut.translate_identifier_xref(
'base.module.other', 'base.module.pretty')
expected = (
'<a href="http://tm.tld/some.html"><code>base.module.pretty</code></a>'
)
assert expected == result
def test_EpydocLinker_translate_identifier_xref_intersphinx_absolute_id():
"""
Returns the link from Sphinx inventory based on a cross reference
ID specified in absolute dotted path and with a custom pretty text for the
URL.
"""
system = model.System()
inventory = SphinxInventory(system.msg)
inventory._links['base.module.other'] = ('http://tm.tld', 'some.html')
system.intersphinx = inventory
target = model.Module(system, 'ignore-name', 'ignore-docstring')
sut = epydoc2stan._EpydocLinker(target)
result = sut.translate_identifier_xref('base.module.other',
'base.module.pretty')
expected = (
'<a href="http://tm.tld/some.html"><code>base.module.pretty</code></a>'
)
assert expected == flatten(result)
def test_generateContent():
"""
Return a string with inventory for all targeted objects, recursive.
"""
sut = sphinx.SphinxInventoryWriter(logger=object(),
project_name='project_name')
system = model.System()
root1 = model.Package(system, 'package1')
root2 = model.Package(system, 'package2')
child1 = model.Package(system, 'child1', parent=root2)
system.addObject(child1)
subjects = [root1, root2]
result = sut._generateContent(subjects)
expected_result = (
b'package1 py:module -1 package1.html -\n'
b'package2 py:module -1 package2.html -\n'
b'package2.child1 py:module -1 package2.child1.html -\n')
assert expected_result == result