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_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>"