Misleading gc docs

[bobzinin]

Documentation

According to gc documentation Python 3.14 and beyond has only 2 generations:
Changed in version 3.14: Generation 1 is removed

However, in gc.set_threshold() we ignore the threshold2:
Changed in version 3.14: threshold2 is ignored

Wouldn't it be clearer to connect the threshold and generation numbers?(And maybe rewrite the set_threshold function, if we have only two generations)

[picnixz]

I'm not sure I understand what you mean by "connect" generation numbers. We cannot really change set_threshold because of its signature (that is we cannot just remove the parameter from the signature due to backwards compatibility).

To be precise, what we did is:

• Ignore generation=1. It just returns an empty list.
• We cannot really ignore threashold1 instead of threshold2 because thos arguments are positional-only.
• It's better to keep those names for historical reasons.

[bobzinin]

@picnixz Ok, I see your point.
Any name changes may lead to compatibility problems…
If we try to change the order of arguments(0->1->2 to 0->2->1) it can make things even worse
If we try to rewrite the gc.get_stats function… we could also get some problems…
Thank you for the explanation!

I can propose to add short comments to each argument, for better readability(if you don't want to read all the text about how things work)
But if it is not needed, I think, the problem is solved)

[picnixz]

It's not usual to add comments to arguments in this case. The argument names are historically correct so we'll just be stuck with it. We could rename the arguments but for historical reasons it's maybe better to leave them as is (here the terminology is more important IMO).

As such, I will close the issue for now. Thank you for your understanding!

[sergey-miryanov]

FTR, it is made by intention to be "compatible" with existing code.

Before 3.14 we have default values for thresholds like (2000, 10, 10). This means that after 100 gc runs (young + middle) we run full collection.
For incremental gc we changed meaning of the second threshold value, and this change documented:

The fraction of the old generation that is collected is inversely proportional to threshold1. The larger threshold1 is, the slower objects in the old generation are collected. For the default value of 10, 1% of the old generation is scanned during each collection.

This means that for default values (2000, 10, 0) after 100 runs we do collection for whole heap like before 3.14.