gh-134075: Document how to make C extensions interruptible

[shaury04]

Long-running C extensions can delay Ctrl-C handling until they return to the
interpreter. Add a guide explaining where to call PyErr_CheckSignals(), how to
propagate exceptions and clean up partial results, and how to keep extension
state safe when signal handlers execute arbitrary Python code.

Include a C example that processes immutable input in chunks, reattaches the
thread state before checking signals, and discards its private output on error.
Cover free-threaded builds, checking frequency, blocking library calls, and
main-thread signal handling. Link to the guide from the C API reference and
make the attached-thread-state requirement explicit there.

Fixes #134075.

Validation

• Both changed HTML pages build with --nitpicky --fail-on-warning and no warnings.
• Full HTML documentation was generated. Its known reference warnings cause
  the strict full-tree build to exit nonzero, as expected by the docs CI workflow;
  all three checks in Doc/tools/check-warnings.py pass against the repository's
  warning baseline.
• sphinx-lint --enable=default-role passes for both changed files.
• The exact C example compiles with -Wall -Wextra -Werror (unused parameters
  excluded) and passes five tests on CPython 3.13.7: chunk boundaries and contents,
  invalid input, KeyboardInterrupt, preservation of custom exceptions, and a
  returning handler that re-enters the extension. The interruption tests verify
  that the C function returns NULL, rather than allowing deferred delivery after
  a successful return. The standalone validation harness is supplied with the
  review artifacts, outside the documentation-only patch.
• git diff --check passes.

AI assistance was used to draft the documentation and validate the example.

• Issue: Give PyErr_CheckSignals guide-level documentation #134075

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35199671 | 📁 Comparing c6f2373 against main (9cb7a5b)

  🔍 Preview build  

2 files changed

± c-api/exceptions.html
± extending/extending.html

[ZeroIntensity]

@zackw This PR seems to be AI-generated, but is this what you were looking for?