docs: Add Subinterpreters cookbook recipe (Python 3.14 in-process multi-core parallelism)

[ndonkoHenri]

Adds a new cookbook recipe for using Python 3.14 subinterpreters (concurrent.interpreters and InterpreterPoolExecutor) in Flet apps for true multi-core CPU parallelism inside a single process — the in-process, mobile-capable counterpart to the Multiprocessing recipe (which can't spawn child processes on iOS/Android).

Verified on every Flet platform

The behaviour was validated on-device with a playground test matrix (two Flet apps exercising each worker shape from main.py and from a module, via interp.call and the pool). All six platforms agree exactly:

	Android	iOS-sim	macOS	Linux	Windows
workers (helper chains, persistent state, C-ext & app-module imports)	✅	✅	✅	✅	✅
generator-expression referencing a module helper	❌	❌	❌	❌	❌

Key findings baked into the recipe:

• Top-level worker functions work everywhere (they transfer by module import); functions nested inside main() only work if fully stateless, so the rule is "define workers at module top level" (same as multiprocessing).
• The one real gotcha is a generator expression that references a module-level helper (NameError) — and it fails from a module too, so it isn't a main-vs-module issue.

Notes

• Web support depends on the hosting model: Dynamic websites run server-side CPython, so subinterpreters work exactly like desktop; static (Pyodide) websites can't run them at all — single-threaded WASM, no per-interpreter GIL. Both cases are documented in the recipe's platform-support box.
• Android support relies on serious_python ≥ 4.3.6 (the per-interpreter import-finder fix, fix(android): make PEP 734 subinterpreters work (concurrent.interpreters / InterpreterPoolExecutor) serious-python#239), which is already bundled by Flet 0.86.3+ (0.86.5 → serious_python 4.5.1). No build-template change is needed here.
• Requires Python 3.14 (requires-python = ">=3.14" or flet build --python-version 3.14).

Summary by Sourcery

Document Python 3.14 subinterpreters as a mobile-capable alternative for CPU-bound parallelism in Flet applications.

Enhancements:

• Add a comprehensive cookbook recipe explaining Python 3.14 subinterpreters for in-process, multi-core CPU parallelism in Flet apps, including platform support, usage guidance, limitations, and common pitfalls.

Documentation:

• Add runnable examples covering parallel pool execution, progress streaming through cross-interpreter queues, and persistent interpreter state.
• Link subinterpreters guidance from the multiprocessing recipe and expose the new recipe in the cookbook navigation.
• Document Python version requirements and platform differences, including support on mobile and dynamic web deployments but not static Pyodide builds.

[cloudflare-workers-and-pages]

Deploying flet-website-v2 with    Cloudflare Pages

Latest commit:	99b59c2
Status:	✅  Deploy successful!
Preview URL:	https://9f584fe7.flet-website-v2.pages.dev
Branch Preview URL:	https://subinterpreters.flet-website-v2.pages.dev

View logs

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}