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_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_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_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_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_EpydocLinker_look_for_intersphinx_no_link():
"""
Return None if inventory had no link for our markup.
"""
system = model.System()
target = model.Module(system, 'ignore-name', 'ignore-docstring')
sut = epydoc2stan._EpydocLinker(target)
result = sut.look_for_intersphinx('base.module')
assert None is result
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_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_EpydocLinker_resolve_identifier_xref_order(capsys):
"""
Check that the best match is picked when there are multiple candidates.
"""
mod = fromText('''
class C:
socket = None
''')
linker = epydoc2stan._EpydocLinker(mod)
url = linker.resolve_identifier_xref('socket.socket')
assert epydoc2stan.STDLIB_URL + 'socket.html#socket.socket' == url
assert not capsys.readouterr().out
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_EpydocLinker_resolve_identifier_xref_order(capsys: CapSys) -> None:
"""
Check that the best match is picked when there are multiple candidates.
"""
mod = fromText('''
class C:
socket = None
''')
mod.system.intersphinx = cast(SphinxInventory, InMemoryInventory())
linker = epydoc2stan._EpydocLinker(mod)
url = linker.resolve_identifier('socket.socket')
url_xref = linker._resolve_identifier_xref('socket.socket', 0)
assert 'https://docs.python.org/3/library/socket.html#socket.socket' == url
assert 'https://docs.python.org/3/library/socket.html#socket.socket' == url_xref
assert not capsys.readouterr().out
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_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_resolve_identifier_xref_internal_full_name() -> None:
"""Link to an internal object referenced by its full name."""
# Object we want to link to.
int_mod = fromText('''
class C:
pass
''', modname='internal_module')
system = int_mod.system
# Dummy module that we want to link from.
target = model.Module(system, 'ignore-name')
sut = epydoc2stan._EpydocLinker(target)
url = sut.resolve_identifier('internal_module.C')
xref = sut._resolve_identifier_xref('internal_module.C', 0)
assert "internal_module.C.html" == url
assert int_mod.contents['C'] is xref
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)
