make Bound and Borrowed types public API

newsfragments/3686.added.md

@@ -0,0 +1 @@
+Add `Bound<T>` and `Borrowed<T>` smart pointers as a new API for accessing Python objects.

src/instance.rs

@@ -45,7 +45,7 @@ pub unsafe trait PyNativeType: Sized {
 
 /// A GIL-attached equivalent to `Py`.
 #[repr(transparent)]
-pub(crate) struct Bound<'py, T>(Python<'py>, ManuallyDrop<Py<T>>);
+pub struct Bound<'py, T>(Python<'py>, ManuallyDrop<Py<T>>);
 
 impl<'py> Bound<'py, PyAny> {
     /// Constructs a new Bound from a pointer. Panics if ptr is null.
@@ -224,7 +224,7 @@ unsafe impl<T> AsPyPointer for Bound<'_, T> {
 ///
 /// Similarly, this type is `Copy` and `Clone`, like a shared reference (`&T`).
 #[repr(transparent)]
-pub(crate) struct Borrowed<'a, 'py, T>(NonNull<ffi::PyObject>, PhantomData<&'a Py<T>>, Python<'py>);
+pub struct Borrowed<'a, 'py, T>(NonNull<ffi::PyObject>, PhantomData<&'a Py<T>>, Python<'py>);
 
 impl<'py, T> Borrowed<'_, 'py, T> {
     /// Creates a new owned `Bound` from this borrowed reference by increasing the reference count.

src/prelude.rs

@@ -12,7 +12,7 @@ pub use crate::conversion::{FromPyObject, IntoPy, ToPyObject};
 #[allow(deprecated)]
 pub use crate::conversion::{PyTryFrom, PyTryInto};
 pub use crate::err::{PyErr, PyResult};
-pub use crate::instance::{Py, PyObject};
+pub use crate::instance::{Borrowed, Bound, Py, PyObject};
 pub use crate::marker::Python;
 pub use crate::pycell::{PyCell, PyRef, PyRefMut};
 pub use crate::pyclass_init::PyClassInitializer;
@@ -24,15 +24,13 @@ pub use pyo3_macros::{pyclass, pyfunction, pymethods, pymodule, FromPyObject};
 #[cfg(feature = "macros")]
 pub use crate::wrap_pyfunction;
 
-// Expected to become public API in 0.21
+pub use crate::types::any::PyAnyMethods;
-// pub(crate) use crate::instance::Bound; // Will be stabilized with a different name
+pub use crate::types::boolobject::PyBoolMethods;
-// pub(crate) use crate::types::any::PyAnyMethods;
+pub use crate::types::bytearray::PyByteArrayMethods;
-// pub(crate) use crate::types::boolobject::PyBoolMethods;
+pub use crate::types::bytes::PyBytesMethods;
-// pub(crate) use crate::types::bytearray::PyByteArrayMethods;
+pub use crate::types::dict::PyDictMethods;
-// pub(crate) use crate::types::bytes::PyBytesMethods;
+pub use crate::types::float::PyFloatMethods;
-// pub(crate) use crate::types::dict::PyDictMethods;
+pub use crate::types::list::PyListMethods;
-// pub(crate) use crate::types::float::PyFloatMethods;
+pub use crate::types::mapping::PyMappingMethods;
-// pub(crate) use crate::types::list::PyListMethods;
+pub use crate::types::sequence::PySequenceMethods;
-// pub(crate) use crate::types::mapping::PyMappingMethods;
+pub use crate::types::string::PyStringMethods;
-// pub(crate) use crate::types::sequence::PySequenceMethods;
-// pub(crate) use crate::types::string::PyStringMethods;

src/types/any.rs

@@ -996,7 +996,7 @@ impl PyAny {
 /// It is recommended you import this trait via `use pyo3::prelude::*` rather than
 /// by importing this trait directly.
 #[doc(alias = "PyAny")]
-pub(crate) trait PyAnyMethods<'py> {
+pub trait PyAnyMethods<'py> {
     /// Returns whether `self` and `other` point to the same object. To compare
     /// the equality of two objects (the `==` operator), use [`eq`](PyAny::eq).
     ///

src/types/bytes.rs

@@ -99,7 +99,7 @@ impl PyBytes {
 /// syntax these methods are separated into a trait, because stable Rust does not yet support
 /// `arbitrary_self_types`.
 #[doc(alias = "PyBytes")]
-pub(crate) trait PyBytesMethods<'py> {
+pub trait PyBytesMethods<'py> {
     /// Gets the Python string as a byte slice.
     fn as_bytes(&self) -> &[u8];
 }

src/types/dict.rs

@@ -265,7 +265,7 @@ impl PyDict {
 /// syntax these methods are separated into a trait, because stable Rust does not yet support
 /// `arbitrary_self_types`.
 #[doc(alias = "PyDict")]
-pub(crate) trait PyDictMethods<'py> {
+pub trait PyDictMethods<'py> {
     /// Returns a new dictionary that contains the same key-value pairs as self.
     ///
     /// This is equivalent to the Python expression `self.copy()`.
@@ -545,7 +545,7 @@ impl<'a> IntoIterator for &'a PyDict {
 }
 
 /// PyO3 implementation of an iterator for a Python `dict` object.
-pub(crate) struct PyDictIterator2<'py> {
+pub struct PyDictIterator2<'py> {
     dict: Bound<'py, PyDict>,
     ppos: ffi::Py_ssize_t,
     di_used: ffi::Py_ssize_t,

src/types/list.rs

@@ -256,7 +256,7 @@ index_impls!(PyList, "list", PyList::len, PyList::get_slice);
 /// syntax these methods are separated into a trait, because stable Rust does not yet support
 /// `arbitrary_self_types`.
 #[doc(alias = "PyList")]
-pub(crate) trait PyListMethods<'py> {
+pub trait PyListMethods<'py> {
     /// Returns the length of the list.
     fn len(&self) -> usize;
 
@@ -594,7 +594,7 @@ impl<'a> IntoIterator for &'a PyList {
 }
 
 /// Used by `PyList::iter()`.
-pub(crate) struct PyListIterator2<'py> {
+pub struct PyListIterator2<'py> {
     list: Bound<'py, PyList>,
     index: usize,
     length: usize,

src/types/mapping.rs

@@ -117,7 +117,7 @@ impl PyMapping {
 /// syntax these methods are separated into a trait, because stable Rust does not yet support
 /// `arbitrary_self_types`.
 #[doc(alias = "PyMapping")]
-pub(crate) trait PyMappingMethods<'py> {
+pub trait PyMappingMethods<'py> {
     /// Returns the number of objects in the mapping.
     ///
     /// This is equivalent to the Python expression `len(self)`.

src/types/sequence.rs

@@ -200,7 +200,7 @@ impl PySequence {
 /// syntax these methods are separated into a trait, because stable Rust does not yet support
 /// `arbitrary_self_types`.
 #[doc(alias = "PySequence")]
-pub(crate) trait PySequenceMethods<'py> {
+pub trait PySequenceMethods<'py> {
     /// Returns the number of objects in sequence.
     ///
     /// This is equivalent to the Python expression `len(self)`.

src/types/string.rs

@@ -239,7 +239,7 @@ impl PyString {
 /// syntax these methods are separated into a trait, because stable Rust does not yet support
 /// `arbitrary_self_types`.
 #[doc(alias = "PyString")]
-pub(crate) trait PyStringMethods<'py> {
+pub trait PyStringMethods<'py> {
     /// Gets the Python string as a Rust UTF-8 string slice.
     ///
     /// Returns a `UnicodeEncodeError` if the input is not valid unicode