🐍 Web Python Kernel

A Jupyter-like Python kernel for the browser with real-time streaming output, interrupt support, and seamless visualization capabilities. Run Python code with numpy, matplotlib, plotly, pandas, and more directly in your web applications.

🎯 Features

- ✅ Real Python Execution - Pyodide-powered Python 3.11 in the browser
- ✅ Streaming Output - Real-time stdout/stderr streaming as code executes
- ✅ Interrupt Support - Stop long-running code with SharedArrayBuffer or fallback
- ✅ Worker Mode - Run Python in Web Workers for better performance
- ✅ Rich Visualizations - matplotlib, plotly, seaborn plots display automatically
- ✅ Package Management - Install packages with micropip
- ✅ TypeScript Support - Full type safety and intellisense
- ✅ Event System - React to kernel state changes and execution events

🚀 Quick Start

$3

``html








Run Python




`

$3

`javascript
// Latest version
import { KernelManager } from 'https://cdn.jsdelivr.net/npm/web-python-kernel@latest/dist/web-python-kernel.mjs';

// Specific version
import { KernelManager } from 'https://cdn.jsdelivr.net/npm/web-python-kernel@0.1.6/dist/web-python-kernel.mjs';

// Alternative CDNs
import { KernelManager } from 'https://unpkg.com/web-python-kernel@0.1.6/dist/web-python-kernel.mjs';
import { KernelManager } from 'https://esm.sh/web-python-kernel@0.1.6/dist/web-python-kernel.mjs';
`

$3

When using the library from a CDN, you must specify the full URL to the worker file:

`javascript
// Using jsdelivr CDN
const manager = new KernelManager({
workerUrl: 'https://cdn.jsdelivr.net/npm/web-python-kernel@latest/dist/kernel.worker.js'
});

// Using unpkg CDN
const manager = new KernelManager({
workerUrl: 'https://unpkg.com/web-python-kernel@latest/dist/kernel.worker.js'
});

// For local development (default behavior)
const manager = new KernelManager(); // Will auto-detect worker location

// You can also set it after initialization
manager.setWorkerUrl('https://cdn.jsdelivr.net/npm/web-python-kernel@latest/dist/kernel.worker.js');
`

Important: When loading from a CDN, always specify the workerUrl to ensure the worker script loads correctly. The library will attempt to auto-detect the worker location, but explicit configuration is more reliable for production use.

$3

`bash
npm install web-python-kernel
`

`javascript
import { KernelManager, KernelMode, KernelLanguage, KernelEvents } from 'web-python-kernel';
`

📋 Basic Usage Example

`javascript
import { KernelManager, KernelMode, KernelLanguage, KernelEvents } from 'web-python-kernel';

// Create kernel manager
const manager = new KernelManager({
// Recommend worker mode for better performance and isolation
allowedKernelTypes: [
{ mode: KernelMode.WORKER, language: KernelLanguage.PYTHON }
],
// Optional: specify worker URL for CDN deployments
// workerUrl: 'https://cdn.jsdelivr.net/npm/web-python-kernel@latest/dist/kernel.worker.js'
});

// Create a kernel
const kernelId = await manager.createKernel({
mode: KernelMode.WORKER,
lang: KernelLanguage.PYTHON
});

// Listen for kernel events
manager.onKernelEvent(kernelId, KernelEvents.KERNEL_BUSY, () => {
console.log('Kernel is busy...');
});

manager.onKernelEvent(kernelId, KernelEvents.KERNEL_IDLE, () => {
console.log('Kernel is ready');
});

// Execute Python code with streaming output
const code =
print("Hello from Python!")
import numpy as np
arr = np.array([1, 2, 3, 4, 5])
print(f"NumPy array: {arr}")
print(f"Sum: {np.sum(arr)}")
;

// Method 1: Real-time streaming (recommended)
const stream = manager.executeStream(kernelId, code);
for await (const event of stream) {
switch (event.type) {
case 'stream':
if (event.data.name === 'stdout') {
console.log('Output:', event.data.text);
}
break;
case 'execute_result':
console.log('Result:', event.data.data['text/plain']);
break;
case 'execute_error':
console.error('Error:', event.data.ename, event.data.evalue);
break;
}
}

// Method 2: Simple execution (no streaming)
const kernel = manager.getKernel(kernelId);
const result = await kernel.kernel.execute(code);
if (result.success) {
console.log('Execution completed');
} else {
console.error('Execution failed:', result.error);
}
`

🔧 Worker Mode Setup (Recommended)

Worker mode runs Python in a Web Worker for better performance and isolation:

`javascript
const manager = new KernelManager({
allowedKernelTypes: [
{ mode: KernelMode.WORKER, language: KernelLanguage.PYTHON }
],
// Enable SharedArrayBuffer-based interruption (recommended)
interruptionMode: 'shared-array-buffer'
});

const kernelId = await manager.createKernel({
mode: KernelMode.WORKER,
lang: KernelLanguage.PYTHON
});
`

$3

For the best interrupt experience, enable SharedArrayBuffer with proper CORS headers:

`javascript
// Server headers required for SharedArrayBuffer
// Cross-Origin-Opener-Policy: same-origin
// Cross-Origin-Embedder-Policy: require-corp

const manager = new KernelManager({
// Use 'shared-array-buffer' for best interrupt performance
// Falls back to 'kernel-interrupt' automatically if SharedArrayBuffer unavailable
interruptionMode: 'auto' // or 'shared-array-buffer'
});

// Interrupt a long-running execution
const interruptSuccess = await manager.interruptKernel(kernelId);
if (interruptSuccess) {
console.log('Execution interrupted successfully');
}
`

🎨 Visualization Support

Web Python Kernel automatically handles matplotlib, plotly, and other visualization libraries:

$3

`javascript
const matplotlibCode =
import matplotlib.pyplot as plt
import numpy as np

Create sample data

x = np.linspace(0, 10, 100)
y = np.sin(x)

Create plot

plt.figure(figsize=(10, 6))
plt.plot(x, y, label='sin(x)')
plt.plot(x, np.cos(x), label='cos(x)')
plt.title('Trigonometric Functions')
plt.legend()
plt.grid(True)

Display plot (automatically generates display_data event)

plt.show()
;

const stream = manager.executeStream(kernelId, matplotlibCode);
for await (const event of stream) {
if (event.type === 'display_data' && event.data.data['image/png']) {
// Create img element to display plot
const img = document.createElement('img');
img.src = data:image/png;base64,${event.data.data['image/png']};
img.style.maxWidth = '100%';
document.body.appendChild(img);
}
}
`

$3

`javascript
const plotlyCode =
import micropip
await micropip.install('plotly')
import plotly.graph_objects as go
import numpy as np

Create interactive plot

x = np.linspace(0, 10, 50)
y = np.sin(x)

fig = go.Figure()
fig.add_trace(go.Scatter(x=x, y=y, mode='lines+markers', name='sin(x)'))
fig.update_layout(title='Interactive Sine Wave')

Display interactive plot

fig.show()
;

// Plotly generates HTML display data
const stream = manager.executeStream(kernelId, plotlyCode);
for await (const event of stream) {
if (event.type === 'display_data' && event.data.data['text/html']) {
const plotDiv = document.createElement('div');
plotDiv.innerHTML = event.data.data['text/html'];
document.body.appendChild(plotDiv);
}
}
`

🎮 Try the Interactive Playground

$3


`bash

Clone and setup

git clone
cd web-python-kernel
npm install

Start playground

npm run playground

Opens http://localhost:8080/playground.html

`

$3

- ✅ Real-time code execution with streaming output
- ✅ Matplotlib/Plotly visualization examples
- ✅ Interrupt demonstration for long-running code
- ✅ Package installation with micropip
- ✅ Both main thread and worker modes

---

🔧 Advanced Usage

$3

Enable kernel pooling for faster kernel creation:

`javascript
const manager = new KernelManager({
pool: {
enabled: true,
poolSize: 2, // Keep 2 kernels ready
autoRefill: true, // Automatically create new kernels
preloadConfigs: [
{ mode: KernelMode.WORKER, language: KernelLanguage.PYTHON }
]
}
});

// Pool kernels are created in background, createKernel returns immediately
const kernelId = await manager.createKernel({
mode: KernelMode.WORKER,
lang: KernelLanguage.PYTHON
});

// Check pool status
const poolStats = manager.getPoolStats();
console.log('Pool stats:', poolStats);
`

$3

`javascript
// Create kernels with namespaces for organization
const dataKernelId = await manager.createKernel({
namespace: 'data-analysis',
mode: KernelMode.WORKER,
lang: KernelLanguage.PYTHON
});

const mlKernelId = await manager.createKernel({
namespace: 'machine-learning',
mode: KernelMode.WORKER,
lang: KernelLanguage.PYTHON
});

// List kernels by namespace
const dataKernels = await manager.listKernels('data-analysis');
console.log('Data analysis kernels:', dataKernels);

// Destroy kernels by namespace
await manager.destroyAll('data-analysis');
`

$3

`javascript
const kernelId = await manager.createKernel({
mode: KernelMode.WORKER,
lang: KernelLanguage.PYTHON,
env: {
'API_KEY': 'your-api-key',
'DEBUG': 'true',
'MODEL_PATH': '/models/trained.pkl'
}
});

// Python code can access these via os.environ
const code =
import os
print(f"API Key: {os.environ.get('API_KEY')}")
print(f"Debug mode: {os.environ.get('DEBUG')}")
;
`

$3

`javascript
const kernelId = await manager.createKernel({
mode: KernelMode.WORKER,
lang: KernelLanguage.PYTHON,
filesystem: {
mountPoints: {
'/data': {
type: 'memory', // or 'indexeddb'
initialData: {
'dataset.csv': csvData,
'config.json': JSON.stringify(config)
}
}
}
}
});

// Python can now access files
const code =
import pandas as pd
df = pd.read_csv('/data/dataset.csv')
print(df.head())
;
`

$3

`javascript
import { KernelEvents } from 'web-python-kernel';

// Listen for all kernel events
manager.onKernelEvent(kernelId, KernelEvents.KERNEL_BUSY, () => {
document.getElementById('status').textContent = 'Running...';
});

manager.onKernelEvent(kernelId, KernelEvents.KERNEL_IDLE, () => {
document.getElementById('status').textContent = 'Ready';
});

manager.onKernelEvent(kernelId, KernelEvents.STREAM, (data) => {
if (data.name === 'stdout') {
appendOutput(data.text);
} else if (data.name === 'stderr') {
appendError(data.text);
}
});

manager.onKernelEvent(kernelId, KernelEvents.DISPLAY_DATA, (data) => {
if (data.data['image/png']) {
displayPlot(data:image/png;base64,${data.data['image/png']});
}
});

manager.onKernelEvent(kernelId, KernelEvents.EXECUTE_ERROR, (data) => {
showError(${data.ename}: ${data.evalue}, data.traceback);
});
`

$3

`javascript
// Install packages dynamically
const installCode =
import micropip
await micropip.install(['pandas', 'scikit-learn', 'seaborn'])

import pandas as pd
import numpy as np
from sklearn.linear_model import LinearRegression
import seaborn as sns

print("All packages installed successfully!")
;

const stream = manager.executeStream(kernelId, installCode);
for await (const event of stream) {
if (event.type === 'stream') {
console.log('Install progress:', event.data.text);
}
}
`

$3

`javascript
// Start a long-running computation
const longCode =
import time
for i in range(100):
print(f"Step {i+1}/100")
time.sleep(1) # Long-running operation
print("Completed!")
;

const stream = manager.executeStream(kernelId, longCode);

// Set up interrupt after 5 seconds
setTimeout(async () => {
const success = await manager.interruptKernel(kernelId);
if (success) {
console.log('Execution interrupted successfully');
}
}, 5000);

// Handle the stream until interruption
try {
for await (const event of stream) {
console.log('Output:', event);
}
} catch (error) {
if (error.message.includes('interrupt')) {
console.log('Execution was interrupted');
}
}
`

📚 API Reference

$3

`typescript
class KernelManager {
constructor(options: IKernelManagerOptions);

// Kernel lifecycle
createKernel(options: IManagerKernelOptions): Promise;
getKernel(id: string): IKernelInstance | undefined;
destroyKernel(id: string): Promise;
destroyAll(namespace?: string): Promise;
listKernels(namespace?: string): Promise;

// Execution
executeStream(kernelId: string, code: string, parent?: any): AsyncGenerator;
interruptKernel(kernelId: string): Promise;

// Events
onKernelEvent(kernelId: string, eventType: KernelEvents, listener: Function): void;
offKernelEvent(kernelId: string, eventType: KernelEvents, listener: Function): void;

// Pool management
getPoolStats(): Record;
getPoolConfig(): PoolConfig;
}
`

$3

`typescript
enum KernelEvents {
KERNEL_BUSY = 'kernel_busy',
KERNEL_IDLE = 'kernel_idle',
STREAM = 'stream',
DISPLAY_DATA = 'display_data',
UPDATE_DISPLAY_DATA = 'update_display_data',
EXECUTE_RESULT = 'execute_result',
EXECUTE_ERROR = 'execute_error',
KERNEL_INFO = 'kernel_info'
}
`

$3

`typescript
interface IKernelManagerOptions {
pool?: IKernelPoolConfig;
allowedKernelTypes?: Array<{
mode: KernelMode;
language: KernelLanguage;
}>;
interruptionMode?: 'shared-array-buffer' | 'kernel-interrupt' | 'auto';
}

interface IManagerKernelOptions {
id?: string;
mode?: KernelMode;
lang?: KernelLanguage;
namespace?: string;
env?: Record;
filesystem?: IFileSystemMountOptions;
lockFileURL?: string;
inactivityTimeout?: number;
maxExecutionTime?: number;
}
`

🔍 Performance Tips

1. Use Worker Mode: Better performance and isolation
2. Enable Kernel Pooling: Faster kernel creation for frequent use
3. Use SharedArrayBuffer: Better interrupt performance with proper CORS headers
4. Preload Packages: Include commonly used packages in lockFileURL
5. Stream Processing: Use executeStream for real-time feedback

🛡️ Security Considerations

- Worker mode provides better isolation than main thread mode
- Set appropriate CORS headers for SharedArrayBuffer
- Limit allowed kernel types in production
- Use namespaces to organize and limit kernel access
- Set inactivity timeouts to prevent resource leaks

🛠 Development Commands

| Command | Description |
|---------|-------------|
| npm run playground | Build and start playground |
| npm run build | Build kernel bundle |
| npm run serve | Start development server |
| npm run test | Run all tests |
| npm run test:watch | Run tests in watch mode |
| npm run clean | Clean build artifacts |

📁 Project Structure

`
web-python-kernel/
├── src/ # TypeScript source code
│ ├── manager.ts # Kernel manager implementation
│ ├── index.ts # Main kernel implementation
│ ├── types.ts # TypeScript interfaces
│ └── kernel.worker.ts # Web Worker implementation
├── tests/ # Test files
├── playground.html # Interactive demo
├── dist/ # Built bundles
│ ├── web-python-kernel.mjs # ES module
│ ├── web-python-kernel.umd.js # UMD bundle
│ └── kernel.worker.js # Worker bundle
└── package.json # Package configuration
``

🚀 Ready to Go!

Your web-python-kernel is ready to power Jupyter-like Python experiences in the browser!

Quick start: Use the CDN version or install via npm and start building amazing Python web applications.

Happy coding! 🐍✨