diff options
Diffstat (limited to 'Doc/library/inspect.rst')
| -rw-r--r-- | Doc/library/inspect.rst | 132 |
1 files changed, 85 insertions, 47 deletions
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 62a3988ae0..41a784d982 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -235,24 +235,6 @@ attributes: listed in the metaclass' custom :meth:`__dir__`. -.. function:: getmoduleinfo(path) - - Returns a :term:`named tuple` ``ModuleInfo(name, suffix, mode, module_type)`` - of values that describe how Python will interpret the file identified by - *path* if it is a module, or ``None`` if it would not be identified as a - module. In that tuple, *name* is the name of the module without the name of - any enclosing package, *suffix* is the trailing part of the file name (which - may not be a dot-delimited extension), *mode* is the :func:`open` mode that - would be used (``'r'`` or ``'rb'``), and *module_type* is an integer giving - the type of the module. *module_type* will have a value which can be - compared to the constants defined in the :mod:`imp` module; see the - documentation for that module for more information on module types. - - .. deprecated:: 3.3 - You may check the file path's suffix against the supported suffixes - listed in :mod:`importlib.machinery` to infer the same information. - - .. function:: getmodulename(path) Return the name of the module named by the file *path*, without including the @@ -266,8 +248,7 @@ attributes: still return ``None``. .. versionchanged:: 3.3 - This function is now based directly on :mod:`importlib` rather than the - deprecated :func:`getmoduleinfo`. + The function is based directly on :mod:`importlib`. .. function:: ismodule(object) @@ -337,6 +318,27 @@ attributes: .. versionadded:: 3.5 +.. function:: isasyncgenfunction(object) + + Return true if the object is an :term:`asynchronous generator` function, + for example:: + + >>> async def agen(): + ... yield 1 + ... + >>> inspect.isasyncgenfunction(agen) + True + + .. versionadded:: 3.6 + + +.. function:: isasyncgen(object) + + Return true if the object is an :term:`asynchronous generator iterator` + created by an :term:`asynchronous generator` function. + + .. versionadded:: 3.6 + .. function:: istraceback(object) Return true if the object is a traceback. @@ -646,6 +648,16 @@ function. The name of the parameter as a string. The name must be a valid Python identifier. + .. impl-detail:: + + CPython generates implicit parameter names of the form ``.0`` on the + code objects used to implement comprehensions and generator + expressions. + + .. versionchanged:: 3.6 + These parameter names are exposed by this module as names like + ``implicit0``. + .. attribute:: Parameter.default The default value for the parameter. If the parameter has no default @@ -824,47 +836,65 @@ Classes and functions .. function:: getargspec(func) - Get the names and default values of a Python function's arguments. A + Get the names and default values of a Python function's parameters. A :term:`named tuple` ``ArgSpec(args, varargs, keywords, defaults)`` is - returned. *args* is a list of the argument names. *varargs* and *keywords* - are the names of the ``*`` and ``**`` arguments or ``None``. *defaults* is a + returned. *args* is a list of the parameter names. *varargs* and *keywords* + are the names of the ``*`` and ``**`` parameters or ``None``. *defaults* is a tuple of default argument values or ``None`` if there are no default arguments; if this tuple has *n* elements, they correspond to the last *n* elements listed in *args*. .. deprecated:: 3.0 - Use :func:`signature` and + Use :func:`getfullargspec` for an updated API that is usually a drop-in + replacement, but also correctly handles function annotations and + keyword-only parameters. + + Alternatively, use :func:`signature` and :ref:`Signature Object <inspect-signature-object>`, which provide a - better introspecting API for callables. + more structured introspection API for callables. .. function:: getfullargspec(func) - Get the names and default values of a Python function's arguments. A + Get the names and default values of a Python function's parameters. A :term:`named tuple` is returned: ``FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)`` - *args* is a list of the argument names. *varargs* and *varkw* are the names - of the ``*`` and ``**`` arguments or ``None``. *defaults* is an *n*-tuple - of the default values of the last *n* arguments, or ``None`` if there are no - default arguments. *kwonlyargs* is a list of - keyword-only argument names. *kwonlydefaults* is a dictionary mapping names - from kwonlyargs to defaults. *annotations* is a dictionary mapping argument - names to annotations. - - The first four items in the tuple correspond to :func:`getargspec`. + *args* is a list of the positional parameter names. + *varargs* is the name of the ``*`` parameter or ``None`` if arbitrary + positional arguments are not accepted. + *varkw* is the name of the ``**`` parameter or ``None`` if arbitrary + keyword arguments are not accepted. + *defaults* is an *n*-tuple of default argument values corresponding to the + last *n* positional parameters, or ``None`` if there are no such defaults + defined. + *kwonlyargs* is a list of keyword-only parameter names. + *kwonlydefaults* is a dictionary mapping parameter names from *kwonlyargs* + to the default values used if no argument is supplied. + *annotations* is a dictionary mapping parameter names to annotations. + The special key ``"return"`` is used to report the function return value + annotation (if any). + + Note that :func:`signature` and + :ref:`Signature Object <inspect-signature-object>` provide the recommended + API for callable introspection, and support additional behaviours (like + positional-only arguments) that are sometimes encountered in extension module + APIs. This function is retained primarily for use in code that needs to + maintain compatibility with the Python 2 ``inspect`` module API. .. 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. - .. deprecated:: 3.5 - Use :func:`signature` and - :ref:`Signature Object <inspect-signature-object>`, which provide a - better introspecting API for callables. + .. versionchanged:: 3.6 + This method was previously documented as deprecated in favour of + :func:`signature` in Python 3.5, but that decision has been reversed + in order to restore a clearly supported standard interface for + single-source Python 2/3 code migrating away from the legacy + :func:`getargspec` API. .. function:: getargvalues(frame) @@ -884,7 +914,7 @@ Classes and functions .. function:: formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]]) Format a pretty argument spec from the values returned by - :func:`getargspec` or :func:`getfullargspec`. + :func:`getfullargspec`. The first seven arguments are (``args``, ``varargs``, ``varkw``, ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``). @@ -1264,20 +1294,29 @@ the following flags: .. data:: CO_COROUTINE - The flag is set when the code object is a coroutine function, i.e. - a coroutine object is returned when the code object is executed. See - :pep:`492` for more details. + The flag is set when the code object is a coroutine function. + When the code object is executed it returns a coroutine object. + See :pep:`492` for more details. .. versionadded:: 3.5 .. data:: CO_ITERABLE_COROUTINE - Used to turn generators into generator-based coroutines. Generator - objects with this flag can be used in ``await`` expression, and can - ``yield from`` coroutine objects. See :pep:`492` for more details. + The flag is used to transform generators into generator-based + coroutines. Generator objects with this flag can be used in + ``await`` expression, and can ``yield from`` coroutine objects. + See :pep:`492` for more details. .. versionadded:: 3.5 +.. data:: CO_ASYNC_GENERATOR + + The flag is set when the code object is an asynchronous generator + function. When the code object is executed it returns an + asynchronous generator object. See :pep:`525` for more details. + + .. versionadded:: 3.6 + .. note:: The flags are specific to CPython, and may not be defined in other Python implementations. Furthermore, the flags are an implementation @@ -1286,7 +1325,6 @@ the following flags: for any introspection needs. - .. _inspect-module-cli: Command Line Interface |