From 86f294f6e66ad45789a0814b0f6a1567a6caa8b5 Mon Sep 17 00:00:00 2001
From: David Hewitt <mail@davidhewitt.dev>
Date: Tue, 16 Jan 2024 21:34:13 +0000
Subject: [PATCH] expose `Bound::from_owned_ptr` etc

---
 src/instance.rs | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/src/instance.rs b/src/instance.rs
index 8ae6d80f..e54312a9 100644
--- a/src/instance.rs
+++ b/src/instance.rs
@@ -105,33 +105,34 @@ where
 }
 
 impl<'py> Bound<'py, PyAny> {
-    /// Constructs a new Bound from a pointer. Panics if ptr is null.
+    /// Constructs a new `Bound<'py, PyAny>` from a pointer. Panics if `ptr` is null.
     ///
     /// # Safety
     ///
-    /// `ptr` must be a valid pointer to a Python object.
-    pub(crate) unsafe fn from_owned_ptr(py: Python<'py>, ptr: *mut ffi::PyObject) -> Self {
+    /// - `ptr` must be a valid pointer to a Python object
+    /// - `ptr` must be an owned Python reference, as the `Bound<'py, PyAny>` will assume ownership
+    pub unsafe fn from_owned_ptr(py: Python<'py>, ptr: *mut ffi::PyObject) -> Self {
         Self(py, ManuallyDrop::new(Py::from_owned_ptr(py, ptr)))
     }
 
-    /// Constructs a new Bound from a pointer. Returns None if ptr is null.
+    /// Constructs a new `Bound<'py, PyAny>` from a pointer. Returns `None`` if `ptr` is null.
     ///
     /// # Safety
     ///
-    /// `ptr` must be a valid pointer to a Python object, or NULL.
-    pub(crate) unsafe fn from_owned_ptr_or_opt(
-        py: Python<'py>,
-        ptr: *mut ffi::PyObject,
-    ) -> Option<Self> {
+    /// - `ptr` must be a valid pointer to a Python object, or null
+    /// - `ptr` must be an owned Python reference, as the `Bound<'py, PyAny>` will assume ownership
+    pub unsafe fn from_owned_ptr_or_opt(py: Python<'py>, ptr: *mut ffi::PyObject) -> Option<Self> {
         Py::from_owned_ptr_or_opt(py, ptr).map(|obj| Self(py, ManuallyDrop::new(obj)))
     }
 
-    /// Constructs a new Bound from a pointer. Returns error if ptr is null.
+    /// Constructs a new `Bound<'py, PyAny>` from a pointer. Returns an `Err` by calling `PyErr::fetch`
+    /// if `ptr` is null.
     ///
     /// # Safety
     ///
-    /// `ptr` must be a valid pointer to a Python object, or NULL.
-    pub(crate) unsafe fn from_owned_ptr_or_err(
+    /// - `ptr` must be a valid pointer to a Python object, or null
+    /// - `ptr` must be an owned Python reference, as the `Bound<'py, PyAny>` will assume ownership
+    pub unsafe fn from_owned_ptr_or_err(
         py: Python<'py>,
         ptr: *mut ffi::PyObject,
     ) -> PyResult<Self> {