Repository navigation
Misleading gc docs #142115
Description
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)
Activity
picnixz commentedon Nov 30, 2025
I'm not sure I understand what you mean by "connect" generation numbers. We cannot really change
set_thresholdbecause 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:
generation=1. It just returns an empty list.threashold1instead ofthreshold2because thos arguments are positional-only.bobzinin commentedon Nov 30, 2025
@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 commentedon Nov 30, 2025
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 commentedon Nov 30, 2025
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:
This means that for default values (2000, 10, 0) after 100 runs we do collection for whole heap like before 3.14.