Merge branch 'main' into either-type

Author: davidhewitt

.github/workflows/benches.yml

@@ -9,6 +9,10 @@ on:
   # performance analysis in order to generate initial data.
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}-${{ github.event.pull_request.number || github.sha }}-benches
+  cancel-in-progress: true
+
 jobs:
   benchmarks:
     runs-on: ubuntu-latest

.github/workflows/ci.yml

@@ -468,6 +468,18 @@ jobs:
           echo PYO3_CONFIG_FILE=$PYO3_CONFIG_FILE >> $GITHUB_ENV
       - run: python3 -m nox -s test
 
+  test-version-limits:
+    needs: [fmt]
+    if: ${{ contains(github.event.pull_request.labels.*.name, 'CI-build-full') || (github.event_name != 'pull_request' && github.ref != 'refs/heads/main') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Swatinem/rust-cache@v2
+        continue-on-error: true
+      - uses: dtolnay/rust-toolchain@stable
+      - run: python3 -m pip install --upgrade pip && pip install nox
+      - run: python3 -m nox -s test-version-limits
+
   conclusion:
     needs:
       - fmt
@@ -480,6 +492,8 @@ jobs:
       - docsrs
       - coverage
       - emscripten
+      - test-debug
+      - test-version-limits
     if: always()
     runs-on: ubuntu-latest
     steps:

Cargo.toml

@@ -81,7 +81,7 @@ multiple-pymethods = ["inventory", "pyo3-macros/multiple-pymethods"]
 extension-module = ["pyo3-ffi/extension-module"]
 
 # Use the Python limited API. See https://www.python.org/dev/peps/pep-0384/ for more.
-abi3 = ["pyo3-build-config/abi3", "pyo3-ffi/abi3", "pyo3-macros/abi3"]
+abi3 = ["pyo3-build-config/abi3", "pyo3-ffi/abi3"]
 
 # With abi3, we can manually set the minimum Python version.
 abi3-py37 = ["abi3-py38", "pyo3-build-config/abi3-py37", "pyo3-ffi/abi3-py37"]

Contributing.md

@@ -35,7 +35,7 @@ Helping others often reveals bugs, documentation weaknesses, and missing APIs. I
 
 ### Implement issues ready for development
 
-Issues where the solution is clear and work is not in progress use the [needs-implementer](https://github.com/PyO3/pyo3/issues?q=is%3Aissue+is%3Aopen+label%3Aneeds-implemeter) label.
+Issues where the solution is clear and work is not in progress use the [needs-implementer](https://github.com/PyO3/pyo3/issues?q=is%3Aissue+is%3Aopen+label%3Aneeds-implementer) label.
 
 Don't be afraid if the solution is not clear to you! The core PyO3 contributors will be happy to mentor you through any questions you have to help you write the solution.
 

README.md

@@ -149,10 +149,10 @@ use pyo3::types::IntoPyDict;
 
 fn main() -> PyResult<()> {
     Python::with_gil(|py| {
-        let sys = py.import("sys")?;
+        let sys = py.import_bound("sys")?;
         let version: String = sys.getattr("version")?.extract()?;
 
-        let locals = [("os", py.import("os")?)].into_py_dict_bound(py);
+        let locals = [("os", py.import_bound("os")?)].into_py_dict_bound(py);
         let code = "os.getenv('USER') or os.getenv('USERNAME') or 'Unknown'";
         let user: String = py.eval_bound(code, None, Some(&locals))?.extract()?;
 

guide/src/class.md

@@ -216,6 +216,7 @@ struct MyClass {
     num: i32,
 }
 Python::with_gil(|py| {
+#   #[allow(deprecated)]
     let obj = PyCell::new(py, MyClass { num: 3 }).unwrap();
     {
         let obj_ref = obj.borrow(); // Get PyRef
@@ -397,11 +398,11 @@ impl SubSubClass {
     }
 }
 # Python::with_gil(|py| {
-#     let subsub = pyo3::PyCell::new(py, SubSubClass::new()).unwrap();
+#     let subsub = pyo3::Py::new(py, SubSubClass::new()).unwrap();
 #     pyo3::py_run!(py, subsub, "assert subsub.method3() == 3000");
 #     let subsub = SubSubClass::factory_method(py, 2).unwrap();
 #     let subsubsub = SubSubClass::factory_method(py, 3).unwrap();
-#     let cls = py.get_type::<SubSubClass>();
+#     let cls = py.get_type_bound::<SubSubClass>();
 #     pyo3::py_run!(py, subsub cls, "assert not isinstance(subsub, cls)");
 #     pyo3::py_run!(py, subsubsub cls, "assert isinstance(subsubsub, cls)");
 # });
@@ -441,7 +442,7 @@ impl DictWithCounter {
     }
 }
 # Python::with_gil(|py| {
-#     let cnt = pyo3::PyCell::new(py, DictWithCounter::new()).unwrap();
+#     let cnt = pyo3::Py::new(py, DictWithCounter::new()).unwrap();
 #     pyo3::py_run!(py, cnt, "cnt.set('abc', 10); assert cnt['abc'] == 10")
 # });
 # }
@@ -497,7 +498,7 @@ impl MyDict {
     // some custom methods that use `private` here...
 }
 # Python::with_gil(|py| {
-#     let cls = py.get_type::<MyDict>();
+#     let cls = py.get_type_bound::<MyDict>();
 #     pyo3::py_run!(py, cls, "cls(a=1, b=2)")
 # });
 # }
@@ -691,7 +692,7 @@ This is the equivalent of the Python decorator `@classmethod`.
 #[pymethods]
 impl MyClass {
     #[classmethod]
-    fn cls_method(cls: &PyType) -> PyResult<i32> {
+    fn cls_method(cls: &Bound<'_, PyType>) -> PyResult<i32> {
         Ok(10)
     }
 }
@@ -719,10 +720,10 @@ To create a constructor which takes a positional class argument, you can combine
 impl BaseClass {
     #[new]
     #[classmethod]
-    fn py_new<'p>(cls: &'p PyType, py: Python<'p>) -> PyResult<Self> {
+    fn py_new(cls: &Bound<'_, PyType>) -> PyResult<Self> {
         // Get an abstract attribute (presumably) declared on a subclass of this class.
-        let subclass_attr = cls.getattr("a_class_attr")?;
-        Ok(Self(subclass_attr.to_object(py)))
+        let subclass_attr: Bound<'_, PyAny> = cls.getattr("a_class_attr")?;
+        Ok(Self(subclass_attr.unbind()))
     }
 }
 ```
@@ -767,7 +768,7 @@ impl MyClass {
 }
 
 Python::with_gil(|py| {
-    let my_class = py.get_type::<MyClass>();
+    let my_class = py.get_type_bound::<MyClass>();
     pyo3::py_run!(py, my_class, "assert my_class.my_attribute == 'hello'")
 });
 ```
@@ -928,7 +929,7 @@ impl MyClass {
     // similarly for classmethod arguments, use $cls
     #[classmethod]
     #[pyo3(text_signature = "($cls, e, f)")]
-    fn my_class_method(cls: &PyType, e: i32, f: i32) -> i32 {
+    fn my_class_method(cls: &Bound<'_, PyType>, e: i32, f: i32) -> i32 {
         e + f
     }
     #[staticmethod]
@@ -1026,7 +1027,7 @@ enum MyEnum {
 Python::with_gil(|py| {
     let x = Py::new(py, MyEnum::Variant).unwrap();
     let y = Py::new(py, MyEnum::OtherVariant).unwrap();
-    let cls = py.get_type::<MyEnum>();
+    let cls = py.get_type_bound::<MyEnum>();
     pyo3::py_run!(py, x y cls, r#"
         assert x == cls.Variant
         assert y == cls.OtherVariant
@@ -1046,7 +1047,7 @@ enum MyEnum {
 }
 
 Python::with_gil(|py| {
-    let cls = py.get_type::<MyEnum>();
+    let cls = py.get_type_bound::<MyEnum>();
     let x = MyEnum::Variant as i32; // The exact value is assigned by the compiler.
     pyo3::py_run!(py, cls x, r#"
         assert int(cls.Variant) == x
@@ -1068,7 +1069,7 @@ enum MyEnum{
 }
 
 Python::with_gil(|py| {
-    let cls = py.get_type::<MyEnum>();
+    let cls = py.get_type_bound::<MyEnum>();
     let x = Py::new(py, MyEnum::Variant).unwrap();
     pyo3::py_run!(py, cls x, r#"
         assert repr(x) == 'MyEnum.Variant'
@@ -1094,7 +1095,7 @@ impl MyEnum {
 }
 
 Python::with_gil(|py| {
-    let cls = py.get_type::<MyEnum>();
+    let cls = py.get_type_bound::<MyEnum>();
     pyo3::py_run!(py, cls, "assert repr(cls.Answer) == '42'")
 })
 ```
@@ -1111,7 +1112,7 @@ enum MyEnum {
 
 Python::with_gil(|py| {
     let x = Py::new(py, MyEnum::Variant).unwrap();
-    let cls = py.get_type::<MyEnum>();
+    let cls = py.get_type_bound::<MyEnum>();
     pyo3::py_run!(py, x cls, r#"
         assert repr(x) == 'RenamedEnum.UPPERCASE'
         assert x == cls.UPPERCASE
@@ -1165,7 +1166,7 @@ enum Shape {
 Python::with_gil(|py| {
     let circle = Shape::Circle { radius: 10.0 }.into_py(py);
     let square = Shape::RegularPolygon { side_count: 4, radius: 10.0 }.into_py(py);
-    let cls = py.get_type::<Shape>();
+    let cls = py.get_type_bound::<Shape>();
     pyo3::py_run!(py, circle square cls, r#"
         assert isinstance(circle, cls)
         assert isinstance(circle, cls.Circle)
@@ -1204,7 +1205,7 @@ enum MyEnum {
 
 Python::with_gil(|py| {
     let x = Py::new(py, MyEnum::Variant { i: 42 }).unwrap();
-    let cls = py.get_type::<MyEnum>();
+    let cls = py.get_type_bound::<MyEnum>();
     pyo3::py_run!(py, x cls, r#"
         assert isinstance(x, cls)
         assert not isinstance(x, cls.Variant)
@@ -1308,7 +1309,7 @@ impl pyo3::impl_::pyclass::PyClassImpl for MyClass {
 }
 
 # Python::with_gil(|py| {
-#     let cls = py.get_type::<MyClass>();
+#     let cls = py.get_type_bound::<MyClass>();
 #     pyo3::py_run!(py, cls, "assert cls.__name__ == 'MyClass'")
 # });
 # }

guide/src/class/numeric.md

@@ -206,7 +206,6 @@ assert hash_djb2('l50_50') == Number(-1152549421)
 ```rust
 use std::collections::hash_map::DefaultHasher;
 use std::hash::{Hash, Hasher};
-use std::convert::TryInto;
 
 use pyo3::exceptions::{PyValueError, PyZeroDivisionError};
 use pyo3::prelude::*;

guide/src/class/object.md

@@ -217,8 +217,8 @@ impl Number {
 
 # fn main() -> PyResult<()> {
 #     Python::with_gil(|py| {
-#         let x = PyCell::new(py, Number(4))?;
-#         let y = PyCell::new(py, Number(4))?;
+#         let x = &Bound::new(py, Number(4))?.into_any();
+#         let y = &Bound::new(py, Number(4))?.into_any();
 #         assert!(x.eq(y)?);
 #         assert!(!x.ne(y)?);
 #         Ok(())

guide/src/class/protocols.md

@@ -207,7 +207,7 @@ impl Container {
 
 # Python::with_gil(|py| {
 #     let container = Container { iter: vec![1, 2, 3, 4] };
-#     let inst = pyo3::PyCell::new(py, container).unwrap();
+#     let inst = pyo3::Py::new(py, container).unwrap();
 #     pyo3::py_run!(py, inst, "assert list(inst) == [1, 2, 3, 4]");
 #     pyo3::py_run!(py, inst, "assert list(iter(iter(inst))) == [1, 2, 3, 4]");
 # });

guide/src/exception.md

@@ -24,7 +24,7 @@ use pyo3::exceptions::PyException;
 create_exception!(mymodule, CustomError, PyException);
 
 Python::with_gil(|py| {
-    let ctx = [("CustomError", py.get_type::<CustomError>())].into_py_dict_bound(py);
+    let ctx = [("CustomError", py.get_type_bound::<CustomError>())].into_py_dict_bound(py);
     pyo3::py_run!(
         py,
         *ctx,
@@ -46,7 +46,7 @@ pyo3::create_exception!(mymodule, CustomError, PyException);
 #[pymodule]
 fn mymodule(py: Python<'_>, m: &PyModule) -> PyResult<()> {
     // ... other elements added to module ...
-    m.add("CustomError", py.get_type::<CustomError>())?;
+    m.add("CustomError", py.get_type_bound::<CustomError>())?;
 
     Ok(())
 }

guide/src/function.md

@@ -83,10 +83,11 @@ The `#[pyo3]` attribute can be used to modify properties of the generated Python
 
     ```rust
     use pyo3::prelude::*;
+    use pyo3::types::PyString;
 
     #[pyfunction]
     #[pyo3(pass_module)]
-    fn pyfunction_with_module(module: &PyModule) -> PyResult<&str> {
+    fn pyfunction_with_module<'py>(module: &Bound<'py, PyModule>) -> PyResult<Bound<'py, PyString>> {
         module.name()
     }
 

guide/src/migration.md

@@ -217,6 +217,28 @@ Because the new `Bound<T>` API brings ownership out of the PyO3 framework and in
 - `Bound<PyList>` and `Bound<PyTuple>` cannot support indexing with `list[0]`, you should use `list.get_item(0)` instead.
 - `Bound<PyTuple>::iter_borrowed` is slightly more efficient than `Bound<PyTuple>::iter`. The default iteration of `Bound<PyTuple>` cannot return borrowed references because Rust does not (yet) have "lending iterators". Similarly `Bound<PyTuple>::get_borrowed_item` is more efficient than `Bound<PyTuple>::get_item` for the same reason.
 - `&Bound<T>` does not implement `FromPyObject` (although it might be possible to do this in the future once the GIL Refs API is completely removed). Use `bound_any.downcast::<T>()` instead of `bound_any.extract::<&Bound<T>>()`.
+- To convert between `&PyAny` and `&Bound<PyAny>` you can use the `as_borrowed()` method:
+
+```rust,ignore
+let gil_ref: &PyAny = ...;
+let bound: &Bound<PyAny> = &gil_ref.as_borrowed();
+```
+
+> Because of the ownership changes, code which uses `.as_ptr()` to convert `&PyAny` and other GIL Refs to a `*mut pyo3_ffi::PyObject` should take care to avoid creating dangling pointers now that `Bound<PyAny>` carries ownership.
+>
+> For example, the following pattern with `Option<&PyAny>` can easily create a dangling pointer when migrating to the `Bound<PyAny>` smart pointer:
+>
+> ```rust,ignore
+> let opt: Option<&PyAny> = ...;
+> let p: *mut ffi::PyObject = opt.map_or(std::ptr::null_mut(), |any| any.as_ptr());
+> ```
+>
+> The correct way to migrate this code is to use `.as_ref()` to avoid dropping the `Bound<PyAny>` in the `map_or` closure:
+>
+> ```rust,ignore
+> let opt: Option<Bound<PyAny>> = ...;
+> let p: *mut ffi::PyObject = opt.as_ref().map_or(std::ptr::null_mut(), Bound::as_ptr);
+> ```
 
 #### Migrating `FromPyObject` implementations
 
@@ -1295,7 +1317,7 @@ impl Names {
     }
 }
 # Python::with_gil(|py| {
-#     let names = PyCell::new(py, Names::new()).unwrap();
+#     let names = Py::new(py, Names::new()).unwrap();
 #     pyo3::py_run!(py, names, r"
 #     try:
 #        names.merge(names)
@@ -1330,7 +1352,7 @@ let obj_ref = PyRef::new(py, MyClass {}).unwrap();
 ```
 
 After:
-```rust
+```rust,ignore
 # use pyo3::prelude::*;
 # #[pyclass]
 # struct MyClass {}

guide/src/python_from_rust.md

@@ -181,7 +181,7 @@ quickly testing your Python extensions.
 
 ```rust
 use pyo3::prelude::*;
-use pyo3::{PyCell, py_run};
+use pyo3::py_run;
 
 # fn main() {
 #[pyclass]
@@ -206,7 +206,7 @@ Python::with_gil(|py| {
         id: 34,
         name: "Yu".to_string(),
     };
-    let userdata = PyCell::new(py, userdata).unwrap();
+    let userdata = Py::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)"
@@ -228,7 +228,7 @@ to this function!
 ```rust
 use pyo3::{
     prelude::*,
-    types::{IntoPyDict, PyModule},
+    types::IntoPyDict,
 };
 
 # fn main() -> PyResult<()> {
@@ -414,7 +414,7 @@ fn main() -> PyResult<()> {
     let path = Path::new("/usr/share/python_app");
     let py_app = fs::read_to_string(path.join("app.py"))?;
     let from_python = Python::with_gil(|py| -> PyResult<Py<PyAny>> {
-        let syspath: &PyList = py.import("sys")?.getattr("path")?.downcast()?;
+        let syspath = py.import_bound("sys")?.getattr("path")?.downcast_into::<PyList>()?;
         syspath.insert(0, &path)?;
         let app: Py<PyAny> = PyModule::from_code(py, &py_app, "", "")?
             .getattr("run")?
@@ -437,7 +437,6 @@ Use context managers by directly invoking `__enter__` and `__exit__`.
 
 ```rust
 use pyo3::prelude::*;
-use pyo3::types::PyModule;
 
 fn main() {
     Python::with_gil(|py| {
@@ -479,7 +478,7 @@ class House(object):
             }
             Err(e) => {
                 house
-                    .call_method1("__exit__", (e.get_type_bound(py), e.value(py), e.traceback_bound(py)))
+                    .call_method1("__exit__", (e.get_type_bound(py), e.value_bound(py), e.traceback_bound(py)))
                     .unwrap();
             }
         }
@@ -498,7 +497,7 @@ use pyo3::prelude::*;
 
 # fn main() -> PyResult<()> {
 Python::with_gil(|py| -> PyResult<()> {
-    let signal = py.import("signal")?;
+    let signal = py.import_bound("signal")?;
     // Set SIGINT to have the default action
     signal
         .getattr("signal")?