implement Decimal to rust_decimal conversions

Implement conversion between rust_decimal::Decimal and decimal.Decimal
from Python's stdlib. The C API does not appear to be exposed on the
Python side so we need to call into it via Python.

TODO: documentation
TODO: examples

Cargo.toml

@@ -38,6 +38,7 @@ hashbrown = { version = ">= 0.9, < 0.14", optional = true }
 indexmap = { version = "1.6", optional = true }
 num-bigint = { version = "0.4", optional = true }
 num-complex = { version = ">= 0.2, < 0.5", optional = true }
+rust_decimal = { version = "1.21.0", default-features = false, optional = true }
 serde = { version = "1.0", optional = true }
 
 [dev-dependencies]
@@ -53,6 +54,7 @@ send_wrapper = "0.6"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0.61"
 rayon = "1.0.2"
+rust_decimal = { version = "1.21.0", features = ["rust-fuzz", "std"] }
 widestring = "0.5.1"
 
 [build-dependencies]
@@ -110,6 +112,7 @@ full = [
     "eyre",
     "anyhow",
     "experimental-inspect",
+    "rust_decimal",
 ]
 
 [[bench]]
@@ -120,6 +123,11 @@ harness = false
 name = "bench_err"
 harness = false
 
+[[bench]]
+name = "bench_decimal"
+harness = false
+required-features = ["rust_decimal"]
+
 [[bench]]
 name = "bench_dict"
 harness = false
@@ -173,5 +181,5 @@ members = [
 
 [package.metadata.docs.rs]
 no-default-features = true
-features = ["macros", "num-bigint", "num-complex", "hashbrown", "serde", "multiple-pymethods", "indexmap", "eyre", "chrono"]
+features = ["macros", "num-bigint", "num-complex", "hashbrown", "serde", "multiple-pymethods", "indexmap", "eyre", "chrono", "rust_decimal"]
 rustdoc-args = ["--cfg", "docsrs"]

benches/bench_decimal.rs

@@ -0,0 +1,35 @@
+use criterion::{black_box, criterion_group, criterion_main, Bencher, Criterion};
+
+use pyo3::prelude::*;
+use pyo3::types::PyDict;
+#[cfg(feature = "rust_decimal")]
+use rust_decimal::Decimal;
+
+#[cfg(feature = "rust_decimal")]
+fn decimal_via_extract(b: &mut Bencher<'_>) {
+    Python::with_gil(|py| {
+        let locals = PyDict::new(py);
+        py.run(
+            r#"
+import decimal
+py_dec = decimal.Decimal("0.0")
+"#,
+            None,
+            Some(locals),
+        )
+        .unwrap();
+        let py_dec = locals.get_item("py_dec").unwrap();
+
+        b.iter(|| {
+            let _: Decimal = black_box(py_dec).extract().unwrap();
+        });
+    })
+}
+
+fn criterion_benchmark(c: &mut Criterion) {
+    #[cfg(feature = "rust_decimal")]
+    c.bench_function("decimal_via_extract", decimal_via_extract);
+}
+
+criterion_group!(benches, criterion_benchmark);
+criterion_main!(benches);

guide/src/features.md

@@ -129,6 +129,10 @@ Adds a dependency on [num-bigint](https://docs.rs/num-bigint) and enables conver
 
 Adds a dependency on [num-complex](https://docs.rs/num-complex) and enables conversions into its [`Complex`](https://docs.rs/num-complex/latest/num_complex/struct.Complex.html) type.
 
+### `rust_decimal`
+
+Adds a dependency on [rust_decimal](https://docs.rs/rust_decimal) and enables conversions into its [`Decimal`](https://docs.rs/rust_decimal/latest/rust_decimal/struct.Decimal.html) type.
+
 ### `serde`
 
 Enables (de)serialization of `Py<T>` objects via [serde](https://serde.rs/).

src/conversions/mod.rs

@@ -7,5 +7,6 @@ pub mod hashbrown;
 pub mod indexmap;
 pub mod num_bigint;
 pub mod num_complex;
+pub mod rust_decimal;
 pub mod serde;
 mod std;

src/conversions/rust_decimal.rs

@@ -0,0 +1,162 @@
+#![cfg(feature = "rust_decimal")]
+
+use crate::exceptions::PyTypeError;
+use crate::types::PyLong;
+use crate::{intern, FromPyObject, IntoPy, PyAny, PyObject, PyResult, Python, ToPyObject};
+use rust_decimal::Decimal;
+
+impl FromPyObject<'_> for Decimal {
+    fn extract(obj: &PyAny) -> PyResult<Self> {
+        // use the string representation to not be lossy
+        // TODO: is PyTypeError the right thing? The Decimal code isn't
+        //       exposed via the C API so its a bit funky to make those
+        //       exceptions directly
+        if obj.is_instance_of::<PyLong>()? {
+            let num_int: i64 = FromPyObject::extract(obj)?;
+            Decimal::try_new(num_int, 0).map_err(|e| PyTypeError::new_err(e.to_string()))
+        } else {
+            Decimal::from_str_exact(obj.str()?.to_str()?)
+                .map_err(|e| PyTypeError::new_err(e.to_string()))
+        }
+    }
+}
+
+impl ToPyObject for Decimal {
+    fn to_object(&self, py: Python<'_>) -> PyObject {
+        // TODO: how do we handle the error gracefully?
+        // look up the decimal.Decimal
+        let dec_mod = py
+            .import(intern!(py, "decimal"))
+            .expect("failed to import decimal");
+        let dec_cls = dec_mod
+            .getattr(intern!(py, "Decimal"))
+            .expect("failed getattr Decimal from decimal");
+        // now call the constructor with the Rust Decimal string-ified
+        // to not be lossy
+        let ret = dec_cls
+            .call1((self.to_string(),))
+            .expect("failed to call decimal.Decimal(value)");
+        ret.to_object(py)
+    }
+}
+
+impl IntoPy<PyObject> for Decimal {
+    fn into_py(self, py: Python<'_>) -> PyObject {
+        self.to_object(py)
+    }
+}
+
+#[cfg(test)]
+mod test_rust_decimal {
+    use super::*;
+    use crate::err::PyErr;
+    use crate::types::PyDict;
+    use rust_decimal::Decimal;
+
+    #[cfg(not(target_arch = "wasm32"))]
+    use proptest::prelude::*;
+
+    macro_rules! convert_constants {
+        ($name:ident, $rs:expr, $py:literal) => {
+            #[test]
+            fn $name() {
+                Python::with_gil(|py| {
+                    let rs_orig = $rs;
+                    let rs_dec = rs_orig.into_py(py);
+                    let locals = PyDict::new(py);
+                    locals.set_item("rs_dec", &rs_dec).unwrap();
+                    // Checks if Rust Decimal -> Python Decimal conversion is correct
+                    py.run(
+                        &format!(
+                            "import decimal\npy_dec = decimal.Decimal({})\nassert py_dec == rs_dec",
+                            $py
+                        ),
+                        None,
+                        Some(locals),
+                    )
+                    .unwrap();
+                    // Checks if Python Decimal -> Rust Decimal conversion is correct
+                    let py_dec = locals.get_item("py_dec").unwrap();
+                    let py_result: Decimal = FromPyObject::extract(py_dec).unwrap();
+                    assert_eq!(rs_orig, py_result);
+                })
+            }
+        };
+    }
+
+    convert_constants!(convert_zero, Decimal::ZERO, "0");
+    convert_constants!(convert_one, Decimal::ONE, "1");
+    convert_constants!(convert_neg_one, Decimal::NEGATIVE_ONE, "-1");
+    convert_constants!(convert_two, Decimal::TWO, "2");
+    convert_constants!(convert_ten, Decimal::TEN, "10");
+    convert_constants!(convert_one_hundred, Decimal::ONE_HUNDRED, "100");
+    convert_constants!(convert_one_thousand, Decimal::ONE_THOUSAND, "1000");
+
+    #[cfg(not(target_arch = "wasm32"))]
+    proptest! {
+        #[test]
+        fn test_roundtrip(
+            lo in any::<u32>(),
+            mid in any::<u32>(),
+            high in any::<u32>(),
+            negative in any::<bool>(),
+            scale in 0..28u32
+        ) {
+            let num = Decimal::from_parts(lo, mid, high, negative, scale);
+            Python::with_gil(|py| {
+                let rs_dec = num.into_py(py);
+                let locals = PyDict::new(py);
+                locals.set_item("rs_dec", &rs_dec).unwrap();
+                py.run(
+                    &format!(
+                       "import decimal\npy_dec = decimal.Decimal(\"{}\")\nassert py_dec == rs_dec",
+                     num.to_string()),
+                None, Some(locals)).unwrap();
+                let roundtripped: Decimal = rs_dec.extract(py).unwrap();
+                assert_eq!(num, roundtripped);
+            })
+        }
+
+        #[test]
+        fn test_integers(num in any::<i64>()) {
+            Python::with_gil(|py| {
+                let py_num = num.into_py(py);
+                let roundtripped: Decimal = py_num.extract(py).unwrap();
+                let rs_dec = Decimal::new(num, 0);
+                assert_eq!(rs_dec, roundtripped);
+            })
+        }
+    }
+
+    #[test]
+    fn test_nan() {
+        Python::with_gil(|py| {
+            let locals = PyDict::new(py);
+            py.run(
+                "import decimal\npy_dec = decimal.Decimal(\"NaN\")",
+                None,
+                Some(locals),
+            )
+            .unwrap();
+            let py_dec = locals.get_item("py_dec").unwrap();
+            let roundtripped: Result<Decimal, PyErr> = FromPyObject::extract(py_dec);
+            assert!(roundtripped.is_err());
+        })
+    }
+
+    #[test]
+    fn test_infinity() {
+        Python::with_gil(|py| {
+            let locals = PyDict::new(py);
+            py.run(
+                "import decimal\npy_dec = decimal.Decimal(\"Infinity\")",
+                None,
+                Some(locals),
+            )
+            .unwrap();
+            let py_dec = locals.get_item("py_dec").unwrap();
+            let roundtripped: Result<Decimal, PyErr> = FromPyObject::extract(py_dec);
+            assert!(roundtripped.is_err());
+        })
+    }
+}

src/lib.rs

@@ -99,6 +99,8 @@
 //! [`BigUint`] types.
 //! - [`num-complex`]: Enables conversions between Python objects and [num-complex]'s [`Complex`]
 //!  type.
+//! - [`rust_decimal`]: Enables conversions between Python's decimal.Decimal and [rust_decimal]'s
+//! [`Decimal`] type.
 //! - [`serde`]: Allows implementing [serde]'s [`Serialize`] and [`Deserialize`] traits for
 //! [`Py`]`<T>` for all `T` that implement [`Serialize`] and [`Deserialize`].
 //!
@@ -275,6 +277,9 @@
 //! [`num-bigint`]: ./num_bigint/index.html "Documentation about the `num-bigint` feature."
 //! [`num-complex`]: ./num_complex/index.html "Documentation about the `num-complex` feature."
 //! [`pyo3-build-config`]: https://docs.rs/pyo3-build-config
+//! [rust_decimal]: https://docs.rs/rust_decimal
+//! [`rust_decimal`]: ./rust_decimal/index.html "Documenation about the `rust_decimal` feature."
+//! [`Decimal`]: https://docs.rs/rust_decimal/latest/rust_decimal/struct.Decimal.html
 //! [`serde`]: <./serde/index.html> "Documentation about the `serde` feature."
 //! [calling_rust]: https://pyo3.rs/latest/python_from_rust.html "Calling Python from Rust - PyO3 user guide"
 //! [examples subdirectory]: https://github.com/PyO3/pyo3/tree/main/examples