From 00b157dfc5dfb790ba63df5ee880cb9d5ba86b99 Mon Sep 17 00:00:00 2001 From: Sreehari Annam Date: Sun, 12 Jul 2026 10:04:29 -0400 Subject: [PATCH 1/5] gh-62172: Document classify_class_attrs(), getabsfile(), and indentsize() in inspect --- Doc/library/inspect.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index a0f7379b12a8a62..a49ea503e6367f6 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -736,6 +736,15 @@ Retrieving source code class, or function. +.. function:: getabsfile(object) + + Return an absolute path to the (text or binary) file in which an object + was defined, normalized for the current platform using + :func:`os.path.normcase`. This uses :func:`getsourcefile` and falls back + to :func:`getfile` if no source file can be found. The idea is for each + object to have a unique origin. + + .. function:: getmodule(object) Try to guess which module an object was defined in. Return ``None`` @@ -791,6 +800,12 @@ Retrieving source code expanded to spaces. +.. function:: indentsize(line) + + Return the indentation size, in number of spaces, at the start of a line + of text, expanding tabs using :meth:`str.expandtabs`. + + .. _inspect-signature-object: Introspecting callables with the Signature object @@ -1220,6 +1235,20 @@ function. Classes and functions --------------------- +.. function:: classify_class_attrs(cls) + + Return a list of ``Attribute(name, kind, defining_class, object)`` named + tuples for each attribute reported by ``dir(cls)``. *kind* is one of + ``'class method'``, ``'static method'``, ``'property'``, ``'method'`` or + ``'data'``, and *defining_class* is the class in *cls*'s :term:`MRO` (or + its metaclass's MRO) that defines the attribute. *object* is the + attribute value, retrieved with :func:`getattr` where possible, falling + back to a lookup in the defining class's ``__dict__``. + + This is used internally by :mod:`pydoc` to build the class documentation + shown by :func:`help`. + + .. function:: getclasstree(classes, unique=False) Arrange the given list of classes into a hierarchy of nested lists. Where a From c4e2a2675913157762252ed05149c3f253b633b0 Mon Sep 17 00:00:00 2001 From: Sreehari Annam Date: Sun, 12 Jul 2026 11:18:46 -0400 Subject: [PATCH 2/5] Address review feedback: simplify getabsfile wording, link named tuple term --- Doc/library/inspect.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index a49ea503e6367f6..eefc93ea90192fa 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -738,11 +738,10 @@ Retrieving source code .. function:: getabsfile(object) - Return an absolute path to the (text or binary) file in which an object - was defined, normalized for the current platform using - :func:`os.path.normcase`. This uses :func:`getsourcefile` and falls back - to :func:`getfile` if no source file can be found. The idea is for each - object to have a unique origin. + Return an absolute, normalized path to the (text or binary) file in + which an object was defined. This uses :func:`getsourcefile` and falls + back to :func:`getfile` if no source file can be found. The idea is for + each object to have a unique origin. .. function:: getmodule(object) @@ -1237,8 +1236,9 @@ Classes and functions .. function:: classify_class_attrs(cls) - Return a list of ``Attribute(name, kind, defining_class, object)`` named - tuples for each attribute reported by ``dir(cls)``. *kind* is one of + Return a list of :term:`named tuples ` + ``Attribute(name, kind, defining_class, object)`` for each attribute + reported by ``dir(cls)``. *kind* is one of ``'class method'``, ``'static method'``, ``'property'``, ``'method'`` or ``'data'``, and *defining_class* is the class in *cls*'s :term:`MRO` (or its metaclass's MRO) that defines the attribute. *object* is the From 1e215a397508089cc4fa7ad3760d38ea52c7f119 Mon Sep 17 00:00:00 2001 From: Sreehari Annam Date: Sun, 12 Jul 2026 17:48:28 -0400 Subject: [PATCH 3/5] gh-62172: Document findsource() and getblock() in inspect --- Doc/library/inspect.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index eefc93ea90192fa..231e5962bc95824 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -758,6 +758,27 @@ Retrieving source code function. +.. function:: findsource(object) + + Return the list of source lines for the entire file containing the given + object, together with the line number in that list where the object's + own source starts. The argument may be a module, class, method, + function, traceback, frame, or code object. An :exc:`OSError` is raised + if the source code cannot be retrieved. + + Unlike :func:`getsourcelines`, this does not call :func:`unwrap` on the + object first, so it will report the location of a decorator-wrapped + callable's wrapper rather than the wrapped function. + + +.. function:: getblock(lines) + + Extract and return the block of code at the top of the given list of + source *lines*, using the :mod:`tokenize` module to detect where the + block ends. This is used together with :func:`findsource` to implement + :func:`getsourcelines`. + + .. function:: getsourcelines(object) Return a list of source lines and starting line number for an object. The From 7fdd7e20dc822ffa572d94c53592caa13f143f93 Mon Sep 17 00:00:00 2001 From: Sreehari Annam Date: Sun, 12 Jul 2026 17:59:54 -0400 Subject: [PATCH 4/5] gh-62172: Document walktree() and getargs() in inspect --- Doc/library/inspect.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 231e5962bc95824..e2f42c71d3f033d 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -1281,6 +1281,29 @@ Classes and functions times. +.. function:: walktree(classes, children, parent) + + Recursive helper function used by :func:`getclasstree` to build its + nested list structure. *children* maps each class to a list of its + direct subclasses, as accumulated by :func:`getclasstree`, and *parent* + is the common parent of *classes* at the current level of recursion (or + ``None`` at the top level). + + +.. function:: getargs(co) + + Get information about the arguments accepted by a code object *co*. + Return an ``Arguments(args, varargs, varkw)`` :term:`named tuple`, where + *args* is a list of argument names (with any keyword-only arguments + appended at the end), and *varargs* and *varkw* are the names of the + ``*`` and ``**`` arguments, or ``None`` if they are not accepted. + + Note that :func:`getfullargspec` provides additional information (such + as default values and annotations) and is the recommended way to inspect + a callable's parameters. This function is retained primarily for use in + code that already works directly with code objects. + + .. function:: getfullargspec(func, *, annotation_format=Format.VALUE) Get the names and default values of a Python function's parameters. A From 1b58423ec868385bf7094c3f667a8f5f29b10de3 Mon Sep 17 00:00:00 2001 From: Sreehari Annam Date: Thu, 23 Jul 2026 07:42:39 -0400 Subject: [PATCH 5/5] gh-62172: Document formatannotation, formatannotationrelativeto, and getlineno in inspect --- Doc/library/inspect.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index e2f42c71d3f033d..4de74d347db904d 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -1375,6 +1375,31 @@ Classes and functions This function was inadvertently marked as deprecated in Python 3.5. +.. function:: formatannotation(annotation, base_module=None, *, quote_annotation_strings=True) + + Format *annotation* for pretty-printing, as used internally when + rendering :class:`Signature` and :class:`Parameter` objects as strings. + + If *annotation* is a :class:`type` whose ``__module__`` is ``'builtins'`` + or equal to *base_module*, only its :attr:`~definition.__qualname__` is + returned; otherwise the module name is included as a prefix. ``typing`` + module prefixes are always stripped from the ``repr`` of *annotation*, + and a :class:`~typing.ForwardRef` is rendered as its forward-referenced + argument string. + + If *quote_annotation_strings* is false, an *annotation* that is already + a :class:`str` is returned unchanged instead of being re-quoted, to avoid + double-quoting stringified annotations. + + +.. function:: formatannotationrelativeto(object) + + Return a version of :func:`formatannotation` that uses the + ``__module__`` of *object* as the *base_module*, so annotations + referring to classes defined in the same module as *object* are + formatted without a module prefix. + + .. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue]) Format a pretty argument spec from the four values returned by @@ -1606,6 +1631,15 @@ line. .. versionchanged:: 3.11 A :class:`Traceback` object is returned instead of a named tuple. + +.. function:: getlineno(frame) + + Get the current line number of *frame* from its :attr:`~frame.f_lineno` + attribute. This function exists as a separate entry point so that how + the line number is obtained can be optimized independently of its + callers; currently it returns ``frame.f_lineno`` directly. + + .. function:: getouterframes(frame, context=1) Get a list of :class:`FrameInfo` objects for a frame and all outer frames.