Add background sampling handle to pm.sample
Description
This adds an opt-in background mode to pm.sample so users can start sampling and continue working while it runs in a background thread. When background=True, pm.sample returns a handle with done(), result(), and exception() helpers, and the progress bar is suppressed to keep output clean. Background mode is currently limited to the built-in nuts_sampler="pymc"; other samplers raise NotImplementedError to make the scope clear. The model is resolved eagerly so the background thread always has a valid context.
Docstring notes describe how to use background=True and the current limitations. Tests cover both a successful background run and error propagation (tests/sampling/test_background_sampling.py).
Summary of changes:
- Add
backgroundflag topm.sampleand return aBackgroundSampleHandlewhen enabled. - Suppress progress bars in background mode.
- Resolve the model before launching the background thread.
- Document background mode in the
pm.sampledocstring. - Add tests for background sampling (happy path and error propagation).
Related Issue
- [x] Closes #7929
Checklist
- [ ] Checked that pre-commit linting/style checks pass
- [x] Included tests that prove the fix is effective or that the new feature works
- [x] Added necessary documentation (docstrings and/or example notebooks)
- [ ] If you are a pro: each commit corresponds to a relevant logical change
Type of change
- [x] New feature / enhancement
- [ ] Bug fix
- [ ] Documentation
- [ ] Maintenance