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 307ff51caf6d92ea6c0469d76fdeff95b2829c2c..0ee52fa4dc17159e1f1be56ddb702c6128c7e361 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -610,6 +610,10 @@ are always available.  They are listed here in alphabetical order.
 
    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 ccb2bd7c22cef7cd6b8519419b35afe421ef397a..0c087123e80d1326a394a8fec5de369e44e4e4cd 100644 (file)
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -729,6 +729,11 @@ Classes and functions
       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 e100865515463fc9d90a9da9c90cdad28574d3e5..3f520e892d23cbd4222c9b4af6e8b1e558c24feb 100644 (file)
--- a/Doc/library/pydoc.rst
+++ b/Doc/library/pydoc.rst
@@ -84,3 +84,8 @@ Reference Manual pages.
 
 .. 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 b1930543a8fc876d8da228f4aa104ebbc9522c9b..4b953fdd874500c1fadc54febe2c9f5ea93b6f28 100644 (file)
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -133,6 +133,8 @@ Significantly Improved Library Modules:
   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 @@ Some smaller changes made to the core Python language are:
   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 @@ Snow in :issue:`19152`.)
 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 @@ metaclasses (Contributed by Ethan Furman in :issue:`18929` and
 
 :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 @@ the child process, instead of ``None``.  (Contributed by Gregory P. Smith.)
 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 @@ accurate signatures for builtins and standard library extension modules
 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 @@ Changes in the Python API
   :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