PyO3

https://docs.rs/pyo3/latest/pyo3/
Admin
PyO3 provides Rust bindings to the Python interpreter, enabling developers to write native Python...
Tokens:546,483
Snippets:4,923
Trust Score:9.7
Update:11 months ago
Show doc for...
Tokens:
Raw
### Build and Test PyO3 Module with Maturin

Source: https://docs.rs/pyo3/latest/pyo3/index

Shell commands to set up a Python virtual environment, install maturin build tool, compile the PyO3 extension module, and test it in Python. Demonstrates the complete workflow from environment setup through module testing with sample function invocation.

```bash
$ cd string_sum
$ python -m venv .env
$ source .env/bin/activate
$ pip install maturin
$ maturin develop
$ python
>>> import string_sum
>>> string_sum.sum_as_string(5, 20)
'25'
```

--------------------------------

### Get Python Interpreter Version String

Source: https://docs.rs/pyo3/latest/pyo3/marker/struct.Python

Retrieves the full version string of the running Python interpreter. The example shows how to assert that the version starts with '3.', indicating a Python 3 installation.

```rust
Python::attach(|py| {
    // The full string could be, for example:
    // "3.10.0 (tags/v3.10.0:b494f59, Oct  4 2021, 19:00:18) [MSC v.1929 64 bit (AMD64)]"
    assert!(py.version().starts_with("3."));
});
```

--------------------------------

### Install Python Development Libraries on Ubuntu

Source: https://docs.rs/pyo3/latest/pyo3/index

System installation command for Python shared library on Ubuntu required to embed Python in Rust applications. This prerequisite ensures that PyO3's auto-initialize feature can properly link and initialize the Python interpreter.

```bash
sudo apt install python3-dev
```

--------------------------------

### Rust: Example of creating and inspecting a PyByteArray

Source: https://docs.rs/pyo3/latest/pyo3/types/struct.PyByteArray

Demonstrates the usage of `PyByteArray::new_with` to create a bytearray and then access its contents as a byte slice. This example shows how to initialize a bytearray with specific data and verify its content.

```rust
use pyo3::{prelude::*,
types::PyByteArray};

Python::attach(|py| -> PyResult<()> {
    let py_bytearray = PyByteArray::new_with(py, 10, |bytes: &mut [u8]| {
        bytes.copy_from_slice(b"Hello Rust");
        Ok(())
    })?;
    let bytearray: &[u8] = unsafe { py_bytearray.as_bytes() };
    assert_eq!(bytearray, b"Hello Rust");
    Ok(())
})
```

--------------------------------

### Setup PyO3 with num-complex

Source: https://docs.rs/pyo3/latest/pyo3/num_complex/index

Instructions for adding the num-complex and pyo3 crates to your Cargo.toml file to enable complex number support. Ensure compatible versions are used.

```toml
[dependencies]
# change * to the latest versions
num-complex = "*"
pyo3 = { version = "0.27.1", features = ["num-complex"] }
```

--------------------------------

### Rust Example: Get Item from PyList

Source: https://docs.rs/pyo3/latest/pyo3/prelude/trait.PyListMethods

Demonstrates how to retrieve an item from a Python list at a specific index using the `get_item` method from the `PyListMethods` trait in pyo3. This example initializes a Python list within a Rust context and then extracts an integer value from the first element.

```rust
use pyo3::{prelude::*},
 use types::PyList;

 Python::attach(|py| {
    let list = PyList::new(py, [2, 3, 5, 7]).unwrap();
    let obj = list.get_item(0);
    assert_eq!(obj.unwrap().extract::<i32>().unwrap(), 2);
 });
```

--------------------------------

### PyRange Methods: Start Value

Source: https://docs.rs/pyo3/latest/pyo3/prelude/struct.Bound

Retrieves the starting value of a PyRange object. This corresponds to the first element in a Python range.

```rust
/// Returns the start of the range.
fn start(&self) -> PyResult<isize>;

```

--------------------------------

### Example: Product Calculation for Result Iterators in Rust

Source: https://docs.rs/pyo3/latest/pyo3/prelude/type.PyResult

Demonstrates calculating the product of parsed numbers from a vector of strings. It shows success and failure cases where parsing might return an Err.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

--------------------------------

### Setup PyO3 Either Feature in Cargo.toml

Source: https://docs.rs/pyo3/latest/pyo3/either/index

Configure Cargo dependencies to enable the `either` feature in PyO3. This setup adds the `either` crate as a dependency and enables the PyO3 `either` feature flag. Ensure compatible versions of both `either` and `pyo3` are used together.

```toml
[dependencies]
either = "*"
pyo3 = { version = "0.27.1", features = ["either"] }
```

--------------------------------

### Example: Downcasting and Casting in pyo3 (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/struct.Py

Demonstrates how to use `downcast_bound` and `cast_bound` to safely convert `Py<PyAny>` and `Py<T>` instances to specific Python types like `PyDict` or user-defined pyclasses. Includes examples of both successful and failed casts.

```rust
use pyo3::prelude::*;
use pyo3::types::{PyDict, PyList};

Python::attach(|py| {
    let any = PyDict::new(py).into_any().unbind();

    assert!(any.downcast_bound::<PyDict>(py).is_ok());
    assert!(any.downcast_bound::<PyList>(py).is_err());
});
```

```rust
use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Py::new(py, Class { i: 0 })?.into_any();

    let class_bound = class.downcast_bound::<Class>(py)?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})
```

```rust
use pyo3::prelude::*;
use pyo3::types::{PyDict, PyList};

Python::attach(|py| {
    let any = PyDict::new(py).into_any().unbind();

    assert!(any.cast_bound::<PyDict>(py).is_ok());
    assert!(any.cast_bound::<PyList>(py).is_err());
});
```

```rust
use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Py::new(py, Class { i: 0 })?.into_any();

    let class_bound = class.cast_bound::<Class>(py)?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})
```

--------------------------------

### Example: Creating and Using PyCFunction from Closure (Python)

Source: https://docs.rs/pyo3/latest/pyo3/types/struct.PyCFunction

Demonstrates creating a Python function `add_one` from a Rust closure using `PyCFunction::new_closure`. The closure takes a tuple of arguments, extracts an i64, adds one, and returns the result. The example then runs Python code to assert the function's correctness.

```python
Python::attach(|py| {
    let add_one = |args: &Bound<'_, PyTuple>, _kwargs: Option<&Bound<'_, PyDict>>| -> PyResult<_> {
        let i = args.extract::<(i64,)>()?.0;
        Ok(i+1)
    };
    let add_one = PyCFunction::new_closure(py, None, None, add_one).unwrap();
    py_run!(py, add_one, "assert add_one(42) == 43");
});
```

--------------------------------

### PyUnicodeError Documentation

Source: https://docs.rs/pyo3/latest/pyo3/exceptions/struct.PyUnicodeError

Details about the PyUnicodeError struct, its purpose, and usage examples.

```APIDOC
## PyUnicodeError

Represents Python’s `UnicodeError` exception.

### Example: Raising UnicodeError from Rust

This exception can be sent to Python code by converting it into a `PyErr`, where Python code can then catch it.

```rust
use pyo3::prelude::*; 
use pyo3::exceptions::PyUnicodeError;

#[pyfunction]
fn always_throws() -> PyResult<()> {
    let message = "I'm UnicodeError, and I was raised from Rust.";
    Err(PyUnicodeError::new_err(message))
}
```

Python code example:

```python
from my_module import always_throws

try:
   always_throws()
except UnicodeError as e:
   print(f"Caught an exception: {e}")
```

### Example: Catching UnicodeError in Rust

```rust
use pyo3::prelude::*; 
use pyo3::exceptions::PyUnicodeError;
use pyo3::ffi::c_str;

Python::attach(|py| {
    let result: PyResult<()> = py.run(c_str!("raise UnicodeError"), None, None);

    let error_type = match result {
        Ok(_) => "Not an error",
        Err(error) if error.is_instance_of::<PyUnicodeError>(py) => "UnicodeError",
        Err(_) => "Some other error",
    };

    assert_eq!(error_type, "UnicodeError");
});
```

### `PyUnicodeError::new_err<A>(args: A) -> PyErr`

Creates a new `PyErr` of this type.

- **args** (A): Arguments to create the error with. Must implement `PyErrArguments`, `Send`, and `Sync`.
```

--------------------------------

### Create PySliceIndices Instance in Rust

Source: https://docs.rs/pyo3/latest/pyo3/types/struct.PySliceIndices

Provides a constructor function `new` for the `PySliceIndices` struct. This function takes the start, stop, and step values as `isize` and returns a new `PySliceIndices` instance.

```rust
pub fn new(start: isize, stop: isize, step: isize) -> PySliceIndices
```

--------------------------------

### Setup pyo3 with anyhow feature

Source: https://docs.rs/pyo3/latest/pyo3/anyhow/index

Demonstrates how to configure Cargo.toml to enable the 'anyhow' feature in pyo3, allowing for integrated error handling between Rust and Python. Requires compatible versions of 'anyhow' and 'pyo3'.

```toml
[dependencies]
anyhow = "*"
pyo3 = { version = "0.27.1", features = ["anyhow"] }
```

--------------------------------

### Rust: Get Start of Python Range

Source: https://docs.rs/pyo3/latest/pyo3/types/trait.PyRangeMethods

Retrieves the starting value of a Python range object from Rust using the start() method provided by the PyRangeMethods trait.

```rust
fn start(&self) -> PyResult<isize>
```

--------------------------------

### Rust: Example of setting and getting context for a PyCapsule

Source: https://docs.rs/pyo3/latest/pyo3/prelude/trait.PyCapsuleMethods

Demonstrates how to use `set_context` and `context` methods of `PyCapsuleMethods`. This example shows storing a `Sender` as context, which is then accessed when the capsule's destructor is called.

```rust
use std::ffi::c_void;
use std::sync::mpsc::{channel, Sender};
use pyo3::{prelude::*, types::PyCapsule};

let (tx, rx) = channel::<String>();

fn destructor(val: u32, context: *mut c_void) {
    let ctx = unsafe { *Box::from_raw(context.cast::<Sender<String>>()) };
    ctx.send("Destructor called!".to_string()).unwrap();
}

Python::attach(|py| {
    let capsule =
        PyCapsule::new_with_destructor(py, 123, None, destructor as fn(u32, *mut c_void))
            .unwrap();
    let context = Box::new(tx);  // `Sender<String>` is our context, box it up and ship it!
    capsule.set_context(Box::into_raw(context).cast()).unwrap();
    // This scope will end, causing our destructor to be called...
});

assert_eq!(rx.recv(), Ok("Destructor called!".to_string()));
```

--------------------------------

### Setup PyO3 with Chrono Feature

Source: https://docs.rs/pyo3/latest/pyo3/chrono/index

Instructions to set up your Cargo.toml to enable the chrono feature for PyO3. This requires adding both `chrono` and `pyo3` as dependencies, specifying the chrono feature for PyO3. Ensure compatible versions of both crates are used.

```toml
[dependencies]
chrono = "0.4"
pyo3 = { version = "0.27.1", features = ["chrono"] }
```

--------------------------------

### Setup: Add indexmap and PyO3 with 'indexmap' feature to Cargo.toml

Source: https://docs.rs/pyo3/latest/pyo3/indexmap/index

This section details the necessary dependencies to include in your `Cargo.toml` file for enabling `indexmap` functionality within your PyO3 project. Ensure compatible versions are used.

```toml
[dependencies]
# change * to the latest versions
indexmap = "*"
pyo3 = { version = "0.27.1", features = ["indexmap"] }
```

--------------------------------

### Get Tuple Item Example - Rust

Source: https://docs.rs/pyo3/latest/pyo3/prelude/trait.PyTupleMethods

Demonstrates how to retrieve an item from a Python tuple using the `get_item` method in Rust with pyo3. This example shows accessing the first element and extracting its value as an i32.

```rust
use pyo3::prelude::*;

Python::attach(|py| -> PyResult<()> {
    let tuple = (1, 2, 3).into_pyobject(py)?;
    let obj = tuple.get_item(0);
    assert_eq!(obj?.extract::<i32>()?, 1);
    Ok(())
})
```

--------------------------------

### Setup Cargo.toml for PyO3 native Python module

Source: https://docs.rs/pyo3/latest/pyo3/index

Configuration file for creating a native Python module using PyO3 and maturin. The cdylib crate type is necessary to produce a shared library for Python to import from.

```toml
[package]
name = "string-sum"
version = "0.1.0"
edition = "2021"

[lib]
name = "string_sum"
# "cdylib" is necessary to produce a shared library for Python to import from.
#
# Downstream Rust code (including code in `bin/`, `examples/`, and `tests/`) will not be able
# to `use string_sum;` unless the "rlib" or "lib" crate type is also included, e.g.:
```

--------------------------------

### Rust: Downcasting to PyClass Reference Example

Source: https://docs.rs/pyo3/latest/pyo3/type.PyObject

Shows an example of using `downcast_bound` to obtain a reference to a Rust `pyclass` embedded within a `Py<PyAny>`. This is useful for mutating class instances. It also demonstrates using `extract` to get a `PyRefMut` directly.

```rust
use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Py::new(py, Class { i: 0 })?.into_any();
    let class_bound = class.downcast_bound::<Class>(py)?;
    class_bound.borrow_mut().i += 1;
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})
```

--------------------------------

### Type Information and Conversion Traits for PyPreConfig (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/ffi/struct.PyPreConfig

Demonstrates blanket implementations of traits like `Any`, `Borrow`, `From`, `Into`, `TryFrom`, and `TryInto` for `PyPreConfig`. These implementations facilitate type introspection, data conversion, and interoperability within the Rust ecosystem.

```rust
impl<T> Any for T where T: 'static + ?Sized {
    fn type_id(&self) -> TypeId
    // ...
}

impl<T> Borrow<T> for T where T: ?Sized {
    fn borrow(&self) -> &T
    // ...
}

impl<T> From<T> for T {
    fn from(t: T) -> T
    // ...
}

impl<T, U> Into<U> for T where U: From<T> {
    fn into(self) -> U
    // ...
}

impl<T, U> TryFrom<U> for T where U: Into<T> {
    type Error = Infallible
    fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
    // ...
}

impl<T, U> TryInto<U> for T where U: TryFrom<T> {
    type Error = <U as TryFrom<T>>::Error
    fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
    // ...
}
```

--------------------------------

### Getting a Mutable Reference to a PyClass Instance in pyo3

Source: https://docs.rs/pyo3/latest/pyo3/prelude/type.PyObject

Shows how to obtain a mutable reference to a pyclass instance contained within a Py<PyAny> using `downcast_bound`. This is particularly useful when you need to modify the state of a Python object represented as a Rust struct. The example also demonstrates an alternative using `extract` to get a `PyRefMut` directly.

```rust
use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Py::new(py, Class { i: 0 })?.into_any();

    let class_bound = class.downcast_bound::<Class>(py)?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})
```

--------------------------------

### Rust: Handling File Metadata with Path and Error Kind

Source: https://docs.rs/pyo3/latest/pyo3/prelude/type.PyResult

Illustrates retrieving file metadata and handling potential errors like 'NotFound'. This example uses `Path::new` and `metadata().and_then()` to chain operations and assert the expected outcomes, including error kinds.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Get Iterator Over Slice Elements

Source: https://docs.rs/pyo3/latest/pyo3/pybacked/struct.PyBackedBytes

Returns an iterator that yields references to the elements of the slice in order from start to end. This is the standard way to process slice elements sequentially in a safe and idiomatic manner.

```rust
pub fn iter(&self) -> Iter<'_, T>

let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```

--------------------------------

### Get Python Interpreter Version Info

Source: https://docs.rs/pyo3/latest/pyo3/marker/struct.Python

Retrieves detailed version information of the Python interpreter as a struct similar to `sys.version_info`. The example demonstrates checking if the version is 3.7 or higher.

```rust
Python::attach(|py| {
    // PyO3 supports Python 3.7 and up.
    assert!(py.version_info() >= (3, 7));
    assert!(py.version_info() >= (3, 7, 0));
});
```

--------------------------------

### Example: Casting to PyClass Reference (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/struct.Borrowed

Shows how to get a reference to a pyclass from a `Bound<'_, PyAny>` using `cast`. This is useful for mutating pyclass instances held as `Py<PyAny>`. It also demonstrates using `extract` to obtain a `PyRefMut` directly.

```rust
use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Bound::new(py, Class { i: 0 })?.into_any();

    let class_bound: &Bound<'_, Class> = class.cast()?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract()?;
    assert_eq!(class_ref.i, 1);
    Ok(())
});
```

--------------------------------

### PyMappingProxy Methods: Size, Keys, Values, Items

Source: https://docs.rs/pyo3/latest/pyo3/prelude/struct.Bound

Provides methods for PyMappingProxy objects to check emptiness and retrieve keys, values, and items. These mirror the corresponding PyMapping methods.

```rust
/// Checks if the mappingproxy is empty, i.e. `len(self) == 0`.
fn is_empty(&self) -> PyResult<bool>;

```

```rust
/// Returns a list containing all keys in the mapping.
fn keys(&self) -> PyResult<Bound<'py, PyList>>;

```

```rust
/// Returns a list containing all values in the mapping.
fn values(&self) -> PyResult<Bound<'py, PyList>>;

```

```rust
/// Returns a list of all (key, value) pairs in the mapping.
fn items(&self) -> PyResult<Bound<'py, PyList>>;

```

--------------------------------

### Import PyO3 Prelude in Rust

Source: https://docs.rs/pyo3/latest/pyo3/prelude/index

Demonstrates how to use the PyO3 prelude module to import all commonly used items with a single glob import statement. This simplifies module headers in PyO3-heavy Rust code by avoiding individual imports for conversion traits, Python types, and macros.

```rust
use pyo3::prelude::*;
```

--------------------------------

### PyRef into_super and as_super Examples

Source: https://docs.rs/pyo3/latest/pyo3/pycell/struct.PyRef

Illustrates how to navigate class hierarchies using `into_super` and `as_super` methods of `PyRef`. `into_super` consumes the `PyRef` to get a `PyRef` to the superclass, while `as_super` provides a shared reference without consuming it, allowing chained access to ancestors.

```rust
use pyo3::prelude::*;

#[pyclass(subclass)]
struct Base1 {
    name1: &'static str,
}

#[pyclass(extends=Base1, subclass)]
struct Base2 {
    name2: &'static str,
}

#[pyclass(extends=Base2)]
struct Sub {
    name3: &'static str,
}

#[pymethods]
impl Sub {
    #[new]
    fn new() -> PyClassInitializer<Self> {
        PyClassInitializer::from(Base1 { name1: "base1" })
            .add_subclass(Base2 { name2: "base2" })
            .add_subclass(Self { name3: "sub" })
    }
    fn name(slf: PyRef<'_, Self>) -> String {
        let subname = slf.name3;
        let super_ = slf.into_super();
        format!("{} {}", super_.as_ref().name1, super_.name2)
    }
}
```

```rust
use pyo3::prelude::*;

#[pyclass(subclass)]
struct Base {
    base_name: &'static str,
}
#[pymethods]
impl Base {
    fn base_name_len(&self) -> usize {
        self.base_name.len()
    }
}

#[pyclass(extends=Base)]
struct Sub {
    sub_name: &'static str,
}

#[pymethods]
impl Sub {
    #[new]
    fn new() -> (Self, Base) {
        (Self { sub_name: "sub_name" }, Base { base_name: "base_name" })
    }
    fn sub_name_len(&self) -> usize {
        self.sub_name.len()
    }
    fn format_name_lengths(slf: PyRef<'_, Self>) -> String {
        format!("{} {}", slf.as_super().base_name_len(), slf.sub_name_len())
    }
}
```

--------------------------------

### Python: Calling Rust Bytes Functions

Source: https://docs.rs/pyo3/latest/pyo3/bytes/index

Illustrates how to call Rust functions, exposed via `pyo3`, from Python. This example shows invoking functions that handle `bytes::Bytes` objects, demonstrating the seamless interaction between Python and Rust for byte manipulation.

```python
from my_module import get_message_bytes, num_bytes

message = get_message_bytes()
assert message == b"Hello Python!"

size = num_bytes(message)
assert size == 13
```

--------------------------------

### Get Immutable Reference for Frozen Class (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/struct.Borrowed

Provides a direct immutable reference to the value `T` for classes marked as `frozen` and `Sync`. This method is simpler and more efficient than borrowing when the class is immutable and thread-safe. Example demonstrates usage with an atomic usize in a frozen struct.

```rust
pub fn get(&self) -> &T
where T: PyClass<Frozen = True> + Sync,
```

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

#[pyclass(frozen)]
struct FrozenCounter {
    value: AtomicUsize,
}

Python::attach(|py| {
    let counter = FrozenCounter { value: AtomicUsize::new(0) };

    let py_counter = Bound::new(py, counter).unwrap();

    py_counter.get().value.fetch_add(1, Ordering::Relaxed);
});
```

--------------------------------

### Rust: Trim Leading Whitespace from String

Source: https://docs.rs/pyo3/latest/pyo3/pybacked/struct.PyBackedStr

Removes only leading whitespace from a string slice, based on the Unicode `White_Space` property. The 'start' is defined by the byte string's first position, respecting text directionality. Examples show basic usage and how it works with left-to-right and right-to-left text.

```rust
let s = "\n Hello\tworld\t\n";
assert_eq!("Hello\tworld\t\n", s.trim_start());

let s = "  English  ";
assert!(Some('E') == s.trim_start().chars().next());

let s = "  עברית  ";
assert!(Some('ע') == s.trim_start().chars().next());
```

--------------------------------

### Import CompareOp from PyClass instead of Module

Source: https://docs.rs/pyo3/latest/pyo3/class/index

Demonstrates the recommended migration path from the deprecated pyo3::class::basic::CompareOp to pyo3::pyclass::CompareOp. This shows the preferred approach for accessing comparison operators in PyO3.

```rust
// Deprecated approach
use pyo3::class::basic::CompareOp;

// Recommended approach
use pyo3::pyclass::CompareOp;
```

--------------------------------

### Get element offset within a slice (Rust - Nightly)

Source: https://docs.rs/pyo3/latest/pyo3/pybacked/struct.PyBackedBytes

This experimental nightly-only API returns the index of an element given a reference to it within the slice. It uses pointer arithmetic and does not compare elements. It returns `None` if the provided element reference is not aligned to the start of an element in the slice. This method panics if `T` is zero-sized.

```rust
#![feature(substr_range)]

let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

```rust
#![feature(substr_range)]

let arr: &[[u32; 2]] = &[[0, 1], [2, 3]];
let flat_arr: &[u32] = arr.as_flattened();

let ok_elm: &[u32; 2] = flat_arr[0..2].try_into().unwrap();
let weird_elm: &[u32; 2] = flat_arr[1..3].try_into().unwrap();

assert_eq!(ok_elm, &[0, 1]);
assert_eq!(weird_elm, &[1, 2]);

assert_eq!(arr.element_offset(ok_elm), Some(0)); // Points to element 0
assert_eq!(arr.element_offset(weird_elm), None); // Points between element 0 and 1
```

--------------------------------

### Setup pyo3 time feature with Cargo.toml

Source: https://docs.rs/pyo3/latest/pyo3/time/index

This snippet shows how to configure your Cargo.toml file to enable the 'time' feature for the pyo3 crate. It requires adding both 'time' and 'pyo3' as dependencies, specifying the 'time' feature for pyo3. Ensure compatible versions of 'time' and 'pyo3' are used.

```toml
[dependencies]
time = "0.3"
pyo3 = { version = "0.27.1", features = ["time"] }
```

--------------------------------

### Get Mutable Reference to PyClass with pyo3

Source: https://docs.rs/pyo3/latest/pyo3/prelude/struct.Bound

Illustrates obtaining a mutable reference to a `PyClass` from a `Bound<'py, PyAny>`. It uses `cast` to get a `&Bound<'_, Class>` and then `borrow_mut()` to modify its fields. Alternatively, `extract` can be used to directly get a `PyRefMut<'_, Class>`.

```rust
use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Bound::new(py, Class { i: 0 })?.into_any();

    let class_bound: &Bound<'_, Class> = class.cast()?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract()?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})
```

--------------------------------

### Initialize Python Interpreter (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/marker/struct.Python

Prepares the Python interpreter for use. If not already initialized, it initializes the interpreter with signal handling disabled. This function is unavailable on PyPy and GraalPy. If the interpreter is already initialized, this function has no effect. It's necessary for using other PyO3 features that require an active Python interpreter.

```rust
pub fn initialize();

```

```rust
use pyo3::prelude::*;

Python::initialize();
Python::attach(|py| py.run(pyo3::ffi::c_str!("print('Hello World')"), None, None))

```

--------------------------------

### Get TypeId of an Object (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/prelude/struct.Bound

Gets the `TypeId` of an object. This is a fundamental operation for runtime type introspection.

```rust
impl<T> Any for T {
    fn type_id(&self) -> TypeId {
        // Implementation details here
    }
}
```

--------------------------------

### Create SubClass Initializer using Base Class Initializer

Source: https://docs.rs/pyo3/latest/pyo3/pyclass_init/struct.PyClassInitializer

Shows how to create an initializer for a subclass by first creating an initializer for its base class and then using `add_subclass`. This pattern is useful when the subclass's constructor depends on the base class's initialization logic.

```rust
use pyo3::prelude::*

#[pyclass(subclass)]
struct BaseClass {
    #[pyo3(get)]
    value: i32,
}

impl BaseClass {
    fn new(value: i32) -> PyResult<Self> {
        Ok(Self { value })
    }
}

#[pyclass(extends=BaseClass)]
struct SubClass {}

#[pymethods]
impl SubClass {
    #[new]
    fn new(value: i32) -> PyResult<PyClassInitializer<Self>> {
        let base_init = PyClassInitializer::from(BaseClass::new(value)?);
        Ok(base_init.add_subclass(SubClass {}))
    }
}

fn main() -> PyResult<()> {
    Python::attach(|py| {
        let m = PyModule::new(py, "example")?;
        m.add_class::<SubClass>()?;
        m.add_class::<BaseClass>()?;

        let instance = m.getattr("SubClass")?.call1((92,))?;

        // `SubClass` does not have a `value` attribute, but `BaseClass` does.
        let n = instance.getattr("value")?.extract::<i32>()?;
        assert_eq!(n, 92);

        Ok(())
    })
}
```

--------------------------------

### Constructing a Full Python Slice (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/types/struct.PySlice

Shows how to create a full Python slice, equivalent to the `::` notation in Python, using `PySlice::full`. This function requires the Python interpreter context and returns a `Bound<'_, PySlice>` representing the full slice.

```Rust
pub fn full(py: Python<'_>) -> Bound<'_, PySlice>
```

--------------------------------

### TryFrom and TryInto Implementations

Source: https://docs.rs/pyo3/latest/pyo3/pyclass/struct.PyClassGuard

Documentation for the `TryFrom` and `TryInto` traits as implemented for PyO3 type conversions.

```APIDOC
### impl<T, U> TryFrom<U> for T
where U: Into<T>,

#### Description
Allows attempting to convert a type `U` into type `T`, where `U` can be converted into `T` using `Into`.

#### type Error = Infallible

##### Description
The type returned in the event of a conversion error. `Infallible` indicates that conversion errors are not expected in this specific implementation.

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

##### Description
Performs the conversion from `U` to `T`.

##### Method
`TryFrom::try_from`

##### Endpoint
N/A (Method call)

##### Parameters
- **value** (U) - Required - The value to convert.

##### Request Body
N/A

##### Request Example
```rust
use std::convert::TryFrom;

// Assuming T and U are defined elsewhere and satisfy the trait bounds
// fn example_try_from<T, U>(value: U) -> Result<T, std::convert::Infallible> where U: Into<T> {
//     T::try_from(value)
// }
```

##### Response
- **Success Response (200)**: `Result<T, Infallible>` - The converted value of type `T` or an infallible error.

##### Response Example
N/A

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

#### Description
Allows attempting to convert a type `T` into type `U` using the `TryFrom` trait.

#### type Error = <U as TryFrom<T>>::Error

##### Description
The type returned in the event of a conversion error, as defined by the `TryFrom` implementation for `U`.

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

##### Description
Performs the conversion from `T` to `U`.

##### Method
`TryInto::try_into`

##### Endpoint
N/A (Method call)

##### Parameters
N/A

##### Request Body
N/A

##### Request Example
```rust
// Assuming T and U are defined elsewhere and satisfy the trait bounds
// fn example_try_into<T, U>(value: T) -> Result<U, <U as TryFrom<T>>::Error> where U: TryFrom<T> {
//     value.try_into()
// }
```

##### Response
- **Success Response (200)**: `Result<U, <U as TryFrom<T>>::Error>` - The converted value of type `U` or an error.

##### Response Example
N/A
```

--------------------------------

### Getting a PyClass Reference with PyO3

Source: https://docs.rs/pyo3/latest/pyo3/prelude/type.PyObject

Demonstrates how to obtain a mutable reference to a Python class instance wrapped by PyO3. This is useful for modifying class attributes. It shows using `cast_bound` and `extract` to get a `PyRefMut` for mutation.

```rust
use pyo3::prelude::*;

#[pyclass]
struct Class {
    i: i32,
}

Python::attach(|py| {
    let class = Py::new(py, Class { i: 0 })?.into_any();

    let class_bound = class.cast_bound::<Class>(py)?;

    class_bound.borrow_mut().i += 1;

    // Alternatively you can get a `PyRefMut` directly
    let class_ref: PyRefMut<'_, Class> = class.extract(py)?;
    assert_eq!(class_ref.i, 1);
    Ok(())
})
```

--------------------------------

### Get Items (Key-Value Pairs) of a Python Dictionary in Rust

Source: https://docs.rs/pyo3/latest/pyo3/prelude/trait.PyDictMethods

Shows how to get a list of key-value pairs (items) from a Python dictionary from Rust using the `items` method from `PyDictMethods`. This is equivalent to `list(dict.items())` in Python.

```rust
fn items(&self) -> Bound<'py, PyList>;
```

--------------------------------

### Setup for pyo3 with chrono-tz feature

Source: https://docs.rs/pyo3/latest/pyo3/chrono_tz/index

This snippet demonstrates how to configure your Cargo.toml file to use the pyo3 crate with the 'chrono-tz' feature enabled. It requires compatible versions of chrono-tz and pyo3, and is available for Python 3.9 and above.

```toml
[dependencies]
chrono-tz = "0.8"
pyo3 = { version = "0.27.1", features = ["chrono-tz"] }
```

--------------------------------

### Rust: Using intern! to optimize dictionary key creation

Source: https://docs.rs/pyo3/latest/pyo3/macro.intern

Demonstrates how to use the intern! macro in Rust with pyo3. The `create_dict_faster` function shows how `intern!` reuses Python string objects for dictionary keys, compared to `create_dict` which creates new objects on each call.

```rust
use pyo3::intern;

#[pyfunction] 
fn create_dict(py: Python<'_>) -> PyResult<Bound<'_, PyDict>> {
    let dict = PyDict::new(py);
    dict.set_item("foo", 42)?;
    Ok(dict)
}

#[pyfunction] 
fn create_dict_faster(py: Python<'_>) -> PyResult<Bound<'_, PyDict>> {
    let dict = PyDict::new(py);
    dict.set_item(intern!(py, "foo"), 42)?;
    Ok(dict)
}
```

--------------------------------

### PyBytes Method: Get Byte Slice (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/prelude/struct.Bound

The `as_bytes()` method for `PyBytes` provides a safe way to get a byte slice view of the Python bytes object. This is useful for directly processing the byte data without copying.

```Rust
impl<'py> PyBytesMethods<'py> for Bound<'py, PyBytes> {
    /// Gets the Python string as a byte slice.
    fn as_bytes(&self) -> &[u8];
}
```

--------------------------------

### PyDictObject Blanket Implementations

Source: https://docs.rs/pyo3/latest/pyo3/ffi/struct.PyDictObject

Describes blanket implementations for PyDictObject, such as Any, Borrow, and From.

```APIDOC
## Blanket Implementations for PyDictObject

### `impl<T> Any for T`
Provides the `type_id` method for any type `T` that is `'static` and `?Sized`.

### `impl<T> Borrow<T> for T`
Provides the `borrow` method for immutably borrowing an owned value.

### `impl<T> BorrowMut<T> for T`
Provides the `borrow_mut` method for mutably borrowing an owned value.

### `impl<T> From<T> for T`
Provides the `from` method, returning the argument unchanged.

### `impl<T, U> Into<U> for T`
Provides the `into` method, converting `self` into `U` using `U::from(self)`.

### `impl<T> IntoEither for T`
Provides `into_either` and `into_either_with` methods for converting `self` into `Either<Self, Self>` variants.

### `impl<T, U> TryFrom<U> for T`
Provides the `try_from` method for fallible conversions, with `Infallible` as the error type.

### `impl<T, U> TryInto<U> for T`
Provides the `try_into` method for fallible conversions.
```

--------------------------------

### Rust: Implement ReadOnlyCell Get Method

Source: https://docs.rs/pyo3/latest/pyo3/buffer/struct.ReadOnlyCell

Implements the `get` method for ReadOnlyCell, which returns a copy of the current value held within the cell. This method is part of the ReadOnlyCell's public API for accessing its data.

```rust
pub fn get(&self) -> T

```

--------------------------------

### Create Py<T> from FFI Pointer (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/prelude/struct.Py

Provides methods to create `Py<T>` instances from raw FFI pointers. Handles cases where the pointer might be null, returning `Option<Self>` or `PyResult<Self>`, or panics if null. Safety requires the pointer to be valid and point to a Python object of the expected type.

```rust
unsafe fn from_owned_ptr_or_opt( _py: Python<'_>, ptr: *mut PyObject, ) -> Option<Self>
// Creates a Py<T> instance by taking ownership of the given FFI pointer.
// Returns None if ptr is null.

unsafe fn from_borrowed_ptr(py: Python<'_>, ptr: *mut PyObject) -> Py<T>
// Creates a Py<T> instance by creating a new reference from the given FFI pointer.
// Panics if ptr is null.

unsafe fn from_borrowed_ptr_or_err( py: Python<'_>, ptr: *mut PyObject, ) -> PyResult<Self>
// Creates a Py<T> instance by creating a new reference from the given FFI pointer.
// Fetches the current Python exception as a PyErr if ptr is null.

unsafe fn from_borrowed_ptr_or_opt( _py: Python<'_>, ptr: *mut PyObject, ) -> Option<Self>
// Creates a Py<T> instance by creating a new reference from the given FFI pointer.
// Returns None if ptr is null.
```

--------------------------------

### Attempt to Get Slice as Fixed-Size Array Reference (Nightly)

Source: https://docs.rs/pyo3/latest/pyo3/pybacked/struct.PyBackedBytes

Attempts to get a reference to the underlying data as a fixed-size array of length N. This is an experimental nightly-only API. It returns None if the slice's length does not exactly match N.

```rust
pub fn as_array<const N: usize>(&self) -> Option<&[T; N]>

// Example usage would require a nightly compiler.
```

--------------------------------

### Configure PyO3 Extension Module in Cargo.toml

Source: https://docs.rs/pyo3/latest/pyo3/index

Defines project configuration for building a Python extension module with PyO3. The crate-type is set to 'cdylib' for creating a shared library loadable by Python. PyO3 version 0.27.1 is specified with the 'extension-module' feature enabled for proper Python integration.

```toml
[dependencies.pyo3]
version = "0.27.1"
features = ["extension-module"]

crate-type = ["cdylib"]
```

--------------------------------

### Constructing a Python Slice (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/types/struct.PySlice

Demonstrates how to create a new Python slice object using the `PySlice::new` function. This function takes the Python interpreter context and `isize` values for start, stop, and step. The output is a `Bound<'_, PySlice>` representing the new slice.

```Rust
pub fn new( py: Python<'_>, start: isize, stop: isize, step: isize, ) -> Bound<'_, PySlice>
```

--------------------------------

### Get Python Ellipsis Object in Rust

Source: https://docs.rs/pyo3/latest/pyo3/types/struct.PyEllipsis

Provides a Rust function to retrieve the Python Ellipsis object using PyO3. The `get` method takes a `Python<'_>` context and returns a `Borrowed<'_, '_, PyEllipsis>`, allowing interaction with the Ellipsis singleton.

```rust
pub fn get(py: Python<'_>) -> Borrowed<'_, '_, PyEllipsis>

```

--------------------------------

### Get Raw PyTypeObject Pointer (pyo3)

Source: https://docs.rs/pyo3/latest/pyo3/exceptions/socket/struct.gaierror

Provides a method to get a raw pointer to the `PyTypeObject` for a Rust type that represents a Python type using pyo3. This is a low-level operation primarily for internal use or advanced scenarios.

```rust
fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

```

--------------------------------

### Clone Implementation for PyPreConfig (Rust)

Source: https://docs.rs/pyo3/latest/pyo3/ffi/struct.PyPreConfig

Provides `Clone` and `Copy` trait implementations for the `PyPreConfig` struct, allowing for simple duplication of configuration values. This is essential for managing configuration instances across different parts of an application.

```rust
impl Clone for PyPreConfig {
    fn clone(&self) -> PyPreConfig
    // ...
    fn clone_from(&mut self, source: &Self)
    // ...
}

impl Copy for PyPreConfig
```

--------------------------------

### PyO3 Procedural Macros for Python Interoperability

Source: https://docs.rs/pyo3/latest/pyo3/prelude/index

Documents the attribute and derive macros available in PyO3 prelude for exposing Rust code to Python. Includes pyclass, pyfunction, pymethods, and pymodule for defining Python classes, functions, methods, and modules in Rust, plus conversion macros for type transformations.

```rust
#[pyclass]
#[pyfunction]
#[pymethods]
#[pymodule]
wrap_pyfunction
#[derive(FromPyObject)]
#[derive(IntoPyObject)]
#[derive(IntoPyObjectRef)]
```

--------------------------------

### Get Python Type String (pyo3 - Experimental)

Source: https://docs.rs/pyo3/latest/pyo3/exceptions/socket/struct.gaierror

Demonstrates how to get the full Python type path string for a Rust type using pyo3, provided the 'experimental-inspect' feature is enabled. This is useful for introspection and defining expected types.

```rust
const PYTHON_TYPE: &'static str = "typing.Any"

```

--------------------------------

### PyMemberDef Struct

Source: https://docs.rs/pyo3/latest/pyo3/ffi/structmember/struct.PyMemberDef

Details about the PyMemberDef struct, its C-representation, and initialization notes.

```APIDOC
## PyMemberDef

### Description
Represents the PyMemberDef structure used in pyo3 for defining Python object members.

**Note**: CPython may leave fields uninitialized. You must always ensure that `name` != NULL before dereferencing or reading other fields.

### Struct Definition
```rust
#[repr(C)]
pub struct PyMemberDef {
    pub name: *const i8,
    pub type_code: i32,
    pub offset: isize,
    pub flags: i32,
    pub doc: *const i8,
}
```

### Fields
*   **`name`**: `*const i8` - The name of the member.
*   **`type_code`**: `i32` - The type code of the member.
*   **`offset`**: `isize` - The offset of the member within the structure.
*   **`flags`**: `i32` - Flags associated with the member.
*   **`doc`**: `*const i8` - Documentation string for the member.
```

--------------------------------

### Rust Method Implementation: Get PyFloat Value

Source: https://docs.rs/pyo3/latest/pyo3/prelude/trait.PyFloatMethods

Shows the implementation of the `PyFloatMethods` trait for the `Bound<'py, PyFloat>` type. This implementation allows calling the `value` method directly on a pyo3-bound Python float object to get its primitive `c_double` representation.

```rust
impl<'py> PyFloatMethods<'py> for Bound<'py, PyFloat> {
    // Method implementation would be here, calling the trait's required fn value(&self) -> c_double;
}
```
Tokens:
Raw