https://github.com/Jij-Inc/serde-pyobject

PyO3's PyAny as a serde data format
https://github.com/Jij-Inc/serde-pyobject

pyo3 rust serde

Last synced: 4 months ago
JSON representation

PyO3's PyAny as a serde data format

• Host: GitHub
• URL: https://github.com/Jij-Inc/serde-pyobject
• Owner: Jij-Inc
• License: apache-2.0
• Created: 2023-10-24T08:29:48.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-04-15T07:38:59.000Z (10 months ago)
• Last Synced: 2024-05-02T00:36:27.457Z (10 months ago)
• Topics: pyo3, rust, serde
• Language: Rust
• Homepage:
• Size: 95.7 KB
• Stars: 13
• Watchers: 6
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE-APACHE

Awesome Lists containing this project

README

        
# serde-pyobject

[![crate](https://img.shields.io/crates/v/serde-pyobject.svg)](https://crates.io/crates/serde-pyobject) 

[![docs.rs](https://docs.rs/serde-pyobject/badge.svg)](https://docs.rs/serde-pyobject)

PyO3's PyAny as a serde data format

## Usage

### Serialize `T: Serialize` into `&'py PyAny`:

```rust

use serde::Serialize;

use pyo3::{Python, Bound, types::{PyAny, PyAnyMethods, PyDict}};

use serde_pyobject::{to_pyobject, pydict};

#[derive(Serialize)]

struct A {

    a: u32,

    b: String,

}

Python::with_gil(|py| {

    let a = A { a: 1, b: "test".to_string() };

    let obj: Bound = to_pyobject(py, &a).unwrap();

    assert!(obj.eq(pydict! { py, "a" => 1, "b" => "test" }.unwrap()).unwrap());

});

```

### Deserialize `&'py PyAny` into `T: Deserialize<'de>`:

```rust

use serde::Deserialize;

use pyo3::{Python, Bound, types::{PyAny, PyAnyMethods, PyDict}};

use serde_pyobject::{from_pyobject, pydict};

#[derive(Debug, PartialEq, Deserialize)]

struct A {

    a: u32,

    b: String,

}

Python::with_gil(|py| {

    let a: Bound = pydict! { py,

      "a" => 1,

      "b" => "test"

    }

    .unwrap();

    let a: A = from_pyobject(a).unwrap();

    assert_eq!(a, A { a: 1, b: "test".to_string() });

});

```

## Mapping between Python and [serde data model]

[serde data model]: https://serde.rs/data-model.html

| [serde data model] | PyO3 type | Rust | Python |

|------------------|-----------|------------|---------------|

| `i8`, `i16`, `i32`, `i64`, `isize`, 
 `u8`, `u16`, `u32`, `u64`, `usize` | `PyLong` | `123` | `123` |

| `f32`, `f64` | `PyFloat` | `1.0` | `1.0` |

| `bool` | `PyBool` | `true` | `true` |

| `char`, `string` | `PyString` | `'a'`, `"test"` | `"a"`, `"test"` |

| option | `PyAny` [^1] | `None`, `Some(1)` | `None`, `1` |

| unit | `PyTuple` | `()` | `()` |

| unit struct | `PyTuple` | `struct Unit` | `()` |

| unit variant | `PyDict` | `E::A` in `enum E { A, B }` | `"A"` |

| newtype struct | `PyDict` | `A(32)` of `struct A(u8)` | `32` |

| newtype variant | `PyDict` | `E::N(41)` of `enum E { N(u8) }` | `{ "N": 41 }` | 

| seq | `PyList` | `vec![1, 2, 3]` | `[1, 2, 3]` |

| tuple | `PyTuple` | `(1, "test")` | `(1, "test")` |

| tuple struct | `PyDict` | `T(1, "a")` of `struct T(u32, String)` | `(1, "a")` |

| tuple variant | `PyDict` | `E::S(1, 2)` of `enum E { S(u8, u8) }` | `{ "S": (1, 2) }` |

| map | `PyDict` | `hashmap!{ "a".to_string() => 1, "b".to_string() => 2 }` | `{ "a": 1, "b": 2 }` |

| struct | `PyDict` | `A { a: 1, b: "test" }` of `struct A { a: u32, b: String }` | `{ "a": 1, "b": "test"}` |

| struct variant | `PyDict` | `E::S { r: 1, g: 2, b: 3 }` of `enum E { S { r: u8, g: u8, b: u8 } }` | `{ "S": { "r": 1, "g": 2, "b": 3 } }` |

[^1]: `Some(value)` is serialized as `value`

## License

© 2023 Jij Inc.

This project is licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or )

- MIT license ([LICENSE-MIT](LICENSE-MIT) or )

at your option.