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