Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(18278)

Side by Side Diff: Doc/library/inspect.rst

Issue 20691: inspect.signature: Consider exposing 'follow_wrapper_chains' option in public API
Patch Set: Created 4 years, 4 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | Lib/inspect.py » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`inspect` --- Inspect live objects 1 :mod:`inspect` --- Inspect live objects
2 ======================================= 2 =======================================
3 3
4 .. module:: inspect 4 .. module:: inspect
5 :synopsis: Extract information and source code from live objects. 5 :synopsis: Extract information and source code from live objects.
6 .. moduleauthor:: Ka-Ping Yee <ping@lfw.org> 6 .. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
7 .. sectionauthor:: Ka-Ping Yee <ping@lfw.org> 7 .. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
8 8
9 **Source code:** :source:`Lib/inspect.py` 9 **Source code:** :source:`Lib/inspect.py`
10 10
(...skipping 413 matching lines...) Expand 10 before | Expand all | Expand 10 after
424 424
425 Introspecting callables with the Signature object 425 Introspecting callables with the Signature object
426 ------------------------------------------------- 426 -------------------------------------------------
427 427
428 .. versionadded:: 3.3 428 .. versionadded:: 3.3
429 429
430 The Signature object represents the call signature of a callable object and its 430 The Signature object represents the call signature of a callable object and its
431 return annotation. To retrieve a Signature object, use the :func:`signature` 431 return annotation. To retrieve a Signature object, use the :func:`signature`
432 function. 432 function.
433 433
434 .. function:: signature(callable) 434 .. function:: signature(callable, \*, follow_wrapped=True)
435 435
436 Return a :class:`Signature` object for the given ``callable``:: 436 Return a :class:`Signature` object for the given ``callable``::
437 437
438 >>> from inspect import signature 438 >>> from inspect import signature
439 >>> def foo(a, *, b:int, **kwargs): 439 >>> def foo(a, *, b:int, **kwargs):
440 ... pass 440 ... pass
441 441
442 >>> sig = signature(foo) 442 >>> sig = signature(foo)
443 443
444 >>> str(sig) 444 >>> str(sig)
445 '(a, *, b:int, **kwargs)' 445 '(a, *, b:int, **kwargs)'
446 446
447 >>> str(sig.parameters['b']) 447 >>> str(sig.parameters['b'])
448 'b:int' 448 'b:int'
449 449
450 >>> sig.parameters['b'].annotation 450 >>> sig.parameters['b'].annotation
451 <class 'int'> 451 <class 'int'>
452 452
453 Accepts a wide range of python callables, from plain functions and classes to 453 Accepts a wide range of python callables, from plain functions and classes to
454 :func:`functools.partial` objects. 454 :func:`functools.partial` objects.
455 455
456 Raises :exc:`ValueError` if no signature can be provided, and 456 Raises :exc:`ValueError` if no signature can be provided, and
457 :exc:`TypeError` if that type of object is not supported. 457 :exc:`TypeError` if that type of object is not supported.
458
459 .. versionadded:: 3.5
460 ``follow_wrapped`` parameter. Pass ``False`` to get a signature of
461 ``callable`` specifically (``callable.__wrapped__`` will not be used to
462 unwrap decorated callables.)
458 463
459 .. note:: 464 .. note::
460 465
461 Some callables may not be introspectable in certain implementations of 466 Some callables may not be introspectable in certain implementations of
462 Python. For example, in CPython, some built-in functions defined in 467 Python. For example, in CPython, some built-in functions defined in
463 C provide no metadata about their arguments. 468 C provide no metadata about their arguments.
464 469
465 470
466 .. class:: Signature(parameters=None, \*, return_annotation=Signature.empty) 471 .. class:: Signature(parameters=None, \*, return_annotation=Signature.empty)
467 472
(...skipping 53 matching lines...) Expand 10 before | Expand all | Expand 10 after
521 526
522 :: 527 ::
523 528
524 >>> def test(a, b): 529 >>> def test(a, b):
525 ... pass 530 ... pass
526 >>> sig = signature(test) 531 >>> sig = signature(test)
527 >>> new_sig = sig.replace(return_annotation="new return anno") 532 >>> new_sig = sig.replace(return_annotation="new return anno")
528 >>> str(new_sig) 533 >>> str(new_sig)
529 "(a, b) -> 'new return anno'" 534 "(a, b) -> 'new return anno'"
530 535
531 .. classmethod:: Signature.from_callable(obj) 536 .. classmethod:: Signature.from_callable(obj, \*, follow_wrapped=True)
532 537
533 Return a :class:`Signature` (or its subclass) object for a given callable 538 Return a :class:`Signature` (or its subclass) object for a given callable
534 ``obj``. This method simplifies subclassing of :class:`Signature`: 539 ``obj``. Pass ``follow_wrapped=False`` to get a signature of ``obj``
540 without unwrapping its ``__wrapped__`` chain.
535 541
536 :: 542 This method simplifies subclassing of :class:`Signature`::
537 543
538 class MySignature(Signature): 544 class MySignature(Signature):
539 pass 545 pass
540 sig = MySignature.from_callable(min) 546 sig = MySignature.from_callable(min)
541 assert isinstance(sig, MySignature) 547 assert isinstance(sig, MySignature)
542 548
543 .. versionadded:: 3.5 549 .. versionadded:: 3.5
544 550
545 551
546 .. class:: Parameter(name, kind, \*, default=Parameter.empty, annotation=Paramet er.empty) 552 .. class:: Parameter(name, kind, \*, default=Parameter.empty, annotation=Paramet er.empty)
(...skipping 551 matching lines...) Expand 10 before | Expand all | Expand 10 after
1098 1104
1099 .. program:: inspect 1105 .. program:: inspect
1100 1106
1101 By default, accepts the name of a module and prints the source of that 1107 By default, accepts the name of a module and prints the source of that
1102 module. A class or function within the module can be printed instead by 1108 module. A class or function within the module can be printed instead by
1103 appended a colon and the qualified name of the target object. 1109 appended a colon and the qualified name of the target object.
1104 1110
1105 .. cmdoption:: --details 1111 .. cmdoption:: --details
1106 1112
1107 Print information about the specified object rather than the source code 1113 Print information about the specified object rather than the source code
OLDNEW
« no previous file with comments | « no previous file | Lib/inspect.py » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+