gh-75537: Add gc.ensure_disabled() context manager

[SakshamKapoor2911]

Fixes: #75537

Summary

Add gc.ensure_disabled() — a context manager that temporarily disables the cyclic garbage collector and reliably restores it to its previous state on exit.

with gc.ensure_disabled():
    ...  # GC is disabled during this block

Background

This feature was originally implemented by @pablogsal in 2018 (PR #4224), merged by @rhettinger, and subsequently reverted (PR #5495/#5496) due to edge cases around GIL release, debug build assertions, and threading concerns during the 3.7 beta window.

The modern CPython C API (PyGC_Disable() returns the old state) resolves the key state-tracking issue. The implementation:

• Uses PyGC_Disable() (returns old state) for atomic state save/restore
• Runs entirely under the GIL — no threading races
• Handles nesting: each level saves and restores its own state
• Properly handles the "already disabled" case: GC stays disabled

Tests

Four new tests in Lib/test/test_gc.py (GCTogglingTests):
test_ensure_disabled, test_ensure_disabled_nesting,
test_ensure_disabled_already_disabled, test_ensure_disabled_exception

Existing test suite: 59 tests pass, 0 regressions.

• Issue: Add context manager to temporarily disable GC #75537

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33856683 | 📁 Comparing 5a55da3 against main (2ac8900)

  🔍 Preview build  

9 files changed · ± 9 modified

± Modified

• deprecations/index.html
• deprecations/pending-removal-in-3.17.html
• library/gc.html
• whatsnew/3.12.html
• whatsnew/3.13.html
• whatsnew/3.14.html
• whatsnew/3.15.html
• whatsnew/3.16.html
• whatsnew/changelog.html

[maurycy]

In my opinion, there much, much more subtlety around pausing (defering):

#153946 (comment)
#153946 (comment)
#154188 (comment)
#154188 (comment)

Perhaps the right course of action is reusing internals that'd be added by #154188.

[maurycy]

gc.ensure_disabled() without with would be irreversible?

[SakshamKapoor2911]

That's correct, and consistent with all Python context managers. threading.Lock().acquire() without with also leaves the lock held indefinitely. This is a known limitation: exit only fires via the with statement. Adding a tp_dealloc fallback to re-enable GC on garbage collection would cause surprising behavior (the GC silently re-enabling at an unpredictable time). The with statement is the only supported usage.

[SakshamKapoor2911]

@maurycy Do you think this is a reasonable tradeoff, or would you suggest I made modifications to prevent this?

[SakshamKapoor2911]

Thanks for the pointer to #154188 and #153946. I think these are complementary layers of the same capability:

• gh-153946: Add API to defer automatic garbage collection #154188 adds a private _PyGC_PauseAutomaticCollection for CPython internals — gc.isenabled() stays True, only automatic collection is deferred. Right for core code building large object graphs.

• This PR adds a public gc.ensure_disabled() for users. gc.isenabled() returns False inside the block, telling user code the GC is off. Right for user code that needs to know the GC is paused.

They differ by design: the private API preserves gc.isenabled() because internals shouldn't change user-visible state. The public API should change gc.isenabled() because users need to see the effect.

The 2018 merged implementation (PR #4224) also used disable/enable, and the revert was for unrelated issues (GIL release, debug crash) that PyGC_Disable() returning old state now resolves.

[Aniketsy]

@SakshamKapoor2911 just small suggestion please avoid force push as this forces members to review PR from beginning instead of new changes ,

[picnixz]

This PR is premature. The discussion did not advance since 3y ago and I believe a newer discussion is necessary first.

[picnixz]

I do not understand why we could not have a pure Python function for that, left to users themselves. What is wrong with manually disabling/enabling the GC first?

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.