#![deny(unsafe_op_in_unsafe_fn)]
mod ffi;
use std::ffi::{CStr, CString};
use std::fmt;
use std::path::{Path, PathBuf};
use std::ptr::NonNull;
use std::sync::OnceLock;
pub const PYTHON_VERSION: &str = env!("PYLINK_PYTHON_VERSION");
pub const PYTHON_RELEASE: &str = env!("PYLINK_PYTHON_RELEASE");
pub const PYO3_CONFIG_FILE: &str = env!("PYLINK_PYO3_CONFIG_FILE");
pub const BUILD_PYTHON_HOME: &str = env!("PYLINK_PYTHON_HOME");
static INITIALIZATION: OnceLock<Result<PathBuf, Error>> = OnceLock::new();
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Error {
InvalidHome { path: PathBuf, reason: String },
InvalidPath(PathBuf),
NonUnicodePath(PathBuf),
CurrentExecutable(String),
Initialization(String),
AlreadyInitialized {
initialized_home: PathBuf,
requested_home: PathBuf,
},
}
impl fmt::Display for Error {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidHome { path, reason } => {
write!(
formatter,
"invalid Python home {}: {reason}",
path.display()
)
}
Self::InvalidPath(path) => {
write!(
formatter,
"path contains a null character: {}",
path.display()
)
}
Self::NonUnicodePath(path) => {
write!(
formatter,
"Python initialization requires a valid Unicode path: {}",
path.display()
)
}
Self::CurrentExecutable(reason) => {
write!(formatter, "cannot locate the current executable: {reason}")
}
Self::Initialization(reason) => {
write!(formatter, "cannot initialize CPython: {reason}")
}
Self::AlreadyInitialized {
initialized_home,
requested_home,
} => write!(
formatter,
"CPython already uses {}; cannot switch to {}",
initialized_home.display(),
requested_home.display()
),
}
}
}
impl std::error::Error for Error {}
pub fn runtime_home() -> Result<PathBuf, Error> {
if let Some(result) = INITIALIZATION.get() {
return result.clone();
}
let executable = current_executable()?;
let override_home = std::env::var_os("PYLINK_PYTHON_HOME").map(PathBuf::from);
resolve_home(override_home, &executable, Path::new(BUILD_PYTHON_HOME))
}
pub fn initialize() -> Result<(), Error> {
if let Some(result) = INITIALIZATION.get() {
return result.as_ref().map(|_| ()).map_err(Clone::clone);
}
initialize_from(runtime_home()?)
}
pub fn initialize_from(home: impl AsRef<Path>) -> Result<(), Error> {
let home = validate_home(home.as_ref())?;
let home_string = utf8_path(&home)?;
let executable = utf8_path(¤t_executable()?)?;
let result = INITIALIZATION
.get_or_init(|| initialize_interpreter(&home_string, &executable).map(|()| home.clone()));
match result {
Ok(initialized_home) if initialized_home == &home => Ok(()),
Ok(initialized_home) => Err(Error::AlreadyInitialized {
initialized_home: initialized_home.clone(),
requested_home: home,
}),
Err(error) => Err(error.clone()),
}
}
fn current_executable() -> Result<PathBuf, Error> {
std::env::current_exe().map_err(|error| Error::CurrentExecutable(error.to_string()))
}
fn resolve_home(
override_home: Option<PathBuf>,
executable: &Path,
build_home: &Path,
) -> Result<PathBuf, Error> {
if let Some(home) = override_home {
return validate_home(&home);
}
if let Some(parent) = executable.parent() {
let adjacent = parent.join("python");
if path_is_present(&adjacent) {
return validate_home(&adjacent);
}
#[cfg(target_os = "macos")]
if parent.file_name().is_some_and(|name| name == "MacOS")
&& let Some(contents) = parent.parent()
{
let resources = contents.join("Resources/python");
if path_is_present(&resources) {
return validate_home(&resources);
}
}
}
validate_home(build_home)
}
fn path_is_present(path: &Path) -> bool {
match std::fs::symlink_metadata(path) {
Ok(_) => true,
Err(error) => error.kind() != std::io::ErrorKind::NotFound,
}
}
fn standard_library(home: &Path) -> PathBuf {
if cfg!(windows) {
home.join("Lib")
} else {
let mut version = PYTHON_VERSION.split('.');
let major = version.next().expect("build-time Python major version");
let minor = version.next().expect("build-time Python minor version");
home.join("lib").join(format!("python{major}.{minor}"))
}
}
fn validate_home(home: &Path) -> Result<PathBuf, Error> {
let _ = utf8_path(home)?;
let resolved = home.canonicalize().map_err(|error| Error::InvalidHome {
path: home.to_path_buf(),
reason: error.to_string(),
})?;
let _ = utf8_path(&resolved)?;
let version_marker = resolved.join(".pylink-version");
match std::fs::read_to_string(&version_marker) {
Ok(version) if version.trim() == PYTHON_VERSION => {}
Ok(version) => {
return Err(Error::InvalidHome {
path: resolved,
reason: format!(
".pylink-version specifies Python {:?}; expected {PYTHON_VERSION}",
version.trim()
),
});
}
Err(error)
if error.kind() == std::io::ErrorKind::NotFound
&& !path_is_present(&version_marker) => {}
Err(error) => {
return Err(Error::InvalidHome {
path: resolved,
reason: format!("cannot read .pylink-version: {error}"),
});
}
}
if !standard_library(&resolved)
.join("encodings")
.join("__init__.py")
.is_file()
{
return Err(Error::InvalidHome {
path: resolved,
reason: format!(
"missing the Python {PYTHON_VERSION} standard library (encodings/__init__.py)"
),
});
}
Ok(resolved)
}
fn initialize_interpreter(home: &CStr, executable: &CStr) -> Result<(), Error> {
unsafe {
if ffi::Py_IsInitialized() != 0 {
return Err(Error::Initialization(
"CPython was initialized outside pylink; call pylink::initialize() first".into(),
));
}
let loaded = CStr::from_ptr(ffi::Py_GetVersion()).to_bytes();
if loaded.split(|byte| *byte == b' ').next() != Some(PYTHON_VERSION.as_bytes()) {
return Err(Error::Initialization(format!(
"loaded CPython does not match the selected version ({PYTHON_VERSION})"
)));
}
}
let mut config = InitConfig::new()?;
config.set_int(c"utf8_mode", 1)?;
config.set_int(c"parse_argv", 0)?;
config.set_int(c"install_signal_handlers", 0)?;
config.set_int(c"write_bytecode", 0)?;
config.set_str(c"home", home)?;
config.set_str(c"executable", executable)?;
config.check(unsafe { ffi::Py_InitializeFromInitConfig(config.0.as_ptr()) })?;
drop(config);
unsafe { ffi::PyEval_SaveThread() };
Ok(())
}
struct InitConfig(NonNull<ffi::PyInitConfig>);
impl InitConfig {
fn new() -> Result<Self, Error> {
NonNull::new(unsafe { ffi::PyInitConfig_Create() })
.map(Self)
.ok_or_else(|| Error::Initialization("cannot allocate Python configuration".into()))
}
fn set_int(&mut self, name: &CStr, value: i64) -> Result<(), Error> {
self.check(unsafe { ffi::PyInitConfig_SetInt(self.0.as_ptr(), name.as_ptr(), value) })
}
fn set_str(&mut self, name: &CStr, value: &CStr) -> Result<(), Error> {
self.check(unsafe {
ffi::PyInitConfig_SetStr(self.0.as_ptr(), name.as_ptr(), value.as_ptr())
})
}
fn check(&self, status: std::ffi::c_int) -> Result<(), Error> {
if status == 0 {
return Ok(());
}
let mut message = std::ptr::null();
unsafe { ffi::PyInitConfig_GetError(self.0.as_ptr(), &mut message) };
let message = if message.is_null() {
"unknown Python initialization error".into()
} else {
unsafe { CStr::from_ptr(message) }
.to_string_lossy()
.into_owned()
};
Err(Error::Initialization(message))
}
}
impl Drop for InitConfig {
fn drop(&mut self) {
unsafe { ffi::PyInitConfig_Free(self.0.as_ptr()) };
}
}
fn utf8_path(path: &Path) -> Result<CString, Error> {
let value = path
.to_str()
.ok_or_else(|| Error::NonUnicodePath(path.to_path_buf()))?;
CString::new(value).map_err(|_| Error::InvalidPath(path.to_path_buf()))
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicUsize, Ordering};
static NEXT_TEMP: AtomicUsize = AtomicUsize::new(0);
struct TempDir(PathBuf);
impl TempDir {
fn new() -> Self {
let path = std::env::temp_dir().join(format!(
"pylink-runtime-{}-{}",
std::process::id(),
NEXT_TEMP.fetch_add(1, Ordering::Relaxed)
));
std::fs::create_dir_all(&path).unwrap();
Self(path)
}
fn python_home(&self, relative: &str) -> PathBuf {
let home = self.0.join(relative);
let encodings = standard_library(&home).join("encodings");
std::fs::create_dir_all(&encodings).unwrap();
std::fs::write(encodings.join("__init__.py"), "").unwrap();
home.canonicalize().unwrap()
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
#[test]
fn discovery_prefers_override_then_bundle_then_cache() {
let temp = TempDir::new();
let cache = temp.python_home("cache");
let executable = temp.0.join("app/bin");
assert_eq!(resolve_home(None, &executable, &cache).unwrap(), cache);
let adjacent = temp.python_home("app/python");
assert_eq!(resolve_home(None, &executable, &cache).unwrap(), adjacent);
let explicit = temp.python_home("custom");
assert_eq!(
resolve_home(Some(explicit.clone()), &executable, &cache).unwrap(),
explicit
);
assert!(resolve_home(Some(temp.0.join("missing")), &executable, &cache).is_err());
}
#[test]
fn invalid_bundle_does_not_fall_back_to_cache() {
let temp = TempDir::new();
let cache = temp.python_home("cache");
std::fs::create_dir_all(temp.0.join("app/python")).unwrap();
assert!(matches!(
resolve_home(None, &temp.0.join("app/bin"), &cache),
Err(Error::InvalidHome { .. })
));
}
#[cfg(unix)]
#[test]
fn broken_bundle_symlink_does_not_fall_back_to_cache() {
let temp = TempDir::new();
let cache = temp.python_home("cache");
std::os::unix::fs::symlink(temp.0.join("missing"), temp.0.join("python")).unwrap();
assert!(matches!(
resolve_home(None, &temp.0.join("app"), &cache),
Err(Error::InvalidHome { .. })
));
}
#[test]
fn version_marker_must_match_the_exact_selected_version() {
let temp = TempDir::new();
let home = temp.python_home("python");
let marker = home.join(".pylink-version");
assert_eq!(validate_home(&home).unwrap(), home);
std::fs::write(&marker, format!("{PYTHON_VERSION}\n")).unwrap();
assert_eq!(validate_home(&home).unwrap(), home);
let version_with_wrong_patch =
format!("{}.99999", PYTHON_VERSION.rsplit_once('.').unwrap().0);
std::fs::write(&marker, &version_with_wrong_patch).unwrap();
let error = validate_home(&home).unwrap_err();
assert!(matches!(error, Error::InvalidHome { .. }));
assert!(error.to_string().contains(&version_with_wrong_patch));
assert!(error.to_string().contains(PYTHON_VERSION));
std::fs::write(&marker, [0xff]).unwrap();
assert!(validate_home(&home).is_err());
#[cfg(unix)]
{
std::fs::remove_file(&marker).unwrap();
std::os::unix::fs::symlink(home.join("missing"), &marker).unwrap();
assert!(validate_home(&home).is_err());
}
}
#[cfg(target_os = "macos")]
#[test]
fn discovers_macos_resources_bundle() {
let temp = TempDir::new();
let resources = temp.python_home("App.app/Contents/Resources/python");
assert_eq!(
resolve_home(
None,
&temp.0.join("App.app/Contents/MacOS/app"),
&temp.0.join("missing")
)
.unwrap(),
resources
);
}
#[test]
fn encodes_unicode_and_rejects_nulls() {
let encoded = utf8_path(Path::new("Python-\u{03bb}-\u{1f40d}")).unwrap();
assert_eq!(encoded.to_str().unwrap(), "Python-\u{03bb}-\u{1f40d}");
assert!(matches!(
utf8_path(Path::new("bad\0path")),
Err(Error::InvalidPath(_))
));
}
#[cfg(unix)]
#[test]
fn rejects_non_utf8_unix_paths() {
use std::os::unix::ffi::OsStrExt;
let path = Path::new(std::ffi::OsStr::from_bytes(b"x\xff\xe2\x82y"));
assert!(matches!(utf8_path(path), Err(Error::NonUnicodePath(_))));
}
}