Serious Python

The channel.on_bytes(handler) method executes the handler synchronously under the Python GIL on the transport's delivery thread. Heavy processing inside this handler will starve the Python runtime.

Recommended Pattern: Use a bounded queue and a worker pool to offload processing from the delivery thread. This prevents the transport from blocking and allows you to implement a 'drop' policy for overflow using queue.put_nowait.

Note on Parallelism:

• Real parallelism requires C extensions that release the GIL (e.g., NumPy, PyTorch, Pillow).
• For pure-Python CPU work, use multiprocessing.
• Warning: multiprocessing is only available on desktop hosts in embedded mode. It is not available on iOS/Android due to OS restrictions on spawning child processes.

def did_mount(self):
    self._queue = queue.Queue(maxsize=4)         # bounded queue for drop policy
    self._pool = ThreadPoolExecutor(max_workers=4)
    self._frames.on_bytes(self._enqueue)
    threading.Thread(target=self._pump, daemon=True).start()

def _enqueue(self, payload):
    try:
        self._queue.put_nowait(payload)
    except queue.Full:
        pass                       # drop overflow to prevent pile-up

def _pump(self):
    while True:
        payload = self._queue.get()
        self._pool.submit(self._decode_and_reply, payload)

Because binaries cannot reside directly on sys.path as .so files on iOS, serious-python uses a specialized loader that relies on two marker files to bridge the gap between the module's logical location and its physical location in the Frameworks folder:

1. .fwork file: Acts as a placeholder in the original location of the binary on sys.path. It contains the path to the actual binary in the Frameworks folder, relative to the app bundle.
2. .origin file: Located inside the .framework directory. It contains the path to the .fwork file, relative to the app bundle, allowing the system to resolve the framework back to its original location.

Module Metadata Behavior:

• When a module is loaded using this mechanism, the module's __file__ attribute reports the location of the .fwork file. This allows developers to use __file__ as an anchor for filesystem traversal.
• The __spec__.origin will reference the location of the actual binary inside the .framework folder.

When working with Flutter/Dart, understand the scope of the PythonBridge and FletBackend:

• Main Isolate: FletBackend.of(context).openDataChannel() is only available on the main Isolate because it requires BuildContext.
• Worker Isolates: To use parallelism in a worker Isolate (e.g., for video decoding), the worker must construct its own PythonBridge directly by importing package:serious_python/bridge.dart. It can then ship its RawReceivePort back to the main Isolate via a SendPort to trigger data_channel_open events.

When building an app, you must ensure that the Python version used to install packages matches the Python runtime bundled in the Flutter app.

The Correct Way: Set the SERIOUS_PYTHON_VERSION environment variable. This variable is read by both the package command (to install the correct site-packages) and by the native Flutter build scripts (to bundle the correct runtime).

The Incorrect Way: Do not rely solely on the --python-version flag in the package command. This flag only affects the packaging step and does not reach the later flutter build phase, which leads to a mismatched app (e.g., 3.13 packages bundled with a 3.14 runtime).

Note: If you change the Python version, perform a clean build (flutter clean) to avoid using stale compiled bytecode.

# Correct: Set the env var to ensure both phases use 3.13
export SERIOUS_PYTHON_VERSION=3.13
dart run serious_python:main package app/src -p Android

# Then run your flutter build as usual
flutter build apk

By default, the embedded Python program runs in a separate thread to prevent blocking the Flutter UI.

Important: Your Flutter app should not attempt to call Python functions or modules directly. Instead, establish communication via standard APIs, such as:

• REST APIs
• Sockets
• SQLite databases
• File system operations

To keep the Python program running in the background, it must be blocking. Examples include:

• Running a Flask app listening on a specific port (e.g., 8000).
• Using threading.Thread for long-running computations combined with threading.Event to prevent the main program from exiting.

If you need to run a short utility program synchronously, use the sync: true parameter in the SeriousPython.run() method. Note that synchronous execution can block the UI unless run in a Dart isolate.

// Example concept: Python running a blocking Flask server
# app.py
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return 'Hello from Python!'

if __name__ == '__main__':
    app.run(port=8000)

The PythonBridge is an in-process byte transport mechanism between the Dart runtime and the embedded CPython runtime. It is designed for high-performance communication without the overhead of a protocol layer like MsgPack or Flet's messaging system.

To optimize performance, the bridge uses separate channels for different types of traffic:

1. Control Channel: Used for interactivity and small messages (e.g., counters, version checks, memory snapshots). It uses UTF-8 JSON with a {"op": ...} request format and a {"event": ...} response format.
2. Echo Channel: Used for high-throughput data transfer (e.g., moving large files or images). It uses raw bytes, where Python echoes the received frame verbatim to minimize framing tax.

Separating these channels ensures that the high-throughput path remains a simple bridge.send → dart_bridge.send_bytes loop, while the JSON dispatcher only handles lightweight control messages.