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