1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101

// Copyright (c) 2015-2019 Georg Brandl.  Licensed under the Apache License,
// Version 2.0 <LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0>
// or the MIT license <LICENSE-MIT or http://opensource.org/licenses/MIT>, at
// your option. This file may not be copied, modified, or distributed except
// according to those terms.

//! Serialization and deserialization for Python's pickle format
//!
//! # Pickle format
//!
//! Please see the [Python docs](http://docs.python.org/library/pickle) for
//! details on the Pickle format.
//!
//! This crate supports all Pickle protocols (0 to 4) when reading, and writing
//! protocol 2 (compatible with Python 2 and 3), or protocol 3 (compatible with
//! Python 3 only).
//!
//! # Supported types
//!
//! Pickle is very powerful.  It is capable of serializing pretty arbitrary
//! graphs of Python objects, with most custom classes being serialized out
//! of the box.  Currently, this crate only supports Python's built-in types
//! that map easily to Rust constructs.  There are:
//!
//! * None
//! * Boolean (Rust `bool`)
//! * Integers (Rust `i64` or bigints from num)
//! * Floats (Rust `f64`)
//! * Strings (Rust `Vec<u8>`)
//! * Unicode strings (Rust `String`)
//! * Lists and tuples (Rust `Vec<Value>`)
//! * Sets and frozensets (Rust `HashSet<Value>`)
//! * Dictionaries (Rust `HashMap<Value, Value>`)
//!
//! When deserializing, arbitrary Python objects saved using a pickled instance
//! dictionary or `__setstate__` are replaced by that state, since version
//! 0.5 of this library.
//!
//! *Note:* since Serde 1.0, fixed-size Rust arrays (which have type `[T; n]` or
//! `&[T; n]`) are treated as tuples when serializing.  In particular, this
//! means that bytes literals will also be serialized as a tuple of integers
//! unless you convert them into an unsized slice first (e.g. `&b"bytes"[..]`).
//!
//! # Exported API
//!
//! The library exports generic serde (de)serializing functions `to_*` and
//! `from_*`.  It also exports functions that produce or take only the specific
//! `Value` struct exposed by this library, which supports all built-in Python
//! types (notably, long integers and sets, which serde's generic types don't
//! handle).  These functions, called `value_from_*` and `value_to_*`, will
//! correctly (un)pickle these types.

#![cfg_attr(test, feature(test))]

#[macro_use]
extern crate serde;
extern crate num_bigint;
extern crate num_traits;
extern crate byteorder;
extern crate iter_read;
#[cfg(test)]
#[macro_use]
extern crate serde_derive;

pub use self::ser::{
    Serializer,
    to_writer,
    to_vec,
    value_to_writer,
    value_to_vec,
};

pub use self::de::{
    Deserializer,
    from_reader,
    from_slice,
    from_iter,
    value_from_reader,
    value_from_slice,
    value_from_iter,
};

pub use self::value::{
    Value,
    HashableValue,
    to_value,
    from_value,
};

pub use self::error::{Error, ErrorCode, Result};

pub mod ser;
pub mod de;
pub mod error;
pub mod value;
mod consts;
mod value_impls;

#[cfg(test)]
#[path = "../test/mod.rs"]
mod test;