Thanks to visit codestin.com
Credit goes to github.com

Skip to content

gh-122058: Lib/inspect: Update docstrings for isfunction, isgenerator, isframe, iscode. #122059

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Aug 6, 2024
Merged

gh-122058: Lib/inspect: Update docstrings for isfunction, isgenerator, isframe, iscode. #122059

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
380347c
Update docstrings
Eclips4 Jul 20, 2024
7c66f21
Fix trailing whitespace
Eclips4 Jul 20, 2024
6113f17
Address review
Eclips4 Jul 22, 2024
506da65
Update Lib/inspect.py
Eclips4 Jul 27, 2024
c5966f6
Update Lib/inspect.py
Eclips4 Jul 27, 2024
d6b3439
Address review
Eclips4 Jul 27, 2024
08e4b6b
Fix linting issue
Eclips4 Jul 27, 2024
f5be7f4
Update Lib/inspect.py
Eclips4 Jul 27, 2024
0d7fb34
Fix frame.clear docstring
Eclips4 Jul 27, 2024
c413656
Address Victor's review
Eclips4 Jul 27, 2024
54f3562
Fix linting issues
Eclips4 Jul 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions Doc/library/inspect.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,19 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
| | f_trace | tracing function for this |
| | | frame, or ``None`` |
+-----------------+-------------------+---------------------------+
| | f_trace_lines | indicate whether a |
| | | tracing event is |
| | | triggered for each source |
| | | source line |
+-----------------+-------------------+---------------------------+
| | f_trace_opcodes | indicate whether |
| | | per-opcode events are |
| | | requested |
+-----------------+-------------------+---------------------------+
| | clear() | used to clear all |
| | | references to local |
| | | variables |
+-----------------+-------------------+---------------------------+
| code | co_argcount | number of arguments (not |
| | | including keyword only |
| | | arguments, \* or \*\* |
Expand Down Expand Up @@ -214,6 +227,18 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
| | | arguments and local |
| | | variables |
+-----------------+-------------------+---------------------------+
| | co_lines() | returns an iterator that |
| | | yields successive |
| | | bytecode ranges |
+-----------------+-------------------+---------------------------+
| | co_positions() | returns an iterator of |
| | | source code positions for |
| | | each bytecode instruction |
+-----------------+-------------------+---------------------------+
| | replace() | returns a copy of the |
| | | code object with new |
| | | values |
+-----------------+-------------------+---------------------------+
| generator | __name__ | name |
+-----------------+-------------------+---------------------------+
| | __qualname__ | qualified name |
Expand Down
33 changes: 24 additions & 9 deletions Lib/inspect.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -378,11 +378,16 @@ def isfunction(object):
Function objects provide these attributes:
__doc__ documentation string
__name__ name with which this function was defined
__qualname__ qualified name of this function
__module__ name of the module the function was defined in or None
__code__ code object containing compiled function bytecode
__defaults__ tuple of any default values for arguments
__globals__ global namespace in which this function was defined
__annotations__ dict of parameter annotations
__kwdefaults__ dict of keyword only parameters with defaults"""
__kwdefaults__ dict of keyword only parameters with defaults
__dict__ namespace which is supporting arbitrary function attributes
__closure__ a tuple of cells or None
__type_params__ tuple of type parameters"""
return isinstance(object, types.FunctionType)

def _has_code_flag(f, flag):
Expand Down Expand Up @@ -447,17 +452,18 @@ def isgenerator(object):
"""Return true if the object is a generator.

Generator objects provide these attributes:
__iter__ defined to support iteration over container
close raises a new GeneratorExit exception inside the
generator to terminate the iteration
gi_code code object
gi_frame frame object or possibly None once the generator has
been exhausted
gi_running set to 1 when generator is executing, 0 otherwise
next return the next item from the container
send resumes the generator and "sends" a value that becomes
gi_yieldfrom object being iterated by yield from or None

__iter__() defined to support iteration over container
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI: I've grouped methods, but I'm not sure if __iter__ really needs to be here. If __iter__ is here, then we also need to add __next__. Our inspect documentation does not mention the __next__ method for generators. In my opinion, we should remove this method from the docstring since it does not make things clearer.

close() raises a new GeneratorExit exception inside the
generator to terminate the iteration
send() resumes the generator and "sends" a value that becomes
the result of the current yield-expression
throw used to raise an exception inside the generator"""
throw() used to raise an exception inside the generator"""
return isinstance(object, types.GeneratorType)

def iscoroutine(object):
Expand Down Expand Up @@ -492,7 +498,11 @@ def isframe(object):
f_lasti index of last attempted instruction in bytecode
f_lineno current line number in Python source code
f_locals local namespace seen by this frame
f_trace tracing function for this frame, or None"""
f_trace tracing function for this frame, or None
f_trace_lines is a tracing event triggered for each source line?
f_trace_opcodes are per-opcode events being requested?

clear() used to clear all references to local variables"""
return isinstance(object, types.FrameType)

def iscode(object):
Expand All @@ -517,7 +527,12 @@ def iscode(object):
co_names tuple of names other than arguments and function locals
co_nlocals number of local variables
co_stacksize virtual machine stack space required
co_varnames tuple of names of arguments and local variables"""
co_varnames tuple of names of arguments and local variables
co_qualname fully qualified function name

co_lines() returns an iterator that yields successive bytecode ranges
co_positions() returns an iterator of source code positions for each bytecode instruction
replace() returns a copy of the code object with a new values"""
return isinstance(object, types.CodeType)

def isbuiltin(object):
Expand Down
2 changes: 1 addition & 1 deletion Objects/frameobject.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1701,7 +1701,7 @@ frame_clear(PyFrameObject *f, PyObject *Py_UNUSED(ignored))
}

PyDoc_STRVAR(clear__doc__,
"F.clear(): clear most references held by the frame");
"F.clear(): clear all references held by the frame");

static PyObject *
frame_sizeof(PyFrameObject *f, PyObject *Py_UNUSED(ignored))
Expand Down
Loading