[issue38316] docs: Code object's "co_stacksize" field is described with mistake

[Paul Sokolovsky]

New submission from Paul Sokolovsky <pfalcon at users.sourceforge.net>:

CPython's Data Model -> Internal types -> Code objects, direct link as of version 3.7 is: https://docs.python.org/3.7/reference/datamodel.html?highlight=co_stacksize#index-55 , states following:

* "co_nlocals is the number of local variables used by the function (including arguments);"
* "co_stacksize is the required stack size (including local variables);"

However, practical checking shows that co_stacksize is the required stack size WITHOUT local variables. One could argue about the meaning of "local variables" in the description of co_stacksize above, saying that what is meant is temporary stack variables of something. That's why I quoted above co_nlocals description too, it clearly shows that local variebles are local function variables (include functions args), and nothing else.

Code to reproduce:

======
def func():
    a = 1
    b = 2
    c = 3

print("co_stacksize", func.__code__.co_stacksize)
print("co_nlocals", func.__code__.co_nlocals)
======

Result of running:
======
$ python3.7 script_under_test.py 
co_stacksize 1
co_nlocals 3
======

Clearly, co_stacksize doesn't include the size of local vars, or it would have been larger than co_nlocals in printout.

----------
assignee: docs at python
components: Documentation
messages: 353508
nosy: docs at python, pfalcon
priority: normal
severity: normal
status: open
title: docs: Code object's "co_stacksize" field is described with mistake
versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38316>
_______________________________________