Address review feedback from @vstinner

- Drop _Py_TRACEBACK_MAX_NTHREADS macro; use 0 as sentinel for default
  100 inside _Py_DumpTracebackThreads so internal callers don't have to
  pass the default explicitly.
- Rename max_nthreads -> max_threads everywhere for naming consistency
  with the public Python kwarg.
- Add max_threads kwarg to faulthandler.enable(); store in
  fatal_error.max_threads and pass through faulthandler_dump_traceback
  to the fatal-signal dump path on both POSIX and Windows.
- Drop the three redundant explanatory comments vstinner flagged.
- Doc: tighten the limitations bullet, drop implementation-detail
  mentions of the "..." truncation marker, switch versionchanged
  directives to "next", document the new enable() kwarg.
- Tests: assertEqual exact count, check whole-line "\n...\n" marker,
  use script_helper.assert_python_ok, drop the default-value test,
  add test_enable_max_threads exercising the fatal-signal path.
- NEWS: trim to two lines, mention all three functions.

Author: efroemling

Doc/library/faulthandler.rst

@@ -31,8 +31,8 @@ tracebacks:
 * Each string is limited to 500 characters.
 * Only the filename, the function name and the line number are
   displayed. (no source code)
-* It is limited to 100 frames per thread, and by default to 100 threads
-  total in newest-first order (configurable via *max_threads*).
+* It is limited to 100 frames per thread, and 100 threads
+  (configurable via *max_threads*).
 * The order is reversed: the most recent call is shown first.
 
 By default, the Python traceback is written to :data:`sys.stderr`. To see
@@ -60,14 +60,14 @@ Dumping the traceback
 
    Dump the tracebacks of all threads into *file*. If *all_threads* is
    ``False``, dump only the current thread. *max_threads* caps the number
-   of threads dumped; a ``...`` marker is written if there are more.
+   of threads dumped.
 
    .. seealso:: :func:`traceback.print_tb`, which can be used to print a traceback object.
 
    .. versionchanged:: 3.5
       Added support for passing file descriptor to this function.
 
-   .. versionchanged:: 3.15
+   .. versionchanged:: next
       Added the *max_threads* keyword argument.
 
 
@@ -105,7 +105,7 @@ instead of the stack, even if the operating system supports dumping stacks.
 Fault handler state
 -------------------
 
-.. function:: enable(file=sys.stderr, all_threads=True, c_stack=True)
+.. function:: enable(file=sys.stderr, all_threads=True, c_stack=True, *, max_threads=100)
 
    Enable the fault handler: install handlers for the :const:`~signal.SIGSEGV`,
    :const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS`
@@ -121,6 +121,8 @@ Fault handler state
    traceback, unless the system does not support it. See :func:`dump_c_stack` for
    more information on compatibility.
 
+   *max_threads* caps the number of threads dumped when a fatal signal fires.
+
    .. versionchanged:: 3.5
       Added support for passing file descriptor to this function.
 
@@ -138,6 +140,9 @@ Fault handler state
    .. versionchanged:: 3.14
       The dump now displays the C stack trace if *c_stack* is true.
 
+   .. versionchanged:: next
+      Added the *max_threads* keyword argument.
+
 .. function:: disable()
 
    Disable the fault handler: uninstall the signal handlers installed by
@@ -159,8 +164,7 @@ Dumping the tracebacks after a timeout
    :c:func:`!_exit` exits the process immediately, which means it doesn't do any
    cleanup like flushing file buffers.) If the function is called twice, the new
    call replaces previous parameters and resets the timeout. The timer has a
-   sub-second resolution. *max_threads* caps the number of threads dumped;
-   a ``...`` marker is written if there are more.
+   sub-second resolution. *max_threads* caps the number of threads dumped.
 
    The *file* must be kept open until the traceback is dumped or
    :func:`cancel_dump_traceback_later` is called: see :ref:`issue with file
@@ -174,7 +178,7 @@ Dumping the tracebacks after a timeout
    .. versionchanged:: 3.7
       This function is now always available.
 
-   .. versionchanged:: 3.15
+   .. versionchanged:: next
       Added the *max_threads* keyword argument.
 
 .. function:: cancel_dump_traceback_later()

Include/internal/pycore_faulthandler.h

@@ -57,6 +57,7 @@ struct _faulthandler_runtime_state {
         void *exc_handler;
 #endif
         int c_stack;
+        unsigned int max_threads;
     } fatal_error;
 
     struct {
@@ -68,8 +69,7 @@ struct _faulthandler_runtime_state {
         int exit;
         char *header;
         size_t header_len;
-        /* Thread-count cap passed to _Py_DumpTracebackThreads. */
-        unsigned int max_nthreads;
+        unsigned int max_threads;
         /* The main thread always holds this lock. It is only released when
            faulthandler_thread() is interrupted before this thread exits, or at
            Python exit. */

Include/internal/pycore_traceback.h

@@ -58,19 +58,11 @@ extern void _Py_DumpTraceback(
 
    This function is signal safe. */
 
-/* The historical per-call cap on the number of threads dumped by
-   _Py_DumpTracebackThreads; surfaced as the public default for the
-   max_threads kwarg on faulthandler.dump_traceback{,_later}. */
-#define _Py_TRACEBACK_MAX_NTHREADS 100
-
-/* max_nthreads is the per-call cap. Pass _Py_TRACEBACK_MAX_NTHREADS
-   for the historical default; user-facing callers should use the
-   clinic-supplied default of the public Python API. */
 extern const char* _Py_DumpTracebackThreads(
     int fd,
     PyInterpreterState *interp,
     PyThreadState *current_tstate,
-    unsigned int max_nthreads);
+    unsigned int max_threads);
 
 /* Write a Unicode object into the file descriptor fd. Encode the string to
    ASCII using the backslashreplace error handler.

Lib/test/test_faulthandler.py

@@ -722,7 +722,7 @@ def test_dump_traceback_later_twice(self):
     def test_dump_traceback_max_threads(self):
         # max_threads caps the dump and writes "...\n" when truncated.
         # Spawn N worker threads, dump with cap < N, and verify the
-        # marker is present and at most CAP thread headers are written.
+        # marker is present and exactly CAP thread headers are written.
         code = dedent("""
             import faulthandler
             import sys
@@ -749,31 +749,42 @@ def worker():
                 for t in threads:
                     t.join()
         """).strip()
-        # spawn_python merges stderr into stdout by default.
-        with support.SuppressCrashReport():
-            process = script_helper.spawn_python('-c', code)
-            with process:
-                output, _ = process.communicate()
-                process.wait()
-        # Truncation marker is written when the cap is hit.
-        self.assertIn(b"...\n", output)
-        # Cap of 3 means at most 3 thread headers in the dump.
-        self.assertLessEqual(output.count(b"Thread 0x"), 3)
-
-    def test_dump_traceback_max_threads_default(self):
-        # The default max_threads of 100 preserves historical behavior:
-        # no truncation when the live thread count is below the cap.
+        proc = script_helper.assert_python_ok('-c', code)
+        output = proc.err
+        # Truncation marker is written on its own line when the cap is hit.
+        self.assertIn(b"\n...\n", output)
+        # Cap of 3 means exactly 3 thread headers in the dump.
+        self.assertEqual(output.count(b"Thread 0x"), 3)
+
+    @skip_segfault_on_android
+    def test_enable_max_threads(self):
+        # enable(max_threads=N) caps the thread dump produced when a
+        # fatal signal fires.
         code = dedent("""
             import faulthandler
-            import sys
-            faulthandler.dump_traceback(file=sys.stderr)
+            import threading
+
+            NTHREADS = 6
+            CAP = 3
+
+            ready = threading.Barrier(NTHREADS + 1)
+            stop = threading.Event()
+
+            def worker():
+                ready.wait()
+                stop.wait()
+
+            for _ in range(NTHREADS):
+                threading.Thread(target=worker, daemon=True).start()
+            ready.wait()
+            faulthandler.enable(max_threads=CAP)
+            faulthandler._sigsegv()
         """).strip()
-        with support.SuppressCrashReport():
-            process = script_helper.spawn_python('-c', code)
-            with process:
-                output, _ = process.communicate()
-                process.wait()
-        self.assertNotIn(b"...\n", output)
+        output, exitcode = self.get_output(code)
+        output = '\n'.join(output)
+        # Cap of 3 means the dump is truncated with "..." on its own line.
+        self.assertIn("\n...\n", output)
+        self.assertNotEqual(exitcode, 0)
 
     @unittest.skipIf(not hasattr(faulthandler, "register"),
                      "need faulthandler.register")

Misc/NEWS.d/next/Library/2026-04-28-16-30-48.gh-issue-149085.5aNgBD.rst

@@ -1,7 +1,2 @@
-Add a *max_threads* keyword argument to :func:`faulthandler.dump_traceback`
-and :func:`faulthandler.dump_traceback_later`, raising the per-call cap on
-the number of threads dumped (previously a hard-coded ``MAX_NTHREADS = 100``
-in :file:`Python/traceback.c`). Useful for server processes with many
-worker or gRPC threads, where dump order (newest-thread-first) means the
-historical 100-thread cap silently elided the main thread. The default of
-``100`` preserves existing behavior.
+Add a *max_threads* keyword argument to :func:`faulthandler.dump_traceback`,
+:func:`faulthandler.dump_traceback_later`, and :func:`faulthandler.enable`.