luxolus
/
pyo3
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #1747 from PyO3/pycell_doc 

pycell: proofread docstrings
This commit is contained in:
David Hewitt 2021-08-01 07:43:56 +01:00 committed by GitHub
parent 8e7737d099 edd5ca9806
commit fab135c1df
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 32 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
src/pycell.rs
View File

@ -29,12 +29,12 @@ pub struct PyCellBase<T> {
unsafe impl<T, U> PyLayout<T> for PyCellBase<U> where U: PySizedLayout<T> {} unsafe impl<T, U> PyLayout<T> for PyCellBase<U> where U: PySizedLayout<T> {}
/// `PyCell` is the container type for [`PyClass`](../pyclass/trait.PyClass.html). /// `PyCell` is the container type for [`PyClass`](../pyclass/trait.PyClass.html) values.
/// ///
/// From Python side, `PyCell<T>` is the concrete layout of `T: PyClass` in the Python heap, /// From the Python side, `PyCell<T>` is the concrete layout of `T: PyClass` in the Python heap,
/// which means we can convert `*const PyClass<T>` to `*mut ffi::PyObject`. /// which means we can convert `*const PyClass<T>` to `*mut ffi::PyObject`.
/// ///
/// From Rust side, `PyCell<T>` is the mutable container of `T`. /// From the Rust side, `PyCell<T>` is the mutable container of `T`.
/// Since `PyCell<T: PyClass>` is always on the Python heap, we don't have the ownership of it. /// Since `PyCell<T: PyClass>` is always on the Python heap, we don't have the ownership of it.
/// Thus, to mutate the data behind `&PyCell<T>` safely, we employ the /// Thus, to mutate the data behind `&PyCell<T>` safely, we employ the
/// [Interior Mutability Pattern](https://doc.rust-lang.org/book/ch15-05-interior-mutability.html) /// [Interior Mutability Pattern](https://doc.rust-lang.org/book/ch15-05-interior-mutability.html)
@ -46,7 +46,7 @@ unsafe impl<T, U> PyLayout<T> for PyCellBase<U> where U: PySizedLayout<T> {}
/// # Examples /// # Examples
/// ///
/// In most cases, `PyCell` is hidden behind `#[pymethods]`. /// In most cases, `PyCell` is hidden behind `#[pymethods]`.
/// However, you can construct `&PyCell` directly to test your pyclass in Rust code. /// However, you can construct a `&PyCell` directly to test your pyclass in Rust code.
/// ///
/// ``` /// ```
/// # use pyo3::prelude::*; /// # use pyo3::prelude::*;
@ -67,7 +67,7 @@ unsafe impl<T, U> PyLayout<T> for PyCellBase<U> where U: PySizedLayout<T> {}
/// }); /// });
/// ``` /// ```
/// You can use `slf: &PyCell<Self>` as an alternative `self` receiver of `#[pymethod]`, /// You can use `slf: &PyCell<Self>` as an alternative `self` receiver of `#[pymethod]`,
/// though you rarely need it. /// though you'll rarely need it.
/// ``` /// ```
/// # use pyo3::prelude::*; /// # use pyo3::prelude::*;
/// use std::collections::HashMap; /// use std::collections::HashMap;
@ -189,7 +189,7 @@ impl<T: PyClass> PyCell<T> {
unsafe impl<T: PyClass> PyNativeType for PyCell<T> {} unsafe impl<T: PyClass> PyNativeType for PyCell<T> {}
impl<T: PyClass> PyCell<T> { impl<T: PyClass> PyCell<T> {
/// Make a new `PyCell` on the Python heap and return the reference to it. /// Makes a new `PyCell` on the Python heap and return the reference to it.
/// ///
/// In cases where the value in the cell does not need to be accessed immediately after /// In cases where the value in the cell does not need to be accessed immediately after
/// creation, consider [`Py::new`](../instance/struct.Py.html#method.new) as a more efficient /// creation, consider [`Py::new`](../instance/struct.Py.html#method.new) as a more efficient
@ -202,7 +202,7 @@ impl<T: PyClass> PyCell<T> {
} }
} }
/// Immutably borrows the value `T`. This borrow lasts untill the returned `PyRef` exists. /// Immutably borrows the value `T`. This borrow lasts as long as the returned `PyRef` exists.
/// ///
/// # Panics /// # Panics
/// ///
@ -212,7 +212,7 @@ impl<T: PyClass> PyCell<T> {
self.try_borrow().expect("Already mutably borrowed") self.try_borrow().expect("Already mutably borrowed")
} }
/// Mutably borrows the value `T`. This borrow lasts untill the returned `PyRefMut` exists. /// Mutably borrows the value `T`. This borrow lasts as long as the returned `PyRefMut` exists.
/// ///
/// # Panics /// # Panics
/// ///
@ -223,7 +223,7 @@ impl<T: PyClass> PyCell<T> {
} }
/// Immutably borrows the value `T`, returning an error if the value is currently /// Immutably borrows the value `T`, returning an error if the value is currently
/// mutably borrowed. This borrow lasts untill the returned `PyRef` exists. /// mutably borrowed. This borrow lasts as long as the returned `PyRef` exists.
/// ///
/// This is the non-panicking variant of [`borrow`](#method.borrow). /// This is the non-panicking variant of [`borrow`](#method.borrow).
/// ///
@ -257,7 +257,7 @@ impl<T: PyClass> PyCell<T> {
} }
/// Mutably borrows the value `T`, returning an error if the value is currently borrowed. /// Mutably borrows the value `T`, returning an error if the value is currently borrowed.
/// This borrow lasts untill the returned `PyRefMut` exists. /// This borrow lasts as long as the returned `PyRefMut` exists.
/// ///
/// This is the non-panicking variant of [`borrow_mut`](#method.borrow_mut). /// This is the non-panicking variant of [`borrow_mut`](#method.borrow_mut).
/// ///
@ -323,7 +323,7 @@ impl<T: PyClass> PyCell<T> {
} }
} }
/// Replaces the wrapped value with a new one, returning the old value, /// Replaces the wrapped value with a new one, returning the old value.
/// ///
/// # Panics /// # Panics
/// ///
@ -410,10 +410,12 @@ impl<T: PyClass + fmt::Debug> fmt::Debug for PyCell<T> {
/// Wraps a borrowed reference to a value in a `PyCell<T>`. /// Wraps a borrowed reference to a value in a `PyCell<T>`.
/// ///
/// See the [`PyCell`](struct.PyCell.html) documentation for more. /// See the [`PyCell`](struct.PyCell.html) documentation for more.
///
/// # Examples /// # Examples
/// You can use `PyRef` as an alternative of `&self` receiver when ///
/// - You need to access the pointer of `PyCell`. /// You can use `PyRef` as an alternative to a `&self` receiver when
/// - You want to get super class. /// - you need to access the pointer of the `PyCell`, or
/// - you want to get a super class.
/// ``` /// ```
/// # use pyo3::prelude::*; /// # use pyo3::prelude::*;
/// #[pyclass(subclass)] /// #[pyclass(subclass)]
@ -449,8 +451,8 @@ pub struct PyRef<'p, T: PyClass> {
} }
impl<'p, T: PyClass> PyRef<'p, T> { impl<'p, T: PyClass> PyRef<'p, T> {
/// Returns `Python` token. /// Returns a `Python` token.
/// This function is safe since PyRef has the same lifetime as a `GILGuard`. /// This function is safe since `PyRef` has the same lifetime as a `GILGuard`.
pub fn py(&self) -> Python { pub fn py(&self) -> Python {
unsafe { Python::assume_gil_acquired() } unsafe { Python::assume_gil_acquired() }
} }
@ -471,8 +473,13 @@ where
T: PyClass<BaseType = U>, T: PyClass<BaseType = U>,
U: PyClass, U: PyClass,
{ {
/// Get `PyRef<T::BaseType>`. /// Gets a `PyRef<T::BaseType>`.
/// You can use this method to get super class of super class. ///
/// While `as_ref()` returns a reference of type `&T::BaseType`, this cannot be
/// used to get the base of `T::BaseType`.
///
/// But with the help of this method, you can get hold of instances of the
/// super-superclass when needed.
/// ///
/// # Examples /// # Examples
/// ``` /// ```
@ -560,14 +567,14 @@ impl<T: PyClass + fmt::Debug> fmt::Debug for PyRef<'_, T> {
/// Wraps a mutable borrowed reference to a value in a `PyCell<T>`. /// Wraps a mutable borrowed reference to a value in a `PyCell<T>`.
/// ///
/// See the [`PyCell`](struct.PyCell.html) and [`PyRef`](struct.PyRef.html) documentations for more. /// See the [`PyCell`](struct.PyCell.html) and [`PyRef`](struct.PyRef.html) documentation for more.
pub struct PyRefMut<'p, T: PyClass> { pub struct PyRefMut<'p, T: PyClass> {
inner: &'p PyCell<T>, inner: &'p PyCell<T>,
} }
impl<'p, T: PyClass> PyRefMut<'p, T> { impl<'p, T: PyClass> PyRefMut<'p, T> {
/// Returns `Python` token. /// Returns a `Python` token.
/// This function is safe since PyRefMut has the same lifetime as a `GILGuard`. /// This function is safe since `PyRefMut` has the same lifetime as a `GILGuard`.
pub fn py(&self) -> Python { pub fn py(&self) -> Python {
unsafe { Python::assume_gil_acquired() } unsafe { Python::assume_gil_acquired() }
} }
@ -598,7 +605,7 @@ where
T: PyClass<BaseType = U>, T: PyClass<BaseType = U>,
U: PyClass, U: PyClass,
{ {
/// Get `PyRef<T::BaseType>`. /// Gets a `PyRef<T::BaseType>`.
/// See [`PyRef::into_super`](struct.PyRef.html#method.into_super) for more. /// See [`PyRef::into_super`](struct.PyRef.html#method.into_super) for more.
pub fn into_super(self) -> PyRefMut<'p, U> { pub fn into_super(self) -> PyRefMut<'p, U> {
let PyRefMut { inner } = self; let PyRefMut { inner } = self;
@ -673,7 +680,7 @@ impl BorrowFlag {
/// An error returned by [`PyCell::try_borrow`](struct.PyCell.html#method.try_borrow). /// An error returned by [`PyCell::try_borrow`](struct.PyCell.html#method.try_borrow).
/// ///
/// In Python, you can catch this error by `except RuntimeError`. /// In Python, you can catch this error using `except RuntimeError`.
pub struct PyBorrowError { pub struct PyBorrowError {
_private: (), _private: (),
} }
@ -698,7 +705,7 @@ impl From<PyBorrowError> for PyErr {
/// An error returned by [`PyCell::try_borrow_mut`](struct.PyCell.html#method.try_borrow_mut). /// An error returned by [`PyCell::try_borrow_mut`](struct.PyCell.html#method.try_borrow_mut).
/// ///
/// In Python, you can catch this error by `except RuntimeError`. /// In Python, you can catch this error using `except RuntimeError`.
pub struct PyBorrowMutError { pub struct PyBorrowMutError {
_private: (), _private: (),
} }