Basic GraalPy Support (#3247)

* graalpy: recognize graalpy implementation when building

* graalpy: global Ellipse, None, NotImplemented, True, and False are only available as pointers

* graalpy: PyObject struct is opaque, use functions for everything

* graalpy: missing many of the same functions as pypy

* graalpy: do not have 128bit conversion functions

* graalpy: add functions for datetime accessor macros

* graalpy: add implementations for list macro functions

* graalpy: skip tuple macros

* graalpy: always use extern Py_CompileString function

* graalpy: disable assertion that does not apply to graalpy

* graalpy: floatobject structure is opaque on graalpy

* graalpy: ignore gc dependent test

* graalpy: add CI config

* graalpy: run rust fmt

* graalpy: add changelog entry

* graalpy: discover interpreter on PATH

* graalpy: interpreter id is not applicable to graalpy (just like pypy)

* graalpy: skip tests that cannot work on GraalPy

* graalpy: fix constructing normalized Err instances

Co-authored-by: David Hewitt <mail@davidhewitt.dev>

* graalpy: correct capi library name, but skip rust tests due to missing symbols

* graalpy: no support for C extensions on windows in latest release

* graalpy: declare support versions

* graalpy: frame, code, method, and function objects access from C API is mostly missing

* graalpy: take care only to expose C structure that GraalPy allocates

* graalpy: Bail out if graalpy version is less than what we support

---------

Co-authored-by: David Hewitt <mail@davidhewitt.dev>

.github/workflows/build.yml

@@ -24,6 +24,7 @@ jobs:
  build:
  continue-on-error: ${{ endsWith(inputs.python-version, '-dev') || contains(fromJSON('["3.7", "pypy3.7"]'), inputs.python-version) || inputs.rust == 'beta' || inputs.rust == 'nightly' }}
  runs-on: ${{ inputs.os }}
+ if: ${{ !(startsWith(inputs.python-version, 'graalpy') && startsWith(inputs.os, 'windows')) }}
  steps:
  - uses: actions/checkout@v4
 
@@ -65,6 +66,7 @@ jobs:
  run: nox -s docs
 
  - name: Build (no features)
+ if: ${{ !startsWith(inputs.python-version, 'graalpy') }}
  run: cargo build --lib --tests --no-default-features
 
  # --no-default-features when used with `cargo build/test -p` doesn't seem to work!
@@ -74,7 +76,7 @@ jobs:
  cargo build --no-default-features
 
  # Run tests (except on PyPy, because no embedding API).
- - if: ${{ !startsWith(inputs.python-version, 'pypy') }}
+ - if: ${{ !startsWith(inputs.python-version, 'pypy') && !startsWith(inputs.python-version, 'graalpy') }}
  name: Test (no features)
  run: cargo test --no-default-features --lib --tests
 
@@ -85,24 +87,25 @@ jobs:
  cargo test --no-default-features
 
  - name: Build (all additive features)
+ if: ${{ !startsWith(inputs.python-version, 'graalpy') }}
  run: cargo build --lib --tests --no-default-features --features "full ${{ inputs.extra-features }}"
 
  - if: ${{ startsWith(inputs.python-version, 'pypy') }}
  name: Build PyPy (abi3-py37)
  run: cargo build --lib --tests --no-default-features --features "abi3-py37 full ${{ inputs.extra-features }}"
 
  # Run tests (except on PyPy, because no embedding API).
- - if: ${{ !startsWith(inputs.python-version, 'pypy') }}
+ - if: ${{ !startsWith(inputs.python-version, 'pypy') && !startsWith(inputs.python-version, 'graalpy') }}
  name: Test
  run: cargo test --no-default-features --features "full ${{ inputs.extra-features }}"
 
  # Run tests again, but in abi3 mode
- - if: ${{ !startsWith(inputs.python-version, 'pypy') }}
+ - if: ${{ !startsWith(inputs.python-version, 'pypy') && !startsWith(inputs.python-version, 'graalpy') }}
  name: Test (abi3)
  run: cargo test --no-default-features --features "abi3 full ${{ inputs.extra-features }}"
 
  # Run tests again, for abi3-py37 (the minimal Python version)
- - if: ${{ (!startsWith(inputs.python-version, 'pypy')) && (inputs.python-version != '3.7') }}
+ - if: ${{ (!startsWith(inputs.python-version, 'pypy') && !startsWith(inputs.python-version, 'graalpy')) && (inputs.python-version != '3.7') }}
  name: Test (abi3-py37)
  run: cargo test --no-default-features --features "abi3-py37 full ${{ inputs.extra-features }}"
 
@@ -120,7 +123,7 @@ jobs:
 
  - uses: dorny/paths-filter@v3
  # pypy 3.7 and 3.8 are not PEP 3123 compliant so fail checks here
- if: ${{ inputs.rust == 'stable' && inputs.python-version != 'pypy3.7' && inputs.python-version != 'pypy3.8' }}
+ if: ${{ inputs.rust == 'stable' && inputs.python-version != 'pypy3.7' && inputs.python-version != 'pypy3.8' && !startsWith(inputs.python-version, 'graalpy') }}
  id: ffi-changes
  with:
  base: ${{ github.event.pull_request.base.ref || github.event.merge_group.base_ref }}
@@ -135,7 +138,7 @@ jobs:
  - name: Run pyo3-ffi-check
  # pypy 3.7 and 3.8 are not PEP 3123 compliant so fail checks here, nor
  # is pypy 3.9 on windows
- if: ${{ endsWith(inputs.python-version, '-dev') || (steps.ffi-changes.outputs.changed == 'true' && inputs.rust == 'stable' && inputs.python-version != 'pypy3.7' && inputs.python-version != 'pypy3.8' && !(inputs.python-version == 'pypy3.9' && contains(inputs.os, 'windows'))) }}
+ if: ${{ endsWith(inputs.python-version, '-dev') || (steps.ffi-changes.outputs.changed == 'true' && inputs.rust == 'stable' && inputs.python-version != 'pypy3.7' && inputs.python-version != 'pypy3.8' && !startsWith(inputs.python-version, 'graalpy') && !(inputs.python-version == 'pypy3.9' && contains(inputs.os, 'windows'))) }}
  run: nox -s ffi-check
 
  env:

.github/workflows/ci.yml

@@ -228,6 +228,7 @@ jobs:
  "pypy3.8",
  "pypy3.9",
  "pypy3.10",
+ "graalpy24.0",
  ]
  platform:
  [

README.md

@@ -17,7 +17,7 @@
 ## Usage
 
 PyO3 supports the following software versions:
- - Python 3.7 and up (CPython and PyPy)
+ - Python 3.7 and up (CPython, PyPy, and GraalPy)
  - Rust 1.56 and up
 
 You can use PyO3 to write a native Python module in Rust, or to embed Python in a Rust binary. The following sections explain each of these in turn.

newsfragments/3247.added.md

@@ -0,0 +1 @@
+Added support for running PyO3 extensions on GraalPy.

pyo3-build-config/src/impl_.rs

@@ -32,6 +32,12 @@ use crate::{
 /// Minimum Python version PyO3 supports.
 const MINIMUM_SUPPORTED_VERSION: PythonVersion = PythonVersion { major: 3, minor: 7 };
 
+/// GraalPy may implement the same CPython version over multiple releases.
+const MINIMUM_SUPPORTED_VERSION_GRAALPY: PythonVersion = PythonVersion {
+ major: 24,
+ minor: 0,
+};
+
 /// Maximum Python version that can be used as minimum required Python version with abi3.
 const ABI3_MAX_MINOR: u8 = 12;
 
@@ -173,6 +179,11 @@ impl InterpreterConfig {
  See https://foss.heptapod.net/pypy/pypy/-/issues/3397 for more information."
  ));
  }
+ } else if self.implementation.is_graalpy() {
+ println!("cargo:rustc-cfg=GraalPy");
+ if self.abi3 {
+ warn!("GraalPy does not support abi3 so the build artifacts will be version-specific.");
+ }
  } else if self.abi3 {
  out.push("cargo:rustc-cfg=Py_LIMITED_API".to_owned());
  }
@@ -197,6 +208,12 @@ import sys
 from sysconfig import get_config_var, get_platform
 
 PYPY = platform.python_implementation() == "PyPy"
+GRAALPY = platform.python_implementation() == "GraalVM"
+
+if GRAALPY:
+ graalpy_ver = map(int, __graalpython__.get_graalvm_version().split('.'));
+ print("graalpy_major", next(graalpy_ver))
+ print("graalpy_minor", next(graalpy_ver))
 
 # sys.base_prefix is missing on Python versions older than 3.3; this allows the script to continue
 # so that the version mismatch can be reported in a nicer way later.
@@ -226,7 +243,7 @@ SHARED = bool(get_config_var("Py_ENABLE_SHARED"))
 print("implementation", platform.python_implementation())
 print("version_major", sys.version_info[0])
 print("version_minor", sys.version_info[1])
-print("shared", PYPY or ANACONDA or WINDOWS or FRAMEWORK or SHARED)
+print("shared", PYPY or GRAALPY or ANACONDA or WINDOWS or FRAMEWORK or SHARED)
 print_if_set("ld_version", get_config_var("LDVERSION"))
 print_if_set("libdir", get_config_var("LIBDIR"))
 print_if_set("base_prefix", base_prefix)
@@ -244,6 +261,23 @@ print("ext_suffix", get_config_var("EXT_SUFFIX"))
  interpreter.as_ref().display()
  );
 
+ if let Some(value) = map.get("graalpy_major") {
+ let graalpy_version = PythonVersion {
+ major: value
+ .parse()
+ .context("failed to parse GraalPy major version")?,
+ minor: map["graalpy_minor"]
+ .parse()
+ .context("failed to parse GraalPy minor version")?,
+ };
+ ensure!(
+ graalpy_version >= MINIMUM_SUPPORTED_VERSION_GRAALPY,
+ "At least GraalPy version {} needed, got {}",
+ MINIMUM_SUPPORTED_VERSION_GRAALPY,
+ graalpy_version
+ );
+ };
+
  let shared = map["shared"].as_str() == "True";
 
  let version = PythonVersion {
@@ -588,7 +622,7 @@ print("ext_suffix", get_config_var("EXT_SUFFIX"))
  /// Lowers the configured version to the abi3 version, if set.
  fn fixup_for_abi3_version(&mut self, abi3_version: Option<PythonVersion>) -> Result<()> {
  // PyPy doesn't support abi3; don't adjust the version
- if self.implementation.is_pypy() {
+ if self.implementation.is_pypy() || self.implementation.is_graalpy() {
  return Ok(());
  }
 
@@ -647,6 +681,7 @@ impl FromStr for PythonVersion {
 pub enum PythonImplementation {
  CPython,
  PyPy,
+ GraalPy,
 }
 
 impl PythonImplementation {
@@ -655,12 +690,19 @@ impl PythonImplementation {
  self == PythonImplementation::PyPy
  }
 
+ #[doc(hidden)]
+ pub fn is_graalpy(self) -> bool {
+ self == PythonImplementation::GraalPy
+ }
+
  #[doc(hidden)]
  pub fn from_soabi(soabi: &str) -> Result<Self> {
  if soabi.starts_with("pypy") {
  Ok(PythonImplementation::PyPy)
  } else if soabi.starts_with("cpython") {
  Ok(PythonImplementation::CPython)
+ } else if soabi.starts_with("graalpy") {
+ Ok(PythonImplementation::GraalPy)
  } else {
  bail!("unsupported Python interpreter");
  }
@@ -672,6 +714,7 @@ impl Display for PythonImplementation {
  match self {
  PythonImplementation::CPython => write!(f, "CPython"),
  PythonImplementation::PyPy => write!(f, "PyPy"),
+ PythonImplementation::GraalPy => write!(f, "GraalVM"),
  }
  }
 }
@@ -682,6 +725,7 @@ impl FromStr for PythonImplementation {
  match s {
  "CPython" => Ok(PythonImplementation::CPython),
  "PyPy" => Ok(PythonImplementation::PyPy),
+ "GraalVM" => Ok(PythonImplementation::GraalPy),
  _ => bail!("unknown interpreter: {}", s),
  }
  }
@@ -760,7 +804,7 @@ pub struct CrossCompileConfig {
  /// The version of the Python library to link against.
  version: Option<PythonVersion>,
 
- /// The target Python implementation hint (CPython or PyPy)
+ /// The target Python implementation hint (CPython, PyPy, GraalPy, ...)
  implementation: Option<PythonImplementation>,
 
  /// The compile target triple (e.g. aarch64-unknown-linux-gnu)
@@ -1264,6 +1308,15 @@ fn is_pypy_lib_dir(path: &str, v: &Option<PythonVersion>) -> bool {
  path == "lib_pypy" || path.starts_with(&pypy_version_pat)
 }
 
+fn is_graalpy_lib_dir(path: &str, v: &Option<PythonVersion>) -> bool {
+ let graalpy_version_pat = if let Some(v) = v {
+ format!("graalpy{}", v)
+ } else {
+ "graalpy2".into()
+ };
+ path == "lib_graalpython" || path.starts_with(&graalpy_version_pat)
+}
+
 fn is_cpython_lib_dir(path: &str, v: &Option<PythonVersion>) -> bool {
  let cpython_version_pat = if let Some(v) = v {
  format!("python{}", v)
@@ -1297,6 +1350,7 @@ fn search_lib_dir(path: impl AsRef<Path>, cross: &CrossCompileConfig) -> Vec<Pat
  search_lib_dir(f.path(), cross)
  } else if is_cpython_lib_dir(&file_name, &cross.version)
  || is_pypy_lib_dir(&file_name, &cross.version)
+ || is_graalpy_lib_dir(&file_name, &cross.version)
  {
  search_lib_dir(f.path(), cross)
  } else {
@@ -1418,7 +1472,7 @@ fn default_cross_compile(cross_compile_config: &CrossCompileConfig) -> Result<In
 ///
 /// Must be called from a PyO3 crate build script.
 fn default_abi3_config(host: &Triple, version: PythonVersion) -> InterpreterConfig {
- // FIXME: PyPy does not support the Stable ABI yet.
+ // FIXME: PyPy & GraalPy do not support the Stable ABI.
  let implementation = PythonImplementation::CPython;
  let abi3 = true;
 
@@ -1524,7 +1578,7 @@ fn default_lib_name_windows(
  // CPython bug: linking against python3_d.dll raises error
  // https://github.com/python/cpython/issues/101614
  format!("python{}{}_d", version.major, version.minor)
- } else if abi3 && !implementation.is_pypy() {
+ } else if abi3 && !(implementation.is_pypy() || implementation.is_graalpy()) {
  WINDOWS_ABI3_LIB_NAME.to_owned()
  } else if mingw {
  // https://packages.msys2.org/base/mingw-w64-python
@@ -1562,6 +1616,7 @@ fn default_lib_name_unix(
  format!("pypy{}-c", version.major)
  }
  }
+ PythonImplementation::GraalPy => "python-native".to_string(),
  }
 }
 
@@ -1662,7 +1717,9 @@ pub fn find_interpreter() -> Result<PathBuf> {
  .find(|bin| {
  if let Ok(out) = Command::new(bin).arg("--version").output() {
  // begin with `Python 3.X.X :: additional info`
- out.stdout.starts_with(b"Python 3") || out.stderr.starts_with(b"Python 3")
+ out.stdout.starts_with(b"Python 3")
+ || out.stderr.starts_with(b"Python 3")
+ || out.stdout.starts_with(b"GraalPy 3")
  } else {
  false
  }

pyo3-build-config/src/import_lib.rs

@@ -7,7 +7,7 @@ use python3_dll_a::ImportLibraryGenerator;
 use target_lexicon::{Architecture, OperatingSystem, Triple};
 
 use super::{PythonImplementation, PythonVersion};
-use crate::errors::{Context, Result};
+use crate::errors::{Context, Error, Result};
 
 /// Generates the `python3.dll` or `pythonXY.dll` import library for Windows targets.
 ///
@@ -42,6 +42,9 @@ pub(super) fn generate_import_lib(
  let implementation = match py_impl {
  PythonImplementation::CPython => python3_dll_a::PythonImplementation::CPython,
  PythonImplementation::PyPy => python3_dll_a::PythonImplementation::PyPy,
+ PythonImplementation::GraalPy => {
+ return Err(Error::from("No support for GraalPy on Windows"))
+ }
  };
 
  ImportLibraryGenerator::new(&arch, &env)

pyo3-build-config/src/lib.rs

@@ -38,6 +38,7 @@ use target_lexicon::OperatingSystem;
 /// | `#[cfg(Py_3_7)]`, `#[cfg(Py_3_8)]`, `#[cfg(Py_3_9)]`, `#[cfg(Py_3_10)]` | These attributes mark code only for a given Python version and up. For example, `#[cfg(Py_3_7)]` marks code which can run on Python 3.7 **and newer**. |
 /// | `#[cfg(Py_LIMITED_API)]` | This marks code which is run when compiling with PyO3's `abi3` feature enabled. |
 /// | `#[cfg(PyPy)]` | This marks code which is run when compiling for PyPy. |
+/// | `#[cfg(GraalPy)]` | This marks code which is run when compiling for GraalPy. |
 ///
 /// For examples of how to use these attributes, [see PyO3's guide](https://pyo3.rs/latest/building-and-distribution/multiple_python_versions.html).
 #[cfg(feature = "resolve-config")]

pyo3-ffi/build.rs

@@ -29,6 +29,17 @@ const SUPPORTED_VERSIONS_PYPY: SupportedVersions = SupportedVersions {
  },
 };
 
+const SUPPORTED_VERSIONS_GRAALPY: SupportedVersions = SupportedVersions {
+ min: PythonVersion {
+ major: 3,
+ minor: 10,
+ },
+ max: PythonVersion {
+ major: 3,
+ minor: 11,
+ },
+};
+
 fn ensure_python_version(interpreter_config: &InterpreterConfig) -> Result<()> {
  // This is an undocumented env var which is only really intended to be used in CI / for testing
  // and development.
@@ -73,6 +84,24 @@ fn ensure_python_version(interpreter_config: &InterpreterConfig) -> Result<()> {
  std::env::var("CARGO_PKG_VERSION").unwrap()
  );
  }
+ PythonImplementation::GraalPy => {
+ let versions = SUPPORTED_VERSIONS_GRAALPY;
+ ensure!(
+ interpreter_config.version >= versions.min,
+ "the configured GraalPy interpreter version ({}) is lower than PyO3's minimum supported version ({})",
+ interpreter_config.version,
+ versions.min,
+ );
+ // GraalPy does not support abi3, so we cannot offer forward compatibility
+ ensure!(
+ interpreter_config.version <= versions.max,
+ "the configured GraalPy interpreter version ({}) is newer than PyO3's maximum supported version ({})\n\
+ = help: please check if an updated version of PyO3 is available. Current version: {}",
+ interpreter_config.version,
+ versions.max,
+ std::env::var("CARGO_PKG_VERSION").unwrap()
+ );
+ }
  }
 
  Ok(())

pyo3-ffi/src/abstract_.rs

@@ -23,6 +23,7 @@ pub unsafe fn PyObject_DelAttr(o: *mut PyObject, attr_name: *mut PyObject) -> c_
 extern "C" {
  #[cfg(all(
  not(PyPy),
+ not(GraalPy),
  any(Py_3_10, all(not(Py_LIMITED_API), Py_3_9)) // Added to python in 3.9 but to limited API in 3.10
  ))]
  #[cfg_attr(PyPy, link_name = "PyPyObject_CallNoArgs")]