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, orscipy. - Web Scraping: Use
BeautifulSouporScrapyright from a TypeScript HTTP handler. - Database Drivers: Connect to legacy systems that lack good TypeScript SDKs.
- Standard Library:
os,sys,subprocess, andmathwork 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.
-
First, ensure any required Python libraries are installed in your host environment using
pipor a virtual environment.pip install pandas -
Run your TypeScript application directly using the NioJS CLI:
nio-js run server.ts --port 3000 -
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
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.