[Python-Dev] [Python-checkins] cpython: Review of signature docs.

Andrew Svetlov andrew.svetlov at gmail.com
Tue Aug 14 10:46:25 CEST 2012


Thank you for review.

On Tue, Aug 14, 2012 at 10:45 AM, georg.brandl
<python-checkins at python.org> wrote:
> http://hg.python.org/cpython/rev/e1e7d628c0b9
> changeset:   78560:e1e7d628c0b9
> user:        Georg Brandl <georg at python.org>
> date:        Tue Aug 14 09:45:28 2012 +0200
> summary:
>   Review of signature docs.
>
> files:
>   Doc/library/inspect.rst |  127 +++++++++++++--------------
>   1 files changed, 62 insertions(+), 65 deletions(-)
>
>
> diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
> --- a/Doc/library/inspect.rst
> +++ b/Doc/library/inspect.rst
> @@ -397,25 +397,18 @@
>
>  .. _inspect-signature-object:
>
> -Introspecting callables with Signature Object
> ----------------------------------------------
> -
> -Signature object represents the call signature of a callable object and its
> -return annotation.  To get a Signature object use the :func:`signature`
> -function.
> -
> +Introspecting callables with the Signature object
> +-------------------------------------------------
>
>  .. versionadded:: 3.3
>
> -.. seealso::
> -
> -   :pep:`362` - Function Signature Object.
> -      The detailed specification, implementation details and examples.
> -
> +The Signature object represents the call signature of a callable object and its
> +return annotation.  To retrieve a Signature object, use the :func:`signature`
> +function.
>
>  .. function:: signature(callable)
>
> -   Returns a :class:`Signature` object for the given ``callable``::
> +   Return a :class:`Signature` object for the given ``callable``::
>
>        >>> from inspect import signature
>        >>> def foo(a, *, b:int, **kwargs):
> @@ -432,24 +425,24 @@
>        >>> sig.parameters['b'].annotation
>        <class 'int'>
>
> -   Accepts a wide range of python callables, from plain functions and classes
> -   to :func:`functools.partial` objects.
> +   Accepts a wide range of python callables, from plain functions and classes to
> +   :func:`functools.partial` objects.
>
>     .. note::
>
> -      Some callables may not be introspectable in certain implementations
> -      of Python. For example, in CPython, built-in functions defined in C
> -      provide no metadata about their arguments.
> +      Some callables may not be introspectable in certain implementations of
> +      Python.  For example, in CPython, built-in functions defined in C provide
> +      no metadata about their arguments.
>
>
>  .. class:: Signature
>
> -   A Signature object represents the call signature of a function and its
> -   return annotation. For each parameter accepted by the function it
> -   stores a :class:`Parameter` object in its :attr:`parameters` collection.
> +   A Signature object represents the call signature of a function and its return
> +   annotation.  For each parameter accepted by the function it stores a
> +   :class:`Parameter` object in its :attr:`parameters` collection.
>
> -   Signature objects are *immutable*. Use :meth:`Signature.replace` to make
> -   a modified copy.
> +   Signature objects are *immutable*.  Use :meth:`Signature.replace` to make a
> +   modified copy.
>
>     .. attribute:: Signature.empty
>
> @@ -462,30 +455,29 @@
>
>     .. attribute:: Signature.return_annotation
>
> -      The "return" annotation for the callable. If the callable has
> -      no "return" annotation, this attribute is set to
> -      :attr:`Signature.empty`.
> +      The "return" annotation for the callable.  If the callable has no "return"
> +      annotation, this attribute is set to :attr:`Signature.empty`.
>
>     .. method:: Signature.bind(*args, **kwargs)
>
> -      Creates a mapping from positional and keyword arguments to parameters.
> -      Returns :class:`BoundArguments` if ``*args`` and ``**kwargs`` match
> -      the signature, or raises a :exc:`TypeError`.
> +      Create a mapping from positional and keyword arguments to parameters.
> +      Returns :class:`BoundArguments` if ``*args`` and ``**kwargs`` match the
> +      signature, or raises a :exc:`TypeError`.
>
>     .. method:: Signature.bind_partial(*args, **kwargs)
>
> -      Works the same way as :meth:`Signature.bind`, but allows the
> -      omission of some required arguments (mimics :func:`functools.partial`
> -      behavior.) Returns :class:`BoundArguments`, or raises a :exc:`TypeError`
> -      if the passed arguments do not match the signature.
> +      Works the same way as :meth:`Signature.bind`, but allows the omission of
> +      some required arguments (mimics :func:`functools.partial` behavior.)
> +      Returns :class:`BoundArguments`, or raises a :exc:`TypeError` if the
> +      passed arguments do not match the signature.
>
>     .. method:: Signature.replace([parameters], *, [return_annotation])
>
> -      Creates a new Signature instance based on the instance replace was
> -      invoked on. It is possible to pass different ``parameters`` and/or
> -      ``return_annotation`` to override the corresponding properties of
> -      the base signature. To remove return_annotation from the copied
> -      Signature, pass in :attr:`Signature.empty`.
> +      Create a new Signature instance based on the instance replace was invoked
> +      on.  It is possible to pass different ``parameters`` and/or
> +      ``return_annotation`` to override the corresponding properties of the base
> +      signature.  To remove return_annotation from the copied Signature, pass in
> +      :attr:`Signature.empty`.
>
>        ::
>
> @@ -497,38 +489,36 @@
>           "(a, b) -> 'new return anno'"
>
>
> -
>  .. class:: Parameter
>
> -   Parameter objects are *immutable*. Instead of modifying a Parameter object,
> +   Parameter objects are *immutable*.  Instead of modifying a Parameter object,
>     you can use :meth:`Parameter.replace` to create a modified copy.
>
>     .. attribute:: Parameter.empty
>
> -      A special class-level marker to specify absence of default
> -      values and annotations.
> +      A special class-level marker to specify absence of default values and
> +      annotations.
>
>     .. attribute:: Parameter.name
>
> -      The name of the parameter as a string. Must be a valid python identifier
> -      name (with the exception of ``POSITIONAL_ONLY`` parameters, which can
> -      have it set to ``None``.)
> +      The name of the parameter as a string.  Must be a valid python identifier
> +      name (with the exception of ``POSITIONAL_ONLY`` parameters, which can have
> +      it set to ``None``).
>
>     .. attribute:: Parameter.default
>
> -      The default value for the parameter. If the parameter has no default
> +      The default value for the parameter.  If the parameter has no default
>        value, this attribute is set to :attr:`Parameter.empty`.
>
>     .. attribute:: Parameter.annotation
>
> -      The annotation for the parameter. If the parameter has no annotation,
> +      The annotation for the parameter.  If the parameter has no annotation,
>        this attribute is set to :attr:`Parameter.empty`.
>
>     .. attribute:: Parameter.kind
>
> -      Describes how argument values are bound to the parameter.
> -      Possible values (accessible via :class:`Parameter`, like
> -      ``Parameter.KEYWORD_ONLY``):
> +      Describes how argument values are bound to the parameter.  Possible values
> +      (accessible via :class:`Parameter`, like ``Parameter.KEYWORD_ONLY``):
>
>        +------------------------+----------------------------------------------+
>        |    Name                | Meaning                                      |
> @@ -577,10 +567,10 @@
>
>     .. method:: Parameter.replace(*, [name], [kind], [default], [annotation])
>
> -      Creates a new Parameter instance based on the instance replaced was
> -      invoked on. To override a :class:`Parameter` attribute, pass the
> -      corresponding argument. To remove a default value or/and an annotation
> -      from a Parameter, pass :attr:`Parameter.empty`.
> +      Create a new Parameter instance based on the instance replaced was invoked
> +      on.  To override a :class:`Parameter` attribute, pass the corresponding
> +      argument.  To remove a default value or/and an annotation from a
> +      Parameter, pass :attr:`Parameter.empty`.
>
>        ::
>
> @@ -604,18 +594,18 @@
>     .. attribute:: BoundArguments.arguments
>
>        An ordered, mutable mapping (:class:`collections.OrderedDict`) of
> -      parameters' names to arguments' values. Contains only explicitly
> -      bound arguments.  Changes in :attr:`arguments` will reflect in
> -      :attr:`args` and :attr:`kwargs`.
> +      parameters' names to arguments' values.  Contains only explicitly bound
> +      arguments.  Changes in :attr:`arguments` will reflect in :attr:`args` and
> +      :attr:`kwargs`.
>
> -      Should be used in conjunction with :attr:`Signature.parameters` for
> -      any arguments processing purposes.
> +      Should be used in conjunction with :attr:`Signature.parameters` for any
> +      argument processing purposes.
>
>        .. note::
>
>           Arguments for which :meth:`Signature.bind` or
>           :meth:`Signature.bind_partial` relied on a default value are skipped.
> -         However, if needed, it's easy to include them
> +         However, if needed, it is easy to include them.
>
>        ::
>
> @@ -638,15 +628,16 @@
>
>     .. attribute:: BoundArguments.args
>
> -      Tuple of positional arguments values. Dynamically computed
> -      from the :attr:`arguments` attribute.
> +      A tuple of positional arguments values.  Dynamically computed from the
> +      :attr:`arguments` attribute.
>
>     .. attribute:: BoundArguments.kwargs
>
> -      Dict of keyword arguments values. Dynamically computed
> -      from the :attr:`arguments` attribute.
> +      A dict of keyword arguments values.  Dynamically computed from the
> +      :attr:`arguments` attribute.
>
> -   :attr:`args` and :attr:`kwargs` properties can be used to invoke functions::
> +   The :attr:`args` and :attr:`kwargs` properties can be used to invoke
> +   functions::
>
>        def test(a, *, b):
>           ...
> @@ -656,6 +647,12 @@
>        test(*ba.args, **ba.kwargs)
>
>
> +.. seealso::
> +
> +   :pep:`362` - Function Signature Object.
> +      The detailed specification, implementation details and examples.
> +
> +
>  .. _inspect-classes-functions:
>
>  Classes and functions
>
> --
> Repository URL: http://hg.python.org/cpython
>
> _______________________________________________
> Python-checkins mailing list
> Python-checkins at python.org
> http://mail.python.org/mailman/listinfo/python-checkins
>



-- 
Thanks,
Andrew Svetlov


More information about the Python-Dev mailing list