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.

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.

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

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

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

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