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 d587272 by Victor Stinner (Batuhan Taşkaya) in branch 'master':
bpo-38316: Fix co_stacksize documentation (GH-16983)
d587272

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

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

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