From 9beb44251d63ef7cf0a1f9f05009dcbaf7cf627a Mon Sep 17 00:00:00 2001 From: Cedric Hutchings Date: Sun, 26 Jan 2020 00:42:35 -0500 Subject: [PATCH 1/5] Add examples showcasing how to embed RustPython in Rust applications --- README.md | 7 ++++++ examples/hello_embed.rs | 20 ++++++++++++++++ examples/mini_repl.rs | 53 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+) create mode 100644 examples/hello_embed.rs create mode 100644 examples/mini_repl.rs diff --git a/README.md b/README.md index b8c28aadf..9dcb647b4 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,13 @@ cargo build --release --target wasm32-wasi --features="freeze-stdlib" > Note: we use the `freeze-stdlib` to include the standard library inside the binary. + +## Embedding RustPython into your Rust Applications + +Interested in exposing Python scripting in an application written in Rust, +perhaps to allow quickly tweaking logic where Rust's compile times would be inhibitive? +Then `examples/hello_embed.rs` and `examples/mini_repl.rs` may be of some assistance. + ## Disclaimer RustPython is in a development phase and should not be used in production or a diff --git a/examples/hello_embed.rs b/examples/hello_embed.rs new file mode 100644 index 000000000..c8c5a8c54 --- /dev/null +++ b/examples/hello_embed.rs @@ -0,0 +1,20 @@ +use rustpython_compiler::compile; +use rustpython_vm::{pyobject::PyResult, PySettings, VirtualMachine}; + +fn main() -> PyResult<()> { + let vm = VirtualMachine::new(PySettings::default()); + + let scope = vm.new_scope_with_builtins(); + + let code_obj = vm + .compile( + r#"print("Hello World!")"#, + compile::Mode::Exec, + "".to_string(), + ) + .map_err(|err| vm.new_syntax_error(&err))?; + + vm.run_code_obj(code_obj, scope)?; + + Ok(()) +} diff --git a/examples/mini_repl.rs b/examples/mini_repl.rs new file mode 100644 index 000000000..8cbdb35c3 --- /dev/null +++ b/examples/mini_repl.rs @@ -0,0 +1,53 @@ +///! This example show cases a very simple REPL. +///! While a much better REPL can be found in ../src/shell, +///! This much smaller REPL is still a useful example because it showcases inserting +///! values and functions into the Python runtime's scope, and showcases use +///! of the compilation mode "Single". +///! Note that in particular this REPL does a horrible job of showing users their errors +///! (instead it simply crashes). +use rustpython_compiler::compile; +use rustpython_vm::{pyobject::PyResult, PySettings, VirtualMachine}; +// this needs to be in scope in order to insert things into scope.globals +use rustpython_vm::pyobject::ItemProtocol; + +fn main() -> PyResult<()> { + let mut on = true; + + let mut input = String::with_capacity(50); + let stdin = std::io::stdin(); + + let vm = VirtualMachine::new(PySettings::default()); + let scope = vm.new_scope_with_builtins(); + + // typing `quit()` is too long, let's make `on(False)` work instead. + scope + .globals + .set_item( + "on", + vm.context().new_rustfunc({ + let on: *mut bool = &mut on; + move |b: bool, _: &VirtualMachine| unsafe { *on = b } + }), + &vm, + ) + .unwrap(); + + while on { + input.clear(); + stdin.read_line(&mut input).unwrap(); + + let code_obj = vm + .compile(&input, compile::Mode::Single, "".to_string()) + .map_err(|err| vm.new_syntax_error(&err))?; + + // this line also automatically prints the output + let output = vm.run_code_obj(code_obj, scope.clone())?; + + // store the last value in the "last" variable + if !vm.is_none(&output) { + scope.globals.set_item("last", output, &vm).unwrap(); + } + } + + Ok(()) +} From c6aed0464aedf1bb20aa9dda26165dc006a8f6b9 Mon Sep 17 00:00:00 2001 From: Cedric Hutchings Date: Sun, 26 Jan 2020 01:04:53 -0500 Subject: [PATCH 2/5] Add note about when output is printed to mini_repl.rs --- examples/mini_repl.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/mini_repl.rs b/examples/mini_repl.rs index 8cbdb35c3..7484a6c75 100644 --- a/examples/mini_repl.rs +++ b/examples/mini_repl.rs @@ -41,6 +41,7 @@ fn main() -> PyResult<()> { .map_err(|err| vm.new_syntax_error(&err))?; // this line also automatically prints the output + // (note that this is only the case when compile::Mode::Single is passed to vm.compile) let output = vm.run_code_obj(code_obj, scope.clone())?; // store the last value in the "last" variable From d1f74f90cd3bca0fbaa2bedec276ab97c28e81a6 Mon Sep 17 00:00:00 2001 From: Cedric Hutchings Date: Sun, 26 Jan 2020 15:29:58 -0500 Subject: [PATCH 3/5] Make suggested improvements to mini_repl.rs --- examples/mini_repl.rs | 125 +++++++++++++++++++++++++++++++----------- 1 file changed, 94 insertions(+), 31 deletions(-) diff --git a/examples/mini_repl.rs b/examples/mini_repl.rs index 7484a6c75..e199fbd4f 100644 --- a/examples/mini_repl.rs +++ b/examples/mini_repl.rs @@ -3,50 +3,113 @@ ///! This much smaller REPL is still a useful example because it showcases inserting ///! values and functions into the Python runtime's scope, and showcases use ///! of the compilation mode "Single". -///! Note that in particular this REPL does a horrible job of showing users their errors -///! (instead it simply crashes). -use rustpython_compiler::compile; -use rustpython_vm::{pyobject::PyResult, PySettings, VirtualMachine}; +use rustpython_compiler as compiler; +use rustpython_vm as vm; +// these are needed for special pointer shenanigans to let us share a variable with Python and Rust +use std::cell::Cell; +use std::rc::Rc; // this needs to be in scope in order to insert things into scope.globals -use rustpython_vm::pyobject::ItemProtocol; +use vm::pyobject::ItemProtocol; -fn main() -> PyResult<()> { - let mut on = true; +// This has to be a macro because it uses the py_compile_bytecode macro, +// which compiles python source to optimized bytecode at compile time, so that +// the program you're embedding this into doesn't take longer to start up. +macro_rules! add_python_function { + ( $scope:ident, $vm:ident, $src:literal $(,)? ) => {{ + // this has to be in scope to turn a PyValue into a PyRef + // (a PyRef is a special reference that points to something in the VirtualMachine) + use vm::pyobject::PyValue; + + // you can safely assume that only one module will be created when passing a source literal + // to py_compile_bytecode. However, it is also possible to pass directories, which may + // return more modules. + let (_, vm::bytecode::FrozenModule { code, .. }): (String, _) = + vm::py_compile_bytecode!(source = $src) + .into_iter() + .collect::>() + .pop() + .expect("No modules found in the provided source!"); + + // takes the first constant in the file that's a function + let def = code + .get_constants() + .find_map(|c| match c { + vm::bytecode::Constant::Code { code } => Some(code), + _ => None, + }) + .expect("No functions found in the provided module!"); + + // inserts the first function found in the module into the provided scope. + $scope.globals.set_item( + &def.obj_name, + $vm.context().new_pyfunction( + vm::obj::objcode::PyCode::new(*def.clone()).into_ref(&$vm), + $scope.clone(), + None, + None, + ), + &$vm, + ) + }}; +} + +fn main() -> vm::pyobject::PyResult<()> { + // you can also use a raw pointer instead of Rc>, but that requires usage of unsafe. + // both methods are ways of circumnavigating the fact that Python doesn't respect Rust's borrow + // checking rules. + let on: Rc> = Rc::new(Cell::new(true)); let mut input = String::with_capacity(50); let stdin = std::io::stdin(); - let vm = VirtualMachine::new(PySettings::default()); - let scope = vm.new_scope_with_builtins(); + let vm = vm::VirtualMachine::new(vm::PySettings::default()); + let scope: vm::scope::Scope = vm.new_scope_with_builtins(); // typing `quit()` is too long, let's make `on(False)` work instead. - scope - .globals - .set_item( - "on", - vm.context().new_rustfunc({ - let on: *mut bool = &mut on; - move |b: bool, _: &VirtualMachine| unsafe { *on = b } - }), - &vm, - ) - .unwrap(); + scope.globals.set_item( + "on", + vm.context().new_function({ + let on = Rc::clone(&on); + move |b: bool| on.set(b) + }), + &vm, + )?; - while on { + // let's include a fibonacci function, but let's be lazy and write it in Python + add_python_function!( + scope, + vm, + // a fun line to test this with is + // ''.join( l * fib(i) for i, l in enumerate('supercalifragilistic') ) + r#"def fib(n): return n if n <= 1 else fib(n - 1) + fib(n - 2)"# + )?; + + while on.get() { input.clear(); - stdin.read_line(&mut input).unwrap(); - - let code_obj = vm - .compile(&input, compile::Mode::Single, "".to_string()) - .map_err(|err| vm.new_syntax_error(&err))?; + stdin + .read_line(&mut input) + .expect("Failed to read line of input"); // this line also automatically prints the output // (note that this is only the case when compile::Mode::Single is passed to vm.compile) - let output = vm.run_code_obj(code_obj, scope.clone())?; - - // store the last value in the "last" variable - if !vm.is_none(&output) { - scope.globals.set_item("last", output, &vm).unwrap(); + match vm + .compile( + &input, + compiler::compile::Mode::Single, + "".to_string(), + ) + .map_err(|err| vm.new_syntax_error(&err)) + .and_then(|code_obj| vm.run_code_obj(code_obj, scope.clone())) + { + Ok(output) => { + // store the last value in the "last" variable + if !vm.is_none(&output) { + scope.globals.set_item("last", output, &vm)?; + } + } + Err(e) => { + vm::exceptions::print_exception(&vm, &e); + } } } From 93ccc69d7d379393bed7cc290ceef432d7109514 Mon Sep 17 00:00:00 2001 From: Cedric Hutchings Date: Sun, 26 Jan 2020 15:40:01 -0500 Subject: [PATCH 4/5] Replace 'pointer' with 'memory' --- examples/mini_repl.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/mini_repl.rs b/examples/mini_repl.rs index e199fbd4f..7a7da6088 100644 --- a/examples/mini_repl.rs +++ b/examples/mini_repl.rs @@ -5,7 +5,7 @@ ///! of the compilation mode "Single". use rustpython_compiler as compiler; use rustpython_vm as vm; -// these are needed for special pointer shenanigans to let us share a variable with Python and Rust +// these are needed for special memory shenanigans to let us share a variable with Python and Rust use std::cell::Cell; use std::rc::Rc; // this needs to be in scope in order to insert things into scope.globals From 62de9548983b429f477ceed10f1d6d529d8e5da6 Mon Sep 17 00:00:00 2001 From: Cedric Hutchings Date: Sun, 26 Jan 2020 16:02:48 -0500 Subject: [PATCH 5/5] Use more specific scoping in hello_embed.rs --- examples/hello_embed.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/examples/hello_embed.rs b/examples/hello_embed.rs index c8c5a8c54..7db217483 100644 --- a/examples/hello_embed.rs +++ b/examples/hello_embed.rs @@ -1,15 +1,15 @@ -use rustpython_compiler::compile; -use rustpython_vm::{pyobject::PyResult, PySettings, VirtualMachine}; +use rustpython_compiler as compiler; +use rustpython_vm as vm; -fn main() -> PyResult<()> { - let vm = VirtualMachine::new(PySettings::default()); +fn main() -> vm::pyobject::PyResult<()> { + let vm = vm::VirtualMachine::new(vm::PySettings::default()); let scope = vm.new_scope_with_builtins(); let code_obj = vm .compile( r#"print("Hello World!")"#, - compile::Mode::Exec, + compiler::compile::Mode::Exec, "".to_string(), ) .map_err(|err| vm.new_syntax_error(&err))?;