def test_subclass_with_same_name():
src = '''
class A:
pass
class A(A):
pass
'''
fromText(src, 'zi', systemcls=ZopeInterfaceSystem)
def test_multiple_types():
mod = fromText('''
def f(a):
"""
@param a: it\'s a parameter!
@type a: a pink thing!
@type a: no, blue! aaaargh!
"""
class C(object):
"""
@ivar a: it\'s an instance var
@type a: a pink thing!
@type a: no, blue! aaaargh!
"""
class D(object):
"""
@cvar a: it\'s an instance var
@type a: a pink thing!
@type a: no, blue! aaaargh!
"""
''')
# basically "assert not fail":
epydoc2stan.doc2stan(mod.contents['f'])
epydoc2stan.doc2stan(mod.contents['C'])
epydoc2stan.doc2stan(mod.contents['D'])
def implements_test(src):
mod = fromText(src, 'zi', systemcls=ZopeInterfaceSystem)
ifoo = mod.contents['IFoo']
ibar = mod.contents['IBar']
foo = mod.contents['Foo']
foobar = mod.contents['FooBar']
onlybar = mod.contents['OnlyBar']
assert ifoo.isinterface and ibar.isinterface
assert not foo.isinterface and not foobar.isinterface and not foobar.isinterface
assert not foo.implementsOnly and not foobar.implementsOnly
assert onlybar.implementsOnly
assert foo.implements_directly == ['zi.IFoo']
assert foo.allImplementedInterfaces == ['zi.IFoo']
assert foobar.implements_directly == ['zi.IBar']
assert foobar.allImplementedInterfaces == ['zi.IBar', 'zi.IFoo']
assert onlybar.implements_directly == ['zi.IBar']
assert onlybar.allImplementedInterfaces == ['zi.IBar']
assert ifoo.implementedby_directly == [foo]
assert ifoo.allImplementations == [foo, foobar]
assert ibar.implementedby_directly == [foobar, onlybar]
assert ibar.allImplementations == [foobar, onlybar]
def test_attribute():
src = '''
import zope.interface as zi
class C:
attr = zi.Attribute("docstring")
'''
mod = fromText(src, systemcls=ZopeInterfaceSystem)
assert len(mod.contents['C'].contents) == 1
def test_simple():
src = '''
def f():
"""This is a docstring."""
'''
mod = fromText(src)
v = getHTMLOf(mod.contents['f'])
assert 'This is a docstring' in v
def test_simple():
m = fromText('''
"""This is a docstring!"""
class C:
pass
''', modname="mod")
root = server.PyDoctorResource(m.system)
assert 'This is a docstring!' in getTextOfPage(root, 'mod.html')
def test_warnerproofing():
src = '''
from zope import interface
Interface = interface.Interface
class IMyInterface(Interface):
pass
'''
mod = fromText(src, systemcls=ZopeInterfaceSystem)
assert mod.contents['IMyInterface'].isinterface
def test_zopeschema():
src = '''
from zope import schema, interface
class IMyInterface(interface.Interface):
text = schema.TextLine(description="fun in a bun")
'''
mod = fromText(src, systemcls=ZopeInterfaceSystem)
text = mod.contents['IMyInterface'].contents['text']
assert text.docstring == 'fun in a bun'
assert text.kind == "TextLine"
def test_rest_support():
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_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_multiply_inheriting_interfaces():
src = '''
from zope.interface import Interface, implements
class IOne(Interface): pass
class ITwo(Interface): pass
class One: implements(IOne)
class Two: implements(ITwo)
class Both(One, Two): pass
'''
mod = fromText(src, 'zi', systemcls=ZopeInterfaceSystem)
assert len(mod.contents['Both'].allImplementedInterfaces) == 2
def test_with_underscore():
src = '''
from zope import schema, interface
class IMyInterface(interface.Interface):
attribute = interface.Attribute(_("fun in a bun"))
text = schema.TextLine(description=_("fun in a bap"))
'''
mod = fromText(src, systemcls=ZopeInterfaceSystem)
text = mod.contents['IMyInterface'].contents['attribute']
assert text.docstring == 'fun in a bun'
assert text.kind == "Attribute"
text = mod.contents['IMyInterface'].contents['text']
assert text.docstring == 'fun in a bap'
assert text.kind == "TextLine"
def test_docsources_includes_interface():
src = '''
from zope import interface
class IInterface(interface.Interface):
def method(self):
"""documentation"""
class Implementation:
interface.implements(IInterface)
def method(self):
pass
'''
mod = fromText(src, systemcls=ZopeInterfaceSystem)
imethod = mod.contents['IInterface'].contents['method']
method = mod.contents['Implementation'].contents['method']
assert imethod in method.docsources(), list(method.docsources())
def test_docsources_from_moduleprovides():
src = '''
from zope import interface
class IBase(interface.Interface):
def bar():
"""documentation"""
interface.moduleProvides(IBase)
def bar():
pass
'''
mod = fromText(src, systemcls=ZopeInterfaceSystem)
imethod = mod.contents['IBase'].contents['bar']
function = mod.contents['bar']
assert imethod in function.docsources(), list(function.docsources())
def test_constructor_param_on_class(capsys: CapSys) -> None:
"""Constructor parameters can be documented on the class."""
mod = fromText('''
class C:
"""
@param p: Constructor parameter.
@param q: Not a constructor parameter.
"""
def __init__(self, p):
pass
''')
html = docstring2html(mod.contents['C']).split('\n')
assert '<td class="fieldArgDesc">Constructor parameter.</td>' in html
# Non-existing parameters should still end up in the output, because:
# - pydoctor might be wrong about them not existing
# - the documentation may still be useful, for example if belongs to
# an existing parameter but the name in the @param field has a typo
assert '<td class="fieldArgDesc">Not a constructor parameter.</td>' in html
captured = capsys.readouterr().out
assert captured == '<test>:5: Documented parameter "q" does not exist\n'
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_func_undocumented_return_something() -> None:
"""When the returned value is undocumented (no 'return' field) and its type
annotation is not None, include the "Returns" entry in the output.
"""
mod = fromText('''
def get_answer() -> int:
return 42
''')
func = mod.contents['get_answer']
lines = docstring2html(func).splitlines()
expected_html = [
'<div>', '<p class="undocumented">Undocumented</p>',
'<table class="fieldTable">', '<tr class="fieldStart">',
'<td class="fieldName" colspan="2">Returns</td>', '</tr>', '<tr>',
'<td class="fieldArgContainer">', '<code>int</code>', '</td>',
'<td class="fieldArgDesc">',
'<span class="undocumented">Undocumented</span>', '</td>', '</tr>',
'</table>', '</div>'
]
assert lines == expected_html, str(lines)
def test_implementer_plainclass(capsys: CapSys) -> None:
"""
Check patching of non-interface classes passed to @implementer.
"""
src = '''
from zope.interface import Interface, implementer
class C:
pass
@implementer(C)
class Implementation:
pass
'''
mod = fromText(src, modname='mod', systemcls=ZopeInterfaceSystem)
C = mod.contents['C']
impl = mod.contents['Implementation']
assert C.isinterface
assert C.kind == "Interface"
assert C.implementedby_directly == [impl]
assert impl.implements_directly == ['mod.C']
captured = capsys.readouterr().out
assert captured == "mod:5: probable interface mod.C not marked as such\n"
def test_implementer_plainclass(capsys: CapSys) -> None:
"""
A non-interface class passed to @implementer will be warned about but
will be stored as an implemented interface.
"""
src = '''
from zope.interface import implementer
class C:
pass
@implementer(C)
class Implementation:
pass
'''
mod = fromText(src, modname='mod', systemcls=ZopeInterfaceSystem)
C = mod.contents['C']
impl = mod.contents['Implementation']
assert not C.isinterface
assert C.kind is model.DocumentableKind.CLASS
assert impl.implements_directly == ['mod.C']
captured = capsys.readouterr().out
assert captured == 'mod:5: Class "mod.C" is not an interface\n'
def test_zopeschema_inheritance():
src = '''
from zope import schema, interface
from zope.schema import Int as INTEGERSCHMEMAFIELD
class MyTextLine(schema.TextLine):
pass
class MyOtherTextLine(MyTextLine):
pass
class IMyInterface(interface.Interface):
mytext = MyTextLine(description="fun in a bun")
myothertext = MyOtherTextLine(description="fun in another bun")
myint = INTEGERSCHMEMAFIELD(description="not as much fun")
'''
mod = fromText(src, systemcls=ZopeInterfaceSystem)
mytext = mod.contents['IMyInterface'].contents['mytext']
assert mytext.docstring == 'fun in a bun'
assert mytext.kind == "MyTextLine"
myothertext = mod.contents['IMyInterface'].contents['myothertext']
assert myothertext.docstring == 'fun in another bun'
assert myothertext.kind == "MyOtherTextLine"
myint = mod.contents['IMyInterface'].contents['myint']
assert myint.kind == "Int"
def test_zopeschema_inheritance() -> None:
src = '''
from zope import schema, interface
from zope.schema import Int as INTEGERSCHMEMAFIELD
class MyTextLine(schema.TextLine):
pass
class MyOtherTextLine(MyTextLine):
pass
class IMyInterface(interface.Interface):
mytext = MyTextLine(description="fun in a bun")
myothertext = MyOtherTextLine(description="fun in another bun")
myint = INTEGERSCHMEMAFIELD(description="not as much fun")
'''
mod = fromText(src, systemcls=ZopeInterfaceSystem)
mytext = mod.contents['IMyInterface'].contents['mytext']
assert mytext.docstring == 'fun in a bun'
assert mytext.kind == "MyTextLine"
myothertext = mod.contents['IMyInterface'].contents['myothertext']
assert myothertext.docstring == 'fun in another bun'
assert myothertext.kind == "MyOtherTextLine"
myint = mod.contents['IMyInterface'].contents['myint']
assert myint.kind == "Int"
def test_summary():
mod = fromText('''
def single_line_summary():
"""
Lorem Ipsum
Ipsum Lorem
"""
def no_summary():
"""
Foo
Bar
Baz
Qux
"""
def three_lines_summary():
"""
Foo
Bar
Baz
Lorem Ipsum
"""
''')
def get_summary(func):
def part_flat(x):
if isinstance(x, list):
return "".join(map(part_flat, x))
else:
return x
return part_flat(
epydoc2stan.doc2stan(mod.contents[func], summary=True)[0].children)
assert u"Lorem Ipsum" == get_summary("single_line_summary")
assert u"Foo Bar Baz" == get_summary("three_lines_summary")
assert u"No summary" == get_summary("no_summary")
def implements_test(src: str) -> None:
mod = fromText(src, modname='zi', systemcls=ZopeInterfaceSystem)
ifoo = mod.contents['IFoo']
ibar = mod.contents['IBar']
foo = mod.contents['Foo']
foobar = mod.contents['FooBar']
onlybar = mod.contents['OnlyBar']
assert ifoo.isinterface and ibar.isinterface
assert not foo.isinterface and not foobar.isinterface and not foobar.isinterface
assert not foo.implementsOnly and not foobar.implementsOnly
assert onlybar.implementsOnly
assert foo.implements_directly == ['zi.IFoo']
assert foo.allImplementedInterfaces == ['zi.IFoo']
assert foobar.implements_directly == ['zi.IBar']
assert foobar.allImplementedInterfaces == ['zi.IBar', 'zi.IFoo']
assert onlybar.implements_directly == ['zi.IBar']
assert onlybar.allImplementedInterfaces == ['zi.IBar']
assert ifoo.implementedby_directly == [foo]
assert ibar.implementedby_directly == [foobar, onlybar]
def test_zopeschema(capsys: CapSys) -> None:
src = '''
from zope import schema, interface
class IMyInterface(interface.Interface):
text = schema.TextLine(description="fun in a bun")
undoc = schema.Bool()
bad = schema.ASCII(description=False)
'''
mod = fromText(src, modname='mod', systemcls=ZopeInterfaceSystem)
text = mod.contents['IMyInterface'].contents['text']
assert text.docstring == 'fun in a bun'
assert type2html(text)== "<code>schema.TextLine</code>"
assert text.kind is model.DocumentableKind.SCHEMA_FIELD
undoc = mod.contents['IMyInterface'].contents['undoc']
assert undoc.docstring is None
assert type2html(undoc) == "<code>schema.Bool</code>"
assert undoc.kind is model.DocumentableKind.SCHEMA_FIELD
bad = mod.contents['IMyInterface'].contents['bad']
assert bad.docstring is None
assert type2html(bad) == "<code>schema.ASCII</code>"
assert bad.kind is model.DocumentableKind.SCHEMA_FIELD
captured = capsys.readouterr().out
assert captured == 'mod:6: description of field "bad" is not a string literal\n'
def test_annotation_formatter(annotation: str) -> None:
"""Perform two checks on the annotation formatter:
- all type names in the annotation are passed to the linker
- the plain text version of the output matches the input
"""
expected_lookups = [found[1:-1] for found in re.findall('<[^>]*>', annotation)]
expected_text = annotation.replace('<', '').replace('>', '')
mod = fromText(f'''
value: {expected_text}
''')
obj = mod.contents['value']
parsed = epydoc2stan.get_parsed_type(obj)
assert parsed is not None
linker = RecordingAnnotationLinker()
stan = parsed.to_stan(linker)
assert linker.requests == expected_lookups
html = flatten(stan)
assert html.startswith('<code>')
assert html.endswith('</code>')
text = html[6:-7]
assert text.replace('<wbr></wbr>', '').replace('<wbr>\n</wbr>', '') == expected_text
def test_summary():
mod = fromText('''
def single_line_summary():
"""
Lorem Ipsum
Ipsum Lorem
"""
def no_summary():
"""
Foo
Bar
Baz
Qux
"""
def three_lines_summary():
"""
Foo
Bar
Baz
Lorem Ipsum
"""
''')
def get_summary(func):
def part_flat(x):
if isinstance(x, list):
return ''.join(map(part_flat, x))
else:
return x
return part_flat(
epydoc2stan.doc2stan(
mod.contents[func],
summary=True)[0].children)
assert u'Lorem Ipsum' == get_summary('single_line_summary')
assert u'Foo Bar Baz' == get_summary('three_lines_summary')
assert u'No summary' == get_summary('no_summary')
def test_nonempty_table() -> None:
mod = fromText('def f(): pass')
t = pages.ChildTable(pages.DocGetter(), mod, mod.contents.values())
flattened = flatten(t)
assert 'The renderer named' not in flattened
def test_empty_table() -> None:
mod = fromText('')
t = pages.ChildTable(pages.DocGetter(), mod, [])
flattened = flatten(t)
assert 'The renderer named' not in flattened
def test_empty_table() -> None:
mod = fromText('')
t = ChildTable(pages.DocGetter(), mod, [],
ChildTable.lookup_loader(TemplateLookup()))
flattened = flatten(t)
assert 'The renderer named' not in flattened
def test_nonempty_table():
mod = fromText("def f(): pass")
t = pages.ChildTable(pages.DocGetter(), mod, mod.orderedcontents)
flattened = flatten(t)
assert "The renderer named" not in flattened
def test_pickling_system():
system = model.System()
fromText("class A: pass", "mod", system)
# not sure how to test this, other than that it doesn't fail...
pickle.loads(pickle.dumps(system))
def test_nonempty_table():
mod = fromText('def f(): pass')
t = pages.ChildTable(pages.DocGetter(), mod, True, mod.orderedcontents)
flattened = flatten(t)
assert 'The renderer named' not in flattened
def test_empty_table():
mod = fromText('')
t = pages.ChildTable(pages.DocGetter(), mod, True, [])
flattened = flatten(t)
assert 'The renderer named' not in flattened
def test_pickling_system():
system = model.System()
fromText("class A: pass", "mod", system)
# not sure how to test this, other than that it doesn't fail...
pickle.loads(pickle.dumps(system))
def test_empty_table():
mod = fromText("")
t = pages.ChildTable(pages.DocGetter(), mod, [])
flattened = flatten(t)
assert "The renderer named" not in flattened
def test_html_empty_module() -> None:
mod = fromText('''
"""Empty module."""
''')
assert docstring2html(mod) == "<div>\n<p>Empty module.</p>\n</div>"
