Improve descriptions of introspection changes
Several of the introspection changes in Python 3.4 are indirect,
where inspect module changes affected pydoc, and those in turn
affected the help builtin. This update adds versionchanged
notes in the key locations, as well as more coverage in the
What's New document (in particular, a note in the porting
section regarding the expanded domain for inspect.getfullargspec).
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 307ff51..0ee52fa 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -610,6 +610,10 @@
This function is added to the built-in namespace by the :mod:`site` module.
+ .. versionchanged:: 3.4
+ Changes to :mod:`pydoc` and :mod:`inspect` mean that the reported
+ signatures for callables are now more comprehensive and consistent.
+
.. function:: hex(x)
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index ccb2bd7..0c08712 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -729,6 +729,11 @@
Consider using the new :ref:`Signature Object <inspect-signature-object>`
interface, which provides a better way of introspecting functions.
+ .. versionchanged:: 3.4
+ This function is now based on :func:`signature`, but still ignores
+ ``__wrapped__`` attributes and includes the already bound first
+ parameter in the signature output for bound methods.
+
.. function:: getargvalues(frame)
diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst
index e100865..3f520e8 100644
--- a/Doc/library/pydoc.rst
+++ b/Doc/library/pydoc.rst
@@ -84,3 +84,8 @@
.. versionchanged:: 3.2
Added the ``-b`` option, deprecated the ``-g`` option.
+
+.. versionchanged:: 3.4
+ :mod:`pydoc` now uses :func:`inspect.signature` rather than
+ :func:`inspect.getfullargspec` to extract signature information from
+ callables.
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index b193054..4b953fd 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -133,6 +133,8 @@
a new :mod:`~email.message.Message` subclass
(:class:`~email.contentmanager.EmailMessage`) that :ref:`simplify MIME
handling <whatsnew_email_contentmanager>` (:issue:`18891`).
+* The :mod:`inspect` and :mod:`pydoc` modules are now capable of
+ correct introspection of a much wider variety of callable objects
* The :mod:`ipaddress` module API has been declared stable
@@ -384,6 +386,10 @@
and supports the :func:`reversed` builtin. (Contributed by Nick Coghlan
and Claudiu Popa in :issue:`18690` and :issue:`19078`.)
+* Signatures reported by :func:`help` have been modified and improved in
+ several cases as a result of the introduction of Argument Clinic and other
+ changes to the :mod:`inspect` and :mod:`pydoc` modules.
+
New Modules
===========
@@ -871,7 +877,7 @@
inspect
-------
-The inspect module now offers a basic :ref:`command line interface
+The :mod:`inspect` module now offers a basic :ref:`command line interface
<inspect-module-cli>` to quickly display source code and other
information for modules, classes and functions. (Contributed by Claudiu Popa
and Nick Coghlan in :issue:`18626`)
@@ -889,10 +895,14 @@
:func:`~inspect.getfullargspec` and :func:`~inspect.getargspec`
now use the :func:`~inspect.signature` API. This allows them to
-support much broader range of functions, including some builtins and
-callables that follow ``__signature__`` protocol. It is still
-recommended to update your code to use :func:`~inspect.signature`
-directly. (Contributed by Yury Selivanov in :issue:`17481`)
+support a much broader range of callables, including those with
+``__signature__`` attributes, those with metadata provided by argument
+clinic, :func:`functools.partial` objects and more. Note that, unlike
+:func:`~inspect.signature`, these functions still ignore ``__wrapped__``
+attributes, and report the already bound first argument for bound methods,
+so it is still necessary to update your code to use
+:func:`~inspect.signature` directly if those features are desired.
+(Contributed by Yury Selivanov in :issue:`17481`)
:func:`~inspect.signature` now supports duck types of CPython functions,
which adds support for functions compiled with Cython. (Contributed
@@ -1086,11 +1096,25 @@
pydoc
-----
-While significant changes have not been made to :mod:`pydoc` directly,
+The :mod:`pydoc` module is now based directly on the
+:func:`inspect.signature` introspection API, allowing it to provide
+signature information for a wider variety of callable objects. This change
+also means that ``__wrapped__`` attributes are now taken into account when
+display help information (Contributed by Larry Hastings in :issue:`19674`)
+
+The :mod:`pydoc` module no longer displays the ``self`` parameter for
+already bound methods. Instead, it aims to always display the exact current
+signature of the supplied callable (Contributed by Larry Hastings in
+:issue:`20710`)
+
+In addition to the changes that have been made to :mod:`pydoc` directly,
its handling of custom ``__dir__`` methods and various descriptor
-behaviours has been improved substantially by the underlying changes in
+behaviours has also been improved substantially by the underlying changes in
the :mod:`inspect` module.
+As the :func:`help` builtin is based on :mod:`pydoc`, the above changes also
+affect the behaviour of :func:`help`.
+
re
--
@@ -1532,7 +1556,12 @@
implemented in C.
Some standard library extension modules have been converted to use Argument
-Clinic in Python 3.4, and :mod:`inspect` has been updated accordingly.
+Clinic in Python 3.4, and :mod:`pydoc` and :mod:`inspect` has been updated
+accordingly.
+
+It is expected that signature metadata for programmatic introspection will
+be added to additional callables implemented in C as part of Python 3.4
+maintenance releases.
.. note::
The Argument Clinic PEP is not fully up to date with the state of the
@@ -1956,6 +1985,14 @@
:func:`inspect.unwrap` to access the first function in the chain that has
no ``__wrapped__`` attribute.
+* :func:`inspect.getfullargspec` has been reimplemented on top of
+ :func`inspect.signature` and hence handles a much wider variety of callable
+ objects than it did in the past. It is expected that additional builtin and
+ extension module callables will gain signature metadata over the course of
+ the Python 3.4 series. Code that assumes that
+ :func:`inspect.getfullargspec` will fail on non-Python callables may need
+ to be adjusted accordingly.
+
* :class:`importlib.machinery.PathFinder` now passes on the current working
directory to objects in :data:`sys.path_hooks` for the empty string. This
results in :data:`sys.path_importer_cache` never containing ``''``, thus