NioJS v0.3.0

Python Integration Guide

NioJS embeds a complete, authentic CPython runtime directly into the engine via PyO3. Write standard Python scripts, utilize the rich ML ecosystem, or connect to Python-only databases—all running natively inside your TypeScript service without IPC overhead.

Why Embedded Python?

Traditional approaches to using Python from Node/TypeScript involve HTTP microservices or spawning child processes. Both introduce serialization overhead, socket latency, and complex deployment topologies.

By embedding CPython natively in the Rust host, NioJS bridges the gap. JavaScript handles the async web routing, JSON orchestration, and I/O, while Python handles heavy data processing, machine learning, and legacy library execution in exactly the same memory space.

Not Just for AI

While heavily marketed as an "AI Bridge" for models (PyTorch, Transformers, LangChain), the embedded runtime is a fully-featured Python environment.

  • General Data Processing: Crunch numbers with pandas, numpy, or scipy.
  • Web Scraping: Use BeautifulSoup or Scrapy right from a TypeScript HTTP handler.
  • Database Drivers: Connect to legacy systems that lack good TypeScript SDKs.
  • Standard Library: os, sys, subprocess, and math work exactly as expected.

Example: Basic Evaluation

import { get, pythonEval } from 'nio.js';

get('/math', () => {
  // Executes synchronously in the CPython runtime
  return pythonEval('100 + 23'); 
});

Example: Importing Python Modules

Write your standard Python code in a .py file.

# analyzer.py
import pandas as pd
import json

def process_data(payload_json: str) -> str:
    data = json.loads(payload_json)
    df = pd.DataFrame(data)
    summary = df.describe().to_json()
    return summary

Import and use it in TypeScript:

// server.ts
import { post } from 'nio.js';
import { process_data } from './analyzer.py';

post('/analyze', async ({ json }) => {
  const payload = await json();
  // Bridge the data directly; no network hop!
  const result = process_data(JSON.stringify(payload));
  // Parse the JSON string returned by Python
  return JSON.parse(result);
});

Running Your Project

Running a Python-integrated project is identical to running a standard NioJS application. The CPython runtime is automatically initialized on demand within the exact same process space.

  1. First, ensure any required Python libraries are installed in your host environment using pip or a virtual environment.

    pip install pandas
  2. Run your TypeScript application directly using the NioJS CLI:

    nio-js run server.ts --port 3000
  3. Your server is now live! The TypeScript handler will seamlessly call the Python function upon receiving a request.

    curl -X POST http://localhost:3000/analyze \
      -H "Content-Type: application/json" \
      -d '[{"id": 1, "value": 10}, {"id": 2, "value": 20}]'

Serialization and Data Types

The boundary between the QuickJS JavaScript engine and the PyO3 Python engine currently relies on String serialization. When calling a Python function, arguments should be passed as JSON strings, and the Python function should return a JSON string. NioJS does this automatically for you via the proxy wrapper, ensuring type safety and memory isolation between the two language garbage collectors.

Concurrency and Blocking

Important: The Python runtime (GIL) and PyO3 execution run synchronously within the current NioJS worker thread.

While NioJS uses a multi-worker QuickJS thread pool, executing a heavy Python function blocks the specific worker handling that request until the Python function returns. For high-concurrency web traffic, prefer short-lived Python tasks (like quick inferences or data transformations).

Installation & Requirements

Python support is included via a feature flag during compilation. If building from source:

cargo build --release --features python

A compatible Python version must be installed on the host system to provide the standard library and site-packages.