docs: Code object's "co_stacksize" field is described with mistake #82497

Activity

1. pfalcon commented on Sep 29, 2019

   

   pfalconmannequin

   on Sep 29, 2019

   MannequinAuthor

   More actions

   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.
2. pfalcon

   added

   3.7 (EOL)end of lifeend of life

   3.8 (EOL)end of lifeend of life

   3.9 (EOL)end of lifeend of life

   on Sep 29, 2019
3. pfalcon

   assigned

   docspython

   on Sep 29, 2019
4. pfalcon

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Sep 29, 2019
5. ammaraskar commented on Sep 29, 2019

   

   ammaraskar

   on Sep 29, 2019

   Member

   More actions

   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.
6. vstinner commented on Dec 15, 2019

   

   vstinner

   on Dec 15, 2019

   Member

   More actions

   New changeset d587272 by Victor Stinner (Batuhan Taşkaya) in branch 'master':
   bpo-38316: Fix co_stacksize documentation (GH-16983)
   d587272
7. miss-islington commented on Dec 19, 2019

   

   miss-islington

   on Dec 19, 2019

   Contributor

   More actions

   New changeset 917419f by Miss Islington (bot) (Batuhan Taşkaya) in branch '3.7':
   [3.7] bpo-38316: Fix co_stacksize documentation (GH-16983). (GH-17660)
   917419f
8. miss-islington commented on Dec 19, 2019

   

   miss-islington

   on Dec 19, 2019

   Contributor

   More actions

   New changeset eba61f3 by Miss Islington (bot) (Batuhan Taşkaya) in branch '3.8':
   [3.8] bpo-38316: Fix co_stacksize documentation (GH-16983) (GH-17661)
   eba61f3
9. vstinner commented on Dec 19, 2019

   

   vstinner

   on Dec 19, 2019

   Member

   More actions

   Thanks Paul Sokolovsky for the bug report and thanks Batuhan Taşkaya for the fix ;-)
10. vstinner

    closed this as completedon Dec 19, 2019
11. ezio-melotti

    transferred this issue fromon Apr 10, 2022