From e8b3b0f3bcc6ea316badc320400bb12a343d1072 Mon Sep 17 00:00:00 2001 From: David Hewitt Date: Tue, 9 Jul 2024 09:05:32 +0100 Subject: [PATCH 1/2] docs: improve signposting to bound and traits --- src/instance.rs | 14 +++++++++++++- src/lib.rs | 5 ++++- src/types/any.rs | 25 +++++++------------------ src/types/boolobject.rs | 6 ++++++ src/types/bytearray.rs | 6 ++++++ src/types/bytes.rs | 10 ++++++++-- src/types/capsule.rs | 5 +++++ src/types/code.rs | 3 +++ src/types/complex.rs | 6 ++++++ src/types/datetime.rs | 23 +++++++++++++++++++---- src/types/dict.rs | 6 ++++++ src/types/ellipsis.rs | 3 +++ src/types/float.rs | 10 ++++++++-- src/types/frame.rs | 3 +++ src/types/frozenset.rs | 8 +++++++- src/types/function.rs | 6 ++++++ src/types/iterator.rs | 3 +++ src/types/list.rs | 6 ++++++ src/types/mapping.rs | 6 ++++++ src/types/memoryview.rs | 3 +++ src/types/module.rs | 6 ++++++ src/types/none.rs | 3 +++ src/types/notimplemented.rs | 3 +++ src/types/num.rs | 3 +++ src/types/pysuper.rs | 3 ++- src/types/sequence.rs | 6 ++++++ src/types/set.rs | 8 +++++++- src/types/slice.rs | 6 ++++++ src/types/string.rs | 7 ++++--- src/types/traceback.rs | 6 ++++++ src/types/tuple.rs | 6 +++++- src/types/typeobject.rs | 9 ++++++++- 32 files changed, 187 insertions(+), 36 deletions(-) diff --git a/src/instance.rs b/src/instance.rs index cc1ae684e44..499f751027c 100644 --- a/src/instance.rs +++ b/src/instance.rs @@ -65,7 +65,19 @@ pub unsafe trait PyNativeType: Sized { } } -/// A GIL-attached equivalent to `Py`. +/// A GIL-attached equivalent to [`Py`]. +/// +/// This type can be thought of as equivalent to the tuple `(Py, Python<'py>)`. By having the `'py` +/// lifetime of the [`Python<'py>`] token, this ties the lifetime of the [`Bound<'py, T>`] smart pointer +/// to the lifetime of the GIL and allows PyO3 to call Python APIs at maximum efficiency. +/// +/// To access the object in situations where the GIL is not held, convert it to [`Py`] +/// using [`.unbind()`][Bound::unbind]. This includes situations where the GIL is temporarily +/// released, such as [`Python::allow_threads`](crate::Python::allow_threads)'s closure. +/// +/// See +#[doc = concat!("[the guide](https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/types.html#boundpy-t)")] +/// for more detail. #[repr(transparent)] pub struct Bound<'py, T>(Python<'py>, ManuallyDrop>); diff --git a/src/lib.rs b/src/lib.rs index a9c5bd0b731..b0dcc9fa63f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -461,7 +461,6 @@ pub mod marshal; #[macro_use] pub mod sync; pub mod panic; -pub mod prelude; pub mod pybacked; pub mod pycell; pub mod pyclass; @@ -495,6 +494,10 @@ mod macros; #[cfg(feature = "experimental-inspect")] pub mod inspect; +// Putting the declaration of prelude at the end seems to help encourage rustdoc to prefer using +// other paths to the same items. (e.g. `pyo3::types::PyAnyMethods` instead of `pyo3::prelude::PyAnyMethods`). +pub mod prelude; + /// Ths module only contains re-exports of pyo3 deprecation warnings and exists /// purely to make compiler error messages nicer. /// diff --git a/src/types/any.rs b/src/types/any.rs index c8c6d67e534..fdeab37712d 100644 --- a/src/types/any.rs +++ b/src/types/any.rs @@ -19,26 +19,15 @@ use std::os::raw::c_int; /// Represents any Python object. /// -/// It currently only appears as a *reference*, `&PyAny`, -/// with a lifetime that represents the scope during which the GIL is held. +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyAny>`][Bound]. /// -/// `PyAny` has some interesting properties, which it shares -/// with the other [native Python types](crate::types): +/// For APIs available on all Python objects, see the [`PyAnyMethods`] trait which is implemented for +/// [`Bound<'py, PyAny>`][Bound]. /// -/// - It can only be obtained and used while the GIL is held, -/// therefore its API does not require a [`Python<'py>`](crate::Python) token. -/// - It can't be used in situations where the GIL is temporarily released, -/// such as [`Python::allow_threads`](crate::Python::allow_threads)'s closure. -/// - The underlying Python object, if mutable, can be mutated through any reference. -/// - It can be converted to the GIL-independent [`Py`]`<`[`PyAny`]`>`, -/// allowing it to outlive the GIL scope. However, using [`Py`]`<`[`PyAny`]`>`'s API -/// *does* require a [`Python<'py>`](crate::Python) token. -/// -/// It can be cast to a concrete type with PyAny::downcast (for native Python types only) -/// and FromPyObject::extract. See their documentation for more information. -/// -/// See [the guide](https://pyo3.rs/latest/types.html) for an explanation -/// of the different Python object types. +/// See +#[doc = concat!("[the guide](https://pyo3.rs/v", env!("CARGO_PKG_VERSION"), "/types.html#concrete-python-types)")] +/// for an explanation of the different Python object types. #[repr(transparent)] pub struct PyAny(UnsafeCell); diff --git a/src/types/boolobject.rs b/src/types/boolobject.rs index ee19797d66e..9ac66529e9a 100644 --- a/src/types/boolobject.rs +++ b/src/types/boolobject.rs @@ -11,6 +11,12 @@ use crate::{ use super::any::PyAnyMethods; /// Represents a Python `bool`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyBool>`][Bound]. +/// +/// For APIs available on `bool` objects, see the [`PyBoolMethods`] trait which is implemented for +/// [`Bound<'py, PyBool>`][Bound]. #[repr(transparent)] pub struct PyBool(PyAny); diff --git a/src/types/bytearray.rs b/src/types/bytearray.rs index c411e830340..57376069355 100644 --- a/src/types/bytearray.rs +++ b/src/types/bytearray.rs @@ -9,6 +9,12 @@ use crate::{AsPyPointer, PyNativeType}; use std::slice; /// Represents a Python `bytearray`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyByteArray>`][Bound]. +/// +/// For APIs available on `bytearray` objects, see the [`PyByteArrayMethods`] trait which is implemented for +/// [`Bound<'py, PyByteArray>`][Bound]. #[repr(transparent)] pub struct PyByteArray(PyAny); diff --git a/src/types/bytes.rs b/src/types/bytes.rs index 0513f4cec8c..512c835f87a 100644 --- a/src/types/bytes.rs +++ b/src/types/bytes.rs @@ -12,10 +12,16 @@ use std::str; /// /// This type is immutable. /// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyBytes>`][Bound]. +/// +/// For APIs available on `bytes` objects, see the [`PyBytesMethods`] trait which is implemented for +/// [`Bound<'py, PyBytes>`][Bound]. +/// /// # Equality /// -/// For convenience, [`Bound<'py, PyBytes>`] implements [`PartialEq<[u8]>`] to allow comparing the -/// data in the Python bytes to a Rust `[u8]`. +/// For convenience, [`Bound<'py, PyBytes>`][Bound] implements [`PartialEq<[u8]>`][PartialEq] to allow comparing the +/// data in the Python bytes to a Rust `[u8]` byte slice. /// /// This is not always the most appropriate way to compare Python bytes, as Python bytes subclasses /// may have different equality semantics. In situations where subclasses overriding equality might be diff --git a/src/types/capsule.rs b/src/types/capsule.rs index 9b9445cdffe..815b70ebc41 100644 --- a/src/types/capsule.rs +++ b/src/types/capsule.rs @@ -15,6 +15,11 @@ use std::os::raw::{c_char, c_int, c_void}; /// > in one module available to other modules, so the regular import mechanism can /// > be used to access C APIs defined in dynamically loaded modules. /// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyCapsule>`][Bound]. +/// +/// For APIs available on capsule objects, see the [`PyCapsuleMethods`] trait which is implemented for +/// [`Bound<'py, PyCapsule>`][Bound]. /// /// # Example /// ``` diff --git a/src/types/code.rs b/src/types/code.rs index f60e7783aa4..04e1efb9fe7 100644 --- a/src/types/code.rs +++ b/src/types/code.rs @@ -2,6 +2,9 @@ use crate::ffi; use crate::PyAny; /// Represents a Python code object. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyCode>`][crate::Bound]. #[repr(transparent)] pub struct PyCode(PyAny); diff --git a/src/types/complex.rs b/src/types/complex.rs index 5ec9e2f00a4..887bc12e438 100644 --- a/src/types/complex.rs +++ b/src/types/complex.rs @@ -7,6 +7,12 @@ use std::os::raw::c_double; /// Represents a Python [`complex`](https://docs.python.org/3/library/functions.html#complex) object. /// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyComplex>`][Bound]. +/// +/// For APIs available on `complex` objects, see the [`PyComplexMethods`] trait which is implemented for +/// [`Bound<'py, PyComplex>`][Bound]. +/// /// Note that `PyComplex` supports only basic operations. For advanced operations /// consider using [num-complex](https://docs.rs/num-complex)'s [`Complex`] type instead. /// This optional dependency can be activated with the `num-complex` feature flag. diff --git a/src/types/datetime.rs b/src/types/datetime.rs index cdf3b011e6c..c07b6be9b2b 100644 --- a/src/types/datetime.rs +++ b/src/types/datetime.rs @@ -191,7 +191,10 @@ pub trait PyTzInfoAccess<'py> { fn get_tzinfo_bound(&self) -> Option>; } -/// Bindings around `datetime.date` +/// Bindings around `datetime.date`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyDate>`][Bound]. #[repr(transparent)] pub struct PyDate(PyAny); pyobject_native_type!( @@ -279,7 +282,10 @@ impl PyDateAccess for Bound<'_, PyDate> { } } -/// Bindings for `datetime.datetime` +/// Bindings for `datetime.datetime`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyDateTime>`][Bound]. #[repr(transparent)] pub struct PyDateTime(PyAny); pyobject_native_type!( @@ -578,7 +584,10 @@ impl<'py> PyTzInfoAccess<'py> for Bound<'py, PyDateTime> { } } -/// Bindings for `datetime.time` +/// Bindings for `datetime.time`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyTime>`][Bound]. #[repr(transparent)] pub struct PyTime(PyAny); pyobject_native_type!( @@ -781,6 +790,9 @@ impl<'py> PyTzInfoAccess<'py> for Bound<'py, PyTime> { /// Bindings for `datetime.tzinfo`. /// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyTzInfo>`][Bound]. +/// /// This is an abstract base class and cannot be constructed directly. /// For concrete time zone implementations, see [`timezone_utc_bound`] and /// the [`zoneinfo` module](https://docs.python.org/3/library/zoneinfo.html). @@ -834,7 +846,10 @@ pub(crate) fn timezone_from_offset<'py>( } } -/// Bindings for `datetime.timedelta` +/// Bindings for `datetime.timedelta`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyDelta>`][Bound]. #[repr(transparent)] pub struct PyDelta(PyAny); pyobject_native_type!( diff --git a/src/types/dict.rs b/src/types/dict.rs index 850e468c672..50d00477c2e 100644 --- a/src/types/dict.rs +++ b/src/types/dict.rs @@ -11,6 +11,12 @@ use crate::PyNativeType; use crate::{ffi, Python, ToPyObject}; /// Represents a Python `dict`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyDict>`][Bound]. +/// +/// For APIs available on `dict` objects, see the [`PyDictMethods`] trait which is implemented for +/// [`Bound<'py, PyDict>`][Bound]. #[repr(transparent)] pub struct PyDict(PyAny); diff --git a/src/types/ellipsis.rs b/src/types/ellipsis.rs index cbeaf489c17..1dc7da08b55 100644 --- a/src/types/ellipsis.rs +++ b/src/types/ellipsis.rs @@ -4,6 +4,9 @@ use crate::{ }; /// Represents the Python `Ellipsis` object. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyEllipsis>`][Bound]. #[repr(transparent)] pub struct PyEllipsis(PyAny); diff --git a/src/types/float.rs b/src/types/float.rs index 8499d1e54aa..1e6cbe51eaf 100644 --- a/src/types/float.rs +++ b/src/types/float.rs @@ -11,9 +11,15 @@ use std::os::raw::c_double; /// Represents a Python `float` object. /// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyFloat>`][Bound]. +/// +/// For APIs available on `float` objects, see the [`PyFloatMethods`] trait which is implemented for +/// [`Bound<'py, PyFloat>`][Bound]. +/// /// You can usually avoid directly working with this type -/// by using [`ToPyObject`] and [`extract`](PyAnyMethods::extract) -/// with `f32`/`f64`. +/// by using [`ToPyObject`] and [`extract`][PyAnyMethods::extract] +/// with [`f32`]/[`f64`]. #[repr(transparent)] pub struct PyFloat(PyAny); diff --git a/src/types/frame.rs b/src/types/frame.rs index 0ab873b8003..8d88d4754ae 100644 --- a/src/types/frame.rs +++ b/src/types/frame.rs @@ -2,6 +2,9 @@ use crate::ffi; use crate::PyAny; /// Represents a Python frame. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyFrame>`][crate::Bound]. #[repr(transparent)] pub struct PyFrame(PyAny); diff --git a/src/types/frozenset.rs b/src/types/frozenset.rs index 78cbf01df67..4ec83915c70 100644 --- a/src/types/frozenset.rs +++ b/src/types/frozenset.rs @@ -56,7 +56,13 @@ impl<'py> PyFrozenSetBuilder<'py> { } } -/// Represents a Python `frozenset` +/// Represents a Python `frozenset`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyFrozenSet>`][Bound]. +/// +/// For APIs available on `frozenset` objects, see the [`PyFrozenSetMethods`] trait which is implemented for +/// [`Bound<'py, PyFrozenSet>`][Bound]. #[repr(transparent)] pub struct PyFrozenSet(PyAny); diff --git a/src/types/function.rs b/src/types/function.rs index c2eec04d42f..62a2b30263b 100644 --- a/src/types/function.rs +++ b/src/types/function.rs @@ -16,6 +16,9 @@ use std::cell::UnsafeCell; use std::ffi::CStr; /// Represents a builtin Python function object. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyCFunction>`][Bound]. #[repr(transparent)] pub struct PyCFunction(PyAny); @@ -241,6 +244,9 @@ struct ClosureDestructor { unsafe impl Send for ClosureDestructor {} /// Represents a Python function object. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyFunction>`][Bound]. #[repr(transparent)] #[cfg(all(not(Py_LIMITED_API), not(all(PyPy, not(Py_3_8)))))] pub struct PyFunction(PyAny); diff --git a/src/types/iterator.rs b/src/types/iterator.rs index 1835f484adf..38f3131be90 100644 --- a/src/types/iterator.rs +++ b/src/types/iterator.rs @@ -7,6 +7,9 @@ use crate::{AsPyPointer, PyDowncastError, PyNativeType}; /// A Python iterator object. /// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyIterator>`][Bound]. +/// /// # Examples /// /// ```rust diff --git a/src/types/list.rs b/src/types/list.rs index 0d911e03199..9cfd574cd0f 100644 --- a/src/types/list.rs +++ b/src/types/list.rs @@ -14,6 +14,12 @@ use crate::types::any::PyAnyMethods; use crate::types::sequence::PySequenceMethods; /// Represents a Python `list`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyList>`][Bound]. +/// +/// For APIs available on `list` objects, see the [`PyListMethods`] trait which is implemented for +/// [`Bound<'py, PyDict>`][Bound]. #[repr(transparent)] pub struct PyList(PyAny); diff --git a/src/types/mapping.rs b/src/types/mapping.rs index aea2b484c3b..82e6b326810 100644 --- a/src/types/mapping.rs +++ b/src/types/mapping.rs @@ -11,6 +11,12 @@ use crate::{err::PyDowncastError, PyNativeType}; use crate::{ffi, Py, PyTypeCheck, Python, ToPyObject}; /// Represents a reference to a Python object supporting the mapping protocol. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyMapping>`][Bound]. +/// +/// For APIs available on mapping objects, see the [`PyMappingMethods`] trait which is implemented for +/// [`Bound<'py, PyMapping>`][Bound]. #[repr(transparent)] pub struct PyMapping(PyAny); pyobject_native_type_named!(PyMapping); diff --git a/src/types/memoryview.rs b/src/types/memoryview.rs index 320b3f9f70b..bff1fdcd4c9 100644 --- a/src/types/memoryview.rs +++ b/src/types/memoryview.rs @@ -6,6 +6,9 @@ use crate::{ffi, Bound, PyAny}; use crate::{AsPyPointer, PyNativeType}; /// Represents a Python `memoryview`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyMemoryView>`][Bound]. #[repr(transparent)] pub struct PyMemoryView(PyAny); diff --git a/src/types/module.rs b/src/types/module.rs index e866ec9cb48..5438c22f681 100644 --- a/src/types/module.rs +++ b/src/types/module.rs @@ -15,6 +15,12 @@ use {super::PyStringMethods, crate::PyNativeType}; /// Represents a Python [`module`][1] object. /// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyModule>`][Bound]. +/// +/// For APIs available on `module` objects, see the [`PyModuleMethods`] trait which is implemented for +/// [`Bound<'py, PyModule>`][Bound]. +/// /// As with all other Python objects, modules are first class citizens. /// This means they can be passed to or returned from functions, /// created dynamically, assigned to variables and so forth. diff --git a/src/types/none.rs b/src/types/none.rs index 0ab1570b92d..78f14be2b25 100644 --- a/src/types/none.rs +++ b/src/types/none.rs @@ -5,6 +5,9 @@ use crate::{ }; /// Represents the Python `None` object. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyNone>`][Bound]. #[repr(transparent)] pub struct PyNone(PyAny); diff --git a/src/types/notimplemented.rs b/src/types/notimplemented.rs index 7fad1220b26..6d1808070a6 100644 --- a/src/types/notimplemented.rs +++ b/src/types/notimplemented.rs @@ -4,6 +4,9 @@ use crate::{ }; /// Represents the Python `NotImplemented` object. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyNotImplemented>`][Bound]. #[repr(transparent)] pub struct PyNotImplemented(PyAny); diff --git a/src/types/num.rs b/src/types/num.rs index 924d4b2c593..b43dddbef88 100644 --- a/src/types/num.rs +++ b/src/types/num.rs @@ -2,6 +2,9 @@ use crate::{ffi, PyAny}; /// Represents a Python `int` object. /// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyLong>`][crate::Bound]. +/// /// You can usually avoid directly working with this type /// by using [`ToPyObject`](crate::conversion::ToPyObject) /// and [`extract`](super::PyAnyMethods::extract) diff --git a/src/types/pysuper.rs b/src/types/pysuper.rs index 7c4d781525a..bd9d042a1f0 100644 --- a/src/types/pysuper.rs +++ b/src/types/pysuper.rs @@ -6,7 +6,8 @@ use crate::{PyAny, PyResult}; /// Represents a Python `super` object. /// -/// This type is immutable. +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PySuper>`][Bound]. #[repr(transparent)] pub struct PySuper(PyAny); diff --git a/src/types/sequence.rs b/src/types/sequence.rs index a5765ebc8b2..39de9efb272 100644 --- a/src/types/sequence.rs +++ b/src/types/sequence.rs @@ -14,6 +14,12 @@ use crate::{err::PyDowncastError, PyNativeType}; use crate::{ffi, FromPyObject, Py, PyTypeCheck, Python, ToPyObject}; /// Represents a reference to a Python object supporting the sequence protocol. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PySequence>`][Bound]. +/// +/// For APIs available on sequence objects, see the [`PySequenceMethods`] trait which is implemented for +/// [`Bound<'py, PySequence>`][Bound]. #[repr(transparent)] pub struct PySequence(PyAny); pyobject_native_type_named!(PySequence); diff --git a/src/types/set.rs b/src/types/set.rs index 1bc4c86be51..9dc44745df2 100644 --- a/src/types/set.rs +++ b/src/types/set.rs @@ -11,7 +11,13 @@ use crate::{ use crate::{ffi, PyAny, PyObject, Python, ToPyObject}; use std::ptr; -/// Represents a Python `set` +/// Represents a Python `set`. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PySet>`][Bound]. +/// +/// For APIs available on `set` objects, see the [`PySetMethods`] trait which is implemented for +/// [`Bound<'py, PySet>`][Bound]. #[repr(transparent)] pub struct PySet(PyAny); diff --git a/src/types/slice.rs b/src/types/slice.rs index 7daa2c030b6..dafe5053059 100644 --- a/src/types/slice.rs +++ b/src/types/slice.rs @@ -8,6 +8,12 @@ use crate::{Bound, PyAny, PyObject, Python, ToPyObject}; /// Represents a Python `slice`. /// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PySlice>`][Bound]. +/// +/// For APIs available on `slice` objects, see the [`PySliceMethods`] trait which is implemented for +/// [`Bound<'py, PySlice>`][Bound]. +/// /// Only `isize` indices supported at the moment by the `PySlice` object. #[repr(transparent)] pub struct PySlice(PyAny); diff --git a/src/types/string.rs b/src/types/string.rs index 828e0024bda..fafeac83091 100644 --- a/src/types/string.rs +++ b/src/types/string.rs @@ -123,10 +123,11 @@ impl<'a> PyStringData<'a> { /// Represents a Python `string` (a Unicode string object). /// -/// This type is only seen inside PyO3's smart pointers as [`Py`], [`Bound<'py, PyString>`], -/// and [`Borrowed<'a, 'py, PyString>`]. +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyString>`][Bound]. /// -/// All functionality on this type is implemented through the [`PyStringMethods`] trait. +/// For APIs available on `str` objects, see the [`PyStringMethods`] trait which is implemented for +/// [`Bound<'py, PyString>`][Bound]. /// /// # Equality /// diff --git a/src/types/traceback.rs b/src/types/traceback.rs index dbbdb6a85ea..5e3496145e2 100644 --- a/src/types/traceback.rs +++ b/src/types/traceback.rs @@ -5,6 +5,12 @@ use crate::PyNativeType; use crate::{ffi, Bound, PyAny}; /// Represents a Python traceback. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyTraceback>`][Bound]. +/// +/// For APIs available on traceback objects, see the [`PyTracebackMethods`] trait which is implemented for +/// [`Bound<'py, PyTraceback>`][Bound]. #[repr(transparent)] pub struct PyTraceback(PyAny); diff --git a/src/types/tuple.rs b/src/types/tuple.rs index fcf931c1d8a..aacc1efe431 100644 --- a/src/types/tuple.rs +++ b/src/types/tuple.rs @@ -52,7 +52,11 @@ fn new_from_iter<'py>( /// Represents a Python `tuple` object. /// -/// This type is immutable. +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyTuple>`][Bound]. +/// +/// For APIs available on `tuple` objects, see the [`PyTupleMethods`] trait which is implemented for +/// [`Bound<'py, PyTuple>`][Bound]. #[repr(transparent)] pub struct PyTuple(PyAny); diff --git a/src/types/typeobject.rs b/src/types/typeobject.rs index 9638a2731a3..dbe4c3efd10 100644 --- a/src/types/typeobject.rs +++ b/src/types/typeobject.rs @@ -9,7 +9,14 @@ use crate::PyNativeType; use crate::{ffi, Bound, PyAny, PyTypeInfo, Python}; use super::PyString; -/// Represents a reference to a Python `type object`. + +/// Represents a reference to a Python `type` object. +/// +/// Values of this type are accessed via PyO3's smart pointers, e.g. as +/// [`Py`][crate::Py] or [`Bound<'py, PyType>`][Bound]. +/// +/// For APIs available on `type` objects, see the [`PyTypeMethods`] trait which is implemented for +/// [`Bound<'py, PyType>`][Bound]. #[repr(transparent)] pub struct PyType(PyAny); From abf56ea8fd1368af18b149004f0e425645ebcc83 Mon Sep 17 00:00:00 2001 From: David Hewitt Date: Tue, 9 Jul 2024 12:32:00 +0100 Subject: [PATCH 2/2] update UI tests --- src/lib.rs | 2 +- tests/ui/invalid_pyfunctions.stderr | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index b0dcc9fa63f..ef905ec356c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -494,7 +494,7 @@ mod macros; #[cfg(feature = "experimental-inspect")] pub mod inspect; -// Putting the declaration of prelude at the end seems to help encourage rustdoc to prefer using +// Putting the declaration of prelude at the end seems to help encourage rustc and rustdoc to prefer using // other paths to the same items. (e.g. `pyo3::types::PyAnyMethods` instead of `pyo3::prelude::PyAnyMethods`). pub mod prelude; diff --git a/tests/ui/invalid_pyfunctions.stderr b/tests/ui/invalid_pyfunctions.stderr index 0f94ef17254..9a42c59366e 100644 --- a/tests/ui/invalid_pyfunctions.stderr +++ b/tests/ui/invalid_pyfunctions.stderr @@ -47,11 +47,11 @@ error: expected `&PyModule` or `Py` as first argument with `pass_modul 32 | fn pass_module_but_no_arguments<'py>() {} | ^^ -error[E0277]: the trait bound `&str: From>` is not satisfied +error[E0277]: the trait bound `&str: From>` is not satisfied --> tests/ui/invalid_pyfunctions.rs:36:14 | 36 | _string: &str, - | ^ the trait `From>` is not implemented for `&str`, which is required by `BoundRef<'_, '_, pyo3::prelude::PyModule>: Into<_>` + | ^ the trait `From>` is not implemented for `&str`, which is required by `BoundRef<'_, '_, pyo3::types::PyModule>: Into<_>` | = help: the following other types implement trait `From`: > @@ -60,4 +60,4 @@ error[E0277]: the trait bound `&str: From>> >> > - = note: required for `BoundRef<'_, '_, pyo3::prelude::PyModule>` to implement `Into<&str>` + = note: required for `BoundRef<'_, '_, pyo3::types::PyModule>` to implement `Into<&str>`