classification
Title: docs: Code object's "co_stacksize" field is described with mistake
Type: Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: ammar2, docs@python, miss-islington, pfalcon, vstinner
Priority: normal Keywords: patch

Created on 2019-09-29 20:34 by pfalcon, last changed 2019-12-19 14:51 by vstinner. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 16983 merged BTaskaya, 2019-10-29 10:02
PR 17660 merged BTaskaya, 2019-12-19 14:36
PR 17661 merged BTaskaya, 2019-12-19 14:38
Messages (6)
msg353508 - (view) Author: Paul Sokolovsky (pfalcon) * Date: 2019-09-29 20:34
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.
msg353511 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2019-09-29 21:47
Yeah, that parenthesized bit seems a bit weird: co_stacksize really has nothing to do with the number of variables, it's just that certain opcodes (https://docs.python.org/3/library/dis.html#python-bytecode-instructions) push and pop off the stack, co_stacksize is just the largest the stack will ever grow to from these operations.

For example:

  >>> def f():
  ...   a = 1
  ...   b = 2
  ...   c = 3
  ...   g(a, b, c)
  ...
  >>> f.__code__.co_stacksize
  4

and

  >>> def g():
  ...   g(1, 2, 3)
  ...
  >>> g.__code__.co_stacksize
  4

have the exact same stack size despite differences in variables because the call to `g` has to push all 3 operands (and g itself) onto the stack.
msg358454 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-12-15 22:02
New changeset d587272fe3b0fcad2f23a490e76f9f82ca7d64ef by Victor Stinner (Batuhan Taşkaya) in branch 'master':
 bpo-38316: Fix co_stacksize documentation (GH-16983)
https://github.com/python/cpython/commit/d587272fe3b0fcad2f23a490e76f9f82ca7d64ef
msg358681 - (view) Author: miss-islington (miss-islington) Date: 2019-12-19 14:41
New changeset 917419f58b2869d71691c5ba54a9e02e5dcf73b2 by Miss Islington (bot) (Batuhan Taşkaya) in branch '3.7':
[3.7] bpo-38316: Fix co_stacksize documentation (GH-16983). (GH-17660)
https://github.com/python/cpython/commit/917419f58b2869d71691c5ba54a9e02e5dcf73b2
msg358682 - (view) Author: miss-islington (miss-islington) Date: 2019-12-19 14:44
New changeset eba61f33d60cc63e35d5f5fcada837a66c89774a by Miss Islington (bot) (Batuhan Taşkaya) in branch '3.8':
[3.8] bpo-38316: Fix co_stacksize documentation (GH-16983) (GH-17661)
https://github.com/python/cpython/commit/eba61f33d60cc63e35d5f5fcada837a66c89774a
msg358683 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-12-19 14:51
Thanks Paul Sokolovsky for the bug report and thanks Batuhan Taşkaya for the fix ;-)
History
Date User Action Args
2019-12-19 14:51:51vstinnersetstatus: open -> closed
resolution: fixed
messages: + msg358683

stage: patch review -> resolved
2019-12-19 14:44:33miss-islingtonsetmessages: + msg358682
2019-12-19 14:41:54miss-islingtonsetnosy: + miss-islington
messages: + msg358681
2019-12-19 14:38:40BTaskayasetpull_requests: + pull_request17129
2019-12-19 14:36:08BTaskayasetpull_requests: + pull_request17128
2019-12-15 22:02:50vstinnersetnosy: + vstinner
messages: + msg358454
2019-10-29 10:02:07BTaskayasetkeywords: + patch
stage: patch review
pull_requests: + pull_request16509
2019-10-05 05:52:51terry.reedysetversions: - Python 3.5, Python 3.6
2019-09-29 21:47:58ammar2setnosy: + ammar2
messages: + msg353511
2019-09-29 20:34:54pfalconcreate