Thank you for review. On Tue, Aug 14, 2012 at 10:45 AM, georg.brandl <python-check...@python.org> wrote: > http://hg.python.org/cpython/rev/e1e7d628c0b9 > changeset: 78560:e1e7d628c0b9 > user: Georg Brandl <ge...@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-check...@python.org > http://mail.python.org/mailman/listinfo/python-checkins >
-- Thanks, Andrew Svetlov _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
