36 releases (16 breaking)

0.16.0 Nov 18, 2020
0.15.2 Oct 23, 2020
0.8.0 Jul 28, 2020

#29 in Encoding

Download history 2875/week @ 2020-08-10 3134/week @ 2020-08-17 2473/week @ 2020-08-24 2845/week @ 2020-08-31 2865/week @ 2020-09-07 3911/week @ 2020-09-14 4317/week @ 2020-09-21 4992/week @ 2020-09-28 4893/week @ 2020-10-05 2749/week @ 2020-10-12 2010/week @ 2020-10-19 2448/week @ 2020-10-26 2134/week @ 2020-11-02 3239/week @ 2020-11-09 2300/week @ 2020-11-16 745/week @ 2020-11-23

13,654 downloads per month
Used in tfschema-bindgen

MIT/Apache

440KB
11K SLoC

Rust 7.5K SLoC // 0.0% comments Go 1K SLoC // 0.0% comments Python 1K SLoC // 0.0% comments Java 890 SLoC // 0.1% comments TypeScript 383 SLoC // 0.0% comments

serde-generate

serde-generate on crates.io Documentation (latest release) Documentation (master) License License

This crate aims to compile the data formats extracted from Rust by serde_reflection into type definitions for other programming languages.

Supported Languages

The following target languages are currently supported:

  • C++ 17
  • Java 8
  • Python 3
  • Rust 2018
  • Go >= 1.13

Work in progress

  • TypeScript > 3.2 (make sure to enable esnext.BigInt and dom at tsconfig.json -> lib)

Supported Encodings

Type definitions in a target language are meant to be used together with a runtime library that provides (de)serialization in a particular Serde encoding format.

This crate provides easy-to-deploy runtime libraries for the following binary formats, in all supported languages:

Quick Start with Python and Bincode

In the following example, we transfer a Test value from Rust to Python using bincode.

use serde::{Deserialize, Serialize};
use serde_reflection::{Registry, Samples, Tracer, TracerConfig};
use std::io::Write;

#[derive(Serialize, Deserialize)]
struct Test {
    a: Vec<u64>,
    b: (u32, u32),
}

// Obtain the Serde format of `Test`. (In practice, formats are more often read from a file.)
let mut tracer = Tracer::new(TracerConfig::default());
tracer.trace_type::<Test>(&Samples::new()).unwrap();
let registry = tracer.registry().unwrap();

// Create Python class definitions.
let mut source = Vec::new();
let config = serde_generate::CodeGeneratorConfig::new("testing".to_string())
    .with_encodings(vec![serde_generate::Encoding::Bincode]);
let generator = serde_generate::python3::CodeGenerator::new(&config);
generator.output(&mut source, &registry)?;

assert!(
    String::from_utf8_lossy(&source).contains(
    r#"
@dataclass(frozen=True)
class Test:
    a: typing.Sequence[st.uint64]
    b: typing.Tuple[st.uint32, st.uint32]
"#));

// Append some test code to demonstrate Bincode deserialization
// using the runtime in `serde_generate/runtime/python/bincode`.
writeln!(
    source,
    r#"
value = Test.bincode_deserialize(bytes({:?}))
assert value == Test(a=[4, 6], b=(3, 5))
"#,
    bincode::serialize(&Test { a: vec![4, 6], b: (3, 5) }).unwrap(),
)?;

// Execute the Python code.
let mut child = std::process::Command::new("python3")
    .arg("-")
    .env("PYTHONPATH", std::env::var("PYTHONPATH").unwrap_or_default() + ":runtime/python")
    .stdin(std::process::Stdio::piped())
    .spawn()?;
child.stdin.as_mut().unwrap().write_all(&source)?;
let output = child.wait_with_output()?;
assert!(output.status.success());

Binary Tool

In addition to a Rust library, this crate provides a binary tool serdegen to process Serde formats saved on disk.

Assuming that a serde_reflection::Registry object has been serialized in a YAML file test.yaml, the following command will generate Python class definitions and write them into test.py:

cargo run -p serde-generate -- --language python3 test.yaml > test.py

To create a python module test and install the bincode runtime in a directory $DEST, you may run:

cargo run -p serde-generate -- --language python3 --with-runtimes serde bincode --module-name test --target-source-dir "$DEST" test.yaml

See the help message of the tool with --help for more options.

Note: Outside of this repository, you may install the tool with cargo install serde-generate then use $HOME/.cargo/bin/serdegen.

Contributing

See the CONTRIBUTING file for how to help out.

License

This project is available under the terms of either the Apache 2.0 license or the MIT license.

Dependencies

~2.4–3.5MB
~61K SLoC