pdoc.doc

   1"""
   2This module defines pdoc's documentation objects. A documentation object corresponds to *something*
   3in your Python code that has a docstring or type annotation. Typically, this only includes
   4modules, classes, functions and methods. However, `pdoc` adds support for extracting documentation
   5from the abstract syntax tree, which means that variables (module, class or instance) are supported too.
   6
   7There are four main types of documentation objects:
   8
   9- `Module`
  10- `Class`
  11- `Function`
  12- `Variable`
  13
  14All documentation types make heavy use of `@functools.cached_property` decorators.
  15This means they have a large set of attributes that are lazily computed on first access.
  16By convention, all attributes are read-only, although this is not enforced at runtime.
  17"""
  18from __future__ import annotations
  19
  20import dataclasses
  21import enum
  22import inspect
  23import os
  24import pkgutil
  25import re
  26import sys
  27import textwrap
  28import traceback
  29import types
  30import warnings
  31from abc import ABCMeta
  32from abc import abstractmethod
  33from collections.abc import Callable
  34from functools import wraps
  35from pathlib import Path
  36from typing import Any
  37from typing import ClassVar
  38from typing import Generic
  39from typing import TypeVar
  40from typing import Union
  41
  42from ._compat import cache
  43from ._compat import cached_property
  44from ._compat import formatannotation
  45from ._compat import get_origin
  46from ._compat import singledispatchmethod
  47from pdoc import doc_ast
  48from pdoc import doc_pyi
  49from pdoc import extract
  50from pdoc.doc_types import empty
  51from pdoc.doc_types import GenericAlias
  52from pdoc.doc_types import NonUserDefinedCallables
  53from pdoc.doc_types import resolve_annotations
  54from pdoc.doc_types import safe_eval_type
  55
  56
  57def _include_fullname_in_traceback(f):
  58    """
  59    Doc.__repr__ should not raise, but it may raise if we screwed up.
  60    Debugging this is a bit tricky, because, well, we can't repr() in the traceback either then.
  61    This decorator adds location information to the traceback, which helps tracking down bugs.
  62    """
  63
  64    @wraps(f)
  65    def wrapper(self):
  66        try:
  67            return f(self)
  68        except Exception as e:
  69            raise RuntimeError(f"Error in {self.fullname}'s repr!") from e
  70
  71    return wrapper
  72
  73
  74T = TypeVar("T")
  75
  76
  77class Doc(Generic[T]):
  78    """
  79    A base class for all documentation objects.
  80    """
  81
  82    modulename: str
  83    """
  84    The module that this object is in, for example `pdoc.doc`.
  85    """
  86
  87    qualname: str
  88    """
  89    The qualified identifier name for this object. For example, if we have the following code:
  90    
  91    ```python
  92    class Foo:
  93        def bar(self):
  94            pass
  95    ```
  96    
  97    The qualname of `Foo`'s `bar` method is `Foo.bar`. The qualname of the `Foo` class is just `Foo`.
  98    
  99    See <https://www.python.org/dev/peps/pep-3155/> for details.
 100    """
 101
 102    obj: T
 103    """
 104    The underlying Python object.
 105    """
 106
 107    taken_from: tuple[str, str]
 108    """
 109    `(modulename, qualname)` of this doc object's original location.
 110    In the context of a module, this points to the location it was imported from,
 111    in the context of classes, this points to the class an attribute is inherited from.
 112    """
 113
 114    kind: ClassVar[str]
 115    """
 116    The type of the doc object, either `"module"`, `"class"`, `"function"`, or `"variable"`.
 117    """
 118
 119    @property
 120    def type(self) -> str:  # pragma: no cover
 121        warnings.warn(
 122            "pdoc.doc.Doc.type is deprecated. Use pdoc.doc.Doc.kind instead.",
 123            DeprecationWarning,
 124        )
 125        return self.kind
 126
 127    def __init__(
 128        self, modulename: str, qualname: str, obj: T, taken_from: tuple[str, str]
 129    ):
 130        """
 131        Initializes a documentation object, where
 132        `modulename` is the name this module is defined in,
 133        `qualname` contains a dotted path leading to the object from the module top-level, and
 134        `obj` is the object to document.
 135        """
 136        self.modulename = modulename
 137        self.qualname = qualname
 138        self.obj = obj
 139        self.taken_from = taken_from
 140
 141    @cached_property
 142    def fullname(self) -> str:
 143        """The full qualified name of this doc object, for example `pdoc.doc.Doc`."""
 144        # qualname is empty for modules
 145        return f"{self.modulename}.{self.qualname}".rstrip(".")
 146
 147    @cached_property
 148    def name(self) -> str:
 149        """The name of this object. For top-level functions and classes, this is equal to the qualname attribute."""
 150        return self.fullname.split(".")[-1]
 151
 152    @cached_property
 153    def docstring(self) -> str:
 154        """
 155        The docstring for this object. It has already been cleaned by `inspect.cleandoc`.
 156
 157        If no docstring can be found, an empty string is returned.
 158        """
 159        return _safe_getdoc(self.obj)
 160
 161    @cached_property
 162    def source(self) -> str:
 163        """
 164        The source code of the Python object as a `str`.
 165
 166        If the source cannot be obtained (for example, because we are dealing with a native C object),
 167        an empty string is returned.
 168        """
 169        return doc_ast.get_source(self.obj)
 170
 171    @cached_property
 172    def source_file(self) -> Path | None:
 173        """The name of the Python source file in which this object was defined. `None` for built-in objects."""
 174        try:
 175            return Path(inspect.getsourcefile(self.obj) or inspect.getfile(self.obj))  # type: ignore
 176        except TypeError:
 177            return None
 178
 179    @cached_property
 180    def source_lines(self) -> tuple[int, int] | None:
 181        """
 182        Return a `(start, end)` line number tuple for this object.
 183
 184        If no source file can be found, `None` is returned.
 185        """
 186        try:
 187            lines, start = inspect.getsourcelines(self.obj)  # type: ignore
 188            return start, start + len(lines) - 1
 189        except Exception:
 190            return None
 191
 192    @cached_property
 193    def is_inherited(self) -> bool:
 194        """
 195        If True, the doc object is inherited from another location.
 196        This most commonly refers to methods inherited by a subclass,
 197        but can also apply to variables that are assigned a class defined
 198        in a different module.
 199        """
 200        return (self.modulename, self.qualname) != self.taken_from
 201
 202    def __lt__(self, other):
 203        assert isinstance(other, Doc)
 204        return self.fullname.replace("__init__", "").__lt__(
 205            other.fullname.replace("__init__", "")
 206        )
 207
 208
 209class Namespace(Doc[T], metaclass=ABCMeta):
 210    """
 211    A documentation object that can have children. In other words, either a module or a class.
 212    """
 213
 214    @cached_property
 215    @abstractmethod
 216    def _member_objects(self) -> dict[str, Any]:
 217        """
 218        A mapping from *all* public and private member names to their Python objects.
 219        """
 220
 221    @cached_property
 222    @abstractmethod
 223    def _var_docstrings(self) -> dict[str, str]:
 224        """A mapping from some member variable names to their docstrings."""
 225
 226    @cached_property
 227    @abstractmethod
 228    def _var_annotations(self) -> dict[str, Any]:
 229        """A mapping from some member variable names to their type annotations."""
 230
 231    @abstractmethod
 232    def _taken_from(self, member_name: str, obj: Any) -> tuple[str, str]:
 233        """The location this member was taken from. If unknown, (modulename, qualname) is returned."""
 234
 235    @cached_property
 236    @abstractmethod
 237    def own_members(self) -> list[Doc]:
 238        """A list of all own (i.e. non-inherited) `members`."""
 239
 240    @cached_property
 241    def members(self) -> dict[str, Doc]:
 242        """A mapping from all members to their documentation objects.
 243
 244        This mapping includes private members; they are only filtered out as part of the template logic.
 245        Constructors for enums, dicts, and abstract base classes are not picked up unless they have a custom docstring.
 246        """
 247        members: dict[str, Doc] = {}
 248        for name, obj in self._member_objects.items():
 249            qualname = f"{self.qualname}.{name}".lstrip(".")
 250            taken_from = self._taken_from(name, obj)
 251            doc: Doc[Any]
 252
 253            is_classmethod = isinstance(obj, classmethod)
 254            is_property = (
 255                isinstance(obj, (property, cached_property))
 256                or
 257                # Python 3.9 - 3.10: @classmethod @property is allowed.
 258                is_classmethod
 259                and isinstance(obj.__func__, (property, cached_property))
 260            )
 261            if is_property:
 262                func = obj
 263                if is_classmethod:
 264                    func = obj.__func__
 265                if isinstance(func, property):
 266                    func = func.fget
 267                else:
 268                    assert isinstance(func, cached_property)
 269                    func = func.func
 270
 271                doc_f = Function(self.modulename, qualname, func, taken_from)
 272                doc = Variable(
 273                    self.modulename,
 274                    qualname,
 275                    docstring=doc_f.docstring,
 276                    annotation=doc_f.signature.return_annotation,
 277                    default_value=empty,
 278                    taken_from=taken_from,
 279                )
 280            elif inspect.isroutine(obj):
 281                doc = Function(self.modulename, qualname, obj, taken_from)  # type: ignore
 282            elif (
 283                inspect.isclass(obj)
 284                and obj is not empty
 285                and not isinstance(obj, GenericAlias)
 286                and obj.__qualname__.rpartition(".")[2] == qualname.rpartition(".")[2]
 287            ):
 288                # `dict[str,str]` is a GenericAlias instance. We want to render type aliases as variables though.
 289                doc = Class(self.modulename, qualname, obj, taken_from)
 290            elif inspect.ismodule(obj):
 291                if os.environ.get("PDOC_SUBMODULES"):  # pragma: no cover
 292                    doc = Module.from_name(obj.__name__)
 293                else:
 294                    continue
 295            elif inspect.isdatadescriptor(obj):
 296                doc = Variable(
 297                    self.modulename,
 298                    qualname,
 299                    docstring=getattr(obj, "__doc__", None) or "",
 300                    annotation=self._var_annotations.get(name, empty),
 301                    default_value=empty,
 302                    taken_from=taken_from,
 303                )
 304            else:
 305                doc = Variable(
 306                    self.modulename,
 307                    qualname,
 308                    docstring="",
 309                    annotation=self._var_annotations.get(name, empty),
 310                    default_value=obj,
 311                    taken_from=taken_from,
 312                )
 313            if self._var_docstrings.get(name):
 314                doc.docstring = self._var_docstrings[name]
 315            members[doc.name] = doc
 316
 317        if isinstance(self, Module):
 318            # quirk: doc_pyi expects .members to be set already
 319            self.members = members  # type: ignore
 320            doc_pyi.include_typeinfo_from_stub_files(self)
 321
 322        return members
 323
 324    @cached_property
 325    def _members_by_origin(self) -> dict[tuple[str, str], list[Doc]]:
 326        """A mapping from (modulename, qualname) locations to the attributes taken from that path"""
 327        locations: dict[tuple[str, str], list[Doc]] = {}
 328        for member in self.members.values():
 329            mod, qualname = member.taken_from
 330            parent_qualname = ".".join(qualname.rsplit(".", maxsplit=1)[:-1])
 331            locations.setdefault((mod, parent_qualname), [])
 332            locations[(mod, parent_qualname)].append(member)
 333        return locations
 334
 335    @cached_property
 336    def inherited_members(self) -> dict[tuple[str, str], list[Doc]]:
 337        """A mapping from (modulename, qualname) locations to the attributes inherited from that path"""
 338        return {
 339            k: v
 340            for k, v in self._members_by_origin.items()
 341            if k not in (self.taken_from, (self.modulename, self.qualname))
 342        }
 343
 344    @cached_property
 345    def flattened_own_members(self) -> list[Doc]:
 346        """
 347        A list of all documented members and their child classes, recursively.
 348        """
 349        flattened = []
 350        for x in self.own_members:
 351            flattened.append(x)
 352            if isinstance(x, Class):
 353                flattened.extend(
 354                    [cls for cls in x.flattened_own_members if isinstance(cls, Class)]
 355                )
 356        return flattened
 357
 358    @cache
 359    def get(self, identifier: str) -> Doc | None:
 360        """Returns the documentation object for a particular identifier, or `None` if the identifier cannot be found."""
 361        head, _, tail = identifier.partition(".")
 362        if tail:
 363            h = self.members.get(head, None)
 364            if isinstance(h, Class):
 365                return h.get(tail)
 366            return None
 367        else:
 368            return self.members.get(identifier, None)
 369
 370
 371class Module(Namespace[types.ModuleType]):
 372    """
 373    Representation of a module's documentation.
 374    """
 375
 376    def __init__(
 377        self,
 378        module: types.ModuleType,
 379    ):
 380        """
 381        Creates a documentation object given the actual
 382        Python module object.
 383        """
 384        super().__init__(module.__name__, "", module, (module.__name__, ""))
 385
 386    kind = "module"
 387
 388    @classmethod
 389    @cache
 390    def from_name(cls, name: str) -> Module:
 391        """Create a `Module` object by supplying the module's (full) name."""
 392        return cls(extract.load_module(name))
 393
 394    @cache
 395    @_include_fullname_in_traceback
 396    def __repr__(self):
 397        return f"<module {self.fullname}{_docstr(self)}{_children(self)}>"
 398
 399    @cached_property
 400    def is_package(self) -> bool:
 401        """
 402        `True` if the module is a package, `False` otherwise.
 403
 404        Packages are a special kind of module that may have submodules.
 405        Typically, this means that this file is in a directory named like the
 406        module with the name `__init__.py`.
 407        """
 408        return _safe_getattr(self.obj, "__path__", None) is not None
 409
 410    @cached_property
 411    def _var_docstrings(self) -> dict[str, str]:
 412        return doc_ast.walk_tree(self.obj).docstrings
 413
 414    @cached_property
 415    def _var_annotations(self) -> dict[str, Any]:
 416        annotations = doc_ast.walk_tree(self.obj).annotations.copy()
 417        for k, v in _safe_getattr(self.obj, "__annotations__", {}).items():
 418            annotations[k] = v
 419
 420        return resolve_annotations(annotations, self.obj, None, self.fullname)
 421
 422    def _taken_from(self, member_name: str, obj: Any) -> tuple[str, str]:
 423        if obj is empty:
 424            return self.modulename, f"{self.qualname}.{member_name}".lstrip(".")
 425        if isinstance(obj, types.ModuleType):
 426            return obj.__name__, ""
 427
 428        mod = _safe_getattr(obj, "__module__", None)
 429        qual = _safe_getattr(obj, "__qualname__", None)
 430        if mod and qual and "<locals>" not in qual:
 431            return mod, qual
 432        else:
 433            # This might be wrong, but it's the best guess we have.
 434            return (mod or self.modulename), f"{self.qualname}.{member_name}".lstrip(
 435                "."
 436            )
 437
 438    @cached_property
 439    def own_members(self) -> list[Doc]:
 440        return list(self.members.values())
 441
 442    @cached_property
 443    def submodules(self) -> list[Module]:
 444        """A list of all (direct) submodules."""
 445        if not self.is_package:
 446            return []
 447
 448        include: Callable[[str], bool]
 449        mod_all = _safe_getattr(self.obj, "__all__", False)
 450        if mod_all is not False:
 451            mod_all_pos = {name: i for i, name in enumerate(mod_all)}
 452            include = mod_all_pos.__contains__
 453        else:
 454
 455            def include(name: str) -> bool:
 456                # optimization: we don't even try to load modules starting with an underscore as they would not be
 457                # visible by default. The downside of this is that someone who overrides `is_public` will miss those
 458                # entries, the upsides are 1) better performance and 2) less warnings because of import failures
 459                # (think of OS-specific modules, e.g. _linux.py failing to import on Windows).
 460                return not name.startswith("_")
 461
 462        submodules = []
 463        for mod in pkgutil.iter_modules(self.obj.__path__, f"{self.fullname}."):
 464            _, _, mod_name = mod.name.rpartition(".")
 465            if not include(mod_name):
 466                continue
 467            try:
 468                module = Module.from_name(mod.name)
 469            except RuntimeError:
 470                warnings.warn(f"Couldn't import {mod.name}:\n{traceback.format_exc()}")
 471                continue
 472            submodules.append(module)
 473
 474        if mod_all:
 475            submodules = sorted(submodules, key=lambda m: mod_all_pos[m.name])
 476
 477        return submodules
 478
 479    @cached_property
 480    def _documented_members(self) -> set[str]:
 481        return self._var_docstrings.keys() | self._var_annotations.keys()
 482
 483    @cached_property
 484    def _member_objects(self) -> dict[str, Any]:
 485        members = {}
 486
 487        all_: list[str] | None = _safe_getattr(self.obj, "__all__", None)
 488        if all_ is not None:
 489            for name in all_:
 490                if not isinstance(name, str):
 491                    # Gracefully handle the case where objects are directly specified in __all__.
 492                    name = _safe_getattr(name, "__name__", str(name))
 493                if name in self.obj.__dict__:
 494                    val = self.obj.__dict__[name]
 495                elif name in self._var_annotations:
 496                    val = empty
 497                else:
 498                    # this may be an unimported submodule, try importing.
 499                    # (https://docs.python.org/3/tutorial/modules.html#importing-from-a-package)
 500                    try:
 501                        val = extract.load_module(f"{self.modulename}.{name}")
 502                    except RuntimeError as e:
 503                        warnings.warn(
 504                            f"Found {name!r} in {self.modulename}.__all__, but it does not resolve: {e}"
 505                        )
 506                        val = empty
 507                members[name] = val
 508
 509        else:
 510            # Starting with Python 3.10, __annotations__ is created on demand,
 511            # so we make a copy here as obj.__dict__ is changed while we iterate over it.
 512            # Additionally, accessing self._documented_members may lead to the execution of TYPE_CHECKING blocks,
 513            # which may also modify obj.__dict__. (https://github.com/mitmproxy/pdoc/issues/351)
 514            for name, obj in list(self.obj.__dict__.items()):
 515                # We already exclude everything here that is imported, only a TypeVar,
 516                # or a variable without annotation and docstring.
 517                # If one needs to document one of these things, __all__ is the correct way.
 518                obj_module = inspect.getmodule(obj)
 519                declared_in_this_module = self.obj.__name__ == _safe_getattr(
 520                    obj_module, "__name__", None
 521                )
 522                include_in_docs = name in self._documented_members or (
 523                    declared_in_this_module and not isinstance(obj, TypeVar)
 524                )
 525                if include_in_docs:
 526                    members[name] = obj
 527            for name in self._var_docstrings:
 528                members.setdefault(name, empty)
 529
 530            members, notfound = doc_ast.sort_by_source(self.obj, {}, members)
 531            members.update(notfound)
 532
 533        return members
 534
 535    @cached_property
 536    def variables(self) -> list[Variable]:
 537        """
 538        A list of all documented module level variables.
 539        """
 540        return [x for x in self.members.values() if isinstance(x, Variable)]
 541
 542    @cached_property
 543    def classes(self) -> list[Class]:
 544        """
 545        A list of all documented module level classes.
 546        """
 547        return [x for x in self.members.values() if isinstance(x, Class)]
 548
 549    @cached_property
 550    def functions(self) -> list[Function]:
 551        """
 552        A list of all documented module level functions.
 553        """
 554        return [x for x in self.members.values() if isinstance(x, Function)]
 555
 556
 557class Class(Namespace[type]):
 558    """
 559    Representation of a class's documentation.
 560    """
 561
 562    kind = "class"
 563
 564    @cache
 565    @_include_fullname_in_traceback
 566    def __repr__(self):
 567        return f"<{_decorators(self)}class {self.modulename}.{self.qualname}{_docstr(self)}{_children(self)}>"
 568
 569    @cached_property
 570    def docstring(self) -> str:
 571        doc = Doc.docstring.__get__(self)  # type: ignore
 572        if doc == dict.__doc__:
 573            # Don't display default docstring for dict subclasses (primarily TypedDict).
 574            return ""
 575        is_dataclass_with_default_docstring = (
 576            dataclasses.is_dataclass(self.obj)
 577            # from https://github.com/python/cpython/blob/3.10/Lib/dataclasses.py
 578            and doc
 579            == self.obj.__name__
 580            + str(inspect.signature(self.obj)).replace(" -> None", "")
 581        )
 582        if is_dataclass_with_default_docstring:
 583            return ""
 584        return doc
 585
 586    @cached_property
 587    def _var_docstrings(self) -> dict[str, str]:
 588        docstrings: dict[str, str] = {}
 589        for cls in self._mro:
 590            for name, docstr in doc_ast.walk_tree(cls).docstrings.items():
 591                docstrings.setdefault(name, docstr)
 592        return docstrings
 593
 594    @cached_property
 595    def _var_annotations(self) -> dict[str, type]:
 596        # this is a bit tricky: __annotations__ also includes annotations from parent classes,
 597        # but we need to execute them in the namespace of the parent class.
 598        # Our workaround for this is to walk the MRO backwards, and only update/evaluate only if the annotation changes.
 599        annotations: dict[
 600            str, tuple[Any, type]
 601        ] = {}  # attribute -> (annotation_unresolved, annotation_resolved)
 602        for cls in reversed(self._mro):
 603            cls_annotations = doc_ast.walk_tree(cls).annotations.copy()
 604            dynamic_annotations = _safe_getattr(cls, "__annotations__", None)
 605            if isinstance(dynamic_annotations, dict):
 606                for attr, unresolved_annotation in dynamic_annotations.items():
 607                    cls_annotations[attr] = unresolved_annotation
 608            cls_fullname = (
 609                _safe_getattr(cls, "__module__", "") + "." + cls.__qualname__
 610            ).lstrip(".")
 611
 612            new_annotations = {
 613                attr: unresolved_annotation
 614                for attr, unresolved_annotation in cls_annotations.items()
 615                if attr not in annotations
 616                or annotations[attr][0] is not unresolved_annotation
 617            }
 618            localns = _safe_getattr(cls, "__dict__", None)
 619            for attr, t in resolve_annotations(
 620                new_annotations, inspect.getmodule(cls), localns, cls_fullname
 621            ).items():
 622                annotations[attr] = (new_annotations[attr], t)
 623
 624        return {k: v[1] for k, v in annotations.items()}
 625
 626    @cached_property
 627    def _mro(self) -> tuple[type, ...]:
 628        orig_bases = _safe_getattr(self.obj, "__orig_bases__", None)
 629        if (
 630            orig_bases
 631            and _safe_getattr(orig_bases[-1], "__name__", None) == "TypedDict"
 632        ):
 633            # TypedDicts have a botched __mro__.
 634            # However, if the subclasses also specify TypedDict as a base class, we can use __orig_bases__
 635            # https://github.com/sphinx-doc/sphinx/pull/10806
 636            return (self.obj, *orig_bases[:-1])
 637        else:
 638            return self.obj.__mro__
 639
 640    @cached_property
 641    def _declarations(self) -> dict[str, tuple[str, str]]:
 642        decls: dict[str, tuple[str, str]] = {}
 643        for cls in self._mro:
 644            treeinfo = doc_ast.walk_tree(cls)
 645            for name in treeinfo.docstrings.keys() | treeinfo.annotations.keys():
 646                decls.setdefault(name, (cls.__module__, f"{cls.__qualname__}.{name}"))
 647            for name in cls.__dict__:
 648                decls.setdefault(name, (cls.__module__, f"{cls.__qualname__}.{name}"))
 649        if decls.get("__init__", None) == ("builtins", "object.__init__"):
 650            decls["__init__"] = (
 651                self.obj.__module__,
 652                f"{self.obj.__qualname__}.__init__",
 653            )
 654        return decls
 655
 656    def _taken_from(self, member_name: str, obj: Any) -> tuple[str, str]:
 657        try:
 658            return self._declarations[member_name]
 659        except KeyError:  # pragma: no cover
 660            # TypedDict botches __mro__ and may need special casing here.
 661            # One workaround is to also specify TypedDict as a base class, see pdoc.doc.Class._mro.
 662            warnings.warn(
 663                f"Cannot determine where {self.fullname}.{member_name} is taken from, assuming current file."
 664            )
 665            return self.modulename, f"{self.qualname}.{member_name}"
 666
 667    @cached_property
 668    def own_members(self) -> list[Doc]:
 669        members = self._members_by_origin.get((self.modulename, self.qualname), [])
 670        if self.taken_from != (self.modulename, self.qualname):
 671            # .taken_from may be != (self.modulename, self.qualname), for example when
 672            # a module re-exports a class from a private submodule.
 673            members += self._members_by_origin.get(self.taken_from, [])
 674        return members
 675
 676    @cached_property
 677    def _member_objects(self) -> dict[str, Any]:
 678        unsorted: dict[str, Any] = {}
 679        for cls in self._mro:
 680            for name, obj in cls.__dict__.items():
 681                unsorted.setdefault(name, obj)
 682        for name in self._var_docstrings:
 683            unsorted.setdefault(name, empty)
 684        for name in self._var_annotations:
 685            unsorted.setdefault(name, empty)
 686
 687        init_has_no_doc = unsorted.get("__init__", object.__init__).__doc__ in (
 688            None,
 689            object.__init__.__doc__,
 690        )
 691        if init_has_no_doc:
 692            if inspect.isabstract(self.obj):
 693                # Special case: We don't want to show constructors for abstract base classes unless
 694                # they have a custom docstring.
 695                del unsorted["__init__"]
 696            elif issubclass(self.obj, enum.Enum):
 697                # Special case: Do not show a constructor for enums. They are typically not constructed by users.
 698                # The alternative would be showing __new__, as __call__ is too verbose.
 699                del unsorted["__init__"]
 700            elif issubclass(self.obj, dict):
 701                # Special case: Do not show a constructor for dict subclasses.
 702                unsorted.pop(
 703                    "__init__", None
 704                )  # TypedDict subclasses may not have __init__.
 705            else:
 706                # Check if there's a helpful Metaclass.__call__ or Class.__new__. This dance is very similar to
 707                # https://github.com/python/cpython/blob/9feae41c4f04ca27fd2c865807a5caeb50bf4fc4/Lib/inspect.py#L2359-L2376
 708                call = _safe_getattr(type(self.obj), "__call__", None)
 709                custom_call_with_custom_docstring = (
 710                    call is not None
 711                    and not isinstance(call, NonUserDefinedCallables)
 712                    and call.__doc__ not in (None, object.__call__.__doc__)
 713                )
 714                if custom_call_with_custom_docstring:
 715                    unsorted["__init__"] = call
 716                else:
 717                    # Does our class define a custom __new__ method?
 718                    new = _safe_getattr(self.obj, "__new__", None)
 719                    custom_new_with_custom_docstring = (
 720                        new is not None
 721                        and not isinstance(new, NonUserDefinedCallables)
 722                        and new.__doc__ not in (None, object.__new__.__doc__)
 723                    )
 724                    if custom_new_with_custom_docstring:
 725                        unsorted["__init__"] = new
 726
 727        sorted: dict[str, Any] = {}
 728        for cls in self._mro:
 729            sorted, unsorted = doc_ast.sort_by_source(cls, sorted, unsorted)
 730        sorted.update(unsorted)
 731        return sorted
 732
 733    @cached_property
 734    def bases(self) -> list[tuple[str, str, str]]:
 735        """
 736        A list of all base classes, i.e. all immediate parent classes.
 737
 738        Each parent class is represented as a `(modulename, qualname, display_text)` tuple.
 739        """
 740        bases = []
 741        for x in _safe_getattr(self.obj, "__orig_bases__", self.obj.__bases__):
 742            if x is object:
 743                continue
 744            o = get_origin(x)
 745            if o:
 746                bases.append((o.__module__, o.__qualname__, str(x)))
 747            elif x.__module__ == self.modulename:
 748                bases.append((x.__module__, x.__qualname__, x.__qualname__))
 749            else:
 750                bases.append(
 751                    (x.__module__, x.__qualname__, f"{x.__module__}.{x.__qualname__}")
 752                )
 753        return bases
 754
 755    @cached_property
 756    def decorators(self) -> list[str]:
 757        """A list of all decorators the class is decorated with."""
 758        decorators = []
 759        for t in doc_ast.parse(self.obj).decorator_list:
 760            decorators.append(f"@{doc_ast.unparse(t)}")
 761        return decorators
 762
 763    @cached_property
 764    def class_variables(self) -> list[Variable]:
 765        """
 766        A list of all documented class variables in the class.
 767
 768        Class variables are variables that are explicitly annotated with `typing.ClassVar`.
 769        All other variables are treated as instance variables.
 770        """
 771        return [
 772            x
 773            for x in self.members.values()
 774            if isinstance(x, Variable) and x.is_classvar
 775        ]
 776
 777    @cached_property
 778    def instance_variables(self) -> list[Variable]:
 779        """
 780        A list of all instance variables in the class.
 781        """
 782        return [
 783            x
 784            for x in self.members.values()
 785            if isinstance(x, Variable) and not x.is_classvar
 786        ]
 787
 788    @cached_property
 789    def classmethods(self) -> list[Function]:
 790        """
 791        A list of all documented `@classmethod`s.
 792        """
 793        return [
 794            x
 795            for x in self.members.values()
 796            if isinstance(x, Function) and x.is_classmethod
 797        ]
 798
 799    @cached_property
 800    def staticmethods(self) -> list[Function]:
 801        """
 802        A list of all documented `@staticmethod`s.
 803        """
 804        return [
 805            x
 806            for x in self.members.values()
 807            if isinstance(x, Function) and x.is_staticmethod
 808        ]
 809
 810    @cached_property
 811    def methods(self) -> list[Function]:
 812        """
 813        A list of all documented methods in the class that are neither static- nor classmethods.
 814        """
 815        return [
 816            x
 817            for x in self.members.values()
 818            if isinstance(x, Function)
 819            and not x.is_staticmethod
 820            and not x.is_classmethod
 821        ]
 822
 823
 824if sys.version_info >= (3, 10):
 825    WrappedFunction = types.FunctionType | staticmethod | classmethod
 826else:  # pragma: no cover
 827    WrappedFunction = Union[types.FunctionType, staticmethod, classmethod]
 828
 829
 830class Function(Doc[types.FunctionType]):
 831    """
 832    Representation of a function's documentation.
 833
 834    This class covers all "flavors" of functions, for example it also
 835    supports `@classmethod`s or `@staticmethod`s.
 836    """
 837
 838    kind = "function"
 839
 840    wrapped: WrappedFunction
 841    """The original wrapped function (e.g., `staticmethod(func)`)"""
 842
 843    obj: types.FunctionType
 844    """The unwrapped "real" function."""
 845
 846    def __init__(
 847        self,
 848        modulename: str,
 849        qualname: str,
 850        func: WrappedFunction,
 851        taken_from: tuple[str, str],
 852    ):
 853        """Initialize a function's documentation object."""
 854        unwrapped: types.FunctionType
 855        if isinstance(func, (classmethod, staticmethod)):
 856            unwrapped = func.__func__  # type: ignore
 857        elif isinstance(func, singledispatchmethod):
 858            unwrapped = func.func  # type: ignore
 859        else:
 860            unwrapped = func
 861        super().__init__(modulename, qualname, unwrapped, taken_from)
 862        self.wrapped = func
 863
 864    @cache
 865    @_include_fullname_in_traceback
 866    def __repr__(self):
 867        if self.is_classmethod:
 868            t = "class"
 869        elif self.is_staticmethod:
 870            t = "static"
 871        elif self.qualname != _safe_getattr(self.obj, "__name__", None):
 872            t = "method"
 873        else:
 874            t = "function"
 875        return f"<{_decorators(self)}{t} {self.funcdef} {self.name}{self.signature}: ...{_docstr(self)}>"
 876
 877    @cached_property
 878    def docstring(self) -> str:
 879        doc = Doc.docstring.__get__(self)  # type: ignore
 880        if not doc:
 881            # inspect.getdoc fails for inherited @classmethods and unbound @property descriptors.
 882            # We now do an ugly dance to obtain the bound object instead,
 883            # that somewhat resembles what inspect._findclass is doing.
 884            cls = sys.modules.get(_safe_getattr(self.obj, "__module__", None), None)
 885            for name in _safe_getattr(self.obj, "__qualname__", "").split(".")[:-1]:
 886                cls = _safe_getattr(cls, name, None)
 887
 888            unbound = _safe_getattr(cls, "__dict__", {}).get(self.name)
 889            is_classmethod_property = isinstance(unbound, classmethod) and isinstance(
 890                unbound.__func__, (property, cached_property)
 891            )
 892            if not is_classmethod_property:
 893                # We choke on @classmethod @property, but that's okay because it's been deprecated with Python 3.11.
 894                # Directly accessing them would give us the return value, which has the wrong docstring.
 895                doc = _safe_getdoc(_safe_getattr(cls, self.name, None))
 896
 897        if doc == object.__init__.__doc__:
 898            # inspect.getdoc(Foo.__init__) returns the docstring, for object.__init__ if left undefined...
 899            return ""
 900        else:
 901            return doc
 902
 903    @cached_property
 904    def is_classmethod(self) -> bool:
 905        """
 906        `True` if this function is a `@classmethod`, `False` otherwise.
 907        """
 908        return isinstance(self.wrapped, classmethod)
 909
 910    @cached_property
 911    def is_staticmethod(self) -> bool:
 912        """
 913        `True` if this function is a `@staticmethod`, `False` otherwise.
 914        """
 915        return isinstance(self.wrapped, staticmethod)
 916
 917    @cached_property
 918    def decorators(self) -> list[str]:
 919        """A list of all decorators the function is decorated with."""
 920        decorators = []
 921        obj: types.FunctionType = self.obj  # type: ignore
 922        for t in doc_ast.parse(obj).decorator_list:
 923            decorators.append(f"@{doc_ast.unparse(t)}")
 924        return decorators
 925
 926    @cached_property
 927    def funcdef(self) -> str:
 928        """
 929        The string of keywords used to define the function, i.e. `"def"` or `"async def"`.
 930        """
 931        if inspect.iscoroutinefunction(self.obj) or inspect.isasyncgenfunction(
 932            self.obj
 933        ):
 934            return "async def"
 935        else:
 936            return "def"
 937
 938    @cached_property
 939    def signature(self) -> inspect.Signature:
 940        """
 941        The function's signature.
 942
 943        This usually returns an instance of `_PrettySignature`, a subclass of `inspect.Signature`
 944        that contains pdoc-specific optimizations. For example, long argument lists are split over multiple lines
 945        in repr(). Additionally, all types are already resolved.
 946
 947        If the signature cannot be determined, a placeholder Signature object is returned.
 948        """
 949        if self.obj is object.__init__:
 950            # there is a weird edge case were inspect.signature returns a confusing (self, /, *args, **kwargs)
 951            # signature for the default __init__ method.
 952            return inspect.Signature()
 953        try:
 954            sig = _PrettySignature.from_callable(self.obj)
 955        except Exception:
 956            return inspect.Signature(
 957                [inspect.Parameter("unknown", inspect.Parameter.POSITIONAL_OR_KEYWORD)]
 958            )
 959        mod = inspect.getmodule(self.obj)
 960        globalns = _safe_getattr(mod, "__dict__", {})
 961        localns = globalns
 962        for parent_cls_name in self.qualname.split(".")[:-1]:
 963            parent_cls = localns.get(parent_cls_name, object)
 964            localns = _safe_getattr(parent_cls, "__dict__", None)
 965            if localns is None:
 966                break  # pragma: no cover
 967
 968        if self.name == "__init__":
 969            sig = sig.replace(return_annotation=empty)
 970        else:
 971            sig = sig.replace(
 972                return_annotation=safe_eval_type(
 973                    sig.return_annotation, globalns, localns, mod, self.fullname
 974                )
 975            )
 976        for p in sig.parameters.values():
 977            p._annotation = safe_eval_type(p.annotation, globalns, localns, mod, self.fullname)  # type: ignore
 978        return sig
 979
 980    @cached_property
 981    def signature_without_self(self) -> inspect.Signature:
 982        """Like `signature`, but without the first argument.
 983
 984        This is useful to display constructors.
 985        """
 986        return self.signature.replace(
 987            parameters=list(self.signature.parameters.values())[1:]
 988        )
 989
 990
 991class Variable(Doc[None]):
 992    """
 993    Representation of a variable's documentation. This includes module, class and instance variables.
 994    """
 995
 996    kind = "variable"
 997
 998    default_value: Any | empty  # technically Any includes empty, but this conveys intent.
 999    """
1000    The variable's default value.
1001    
1002    In some cases, no default value is known. This may either be because a variable is only defined in the constructor,
1003    or it is only declared with a type annotation without assignment (`foo: int`).
1004    To distinguish this case from a default value of `None`, `pdoc.doc_types.empty` is used as a placeholder.
1005    """
1006
1007    annotation: type | empty
1008    """
1009    The variable's type annotation.
1010    
1011    If there is no type annotation, `pdoc.doc_types.empty` is used as a placeholder.
1012    """
1013
1014    def __init__(
1015        self,
1016        modulename: str,
1017        qualname: str,
1018        *,
1019        taken_from: tuple[str, str],
1020        docstring: str,
1021        annotation: type | empty = empty,
1022        default_value: Any | empty = empty,
1023    ):
1024        """
1025        Construct a variable doc object.
1026
1027        While classes and functions can introspect themselves to see their docstring,
1028        variables can't do that as we don't have a "variable object" we could query.
1029        As such, docstring, declaration location, type annotation, and the default value
1030        must be passed manually in the constructor.
1031        """
1032        super().__init__(modulename, qualname, None, taken_from)
1033        # noinspection PyPropertyAccess
1034        self.docstring = inspect.cleandoc(docstring)
1035        self.annotation = annotation
1036        self.default_value = default_value
1037
1038    @cache
1039    @_include_fullname_in_traceback
1040    def __repr__(self):
1041        return f'<var {self.qualname.rsplit(".")[-1]}{self.annotation_str}{self.default_value_str}{_docstr(self)}>'
1042
1043    @cached_property
1044    def is_classvar(self) -> bool:
1045        """`True` if the variable is a class variable, `False` otherwise."""
1046        if get_origin(self.annotation) is ClassVar:
1047            return True
1048        else:
1049            return False
1050
1051    @cached_property
1052    def is_enum_member(self) -> bool:
1053        """`True` if the variable is an enum member, `False` otherwise."""
1054        if isinstance(self.default_value, enum.Enum):
1055            return True
1056        else:
1057            return False
1058
1059    @cached_property
1060    def default_value_str(self) -> str:
1061        """The variable's default value as a pretty-printed str."""
1062        if self.default_value is empty:
1063            return ""
1064        else:
1065            try:
1066                return re.sub(
1067                    r" at 0x[0-9a-fA-F]+(?=>)",
1068                    "",
1069                    f" = {repr(self.default_value)}",
1070                )
1071            except Exception:
1072                return " = <unable to get value representation>"
1073
1074    @cached_property
1075    def annotation_str(self) -> str:
1076        """The variable's type annotation as a pretty-printed str."""
1077        if self.annotation is not empty:
1078            return f": {formatannotation(self.annotation)}"
1079        else:
1080            return ""
1081
1082
1083class _PrettySignature(inspect.Signature):
1084    """
1085    A subclass of `inspect.Signature` that pads __str__ over several lines
1086    for complex signatures.
1087    """
1088
1089    MULTILINE_CUTOFF = 70
1090
1091    def _params(self) -> list[str]:
1092        # redeclared here to keep code snipped below as-is.
1093        _POSITIONAL_ONLY = inspect.Parameter.POSITIONAL_ONLY
1094        _VAR_POSITIONAL = inspect.Parameter.VAR_POSITIONAL
1095        _KEYWORD_ONLY = inspect.Parameter.KEYWORD_ONLY
1096
1097        # https://github.com/python/cpython/blob/799f8489d418b7f9207d333eac38214931bd7dcc/Lib/inspect.py#L3083-L3117
1098        # Change: added re.sub() to formatted = ....
1099        # ✂ start ✂
1100        result = []
1101        render_pos_only_separator = False
1102        render_kw_only_separator = True
1103        for param in self.parameters.values():
1104            formatted = re.sub(r" at 0x[0-9a-fA-F]+(?=>$)", "", str(param))
1105
1106            kind = param.kind
1107
1108            if kind == _POSITIONAL_ONLY:
1109                render_pos_only_separator = True
1110            elif render_pos_only_separator:
1111                # It's not a positional-only parameter, and the flag
1112                # is set to 'True' (there were pos-only params before.)
1113                result.append("/")
1114                render_pos_only_separator = False
1115
1116            if kind == _VAR_POSITIONAL:
1117                # OK, we have an '*args'-like parameter, so we won't need
1118                # a '*' to separate keyword-only arguments
1119                render_kw_only_separator = False
1120            elif kind == _KEYWORD_ONLY and render_kw_only_separator:
1121                # We have a keyword-only parameter to render and we haven't
1122                # rendered an '*args'-like parameter before, so add a '*'
1123                # separator to the parameters list ("foo(arg1, *, arg2)" case)
1124                result.append("*")
1125                # This condition should be only triggered once, so
1126                # reset the flag
1127                render_kw_only_separator = False
1128
1129            result.append(formatted)
1130
1131        if render_pos_only_separator:
1132            # There were only positional-only parameters, hence the
1133            # flag was not reset to 'False'
1134            result.append("/")
1135        # ✂ end ✂
1136
1137        return result
1138
1139    def _return_annotation_str(self) -> str:
1140        if self.return_annotation is not empty:
1141            return formatannotation(self.return_annotation)
1142        else:
1143            return ""
1144
1145    def __str__(self):
1146        result = self._params()
1147        return_annot = self._return_annotation_str()
1148
1149        total_len = sum(len(x) + 2 for x in result) + len(return_annot)
1150
1151        if total_len > self.MULTILINE_CUTOFF:
1152            rendered = "(\n    " + ",\n    ".join(result) + "\n)"
1153        else:
1154            rendered = "({})".format(", ".join(result))
1155        if return_annot:
1156            rendered += f" -> {return_annot}"
1157
1158        return rendered
1159
1160
1161def _cut(x: str) -> str:
1162    """helper function for Doc.__repr__()"""
1163    if len(x) < 20:
1164        return x
1165    else:
1166        return x[:20] + "…"
1167
1168
1169def _docstr(doc: Doc) -> str:
1170    """helper function for Doc.__repr__()"""
1171    docstr = []
1172    if doc.is_inherited:
1173        docstr.append(f"inherited from {'.'.join(doc.taken_from).rstrip('.')}")
1174    if doc.docstring:
1175        docstr.append(_cut(doc.docstring))
1176    if docstr:
1177        return f"  # {', '.join(docstr)}"
1178    else:
1179        return ""
1180
1181
1182def _decorators(doc: Class | Function) -> str:
1183    """helper function for Doc.__repr__()"""
1184    if doc.decorators:
1185        return " ".join(doc.decorators) + " "
1186    else:
1187        return ""
1188
1189
1190def _children(doc: Namespace) -> str:
1191    children = "\n".join(
1192        repr(x)
1193        for x in doc.members.values()
1194        if not x.name.startswith("_") or x.name == "__init__"
1195    )
1196    if children:
1197        children += "\n"
1198        children = f"\n{textwrap.indent(children, '    ')}"
1199    return children
1200
1201
1202def _safe_getattr(obj, attr, default):
1203    """Like `getattr()`, but never raises."""
1204    try:
1205        return getattr(obj, attr, default)
1206    except Exception as e:
1207        warnings.warn(
1208            f"getattr({obj!r}, {attr!r}, {default!r}) raised an exception: {e!r}"
1209        )
1210        return default
1211
1212
1213def _safe_getdoc(obj: Any) -> str:
1214    """Like `inspect.getdoc()`, but never raises. Always returns a stripped string."""
1215    try:
1216        doc = inspect.getdoc(obj) or ""
1217    except Exception as e:
1218        warnings.warn(f"inspect.getdoc({obj!r}) raised an exception: {e!r}")
1219        return ""
1220    else:
1221        return doc.strip()