Mini Shell

# -*- test-case-name: twisted.python.test.test_pydoctor -*-
# Copyright (c) Twisted Matrix Laboratories.
# See LICENSE for details.

"""
Support for a few things specific to documenting Twisted using pydoctor.

FIXME: https://github.com/twisted/pydoctor/issues/106
This documentation does not link to pydoctor API as there is no public API yet.
"""

import ast
from typing import Optional

from pydoctor import astbuilder, model, zopeinterface  # type: ignore[import]
from pydoctor.sphinx import SphinxInventory  # type: ignore[import]


class TwistedSphinxInventory(SphinxInventory):
    """
    Custom SphinxInventory to work around broken external references to
    Sphinx.

    All exceptions should be reported upstream and a comment should be created
    with a link to the upstream report.
    """

    def getLink(self, name):
        """
        Resolve the full URL for a cross reference.

        @param name: Value of the cross reference.
        @type name: L{str}

        @return: A full URL for the I{name} reference or L{None} if no link was
            found.
        @rtype: L{str} or L{None}
        """
        result = super().getLink(name)
        if result is not None:
            # We already got a link. Look no further.
            return result

        if name.startswith("zope.interface."):
            # This is a link from zope.interface. which is not advertised in
            # the Sphinx inventory.
            # See if the link is a known broken link which should be handled
            # as an exceptional case.
            # We get the base URL from IInterface which is assume that is
            # always and already well defined in the Sphinx index.
            baseURL, _ = self._links.get(
                "zope.interface.interfaces.IInterface", (None, None)
            )

            if baseURL is None:
                # Most probably the zope.interface inventory was
                # not loaded.
                return None

            if name == "zope.interface.adapter.AdapterRegistry":
                # FIXME:
                # https://github.com/zopefoundation/zope.interface/issues/41
                relativeLink: Optional[str] = "adapter.html"
            else:
                # Not a known exception.
                relativeLink = None

            if relativeLink is None:
                return None

            return f"{baseURL}/{relativeLink}"

        return None


def getDeprecated(self, decorators):
    """
    With a list of decorators, and the object it is running on, set the
    C{_deprecated_info} flag if any of the decorators are a Twisted deprecation
    decorator.
    """
    for a in decorators:
        if isinstance(a, ast.Call):
            fn = astbuilder.node2fullname(a.func, self)

            if fn in (
                "twisted.python.deprecate.deprecated",
                "twisted.python.deprecate.deprecatedProperty",
            ):
                try:
                    self._deprecated_info = deprecatedToUsefulText(self, self.name, a)
                except AttributeError:
                    # It's a reference or something that we can't figure out
                    # from the AST.
                    pass


class TwistedModuleVisitor(zopeinterface.ZopeInterfaceModuleVisitor):
    def visit_ClassDef(self, node):
        """
        Called when a class definition is visited.
        """
        super().visit_ClassDef(node)
        try:
            cls = self.builder.current.contents[node.name]
        except KeyError:
            # Classes inside functions are ignored.
            return

        getDeprecated(cls, cls.raw_decorators)

    def visit_FunctionDef(self, node):
        """
        Called when a function definition is visited.
        """
        super().visit_FunctionDef(node)
        try:
            func = self.builder.current.contents[node.name]
        except KeyError:
            # Inner functions are ignored.
            return

        if func.decorators:
            getDeprecated(func, func.decorators)


def versionToUsefulObject(version):
    """
    Change an AST C{Version()} to a real one.
    """
    from incremental import Version

    package = version.args[0].s
    major = getattr(version.args[1], "n", getattr(version.args[1], "s", None))
    assert isinstance(major, int) or major == "NEXT"
    return Version(package, major, *(x.n for x in version.args[2:] if x))


def deprecatedToUsefulText(visitor, name, deprecated):
    """
    Change a C{@deprecated} to a display string.
    """
    from twisted.python.deprecate import _getDeprecationWarningString

    version = versionToUsefulObject(deprecated.args[0])
    if len(deprecated.args) > 1 and deprecated.args[1]:
        if isinstance(deprecated.args[1], ast.Name):
            replacement = visitor.resolveName(deprecated.args[1].id)
        else:
            replacement = deprecated.args[1].s
    else:
        replacement = None
        for keyword in deprecated.keywords:
            if keyword.arg == "replacement":
                replacement = keyword.value.s

    return _getDeprecationWarningString(name, version, replacement=replacement) + "."


class TwistedASTBuilder(zopeinterface.ZopeInterfaceASTBuilder):
    # Vistor is not a typo...
    ModuleVistor = TwistedModuleVisitor


class TwistedSystem(zopeinterface.ZopeInterfaceSystem):
    """
    A PyDoctor "system" used to generate the docs.
    """

    defaultBuilder = TwistedASTBuilder

    def __init__(self, options=None):
        super().__init__(options=options)
        # Use custom SphinxInventory so that we can resolve valid L{} markup
        # for which the Sphinx inventory is not published or broken.
        self.intersphinx = TwistedSphinxInventory(
            logger=self.msg, project_name=self.projectname
        )

    def privacyClass(self, documentable):
        """
        Report the privacy level for an object.

        Hide all tests with the exception of L{twisted.test.proto_helpers}.

        param obj: Object for which the privacy is reported.
        type obj: C{model.Documentable}

        rtype: C{model.PrivacyClass} member
        """
        if documentable.fullName() == "twisted.test":
            # Match this package exactly, so that proto_helpers
            # below is visible
            return model.PrivacyClass.VISIBLE

        current = documentable
        while current:
            if current.fullName() == "twisted.test.proto_helpers":
                return model.PrivacyClass.VISIBLE
            if isinstance(current, model.Package) and current.name == "test":
                return model.PrivacyClass.HIDDEN
            current = current.parent

        return super().privacyClass(documentable)