Add Python::with_gil

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [Unreleased]
 ### Added
 - Add FFI definitions `Py_FinalizeEx`, `PyOS_getsig`, `PyOS_setsig`. [#1021](https://github.com/PyO3/pyo3/pull/1021)
+- Add `Python::with_gil` for executing a closure with the Python GIL. [#1037](https://github.com/PyO3/pyo3/pull/1037)
 
 ### Changed
 - Correct FFI definitions `Py_SetProgramName` and `Py_SetPythonHome` to take `*const` argument instead of `*mut`. [#1021](https://github.com/PyO3/pyo3/pull/1021)

README.md

@@ -108,12 +108,12 @@ use pyo3::prelude::*;
 use pyo3::types::IntoPyDict;
 
 fn main() -> Result<(), ()> {
- let gil = Python::acquire_gil();
- let py = gil.python();
- main_(py).map_err(|e| {
- // We can't display Python exceptions via std::fmt::Display,
- // so print the error here manually.
- e.print_and_set_sys_last_vars(py);
+ Python::with_gil(|py| {
+  main_(py).map_err(|e| {
+  // We can't display Python exceptions via std::fmt::Display,
+  // so print the error here manually.
+  e.print_and_set_sys_last_vars(py);
+ })
  })
 }
 

guide/src/python_from_rust.md

@@ -13,12 +13,12 @@ module available in your environment.
 use pyo3::prelude::*;
 
 fn main() -> PyResult<()> {
- let gil = Python::acquire_gil();
- let py = gil.python();
- let builtins = PyModule::import(py, "builtins")?;
- let total: i32 = builtins.call1("sum", (vec![1, 2, 3],))?.extract()?;
- assert_eq!(total, 6);
- Ok(())
+ Python::with_gil(|py| {
+  let builtins = PyModule::import(py, "builtins")?;
+  let total: i32 = builtins.call1("sum", (vec![1, 2, 3],))?.extract()?;
+  assert_eq!(total, 6);
+  Ok(())
+ })
 }
 ```
 
@@ -33,14 +33,14 @@ use pyo3::prelude::*;
 use pyo3::types::IntoPyDict;
 
 fn main() -> Result<(), ()> {
- let gil = Python::acquire_gil();
- let py = gil.python();
- let result = py.eval("[i * 10 for i in range(5)]", None, None).map_err(|e| {
- e.print_and_set_sys_last_vars(py);
- })?;
- let res: Vec<i64> = result.extract().unwrap();
- assert_eq!(res, vec![0, 10, 20, 30, 40]);
- Ok(())
+ Python::with_gil(|py| {
+  let result = py.eval("[i * 10 for i in range(5)]", None, None).map_err(|e| {
+  e.print_and_set_sys_last_vars(py);
+ })?;
+  let res: Vec<i64> = result.extract().unwrap();
+  assert_eq!(res, vec![0, 10, 20, 30, 40]);
+  Ok(())
+ })
 }
 ```
 
@@ -76,18 +76,19 @@ impl PyObjectProtocol for UserData {
  Ok(format!("User {}(id: {})", self.name, self.id))
  }
 }
-let gil = Python::acquire_gil();
-let py = gil.python();
-let userdata = UserData {
- id: 34,
- name: "Yu".to_string(),
-};
-let userdata = PyCell::new(py, userdata).unwrap();
-let userdata_as_tuple = (34, "Yu");
-py_run!(py, userdata userdata_as_tuple, r#"
+
+Python::with_gil(|py| {
+ let userdata = UserData {
+  id: 34,
+  name: "Yu".to_string(),
+ };
+ let userdata = PyCell::new(py, userdata).unwrap();
+ let userdata_as_tuple = (34, "Yu");
+ py_run!(py, userdata userdata_as_tuple, r#"
 assert repr(userdata) == "User Yu(id: 34)"
 assert userdata.as_tuple() == userdata_as_tuple
-"#);
+ "#);
+})
 # }
 ```
 
@@ -100,26 +101,27 @@ can be used to generate a Python module which can then be used just as if it was
 ```rust
 use pyo3::{prelude::*, types::{IntoPyDict, PyModule}};
 # fn main() -> PyResult<()> {
-let gil = Python::acquire_gil();
-let py = gil.python();
-let activators = PyModule::from_code(py, r#"
+Python::with_gil(|py| {
+ let activators = PyModule::from_code(py, r#"
 def relu(x):
  """see https://en.wikipedia.org/wiki/Rectifier_(neural_networks)"""
  return max(0.0, x)
 
 def leaky_relu(x, slope=0.01):
  return x if x >= 0 else x * slope
-"#, "activators.py", "activators")?;
-
-let relu_result: f64 = activators.call1("relu", (-1.0,))?.extract()?;
-assert_eq!(relu_result, 0.0);
-
-let kwargs = [("slope", 0.2)].into_py_dict(py);
-let lrelu_result: f64 = activators
- .call("leaky_relu", (-1.0,), Some(kwargs))?
- .extract()?;
-assert_eq!(lrelu_result, -0.2);
-# Ok(()) }
+ "#, "activators.py", "activators")?;
+
+ let relu_result: f64 = activators.call1("relu", (-1.0,))?.extract()?;
+ assert_eq!(relu_result, 0.0);
+
+ let kwargs = [("slope", 0.2)].into_py_dict(py);
+ let lrelu_result: f64 = activators
+ .call("leaky_relu", (-1.0,), Some(kwargs))?
+ .extract()?;
+ assert_eq!(lrelu_result, -0.2);
+# Ok(())
+})
+# }
 ```
 
 [`Python::run`]: https://pyo3.rs/master/doc/pyo3/struct.Python.html#method.run