wip bound docs

PyO3 · Mar 6, 2024 · 718f887 · 718f887
1 parent 57bbc32
commit 718f887
Show file tree

Hide file tree

Showing 9 changed files with 629 additions and 564 deletions.
diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md
@@ -5,22 +5,25 @@
 ---
 
 - [Getting started](getting_started.md)
-- [Python modules](module.md)
-- [Python functions](function.md)
-  - [Function signatures](function/signature.md)
-  - [Error handling](function/error_handling.md)
-- [Python classes](class.md)
-  - [Class customizations](class/protocols.md)
-    - [Basic object customization](class/object.md)
-    - [Emulating numeric types](class/numeric.md)
-    - [Emulating callable objects](class/call.md)
+- [Using Rust from Python](rust_from_python.md)
+  - [Python modules](module.md)
+  - [Python functions](function.md)
+    - [Function signatures](function/signature.md)
+    - [Error handling](function/error_handling.md)
+  - [Python classes](class.md)
+    - [Class customizations](class/protocols.md)
+      - [Basic object customization](class/object.md)
+      - [Emulating numeric types](class/numeric.md)
+      - [Emulating callable objects](class/call.md)
+- [Using Python from Rust](python_from_rust.md)
+  - [Python object types](types.md)
+  - [Python exceptions](exception.md)
+  - [Calling Python functions](python_from_rust/function-calls.md)
+  - [Executing existing Python code](python_from_rust/calling-existing-code.md)
 - [Type conversions](conversions.md)
   - [Mapping of Rust types to Python types](conversions/tables.md)
   - [Conversion traits](conversions/traits.md)
-- [Python exceptions](exception.md)
-- [Calling Python from Rust](python_from_rust.md)
 - [Using `async` and `await`](async-await.md)
-- [GIL, mutability and object types](types.md)
 - [Parallelism](parallelism.md)
 - [Debugging](debugging.md)
 - [Features reference](features.md)

diff --git a/guide/src/conversions/tables.md b/guide/src/conversions/tables.md
@@ -12,49 +12,49 @@ The table below contains the Python type and the corresponding function argument
 
 | Python        | Rust                            | Rust (Python-native) |
 | ------------- |:-------------------------------:|:--------------------:|
-| `object`      | -                               | `&PyAny`             |
-| `str`         | `String`, `Cow<str>`, `&str`, `char`, `OsString`, `PathBuf`, `Path` | `&PyString`, `&PyUnicode` |
-| `bytes`       | `Vec<u8>`, `&[u8]`, `Cow<[u8]>` | `&PyBytes`           |
-| `bool`        | `bool`                          | `&PyBool`            |
-| `int`         | `i8`, `u8`, `i16`, `u16`, `i32`, `u32`, `i64`, `u64`, `i128`, `u128`, `isize`, `usize`, `num_bigint::BigInt`[^1], `num_bigint::BigUint`[^1] | `&PyLong` |
-| `float`       | `f32`, `f64`                    | `&PyFloat`           |
-| `complex`     | `num_complex::Complex`[^2]      | `&PyComplex`         |
-| `list[T]`     | `Vec<T>`                        | `&PyList`            |
-| `dict[K, V]`  | `HashMap<K, V>`, `BTreeMap<K, V>`, `hashbrown::HashMap<K, V>`[^3], `indexmap::IndexMap<K, V>`[^4] | `&PyDict` |
-| `tuple[T, U]` | `(T, U)`, `Vec<T>`              | `&PyTuple`           |
-| `set[T]`      | `HashSet<T>`, `BTreeSet<T>`, `hashbrown::HashSet<T>`[^3] | `&PySet` |
-| `frozenset[T]` | `HashSet<T>`, `BTreeSet<T>`, `hashbrown::HashSet<T>`[^3] | `&PyFrozenSet` |
-| `bytearray`   | `Vec<u8>`, `Cow<[u8]>`          | `&PyByteArray`       |
-| `slice`       | -                               | `&PySlice`           |
-| `type`        | -                               | `&PyType`            |
-| `module`      | -                               | `&PyModule`          |
+| `object`      | -                               | `PyAny`             |
+| `str`         | `String`, `Cow<str>`, `&str`, `char`, `OsString`, `PathBuf`, `Path` | `PyString`, `PyUnicode` |
+| `bytes`       | `Vec<u8>`, `&[u8]`, `Cow<[u8]>` | `PyBytes`           |
+| `bool`        | `bool`                          | `PyBool`            |
+| `int`         | `i8`, `u8`, `i16`, `u16`, `i32`, `u32`, `i64`, `u64`, `i128`, `u128`, `isize`, `usize`, `num_bigint::BigInt`[^1], `num_bigint::BigUint`[^1] | `PyLong` |
+| `float`       | `f32`, `f64`                    | `PyFloat`           |
+| `complex`     | `num_complex::Complex`[^2]      | `PyComplex`         |
+| `list[T]`     | `Vec<T>`                        | `PyList`            |
+| `dict[K, V]`  | `HashMap<K, V>`, `BTreeMap<K, V>`, `hashbrown::HashMap<K, V>`[^3], `indexmap::IndexMap<K, V>`[^4] | `PyDict` |
+| `tuple[T, U]` | `(T, U)`, `Vec<T>`              | `PyTuple`           |
+| `set[T]`      | `HashSet<T>`, `BTreeSet<T>`, `hashbrown::HashSet<T>`[^3] | `PySet` |
+| `frozenset[T]` | `HashSet<T>`, `BTreeSet<T>`, `hashbrown::HashSet<T>`[^3] | `PyFrozenSet` |
+| `bytearray`   | `Vec<u8>`, `Cow<[u8]>`          | `PyByteArray`       |
+| `slice`       | -                               | `PySlice`           |
+| `type`        | -                               | `PyType`            |
+| `module`      | -                               | `PyModule`          |
 | `collections.abc.Buffer` | -                    | `PyBuffer<T>`        |
-| `datetime.datetime` | `SystemTime`, `chrono::DateTime<Tz>`[^5], `chrono::NaiveDateTime`[^5] | `&PyDateTime`        |
-| `datetime.date` | `chrono::NaiveDate`[^5]       | `&PyDate`            |
-| `datetime.time` | `chrono::NaiveTime`[^5]       | `&PyTime`            |
-| `datetime.tzinfo` | `chrono::FixedOffset`[^5], `chrono::Utc`[^5], `chrono_tz::TimeZone`[^6] | `&PyTzInfo`          |
-| `datetime.timedelta` | `Duration`, `chrono::Duration`[^5] | `&PyDelta`           |
+| `datetime.datetime` | `SystemTime`, `chrono::DateTime<Tz>`[^5], `chrono::NaiveDateTime`[^5] | `PyDateTime`        |
+| `datetime.date` | `chrono::NaiveDate`[^5]       | `PyDate`            |
+| `datetime.time` | `chrono::NaiveTime`[^5]       | `PyTime`            |
+| `datetime.tzinfo` | `chrono::FixedOffset`[^5], `chrono::Utc`[^5], `chrono_tz::TimeZone`[^6] | `PyTzInfo`          |
+| `datetime.timedelta` | `Duration`, `chrono::Duration`[^5] | `PyDelta`           |
 | `decimal.Decimal` | `rust_decimal::Decimal`[^7] | -                    |
 | `ipaddress.IPv4Address` | `std::net::IpAddr`, `std::net::IpV4Addr` | - |
 | `ipaddress.IPv6Address` | `std::net::IpAddr`, `std::net::IpV6Addr` | - |
-| `os.PathLike ` | `PathBuf`, `Path`              | `&PyString`, `&PyUnicode` |
-| `pathlib.Path` | `PathBuf`, `Path`              | `&PyString`, `&PyUnicode` |
+| `os.PathLike ` | `PathBuf`, `Path`              | `PyString`, `PyUnicode` |
+| `pathlib.Path` | `PathBuf`, `Path`              | `PyString`, `PyUnicode` |
 | `typing.Optional[T]` | `Option<T>`              | -                    |
-| `typing.Sequence[T]` | `Vec<T>`                 | `&PySequence`        |
+| `typing.Sequence[T]` | `Vec<T>`                 | `PySequence`        |
 | `typing.Mapping[K, V]` | `HashMap<K, V>`, `BTreeMap<K, V>`, `hashbrown::HashMap<K, V>`[^3], `indexmap::IndexMap<K, V>`[^4] | `&PyMapping` |
-| `typing.Iterator[Any]` | -                      | `&PyIterator`        |
+| `typing.Iterator[Any]` | -                      | `PyIterator`        |
 | `typing.Union[...]` | See [`#[derive(FromPyObject)]`](traits.html#deriving-a-hrefhttpsdocsrspyo3latestpyo3conversiontraitfrompyobjecthtmlfrompyobjecta-for-enums) | - |
 
-There are also a few special types related to the GIL and Rust-defined `#[pyclass]`es which may come in useful:
+It is also worth remembering the following special types:
 
-| What          | Description |
-| ------------- | ------------------------------------- |
-| `Python`      | A GIL token, used to pass to PyO3 constructors to prove ownership of the GIL |
-| `Py<T>`       | A Python object isolated from the GIL lifetime. This can be sent to other threads. |
-| `PyObject`    | An alias for `Py<PyAny>`              |
-| `&PyCell<T>`  | A `#[pyclass]` value owned by Python. |
-| `PyRef<T>`    | A `#[pyclass]` borrowed immutably.    |
-| `PyRefMut<T>` | A `#[pyclass]` borrowed mutably.      |
+| What             | Description                           |
+| ---------------- | ------------------------------------- |
+| `Python<'py>`    | A GIL token, used to pass to PyO3 constructors to prove ownership of the GIL. |
+| `Bound<'py, T>`  | A Python object connected to the GIL lifetime. This provides access to most of PyO3's APIs. |
+| `Py<T>`          | A Python object isolated from the GIL lifetime. This can be sent to other threads. |
+| `PyObject`       | An alias for `Py<PyAny>`              |
+| `PyRef<T>`       | A `#[pyclass]` borrowed immutably.    |
+| `PyRefMut<T>`    | A `#[pyclass]` borrowed mutably.      |
 
 For more detail on accepting `#[pyclass]` values as function arguments, see [the section of this guide on Python Classes](../class.md).
 
@@ -95,7 +95,8 @@ Finally, the following Rust types are also able to convert to Python as return v
 | `BTreeMap<K, V>` | `Dict[K, V]`                 |
 | `HashSet<T>`  | `Set[T]`                        |
 | `BTreeSet<T>` | `Set[T]`                        |
-| `&PyCell<T: PyClass>` | `T`                     |
+| `Py<T>` | `T`                                   |
+| `Bound<T>` | `T`                                |
 | `PyRef<T: PyClass>` | `T`                       |
 | `PyRefMut<T: PyClass>` | `T`                    |
 

diff --git a/guide/src/function-calls.md b/guide/src/function-calls.md
@@ -0,0 +1 @@
+# Calling Python functions
diff --git a/guide/src/index.md b/guide/src/index.md
@@ -2,6 +2,22 @@
 
 Welcome to the PyO3 user guide! This book is a companion to [PyO3's API docs](https://docs.rs/pyo3). It contains examples and documentation to explain all of PyO3's use cases in detail.
 
+The rough order of material in this user guide is as follows:
+  1. Getting started
+  2. Wrapping Rust code for use from Python
+  3. How to use Python code from Rust
+  4. Remaining topics which go into advanced concepts in detail
+
 Please choose from the chapters on the left to jump to individual topics, or continue below to start with PyO3's README.
 
+<div class="warning">
+⚠️ Warning: API update in progress 🛠️
+
+PyO3 0.21 has introduced a significant new API, termed the "Bound" API after the new smart pointer `Bound<T>`.
+
+While much of the guide has been updated to the new API, it is possible some stray references to the older "GIL Refs" API such as `&PyAny` may remain.
+</div>
+
+<hr style="opacity:0.2">
+
 {{#include ../../README.md}}