def describe(value):
if value == u"":
return u"(empty string)"
if value is None:
return u"(no value)"
return html.code(unicode(value))
def rowsForNamespaces(namespaces):
for namespace in namespaces:
if namespace is None:
name = u"(default)"
else:
name = html.code(namespace)
value = html.code(
Logger.publisher.levels.logLevelForNamespace(
namespace
).name
)
yield tag.clone().fillSlots(
log_level_name=name,
log_level_value=value,
)
def packageInitTable(self):
init = self.ob.contents["__init__"]
children = sorted(
[o for o in init.orderedcontents if o.isVisible], key=lambda o2: (-o2.privacyClass, o2.fullName())
)
if children:
return [
tags.p("From the ", tags.code("__init__.py"), " module:", class_="fromInitPy"),
ChildTable(self.docgetter, init, children),
]
else:
return ()
def namespace(self, obj: model.Documentable) -> List[Union[Tag, str]]:
page_url = self.page_url
parts: List[Union[Tag, str]] = []
ob: Optional[model.Documentable] = obj
while ob:
if ob.documentation_location is model.DocLocation.OWN_PAGE:
if parts:
parts.extend(['.', tags.wbr])
parts.append(
tags.code(epydoc2stan.taglink(ob, page_url, ob.name)))
ob = ob.parent
parts.reverse()
return parts
def visit_title_reference(self, node):
m = _TARGET_RE.match(node.astext())
if m: text, target = m.groups()
else: target = text = node.astext()
label = tags.code(text)
try:
url = self._linker.resolve_identifier_xref(target)
except LookupError:
xref = label
else:
xref = tags.a(label, href=url)
self.body.append(flatten(xref))
raise SkipNode()
def link_xref(self, target: str, label: str, lineno: int) -> Tag:
xref: Union[Tag, str]
try:
resolved = self._resolve_identifier_xref(target, lineno)
except LookupError:
xref = label
else:
if isinstance(resolved, model.Documentable):
xref = taglink(resolved, self.obj.page_object.url, label)
else:
xref = tags.a(label, href=resolved)
ret: Tag = tags.code(xref)
return ret
def functionExtras(self, ob: model.Documentable) -> List["Flattenable"]:
imeth = self.interfaceMeth(ob.name)
r: List["Flattenable"] = []
if imeth:
iface = imeth.parent
assert iface is not None
r.append(
tags.div(class_="interfaceinfo")('from ',
tags.code(
epydoc2stan.taglink(
imeth, self.page_url,
iface.fullName()))))
r.extend(super().functionExtras(ob))
return r
def packageInitTable(self):
init = self.ob.contents['__init__']
children = sorted([o for o in init.orderedcontents if o.isVisible],
key=lambda o2: (-o2.privacyClass, o2.fullName()))
if children:
return [
tags.p("From the ",
tags.code("__init__.py"),
" module:",
class_="fromInitPy"),
ChildTable(self.docgetter, init, children)
]
else:
return ()
def stuff(self, request, tag):
t = tag
anchors = set()
for b, o in findRootClasses(self.system):
if isinstance(o, model.Class):
t(subclassesFrom(self.system, o, anchors))
else:
item = tags.li(tags.code(b))
if o:
ul = tags.ul()
for sc in sorted(o, key=_lckey):
ul(subclassesFrom(self.system, sc, anchors))
item(ul)
t(item)
return t
def packageInitTable(self) -> "Flattenable":
children = sorted((o for o in self.ob.contents.values()
if not isinstance(o, model.Module) and o.isVisible),
key=objects_order)
if children:
loader = ChildTable.lookup_loader(self.template_lookup)
return [
tags.p("From ",
tags.code("__init__.py"),
":",
class_="fromInitPy"),
ChildTable(self.docgetter, self.ob, children, loader)
]
else:
return ()
def part(self):
if self.ob.parent:
parent = self.ob.parent
if isinstance(parent, model.Module) and parent.name == "__init__":
parent = parent.parent
parts = []
while parent.parent:
parts.append(taglink(parent, parent.name))
parts.append(".")
parent = parent.parent
parts.append(taglink(parent, parent.name))
parts.reverse()
return "Part of ", tags.code(parts)
else:
return []
def stuff(self, request, tag):
t = tag
anchors = set()
for b, o in findRootClasses(self.system):
if isinstance(o, model.Class):
t(subclassesFrom(self.system, o, anchors))
else:
item = tags.li(tags.code(b))
if o:
ul = tags.ul()
for sc in sorted(o, key=_lckey):
ul(subclassesFrom(self.system, sc, anchors))
item(ul)
t(item)
return t
def part(self):
if self.ob.parent:
parent = self.ob.parent
if isinstance(parent, model.Module) and parent.name == '__init__':
parent = parent.parent
parts = []
while parent.parent:
parts.append(util.taglink(parent, parent.name))
parts.append('.')
parent = parent.parent
parts.append(util.taglink(parent, parent.name))
parts.reverse()
return 'Part of ', tags.code(parts)
else:
return []
def visit_title_reference(self, node: Node) -> None:
m = _TARGET_RE.match(node.astext())
if m: text, target = m.groups()
else: target = text = node.astext()
label = tags.code(text)
# TODO: 'node.line' is None for some reason.
# https://github.com/twisted/pydoctor/issues/237
lineno = 0
try:
url = self._linker.resolve_identifier_xref(target, lineno)
except LookupError:
xref = label
else:
xref = tags.a(label, href=url)
self.body.append(flatten(xref))
raise SkipNode()
def packageInitTable(self):
init = self.ob.contents['__init__']
children = sorted([o for o in init.contents.values() if o.isVisible],
key=lambda o2:
(-o2.privacyClass.value, o2.fullName()))
if children:
loader = ChildTable.lookup_loader(self.template_lookup)
return [
tags.p("From the ",
tags.code("__init__.py"),
" module:",
class_="fromInitPy"),
ChildTable(self.docgetter, init, children, loader)
]
else:
return ()
def moduleSummary(modorpack, page_url):
r = tags.li(tags.code(epydoc2stan.taglink(modorpack, page_url)), ' - ',
epydoc2stan.format_summary(modorpack))
if modorpack.isPrivate:
r(class_='private')
if not isinstance(modorpack, model.Package):
return r
contents = [
m for m in modorpack.contents.values()
if m.isVisible and m.name != '__init__'
]
if not contents:
return r
ul = tags.ul()
for m in sorted(contents, key=lambda m: m.fullName()):
ul(moduleSummary(m, page_url))
return r(ul)
def subclassesFrom(hostsystem, cls, anchors, page_url):
r = tags.li()
if isClassNodePrivate(cls):
r(class_='private')
name = cls.fullName()
if name not in anchors:
r(tags.a(name=name))
anchors.add(name)
r(tags.code(epydoc2stan.taglink(cls, page_url)), ' - ',
epydoc2stan.format_summary(cls))
scs = [sc for sc in cls.subclasses if sc.system is hostsystem and ' ' not in sc.fullName()
and sc.isVisible]
if len(scs) > 0:
ul = tags.ul()
for sc in sorted(scs, key=_lckey):
ul(subclassesFrom(hostsystem, sc, anchors, page_url))
r(ul)
return r
def stuff(self, request: object, tag: Tag) -> Tag:
t = tag
anchors: MutableSet[str] = set()
for b, o in findRootClasses(self.system):
if isinstance(o, model.Class):
t(subclassesFrom(self.system, o, anchors, self.filename))
else:
item = tags.li(tags.code(b))
if all(isClassNodePrivate(sc) for sc in o):
# This is an external class used only by private API;
# mark the whole node private.
item(class_='private')
if o:
ul = tags.ul()
for sc in sorted(o, key=_lckey):
ul(subclassesFrom(self.system, sc, anchors, self.filename))
item(ul)
t(item)
return t
def moduleSummary(module: model.Module, page_url: str) -> Tag:
r: Tag = tags.li(
tags.code(epydoc2stan.taglink(module, page_url)), ' - ',
epydoc2stan.format_summary(module)
)
if module.isPrivate:
r(class_='private')
if not isinstance(module, model.Package):
return r
contents = [m for m in module.contents.values()
if isinstance(m, model.Module) and m.isVisible]
if not contents:
return r
ul = tags.ul()
def fullName(obj: model.Documentable) -> str:
return obj.fullName()
for m in sorted(contents, key=fullName):
ul(moduleSummary(m, page_url))
r(ul)
return r
def extras(self):
r = super().extras()
sourceHref = util.srclink(self.ob)
if sourceHref:
source = (" ", tags.a("(source)", href=sourceHref))
else:
source = tags.transparent
r.append(tags.p(tags.code(
tags.span("class", class_='py-keyword'), " ",
self.mediumName(self.ob), ":", source
)))
scs = sorted(self.ob.subclasses, key=lambda o:o.fullName().lower())
if not scs:
return r
p = assembleList(self.ob.system, "Known subclasses: ",
[o.fullName() for o in scs], "moreSubclasses")
if p is not None:
r.append(tags.p(p))
return r
def functionExtras(self, ob: model.Documentable) -> List["Flattenable"]:
page_url = self.page_url
name = ob.name
r: List["Flattenable"] = []
for b in self.ob.allbases(include_self=False):
if name not in b.contents:
continue
overridden = b.contents[name]
r.append(
tags.div(class_="interfaceinfo")(
'overrides ',
tags.code(epydoc2stan.taglink(overridden, page_url))))
break
ocs = sorted(overriding_subclasses(self.ob, name), key=objects_order)
if ocs:
self.overridenInCount += 1
idbase = 'overridenIn' + str(self.overridenInCount)
l = assembleList(self.ob.system, 'overridden in ',
[o.fullName() for o in ocs], idbase,
self.page_url)
if l is not None:
r.append(tags.div(class_="interfaceinfo")(l))
return r
def functionExtras(self, data):
page_url = self.page_url
r = []
for b in self.ob.allbases(include_self=False):
if data.name not in b.contents:
continue
overridden = b.contents[data.name]
r.append(
tags.div(class_="interfaceinfo")(
'overrides ',
tags.code(epydoc2stan.taglink(overridden, page_url))))
break
ocs = sorted(overriding_subclasses(self.ob, data.name),
key=lambda o: o.fullName().lower())
if ocs:
self.overridenInCount += 1
idbase = 'overridenIn' + str(self.overridenInCount)
l = assembleList(self.ob.system, 'overridden in ',
[o.fullName() for o in ocs], idbase,
self.page_url)
if l is not None:
r.append(tags.div(class_="interfaceinfo")(l))
return r
def heading(self):
return tags.h1(class_=util.css_class(self.ob))(tags.code(
self.namespace(self.ob)))
def heading(self):
return tags.h1(class_=self.ob.css_class)(
tags.code(self.mediumName(self.ob)),
" ",
tags.small(self.ob.kind.lower(), " documentation"),
)
def part(self):
parent = self.ob.parent
if parent:
return 'Part of ', tags.code(self.namespace(parent))
else:
return []
def to_stan(self, docstring_linker):
src = astor.to_source(self.annotation).strip()
return tags.code(src)
def roots(self, request, tag):
r = []
for o in self.system.rootobjects:
r.append(tag.clone().fillSlots(
root=tags.code(epydoc2stan.taglink(o, self.filename))))
return r
def one(item: str) -> "Flattenable":
if item in system.allobjects:
return tags.code(
epydoc2stan.taglink(system.allobjects[item], page_url))
else:
return item
def heading(self):
return tags.h1(class_=self.ob.css_class)(
tags.code(self.mediumName(self.ob)), " ", tags.small(self.ob.kind.lower(), " documentation")
)
def format(self) -> Iterator[Tag]:
yield tags.td(tags.code(self.type), class_="fieldArgContainer")
yield tags.td(self.body or self._UNDOCUMENTED)
def one(item):
if item in system.allobjects:
return tags.code(
epydoc2stan.taglink(system.allobjects[item], page_url))
else:
return item
def link_xref(self, target: str, label: str, lineno: int) -> Tag:
return tags.code(label)
def link_xref(self, target: str, label: str, lineno: int) -> Tag:
return tags.code(label) # type: ignore[no-any-return]
def name(self, request, tag):
return tag.clear()(tags.code(
epydoc2stan.taglink(self.child, self.ob.url, self.child.name)
))
def to_stan(self, docstring_linker: DocstringLinker) -> Tag:
return tags.code(
_AnnotationFormatter(docstring_linker).visit(self.annotation))
def translate_identifier_xref(self, fullID, prettyID):
"""Figure out what ``L{fullID}`` should link to.
There is a lot of DWIM here. The order goes:
1. Check if fullID refers to an object by Python name resolution in
our context.
2. Walk up the object tree and see if fullID refers to an object by
Python name resolution in each context.
3. Check if fullID is the fullName of an object.
4. Check to see if fullID names a builtin or standard library
module.
4. Walk up the object tree again and see if fullID refers to an
object in an "uncle" object. (So if p.m1 has a class C, the
docstring for p.m2 can say L{C} to refer to the class in m1). If
at any level fullID refers to more than one object, complain.
5. Examine every module and package in the system and see if fullID
names an object in each one. Again, if more than one object is
found, complain.
"""
src = self.obj
while src is not None:
target = src.resolveName(fullID)
if target is not None:
return self._objLink(target, prettyID)
src = src.parent
target = self.obj.system.objForFullName(fullID)
if target is not None:
return self._objLink(target, prettyID)
fullerID = self.obj.expandName(fullID)
linktext = stdlib_doc_link_for_name(fullerID)
if linktext is not None:
return tags.a(tags.code(prettyID), href=linktext)
src = self.obj
while src is not None:
target = self.look_for_name(fullID, src.contents.values())
if target is not None:
return self._objLink(target, prettyID)
src = src.parent
target = self.look_for_name(fullID, itertools.chain(
self.obj.system.objectsOfType(model.Module),
self.obj.system.objectsOfType(model.Package)))
if target is not None:
return self._objLink(target, prettyID)
target = self.look_for_intersphinx(fullerID)
if not target:
# FIXME: https://github.com/twisted/pydoctor/issues/125
# expandName is unreliable so in the case fullerID fails, we
# try our luck with fullID.
target = self.look_for_intersphinx(fullID)
if target:
return tags.a(tags.code(prettyID), href=target)
if fullID != fullerID:
self.obj.system.msg(
"translate_identifier_xref", "%s:%s invalid ref to '%s' "
"resolved as '%s'" % (
self.obj.fullName(), self.obj.linenumber, fullID, fullerID),
thresh=-1)
return tags.code(prettyID)