Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitca11aec

Browse files
authored
[3.12]gh-101100: Improve documentation of code object attributes (#112781) (#112816)
(cherry-picked from commite9707d3)
1 parentaf7cf38 commitca11aec

File tree

9 files changed

+109
-51
lines changed

9 files changed

+109
-51
lines changed

‎Doc/c-api/function.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,15 +37,15 @@ There are a few functions specific to Python functions.
3737
The function's docstring and name are retrieved from the code object. *__module__*
3838
is retrieved from *globals*. The argument defaults, annotations and closure are
3939
set to ``NULL``. *__qualname__* is set to the same value as the code object's
40-
``co_qualname`` field.
40+
:attr:`~codeobject.co_qualname` field.
4141
4242
4343
..c:function:: PyObject*PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
4444
4545
As:c:func:`PyFunction_New`, but also allows setting the function object's
4646
``__qualname__`` attribute. *qualname* should be a unicode object or ``NULL``;
4747
if ``NULL``, the ``__qualname__`` attribute is set to the same value as the
48-
code object's``co_qualname`` field.
48+
code object's:attr:`~codeobject.co_qualname` field.
4949
5050
..versionadded::3.3
5151

‎Doc/c-api/import.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@ Importing Modules
138138
:class:`~importlib.machinery.SourceFileLoader` otherwise.
139139
140140
The module's :attr:`__file__` attribute will be set to the code object's
141-
:attr:`!co_filename`. If applicable, :attr:`__cached__` will also
141+
:attr:`~codeobject.co_filename`. If applicable, :attr:`__cached__` will also
142142
be set.
143143
144144
This function will reload the module if it was already imported. See

‎Doc/library/dis.rst

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -324,8 +324,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
324324
Line numbers can be decreasing. Before, they were always increasing.
325325

326326
..versionchanged::3.10
327-
The:pep:`626` ``co_lines`` method is used instead of the ``co_firstlineno``
328-
and ``co_lnotab`` attributes of the code object.
327+
The:pep:`626` ``co_lines`` method is used instead of the
328+
:attr:`~codeobject.co_firstlineno` and:attr:`~codeobject.co_lnotab`
329+
attributes of the code object.
329330

330331

331332
..function::findlabels(code)
@@ -889,13 +890,13 @@ iterations of the loop.
889890
..opcode::STORE_NAME (namei)
890891

891892
Implements ``name = STACK.pop()``. *namei* is the index of *name* in the attribute
892-
:attr:`!co_names` of the:ref:`code object<code-objects>`.
893+
:attr:`~codeobject.co_names` of the:ref:`code object<code-objects>`.
893894
The compiler tries to use:opcode:`STORE_FAST` or:opcode:`STORE_GLOBAL` if possible.
894895

895896

896897
..opcode::DELETE_NAME (namei)
897898

898-
Implements ``del name``, where *namei* is the index into:attr:`!co_names`
899+
Implements ``del name``, where *namei* is the index into:attr:`~codeobject.co_names`
899900
attribute of the:ref:`code object<code-objects>`.
900901

901902

@@ -935,7 +936,7 @@ iterations of the loop.
935936
value = STACK.pop()
936937
obj.name = value
937938

938-
where *namei* is the index of name in:attr:`!co_names` of the
939+
where *namei* is the index of name in:attr:`~codeobject.co_names` of the
939940
:ref:`code object<code-objects>`.
940941

941942
..opcode::DELETE_ATTR (namei)
@@ -945,7 +946,7 @@ iterations of the loop.
945946
obj = STACK.pop()
946947
del obj.name
947948

948-
where *namei* is the index of name into:attr:`!co_names` of the
949+
where *namei* is the index of name into:attr:`~codeobject.co_names` of the
949950
:ref:`code object<code-objects>`.
950951

951952

@@ -1308,7 +1309,7 @@ iterations of the loop.
13081309
Pushes a reference to the object the cell contains on the stack.
13091310

13101311
..versionchanged::3.11
1311-
``i`` is no longer offset by the length of``co_varnames``.
1312+
``i`` is no longer offset by the length of:attr:`~codeobject.co_varnames`.
13121313

13131314

13141315
..opcode::LOAD_FROM_DICT_OR_DEREF (i)
@@ -1330,7 +1331,7 @@ iterations of the loop.
13301331
storage.
13311332

13321333
..versionchanged::3.11
1333-
``i`` is no longer offset by the length of``co_varnames``.
1334+
``i`` is no longer offset by the length of:attr:`~codeobject.co_varnames`.
13341335

13351336

13361337
..opcode::DELETE_DEREF (i)
@@ -1341,7 +1342,7 @@ iterations of the loop.
13411342
..versionadded::3.2
13421343

13431344
..versionchanged::3.11
1344-
``i`` is no longer offset by the length of``co_varnames``.
1345+
``i`` is no longer offset by the length of:attr:`~codeobject.co_varnames`.
13451346

13461347

13471348
..opcode::COPY_FREE_VARS (n)

‎Doc/library/inspect.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1579,8 +1579,8 @@ updated as expected:
15791579
Code Objects Bit Flags
15801580
----------------------
15811581

1582-
Python code objects have a``co_flags`` attribute, which is a bitmap of
1583-
the following flags:
1582+
Python code objects have a:attr:`~codeobject.co_flags` attribute,
1583+
which is a bitmap ofthe following flags:
15841584

15851585
..data::CO_OPTIMIZED
15861586

‎Doc/reference/datamodel.rst

Lines changed: 84 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1077,57 +1077,111 @@ indirectly) to mutable objects.
10771077
single: co_freevars (code object attribute)
10781078
single: co_qualname (code object attribute)
10791079

1080-
Special read-only attributes::attr:`co_name` gives the function name;
1081-
:attr:`co_qualname` gives the fully qualified function name;
1082-
:attr:`co_argcount` is the total number of positional arguments
1083-
(including positional-only arguments and arguments with default values);
1084-
:attr:`co_posonlyargcount` is the number of positional-only arguments
1085-
(including arguments with default values);:attr:`co_kwonlyargcount` is
1086-
the number of keyword-only arguments (including arguments with default
1087-
values);:attr:`co_nlocals` is the number of local variables used by the
1088-
function (including arguments);:attr:`co_varnames` is a tuple containing
1089-
the names of the local variables (starting with the argument names);
1090-
:attr:`co_cellvars` is a tuple containing the names of local variables
1091-
that are referenced by nested functions;:attr:`co_freevars` is a tuple
1092-
containing the names of free variables;:attr:`co_code` is a string
1093-
representing the sequence of bytecode instructions;:attr:`co_consts` is
1094-
a tuple containing the literals used by the bytecode;:attr:`co_names` is
1095-
a tuple containing the names used by the bytecode;:attr:`co_filename` is
1096-
the filename from which the code was compiled;:attr:`co_firstlineno` is
1097-
the first line number of the function;:attr:`co_lnotab` is a string
1098-
encoding the mapping from bytecode offsets to line numbers (for details
1099-
see the source code of the interpreter, is deprecated since 3.12
1100-
and may be removed in 3.14);:attr:`co_stacksize` is the
1101-
required stack size;:attr:`co_flags` is an integer encoding a number
1102-
of flags for the interpreter.
1080+
Special read-only attributes
1081+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1082+
1083+
..list-table::
1084+
1085+
* - .. attribute:: codeobject.co_name
1086+
- The function name
1087+
1088+
* - .. attribute:: codeobject.co_qualname
1089+
- The fully qualified function name
1090+
1091+
* - .. attribute:: codeobject.co_argcount
1092+
- The total number of positional:term:`parameters <parameter>`
1093+
(including positional-only parameters and parameters with default values)
1094+
that the function has
1095+
1096+
* - .. attribute:: codeobject.co_posonlyargcount
1097+
- The number of positional-only:term:`parameters <parameter>`
1098+
(including arguments with default values) that the function has
1099+
1100+
* - .. attribute:: codeobject.co_kwonlyargcount
1101+
- The number of keyword-only:term:`parameters <parameter>`
1102+
(including arguments with default values) that the function has
1103+
1104+
* - .. attribute:: codeobject.co_nlocals
1105+
- The number of:ref:`local variables<naming>` used by the function
1106+
(including parameters)
1107+
1108+
* - .. attribute:: codeobject.co_varnames
1109+
- A:class:`tuple` containing the names of the local variables in the
1110+
function (starting with the parameter names)
1111+
1112+
* - .. attribute:: codeobject.co_cellvars
1113+
- A:class:`tuple` containing the names of:ref:`local variables<naming>`
1114+
that are referenced by nested functions inside the function
1115+
1116+
* - .. attribute:: codeobject.co_freevars
1117+
- A:class:`tuple` containing the names of free variables in the function
1118+
1119+
* - .. attribute:: codeobject.co_code
1120+
- A string representing the sequence of:term:`bytecode` instructions in
1121+
the function
1122+
1123+
* - .. attribute:: codeobject.co_consts
1124+
- A:class:`tuple` containing the literals used by the:term:`bytecode` in
1125+
the function
1126+
1127+
* - .. attribute:: codeobject.co_names
1128+
- A:class:`tuple` containing the names used by the:term:`bytecode` in
1129+
the function
1130+
1131+
* - .. attribute:: codeobject.co_filename
1132+
- The name of the file from which the code was compiled
1133+
1134+
* - .. attribute:: codeobject.co_firstlineno
1135+
- The line number of the first line of the function
1136+
1137+
* - .. attribute:: codeobject.co_lnotab
1138+
- A string encoding the mapping from:term:`bytecode` offsets to line
1139+
numbers. For details, see the source code of the interpreter.
1140+
1141+
..deprecated::3.12
1142+
This attribute of code objects is deprecated, and may be removed in
1143+
Python 3.14.
1144+
1145+
* - .. attribute:: codeobject.co_stacksize
1146+
- The required stack size of the code object
1147+
1148+
* - .. attribute:: codeobject.co_flags
1149+
- An:class:`integer <int>` encoding a number of flags for the
1150+
interpreter.
11031151

11041152
..index::pair: object; generator
11051153

1106-
The following flag bits are defined for:attr:`co_flags`: bit ``0x04`` is set if
1154+
The following flag bits are defined for:attr:`~codeobject.co_flags`:
1155+
bit ``0x04`` is set if
11071156
the function uses the ``*arguments`` syntax to accept an arbitrary number of
11081157
positional arguments; bit ``0x08`` is set if the function uses the
11091158
``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
1110-
if the function is a generator.
1159+
if the function is a generator. See:ref:`inspect-module-co-flags` for details
1160+
on the semantics of each flags that might be present.
11111161

11121162
Future feature declarations (``from __future__ import division``) also use bits
1113-
in:attr:`co_flags` to indicate whether a code object was compiled with a
1163+
in:attr:`~codeobject.co_flags` to indicate whether a code object was compiled with a
11141164
particular feature enabled: bit ``0x2000`` is set if the function was compiled
11151165
with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
11161166
versions of Python.
11171167

1118-
Other bits in:attr:`co_flags` are reserved for internal use.
1168+
Other bits in:attr:`~codeobject.co_flags` are reserved for internal use.
11191169

11201170
..index::single: documentation string
11211171

1122-
If a code object represents a function, the first item in:attr:`co_consts` is
1172+
If a code object represents a function, the first item in
1173+
:attr:`~codeobject.co_consts` is
11231174
the documentation string of the function, or ``None`` if undefined.
11241175

1176+
The:meth:`!co_positions` method
1177+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1178+
11251179
..method::codeobject.co_positions()
11261180

1127-
Returns an iterable over the source code positions of each bytecode
1181+
Returns an iterable over the source code positions of each:term:`bytecode`
11281182
instruction in the code object.
11291183

1130-
The iterator returnstuples containing the ``(start_line, end_line,
1184+
The iterator returns:class:`tuple`\s containing the ``(start_line, end_line,
11311185
start_column, end_column)``. The *i-th* tuple corresponds to the
11321186
position of the source code that compiled to the *i-th* instruction.
11331187
Column information is 0-indexed utf-8 byte offsets on the given source

‎Doc/whatsnew/2.7.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2405,7 +2405,7 @@ Other Changes and Fixes
24052405
:issue:`5464`.)
24062406

24072407
* When importing a module from a:file:`.pyc` or:file:`.pyo` file
2408-
with an existing:file:`.py` counterpart, the:attr:`co_filename`
2408+
with an existing:file:`.py` counterpart, the:attr:`~codeobject.co_filename`
24092409
attributes of the resulting code objects are overwritten when the
24102410
original filename is obsolete. This can happen if the file has been
24112411
renamed, moved, or is accessed through different paths. (Patch by

‎Doc/whatsnew/3.10.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -402,7 +402,8 @@ Tracing events, with the correct line number, are generated for all lines of cod
402402
The :attr:`~frame.f_lineno` attribute of frame objects will always contain the
403403
expected line number.
404404
405-
The``co_lnotab`` attribute of code objectsis deprecatedand will be removedin3.12.
405+
The :attr:`~codeobject.co_lnotab` attribute of code objectsis deprecatedand
406+
will be removedin3.12.
406407
Code that needs to convertfrom offset to line number should use the new``co_lines()`` method instead.
407408
408409
PEP634: Structural Pattern Matching

‎Doc/whatsnew/3.12.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1323,7 +1323,8 @@ Deprecated
13231323
``int``, convert to int explicitly: ``~int(x)``. (Contributed by Tim Hoffmann
13241324
in:gh:`103487`.)
13251325

1326-
* Accessing ``co_lnotab`` on code objects was deprecated in Python 3.10 via:pep:`626`,
1326+
* Accessing:attr:`~codeobject.co_lnotab` on code objects was deprecated in
1327+
Python 3.10 via:pep:`626`,
13271328
but it only got a proper:exc:`DeprecationWarning` in 3.12,
13281329
therefore it will be removed in 3.14.
13291330
(Contributed by Nikita Sobolev in:gh:`101866`.)
@@ -1430,7 +1431,7 @@ and will be removed in Python 3.14.
14301431

14311432
* The ``__package__`` and ``__cached__`` attributes on module objects.
14321433

1433-
* The``co_lnotab`` attribute of code objects.
1434+
* The:attr:`~codeobject.co_lnotab` attribute of code objects.
14341435

14351436
Pending Removal in Python 3.15
14361437
------------------------------

‎Doc/whatsnew/3.6.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2160,14 +2160,15 @@ Changes in the Python API
21602160
*:c:func:`PyErr_SetImportError` now sets:exc:`TypeError` when its **msg**
21612161
argument is not set. Previously only ``NULL`` was returned.
21622162

2163-
* The format of the ``co_lnotab`` attribute of code objects changed to support
2163+
* The format of the:attr:`~codeobject.co_lnotab` attribute of code objects
2164+
changed to support
21642165
a negative line number delta. By default, Python does not emit bytecode with
21652166
a negative line number delta. Functions using:attr:`frame.f_lineno`,
21662167
``PyFrame_GetLineNumber()`` or ``PyCode_Addr2Line()`` are not affected.
2167-
Functions directly decoding``co_lnotab`` should be updated to use a signed
2168+
Functions directly decoding:attr:`!co_lnotab` should be updated to use a signed
21682169
8-bit integer type for the line number delta, but this is only required to
21692170
support applications using a negative line number delta. See
2170-
``Objects/lnotab_notes.txt`` for the``co_lnotab`` format and how to decode
2171+
``Objects/lnotab_notes.txt`` for the:attr:`!co_lnotab` format and how to decode
21712172
it, and see the:pep:`511` for the rationale.
21722173

21732174
* The functions in the:mod:`compileall` module now return booleans instead

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp