RustPython · bschoenmaeckers · Apr 21, 2026 · Apr 21, 2026 · Apr 21, 2026 · Apr 21, 2026
diff --git a/.cspell.dict/cpython.txt b/.cspell.dict/cpython.txt
@@ -161,6 +161,7 @@ Pyfunc
 pylifecycle
 pymain
 pyrepl
+pystate
 PYTHONTRACEMALLOC
 PYTHONUTF8
 pythonw

diff --git a/.cspell.dict/python-more.txt b/.cspell.dict/python-more.txt
@@ -189,6 +189,7 @@ pycodecs
 pycs
 pydatetime
 pyexpat
+PYGILSTATE
 pyio
 pymain
 PYTHONAPI

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -10,6 +10,7 @@ repository.workspace = true
 license.workspace = true
 
 [features]
+capi = ["dep:rustpython-capi", "threading"]
 default = ["threading", "stdlib", "stdio", "importlib", "ssl-rustls", "host_env"]
 host_env = ["rustpython-vm/host_env", "rustpython-stdlib?/host_env"]
 importlib = ["rustpython-vm/importlib"]
@@ -31,6 +32,7 @@ tkinter = ["rustpython-stdlib/tkinter"]
 winresource = "0.1"
 
 [dependencies]
+rustpython-capi = { workspace = true, optional = true }
 rustpython-compiler = { workspace = true }
 rustpython-pylib = { workspace = true, optional = true }
 rustpython-stdlib = { workspace = true, optional = true, features = ["compiler"] }
@@ -140,6 +142,7 @@ repository = "https://github.com/RustPython/RustPython"
 license = "MIT"
 
 [workspace.dependencies]
+rustpython-capi = { path = "crates/capi", version = "0.5.0" }
 rustpython-compiler-core = { path = "crates/compiler-core", version = "0.5.0" }
 rustpython-compiler = { path = "crates/compiler", version = "0.5.0" }
 rustpython-codegen = { path = "crates/codegen", version = "0.5.0" }
@@ -256,7 +259,6 @@ rustls-platform-verifier = "0.7"
 rustyline = "18"
 serde = { package = "serde_core", version = "1.0.225", default-features = false, features = ["alloc"] }
 schannel = "0.1.29"
-scoped-tls = "1"
 scopeguard = "1"
 sha-1 = "0.10.0"
 sha2 = "0.10.2"

diff --git a/build.rs b/build.rs
@@ -1,17 +1,29 @@
 fn main() {
-    if std::env::var("CARGO_CFG_TARGET_OS").unwrap() == "windows" {
-        println!("cargo:rerun-if-changed=logo.ico");
-        let mut res = winresource::WindowsResource::new();
-        if std::path::Path::new("logo.ico").exists() {
-            res.set_icon("logo.ico");
-        } else {
-            println!("cargo:warning=logo.ico not found, skipping icon embedding");
-            return;
+    let target = std::env::var("CARGO_CFG_TARGET_OS").unwrap();
+    let capi_enabled = std::env::var_os("CARGO_FEATURE_CAPI").is_some();
+
+    match target.as_str() {
+        "linux" if capi_enabled => {
+            println!("cargo:rustc-link-arg-bin=rustpython=-Wl,--export-dynamic");
         }
-        res.compile()
-            .map_err(|e| {
-                println!("cargo:warning=Failed to compile Windows resources: {e}");
-            })
-            .ok();
+        "macos" if capi_enabled => {
+            println!("cargo:rustc-link-arg-bin=rustpython=-Wl,-export_dynamic");
+        }
+        "windows" => {
+            println!("cargo:rerun-if-changed=logo.ico");
+            let mut res = winresource::WindowsResource::new();
+            if std::path::Path::new("logo.ico").exists() {
+                res.set_icon("logo.ico");
+            } else {
+                println!("cargo:warning=logo.ico not found, skipping icon embedding");
+                return;
+            }
+            res.compile()
+                .map_err(|e| {
+                    println!("cargo:warning=Failed to compile Windows resources: {e}");
+                })
+                .ok();
+        }
+        _ => {}
     }
 }
diff --git a/crates/capi/.cargo/config.toml b/crates/capi/.cargo/config.toml
@@ -0,0 +1,3 @@
+[env]
+PYO3_CONFIG_FILE = { value = "pyo3-rustpython.config", relative = true }
+PYO3_NO_PYTHON = { value = "1" }
diff --git a/crates/capi/Cargo.toml b/crates/capi/Cargo.toml
@@ -0,0 +1,26 @@
+[package]
+name = "rustpython-capi"
+description = "Minimal CPython C-API compatibility exports for RustPython"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+license.workspace = true
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+rustpython-vm = { workspace = true, features = ["threading"] }
+rustpython-stdlib = {workspace = true, features = ["threading"] }
+
+[dev-dependencies]
+pyo3 = { version = "0.28", features = ["auto-initialize", "abi3"] }
+
+[lints]
+workspace = true
+
+[package.metadata.cargo-shear]
+# Not a direct dependency (yet), but we need to enable threading support in the stdlib.
+ignored = ["rustpython-stdlib"]
diff --git a/crates/capi/pyo3-rustpython.config b/crates/capi/pyo3-rustpython.config
@@ -0,0 +1,5 @@
+implementation=CPython
+version=3.14
+shared=true
+abi3=true
+suppress_build_script_link_lines=true
diff --git a/crates/capi/src/lib.rs b/crates/capi/src/lib.rs
@@ -0,0 +1,33 @@
+#![allow(clippy::missing_safety_doc)]
+
+use crate::pyerrors::init_exception_statics;
+use crate::pylifecycle::MAIN_INTERP;
+pub use rustpython_vm::PyObject;
+use rustpython_vm::{Context, Interpreter};
+use std::sync::MutexGuard;
+
+extern crate alloc;
+
+pub mod object;
+pub mod pyerrors;
+pub mod pylifecycle;
+pub mod pystate;
+pub mod refcount;
+mod util;
+
+/// Get main interpreter of this process. Will be None if it has not been initialized yet.
+pub fn get_main_interpreter() -> MutexGuard<'static, Option<Interpreter>> {
+    MAIN_INTERP
+        .lock()
+        .expect("Failed to lock interpreter mutex")
+}
+
+/// Set the main interpreter of this process. This method will panic when there is already an
+/// interpreter set.
+pub fn set_main_interpreter(interpreter: Interpreter) {
+    let mut interp = get_main_interpreter();
+    assert!(interp.is_none(), "Main interpreter is already set");
+    // Safety: Interpreter was not initialized before, so we can safely assume the statics are not used
+    unsafe { init_exception_statics(&Context::genesis().exceptions) };
+    *interp = Some(interpreter);
+}
diff --git a/crates/capi/src/object.rs b/crates/capi/src/object.rs
@@ -0,0 +1,83 @@
+use crate::PyObject;
+use crate::pystate::with_vm;
+use core::ffi::{c_int, c_uint, c_ulong};
+use rustpython_vm::builtins::PyType;
+use rustpython_vm::{AsObject, Context, Py};
+
+const PY_TPFLAGS_LONG_SUBCLASS: c_ulong = 1 << 24;
+const PY_TPFLAGS_LIST_SUBCLASS: c_ulong = 1 << 25;
+const PY_TPFLAGS_TUPLE_SUBCLASS: c_ulong = 1 << 26;
+const PY_TPFLAGS_BYTES_SUBCLASS: c_ulong = 1 << 27;
+const PY_TPFLAGS_UNICODE_SUBCLASS: c_ulong = 1 << 28;
+const PY_TPFLAGS_DICT_SUBCLASS: c_ulong = 1 << 29;
+const PY_TPFLAGS_BASE_EXC_SUBCLASS: c_ulong = 1 << 30;
+const PY_TPFLAGS_TYPE_SUBCLASS: c_ulong = 1 << 31;
+
+pub type PyTypeObject = Py<PyType>;
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn Py_TYPE(op: *mut PyObject) -> *const PyTypeObject {
+    unsafe { (*op).class() }
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn Py_IS_TYPE(op: *mut PyObject, ty: *mut PyTypeObject) -> c_int {
+    with_vm(|_vm| {
+        let obj = unsafe { &*op };
+        let ty = unsafe { &*ty };
+        obj.class().is(ty)
+    })
+}
+
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn PyType_GetFlags(ptr: *const PyTypeObject) -> c_ulong {
+    let ctx = Context::genesis();
+    let zoo = &ctx.types;
+    let exp_zoo = &ctx.exceptions;
+
+    let ty = unsafe { &*ptr };
+    let mut flags = ty.slots.flags.bits();
+
+    if ty.is_subtype(zoo.int_type) {
+        flags |= PY_TPFLAGS_LONG_SUBCLASS;
+    }
+    if ty.is_subtype(zoo.list_type) {
+        flags |= PY_TPFLAGS_LIST_SUBCLASS
+    }
+    if ty.is_subtype(zoo.tuple_type) {
+        flags |= PY_TPFLAGS_TUPLE_SUBCLASS;
+    }
+    if ty.is_subtype(zoo.bytes_type) {
+        flags |= PY_TPFLAGS_BYTES_SUBCLASS;
+    }
+    if ty.is_subtype(zoo.str_type) {
+        flags |= PY_TPFLAGS_UNICODE_SUBCLASS;
+    }
+    if ty.is_subtype(zoo.dict_type) {
+        flags |= PY_TPFLAGS_DICT_SUBCLASS;
+    }
+    if ty.is_subtype(exp_zoo.base_exception_type) {
+        flags |= PY_TPFLAGS_BASE_EXC_SUBCLASS;
+    }
+    if ty.is_subtype(zoo.type_type) {
+        flags |= PY_TPFLAGS_TYPE_SUBCLASS;
+    }
+
+    flags
+}
+
+#[unsafe(no_mangle)]
+pub extern "C" fn Py_GetConstantBorrowed(constant_id: c_uint) -> *mut PyObject {
+    with_vm(|vm| {
+        let ctx = &vm.ctx;
+        match constant_id {
+            0 => ctx.none.as_object(),
+            1 => ctx.false_value.as_object(),
+            2 => ctx.true_value.as_object(),
+            3 => ctx.ellipsis.as_object(),
+            4 => ctx.not_implemented.as_object(),
+            _ => panic!("Invalid constant_id passed to Py_GetConstantBorrowed"),
+        }
+        .as_raw()
+    })
+}
-Original file line number
+Diff line change
@@ Expand Up / @@ -161,6 +161,7 @@ Pyfunc @@
     pylifecycle
     pymain
     pyrepl
+    pystate
     PYTHONTRACEMALLOC
     PYTHONUTF8
     pythonw
@@ Expand Down @@