Add schedule_display_output for pushing messages to frontends outside execution

[blink1073]

References

closes #198

Description

Kernel authors sometimes need to push output to all connected frontends from a background thread — for example, when wrapping an application that emits periodic events or async notifications. Previously there was no supported way to do this.

This PR adds MetaKernel.schedule_display_output(callback), which schedules a zero-argument callable on the kernel's main Tornado IO loop. Because ZMQ sockets are not thread-safe, calling Print/Display/etc. directly from a background thread is unsafe; routing through io_loop.add_callback (Tornado's thread-safe mechanism) ensures the message is delivered correctly to all frontends even when no cell execution is in progress. When io_loop is unavailable (e.g. in unit tests), the callback is invoked directly.

Changes

• metakernel/_metakernel.py: add schedule_display_output(callback) method; add Callable to typing imports
• tests/test_metakernel.py: four new tests in TestScheduleDisplayOutput covering the no-io_loop fallback, iopub message delivery, io_loop delegation, and a real background thread
• docs/new_kernel.md: new "Pushing output from background threads" section with a complete example
• docs/new_magic.md: new schedule_display_output entry in the kernel output helpers reference

Backwards-incompatible changes

None

Testing

New unit tests added. All existing tests pass (one pre-existing failure in test_px_error_reports_exception_not_noisy_traceback unrelated to this change).

AI usage

• Some or all of the content of this PR was generated by AI.
• The human author has carefully reviewed this PR and run this code.
• AI tools and models used: Claude Sonnet 4.6 (Claude Code)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.86%. Comparing base (64e73e6) to head (bc79354).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #382      +/-   ##
==========================================
+ Coverage   90.85%   90.86%   +0.01%     
==========================================
  Files          51       51              
  Lines        2952     2957       +5     
  Branches      413      414       +1     
==========================================
+ Hits         2682     2687       +5     
  Misses        190      190              
  Partials       80       80              

Files with missing lines	Coverage Δ
metakernel/_metakernel.py	92.17% <100.00%> (+0.06%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.