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