PyO3

https://pyo3.rs/main/
Admin
PyO3 provides Rust bindings for Python, enabling the creation of native Python extension modules and...
Tokens:1,475,461
Snippets:10,725
Trust Score:9.5
Update:5 days ago
Show doc for...
Tokens:
Raw
### Build user guide with nox

Source: https://pyo3.rs/main/contributing

Builds the PyO3 user guide locally using mdbook. Requires installing mdbook, the mdbook-tabs plugin, and nox. The '--open' flag opens the guide in a browser.

```bash
nox -s build-guide -- --open
```

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

### Setup virtualenv and install maturin

Source: https://pyo3.rs/main/doc/pyo3/index.html

Commands to create a virtual environment and install maturin for building the extension module. Run from the project directory.

```bash
$ cd string_sum
$ python -m venv .env
$ source .env/bin/activate
$ pip install maturin
```

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

### Single copy-and-paste setup script

Source: https://pyo3.rs/main/index.html

Bash script to create, build, and install a PyO3 package in one go. Replace 'string_sum' with the desired package name.

```bash
mkdir string_sum && cd "$_"
python -m venv .env
source .env/bin/activate
pip install maturin
maturin init --bindings pyo3
maturin develop
```

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

### Check guide links with nox

Source: https://pyo3.rs/main/contributing

Checks all links in the user guide are valid. Requires installing lychee in addition to the other dependencies.

```bash
nox -s check-guide
```

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

### expect example: recommended message style

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Shows the recommended style for expect messages: describe the reason you expect the Option to be Some. The example uses a slice get with an expect message.

```rust
let item = slice.get(0)
    .expect("slice should not be empty");
```

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

### Python::initialize example

Source: https://pyo3.rs/main/doc/pyo3/marker/struct.Python.html

Example of initializing the Python interpreter and running a Python script using Python::attach.

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

Python::initialize();
Python::attach(|py| py.run(c"print('Hello World')", None, None))
```

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

### Get Python version string with version_str

Source: https://pyo3.rs/main/doc/pyo3/marker/struct.Python.html

Gets the running Python interpreter version as a string. The example asserts that the version starts with "3.".

```rust
assert!(Python::version_str().starts_with("3."));
```

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

### iter example: iterating over slice elements

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedBytes.html

Shows how to use iter to get an iterator over the slice's elements, yielding items from start to end.

```rust
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);
```

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

### Example my_project.pyi stub file

Source: https://pyo3.rs/main/python-typing-hints

Example stub file for a module. Shows class and method signatures with docstrings.

```python
class Car:
    """
    A class representing a car.

    :param body_type: the name of body type, e.g. hatchback, sedan
    :param horsepower: power of the engine in horsepower
    """

    def __init__(self, body_type: str, horsepower: int) -> None: ...

    @classmethod
    def from_unique_name(cls, name: str) -> "Car":
        """
        Creates a Car based on unique name

        :param name: model name of a car to be created
        :return: a Car instance with default data
        """

    def best_color(self) -> str:
        """
        Gets the best color for the car.

        :return: the name of the color our great algorithm thinks is the best for this car
        """
```

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

### PyErr::traceback example

Source: https://pyo3.rs/main/doc/pyo3/prelude/struct.PyErr.html

Example of getting the traceback of a PyErr.

```rust
use pyo3::{exceptions::PyTypeError, Python};

Python::attach(|py| {
    let err = PyTypeError::new_err(("some type error",));
    assert!(err.traceback(py).is_none());
});
```

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

### Python::initialize example

Source: https://pyo3.rs/main/doc/pyo3/marker/struct.python

Shows how to initialize the Python interpreter with Python::initialize and then attach to it to run a Python print statement. The example prints 'Hello World'.

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

Python::initialize();
Python::attach(|py| py.run(c"print('Hello World')", None, None))

```

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

### PyErr::value example

Source: https://pyo3.rs/main/doc/pyo3/prelude/struct.PyErr.html

Example of getting the value of a PyErr.

```rust
use pyo3::{exceptions::PyTypeError, PyErr, Python};

Python::attach(|py| {
    let err: PyErr = PyTypeError::new_err(("some type error",));
    assert!(err.is_instance_of::<PyTypeError>(py));
    assert_eq!(err.value(py).to_string(), "some type error");
});
```

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

### Create and use PythonVersionInfo

Source: https://pyo3.rs/main/doc/pyo3/struct.PythonVersionInfo.html

Example showing how to create a PythonVersionInfo instance and access its version fields.

```rust
Python::attach(|py| {
    let version_info = py.version_info();
    assert_eq!(version_info.major, 3);
    assert_eq!(version_info.minor, 9);
    assert_eq!(version_info.patch, 0);
});
```

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

### PyErr::get_type example

Source: https://pyo3.rs/main/doc/pyo3/prelude/struct.PyErr.html

Example of getting the type of a PyErr.

```rust
use pyo3::{prelude::*, exceptions::PyTypeError, types::PyType};

Python::attach(|py| {
    let err: PyErr = PyTypeError::new_err(("some type error",));
    assert!(err.get_type(py).is(&PyType::new::<PyTypeError>(py)));
});
```

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

### get() example

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedBytes.html

Returns a reference to an element or subslice depending on the index type. The example shows getting an element by position, a subslice by range, and out-of-bounds cases returning None.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

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

### to_lowercase method examples

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedStr.html

Shows basic usage, tricky sigma examples, and languages without case.

```rust
let s = "HELLO WORLD";

assert_eq!("hello world", s.to_lowercase());
```

```rust
let sigma = "Σ";

assert_eq!("σ", sigma.to_lowercase());

// but at the end of a word, it's ς, not σ:
let odysseus = "ὈΔΥΣΣΕΎΣ";

assert_eq!("ὀδυσσεύς", odysseus.to_lowercase());

let odysseus_king_of_ithaca = "Ο ΟΔΥΣΣΈΑΣ ΒΑΣΙΛΙΆΣ ΤΗΣ ΙΘΆΚΗΣ";

assert_eq!("ο οδυσσέας βασιλιάς της ιθάκης", odysseus_king_of_ithaca.to_lowercase());
```

```rust
let new_year = "农历新年";

assert_eq!(new_year, new_year.to_lowercase());
```

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

### match_indices examples: matches with start indices

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.pybackedstr

Examples for the match_indices method, returning an iterator over disjoint matches along with the starting index. Overlapping matches are not included; only the first match is returned.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
```

```rust
let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, [(1, "abc"), (4, "abc")]);
```

```rust
let v: Vec<_> = "ababa".match_indices("aba").collect();
assert_eq!(v, [(0, "aba")]); // only the first `aba`
```

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

### Example for Option::as_ref

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Shows how to use `as_ref` to convert `Option<String>` to `Option<&String>` and then use `map` without consuming the original.

```rust
let text: Option<String> = Some("Hello, world!".to_string());
// First, cast `Option<String>` to `Option<&String>` with `as_ref`,
// then consume *that* with `map`, leaving `text` on the stack.
let text_length: Option<usize> = text.as_ref().map(|s| s.len());
println!("still can print text: {text:?}");
```

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

### Create new project with maturin new

Source: https://pyo3.rs/main/getting-started.html

Creates a new PyO3 project named 'pyo3-example' using maturin's new command, then sets up the virtual environment with pyenv.

```bash
maturin new -b pyo3 pyo3-example
cd pyo3-example
pyenv virtualenv pyo3
pyenv local pyo3
```

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

### Python usage example

Source: https://pyo3.rs/main/doc/pyo3/num_rational

Python code demonstrating how to use the add_five_to_fraction function.

```python
from my_module import add_five_to_fraction
from fractions import Fraction

fraction = Fraction(2, 1)
fraction_plus_five = add_five_to_fraction(fraction)
assert fraction + 5 == fraction_plus_five
```

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

### PyByteArrayMethods::data

Source: https://pyo3.rs/main/doc/pyo3/prelude/struct.Bound.html

Gets the start of the buffer containing the contents of the bytearray.

```APIDOC
## PyByteArrayMethods::data

### Description
Gets the start of the buffer containing the contents of the bytearray.

### Method
data

### Signature
fn data(&self) -> *mut u8

### Returns
- **\*mut u8** - Pointer to the start of the buffer.
```

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

### word_to_titlecase method examples

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedStr.html

Shows basic usage, first cased letter, languages without case, Georgian uppercase, no word segmentation, and tricky sigma examples.

```rust
#![feature(titlecase)]
let s = "HELLO WORLD";

assert_eq!("Hello world", s.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let the_night_before_christmas = "'twas";

assert_eq!("'Twas", the_night_before_christmas.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let new_year = "农历新年";

assert_eq!(new_year, new_year.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let georgian = "ერთობაშია";

assert_eq!(georgian, georgian.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let blazingly_fast = "ferris and I";

assert_eq!("Ferris and i", blazingly_fast.word_to_titlecase());
```

```rust
#![feature(titlecase)]
let odysseus = "ὈΔΥΣΣΕΎΣ";

assert_eq!("Ὀδυσσεύς", odysseus.word_to_titlecase());

let odysseus_king_of_ithaca = "Ο ΟΔΥΣΣΈΑΣ ΒΑΣΙΛΙΆΣ ΤΗΣ ΙΘΆΚΗΣ";
```

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

### Get Python version info with version_info

Source: https://pyo3.rs/main/doc/pyo3/marker/struct.Python.html

Gets the running Python interpreter version as a struct similar to sys.version_info. The example asserts that the version is at least 3.9.

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

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

### Creating a PyTuple with PyTuple::new and into_pyobject

Source: https://pyo3.rs/main/doc/pyo3/types/struct.PyTuple.html

Example showing how to create a PyTuple from a Vec<i32> using PyTuple::new, and an alternative using into_pyobject() on a Rust tuple. The output is formatted as a debug string.

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

Python::attach(|py| {
    let elements: Vec<i32> = vec![0, 1, 2, 3, 4, 5];
    let tuple = PyTuple::new(py, elements)?;
    assert_eq!(format!("{:?}", tuple), "(0, 1, 2, 3, 4, 5)");

    // alternative using `into_pyobject()`
    let tuple = (0, "hello", true).into_pyobject(py)?;
    assert_eq!(format!("{:?}", tuple), "(0, 'hello', True)");
})
```

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

### ok example

Source: https://pyo3.rs/main/doc/pyo3/prelude/type.PyResult.html

Demonstrates converting a Result to an Option, returning Some(value) for Ok and None for Err.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

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

### Example for str::as_ptr method

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedStr.html

Gets a raw pointer to the first byte of the string slice.

```rust
let s = "Hello";
let ptr = s.as_ptr();
```

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

### fn data(&self) -> *mut u8

Source: https://pyo3.rs/main/doc/pyo3/prelude/trait.PyByteArrayMethods.html

Gets the start of the buffer containing the contents of the bytearray.

```APIDOC
## fn data(&self) -> *mut u8

### Description
Gets the start of the buffer containing the contents of the bytearray.

### Method
data

### Signature
`fn data(&self) -> *mut u8`

### Parameters
None

### Returns
- **\*mut u8** - Pointer to the start of the buffer.

### Safety
See the safety requirements of `PyByteArrayMethods::as_bytes` and `PyByteArrayMethods::as_bytes_mut`.
```

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

### Option::from example

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Shows how to create an Option from a value using From. The example converts 67 into Some(67) and asserts equality.

```rust
let o: Option<u8> = Option::from(67);

assert_eq!(Some(67), o);
```

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

### buf_ptr

Source: https://pyo3.rs/main/doc/pyo3/buffer/struct.pybuffer

Gets the pointer to the start of the buffer memory. Warning: the buffer memory can be mutated by other code.

```APIDOC
## buf_ptr

### Description
Gets the pointer to the start of the buffer memory.

### Method
buf_ptr

### Signature
pub fn buf_ptr(&self) -> *mut c_void

### Returns
- **\*mut c_void** - Pointer to the start of the buffer memory.

### Warning
The buffer memory can be mutated by other code (including other Python functions, if the GIL is released, or other extension modules even if the GIL is held). You must either access memory atomically, or ensure there are no data races yourself.
```

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

### Option::take example

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Shows how to take the value out of an Option, leaving None in its place.

```rust
let mut x = Some(2);
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, Some(2));

let mut x: Option<u32> = None;
let y = x.take();
assert_eq!(x, None);
assert_eq!(y, None);
```

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

### as_simd example

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedBytes.html

Demonstrates using as_simd to split a slice into prefix, middle SIMD type, and suffix. Requires nightly-only portable_simd feature. Shows that the middle is empty when not enough elements, and includes a basic SIMD sum function.

```rust
#![feature(portable_simd)]
use core::simd::prelude::*;

let short = &[1, 2, 3];
let (prefix, middle, suffix) = short.as_simd::<4>();
assert_eq!(middle, []); // Not enough elements for anything in the middle

// They might be split in any possible way between prefix and suffix
let it = prefix.iter().chain(suffix).copied();
assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);

fn basic_simd_sum(x: &[f32]) -> f32 {
    use std::ops::Add;
    let (prefix, middle, suffix) = x.as_simd();
    let sums = f32x4::from_array([
        prefix.iter().copied().sum(),
        0.0,
        0.0,
        suffix.iter().copied().sum(),
    ]);
    let sums = middle.iter().copied().fold(sums, f32x4::add);
    sums.reduce_sum()
}

let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);
```

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

### Using get() with frozen class

Source: https://pyo3.rs/main/doc/pyo3/prelude/struct.Py.html

Example of using the get() method on a frozen #[pyclass] struct to immutably borrow the value without attaching to the Python interpreter. The class must be frozen and Sync.

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

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

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

    Py::new(py, counter).unwrap()
});

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

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

### PyBytes::new_with_writer example

Source: https://pyo3.rs/main/doc/pyo3/types/bytes/struct.pybytes

Creates a new Python bytes object using a writer closure. The buffer starts with at least reserved_capacity bytes and grows dynamically as needed. If reserved_capacity is 0, it starts empty.

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

Python::attach(|py| -> PyResult<()> {
    let py_bytes = PyBytes::new_with_writer(py, 0, |writer| {
        writer.write_bytes(b"hello world")?;
        Ok(())
    })?;
    assert_eq!(py_bytes.as_bytes(), b"hello world");
    Ok(())
})
```

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

### compare method example with Ordering::Less

Source: https://pyo3.rs/main/doc/pyo3/prelude/trait.PyAnyMethods.html

Example showing compare returning Ordering::Less for comparable values.

```rust
use pyo3::prelude::*;
use pyo3::types::PyFloat;
use core::cmp::Ordering;

Python::attach(|py| -> PyResult<()> {
    let a = PyFloat::new(py, 0_f64);
    let b = PyFloat::new(py, 42_f64);
    assert_eq!(a.compare(b)?, Ordering::Less);
    Ok(())
})?;
```

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

### expect example (recommended message style)

Source: https://pyo3.rs/main/doc/pyo3/prelude/type.PyResult.html

Recommended expect message style: describe the reason you expect the Result to be Ok. The example uses an environment variable.

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

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

### substr_range example

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedStr.html

Demonstrates using substr_range to get the range of a substring within a string, useful with split.

```rust
use core::range::Range;

let data = "a, b, b, a";
let mut iter = data.split(", ").map(|s| data.substr_range(s).unwrap());

assert_eq!(iter.next(), Some(Range { start: 0, end: 1 }));
assert_eq!(iter.next(), Some(Range { start: 3, end: 4 }));
assert_eq!(iter.next(), Some(Range { start: 6, end: 7 }));
assert_eq!(iter.next(), Some(Range { start: 9, end: 10 }));
```

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

### PyInitConfig_Create

Source: https://pyo3.rs/main/doc/pyo3/ffi/index.html

Creates a new initialization configuration.

```APIDOC
## PyInitConfig_Create

### Description
Creates a new initialization configuration.

### Signature
`PyInitConfig_Create() -> *mut PyInitConfig`

### Returns
- `*mut PyInitConfig` - A new initialization configuration, or NULL on failure.

### Safety
This function is marked with a warning symbol (⚠) indicating it is unsafe and requires careful handling.
```

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

### Option::get_or_insert example

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Shows how to get a mutable reference to the contained value, inserting a default if None.

```rust
let mut x = None;

{
    let y: &mut u32 = x.get_or_insert(5);
    assert_eq!(y, &5);

    *y = 7;
}

assert_eq!(x, Some(7));
```

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

### Option::zip example

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Shows how to combine two Option values into a tuple using zip. The example asserts that zipping Some(1) with Some("hi") yields Some((1, "hi")), and zipping with None yields None.

```rust
assert_eq!(x.zip(y), Some((1, "hi")));
assert_eq!(x.zip(z), None);
```

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

### Option::iter example

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Shows how to use Option::iter to get an iterator over the possibly contained value.

```rust
let x = Some(4);
assert_eq!(x.iter().next(), Some(&4));
```

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

### Py_InitializeEx

Source: https://pyo3.rs/main/doc/pyo3/ffi/index.html

Initializes the Python interpreter with options.

```APIDOC
## Py_InitializeEx

### Description
Initializes the Python interpreter with options.

### Function
Py_InitializeEx

### Parameters
- **initsigs** (int) - Required - Whether to initialize signal handlers.

### Returns
- **void** - None.

### Safety
This function is unsafe and must be called with valid pointers and proper GIL handling.
```

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

### Example for Option::as_mut

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Demonstrates using `as_mut` to get a mutable reference to the contained value and modify it.

```rust
let mut x = Some(2);
match x.as_mut() {
    Some(v) => *v = 42,
    None => {},
}
assert_eq!(x, Some(42));
```

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

### Example: nested #[pyclass] initialization with add_subclass

Source: https://pyo3.rs/main/doc/pyo3/pyclass_init/struct.PyClassInitializer.html

Shows how to use PyClassInitializer::from and add_subclass to initialize a chain of subclasses. The example defines BaseClass, SubClass, and SubSubClass, and uses a #[new] method to return a PyClassInitializer<Self>. It then attaches to Python and verifies the attributes.

```rust
#[pyclass(subclass)]
struct BaseClass {
    #[pyo3(get)]
    basename: &'static str,
}
#[pyclass(extends=BaseClass, subclass)]
struct SubClass {
    #[pyo3(get)]
    subname: &'static str,
}
#[pyclass(extends=SubClass)]
struct SubSubClass {
    #[pyo3(get)]
    subsubname: &'static str,
}

#[pymethods]
impl SubSubClass {
    #[new]
    fn new() -> PyClassInitializer<Self> {
        PyClassInitializer::from(BaseClass { basename: "base" })
            .add_subclass(SubClass { subname: "sub" })
            .add_subclass(SubSubClass {
                subsubname: "subsub",
            })
    }
}
Python::attach(|py| {
    let typeobj = py.get_type::<SubSubClass>();
    let sub_sub_class = typeobj.call((), None).unwrap();
    py_run!(
        py,
        sub_sub_class,
        r#"
 assert sub_sub_class.basename == 'base'
 assert sub_sub_class.subname == 'sub'
 assert sub_sub_class.subsubname == 'subsub'"#
    );
});
```

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

### match_indices with string pattern

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedStr.html

Example for the match_indices method using a string pattern to find matches and their starting indices.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
```

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

### Build docs with nox

Source: https://pyo3.rs/main/contributing

Builds the PyO3 documentation (including all features) using nox. Requires installing nox first. The 'open' argument opens the built docs in a browser.

```bash
nox -s docs -- open
```

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

### starts_with() with &str Example

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedStr.html

Shows checking if a string starts with a prefix. Returns true if the pattern matches a prefix.

```rust
let bananas = "bananas";

assert!(bananas.starts_with("bana"));
assert!(!bananas.starts_with("nana"));
```

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

### starts_with example

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedBytes.html

Checks if the slice starts with the given needle. Returns true if needle is a prefix or equal to the slice.

```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

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

### Option::zip example

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Demonstrates combining two Options into a tuple if both are Some, otherwise None.

```rust
let x = Some(1);
let y = Some("hi");
let z = None::<u8>;
```

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

### Example: using PySuper to call base class method

Source: https://pyo3.rs/main/doc/pyo3/types/struct.PySuper.html

Shows how to construct a super object and call a method on the base class from a subclass method.

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

#[pyclass(subclass)]
struct BaseClass {
    val1: usize,
}

#[pymethods]
impl BaseClass {
    #[new]
    fn new() -> Self {
        BaseClass { val1: 10 }
    }

    pub fn method(&self) -> usize {
        self.val1
    }
}

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

#[pymethods]
impl SubClass {
    #[new]
    fn new() -> PyClassInitializer<Self> {
        PyClassInitializer::from(BaseClass::new()).add_subclass(SubClass {})
    }

    fn method<'py>(self_: &Bound<'py, Self>) -> PyResult<Bound<'py, PyAny>> {
        let super_ = self_.py_super()?;
        super_.call_method("method", (), None)
    }
}
```

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

### rsplit basic example

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedBytes.html

Iterates over subslices separated by the predicate, starting from the end of the slice. The matched element is not included.

```rust
let slice = [11, 22, 33, 0, 44, 55];
let mut iter = slice.rsplit(|num| *num == 0);

assert_eq!(iter.next().unwrap(), &[44, 55]);
assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
assert_eq!(iter.next(), None);
```

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

### as_rchunks example

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedBytes.html

Splits the slice into N-element arrays starting from the end, with a remainder at the beginning. Panics if N is zero.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let (remainder, chunks) = slice.as_rchunks();
assert_eq!(remainder, &['l']);
assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);
```

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

### replace method examples

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedStr.html

Shows basic usage of replace, including when the pattern doesn't match.

```rust
assert_eq!("this is new", s.replace("old", "new"));
assert_eq!("than an old", s.replace("is", "an"));
```

```rust
let s = "this is old";
assert_eq!(s, s.replace("cookie monster", "little lamb"));
```

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

### Example: using watch_callback! with PyContext::add_watcher

Source: https://pyo3.rs/main/doc/pyo3/macro.watch_callback.html

A complete example showing a safe Rust function with the required signature and how to register it as a context watcher using `watch_callback!` and `PyContext::add_watcher`. The function must be a path because CPython's context watcher callback has no user-data pointer.

```rust
use pyo3::prelude::*;
use pyo3::types::context::{watch_callback, ContextEvent};
use pyo3::types::PyContext;

fn context_changed(
    _py: Python<'_>,
    _event: ContextEvent<'_, '_>,
) -> PyResult<()> {
    Ok(())
}

Python::attach(|py| {
    let _watcher = PyContext::add_watcher(py, watch_callback!(context_changed))?;
    Ok(())
})
```

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

### Example for str::get method

Source: https://pyo3.rs/main/doc/pyo3/pybacked/struct.PyBackedStr.html

Shows how to safely get a subslice of a string, returning None for invalid indices.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

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

### Example: add_subclass with base class initializer

Source: https://pyo3.rs/main/doc/pyo3/pyclass_init/struct.PyClassInitializer.html

Shows how to use PyClassInitializer::from and add_subclass to initialize a subclass that extends a base class. The example defines BaseClass and SubClass, and uses a #[new] method to return a PyClassInitializer<Self>. It then attaches to Python, creates a module, and verifies that the instance has the 'value' attribute from the base class.

```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(())
    })
}
```

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

### Example for Option::as_slice

Source: https://pyo3.rs/main/doc/pyo3/ffi/type.wrapperfunc.html

Shows how to use `as_slice` to get a slice of the contained value, or an empty slice if `None`.

```rust
assert_eq!(
    [Some(1234).as_slice(), None.as_slice()],
    [&[1234][..], &[][..]],
);
```

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

### get_ptr

Source: https://pyo3.rs/main/doc/pyo3/buffer/struct.pyuntypedbuffer

Gets a pointer to the specified item. If indices.len() < self.dimensions(), returns the start address of the sub-array at the specified dimension.

```APIDOC
## get_ptr

### Description
Gets a pointer to the specified item. If `indices.len() < self.dimensions()`, returns the start address of the sub-array at the specified dimension.

### Method
`pub fn get_ptr(&self, indices: &[usize]) -> *mut c_void`

### Parameters
- **indices** (`&[usize]`) - The indices of the item to get a pointer to.

### Returns
- `*mut c_void` - Pointer to the specified item or sub-array.
```
Tokens:
Raw