ferray_numpy_interop/lib.rs
1//! # ferray-numpy-interop
2//!
3//! A companion crate providing zero-copy (where possible) conversions between
4//! ferray arrays and external array ecosystems:
5//!
6//! - **NumPy** (via PyO3) — feature `"python"`
7//! - **Apache Arrow** — feature `"arrow"`
8//! - **Polars** — feature `"polars"`
9//!
10//! All three backends are feature-gated and disabled by default. Enable them
11//! in your `Cargo.toml`:
12//!
13//! ```toml
14//! [dependencies.ferray-numpy-interop]
15//! version = "0.1"
16//! features = ["arrow"] # or "python", "polars"
17//! ```
18//!
19//! ## Design principles
20//!
21//! 1. **Safety first** — every conversion validates dtypes and memory layout
22//! before returning. No silent reinterpretation of memory.
23//! 2. **Zero-copy when possible** — C-contiguous arrays are shared without
24//! copying where the target format supports it.
25//! 3. **Explicit errors** — dtype mismatches, null values, and unsupported
26//! types produce clear [`FerrayError`](ferray_core::FerrayError) messages.
27
28pub mod dtype_map;
29
30#[cfg(feature = "python")]
31pub mod numpy_conv;
32
33#[cfg(feature = "arrow")]
34pub mod arrow_conv;
35
36#[cfg(feature = "polars")]
37pub mod polars_conv;
38
39// Re-export the main conversion traits at crate root for ergonomics.
40
41#[cfg(feature = "arrow")]
42pub use arrow_conv::{FromArrow, FromArrowBool, ToArrow, ToArrowBool};
43
44#[cfg(feature = "polars")]
45pub use polars_conv::{FromPolars, FromPolarsBool, ToPolars, ToPolarsBool};
46
47#[cfg(feature = "python")]
48pub use numpy_conv::{AsFerray, IntoNumPy};