diff --git a/Cargo.toml b/Cargo.toml index 8686003f2..2261c27a7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "numpy" -version = "0.2.1" +version = "0.3.0" authors = ["Toshiki Teramura "] description = "Rust binding of NumPy C-API" diff --git a/README.md b/README.md index 5b7c5822f..d005bd862 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,29 @@ rust-numpy [![Build Status](https://travis-ci.org/rust-numpy/rust-numpy.svg?branch=master)](https://travis-ci.org/rust-numpy/rust-numpy) [![Build status](https://ci.appveyor.com/api/projects/status/bjaru43c7t1alx2x/branch/master?svg=true)](https://ci.appveyor.com/project/kngwyu/rust-numpy/branch/master) [![Crate](http://meritbadge.herokuapp.com/numpy)](https://crates.io/crates/numpy) -[![docs.rs](https://docs.rs/numpy/badge.svg)](https://docs.rs/numpy) Rust binding of NumPy C-API -Dependencies +API documentation ------------- +- [Latest release(possibly broken)](https://docs.rs/numpy) +- [Current Master](https://rust-numpy.github.io/rust-numpy) -- [rust-ndarray](https://github.com/bluss/rust-ndarray) -- [rust-cpython](https://github.com/dgrunwald/rust-cpython) -and more (see [Cargo.toml](Cargo.toml)) +Requirements +------------- +- current nightly rust (see https://github.com/PyO3/pyo3/issues/5 for nightly features, and +https://github.com/PyO3/pyo3/blob/master/build.rs for minimum required version) +- some rust libraries + - [rust-ndarray](https://github.com/bluss/rust-ndarray) for rust-side matrix library + - [pyo3](https://github.com/PyO3/pyo3) for cpython binding + - and more (see [Cargo.toml](Cargo.toml)) +- [numpy](http://www.numpy.org/) installed in your python environments(e.g. via `pip install numpy`) + +**Note** +From 0.3, we migrated from rust-cpython to pyo3. +If you want to use rust-cpython, use version 0.2.1 from crates.io. + Example --------- @@ -25,66 +37,71 @@ name = "rust_ext" crate-type = ["cdylib"] [dependencies] -numpy = "*" -cpython = "*" -ndarray = "*" +numpy = "0.3" +pyo3 = "^0.3.1" +ndarray = "0.11" ``` ```rust -#[macro_use] -extern crate cpython; -extern crate numpy; +#![feature(use_extern_macros, specialization)] + extern crate ndarray; +extern crate numpy; +extern crate pyo3; -use numpy::*; use ndarray::*; -use cpython::{PyResult, Python, PyObject}; - -/* Pure rust-ndarray functions */ - -// immutable example -fn axpy(a: f64, x: ArrayViewD, y: ArrayViewD) -> ArrayD { - a * &x + &y -} - -// mutable example (no return) -fn mult(a: f64, mut x: ArrayViewMutD) { - x *= a; -} - -/* rust-cpython wrappers (to be exposed) */ - -// wrapper of `axpy` -fn axpy_py(py: Python, a: f64, x: PyArray, y: PyArray) -> PyResult { - let np = PyArrayModule::import(py)?; - let x = x.as_array().into_pyresult(py, "x must be f64 array")?; - let y = y.as_array().into_pyresult(py, "y must be f64 array")?; - Ok(axpy(a, x, y).into_pyarray(py, &np)) -} - -// wrapper of `mult` -fn mult_py(py: Python, a: f64, x: PyArray) -> PyResult { - let x = x.as_array_mut().into_pyresult(py, "x must be f64 array")?; - mult(a, x); - Ok(py.None()) // Python function must returns -} +use numpy::*; +use pyo3::prelude::*; + +#[pymodinit] +fn rust_ext(py: Python, m: &PyModule) -> PyResult<()> { + // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + // You **must** write this sentence for PyArray type checker working correctly + // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + let _np = PyArrayModule::import(py)?; + + // immutable example + fn axpy(a: f64, x: ArrayViewD, y: ArrayViewD) -> ArrayD { + a * &x + &y + } + + // mutable example (no return) + fn mult(a: f64, mut x: ArrayViewMutD) { + x *= a; + } + + // wrapper of `axpy` + #[pyfn(m, "axpy")] + fn axpy_py(py: Python, a: f64, x: &PyArray, y: &PyArray) -> PyResult { + let np = PyArrayModule::import(py)?; + let x = x.as_array().into_pyresult("x must be f64 array")?; + let y = y.as_array().into_pyresult("y must be f64 array")?; + Ok(axpy(a, x, y).into_pyarray(py, &np)) + } + + // wrapper of `mult` + #[pyfn(m, "mult")] + fn mult_py(_py: Python, a: f64, x: &PyArray) -> PyResult<()> { + let x = x.as_array_mut().into_pyresult("x must be f64 array")?; + mult(a, x); + Ok(()) + } -/* Define module "_rust_ext" */ -py_module_initializer!(_rust_ext, init_rust_ext, PyInit__rust_ext, |py, m| { - m.add(py, "__doc__", "Rust extension for NumPy")?; - m.add(py, "axpy", py_fn!(py, axpy_py(a: f64, x: PyArray, y: PyArray)))?; - m.add(py, "mult", py_fn!(py, mult_py(a: f64, x: PyArray)))?; Ok(()) -}); +} ``` Contribution ------------- This project is in pre-alpha version. -We need your feedback. Don't hesitate to open [issue](https://github.com/termoshtt/rust-numpy/issues)! +We need your feedback. Don't hesitate to open [issues](https://github.com/termoshtt/rust-numpy/issues)! Version -------- +- v0.3.0 + - Breaking Change: Migrated to pyo3 from rust-cpython + - Some api addition + - [Static type checking with PhantomData](https://github.com/rust-numpy/rust-numpy/pull/41) - v0.2.1 - NEW: trait `IntoPyErr`, `IntoPyResult` for error translation diff --git a/src/convert.rs b/src/convert.rs index 535307957..8ae55da98 100644 --- a/src/convert.rs +++ b/src/convert.rs @@ -1,3 +1,5 @@ +//! Defines conversion trait between rust types and numpy data types. + use ndarray::*; use pyo3::Python; diff --git a/src/error.rs b/src/error.rs index 10452f29a..14964e6f2 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,4 +1,4 @@ -//! Define Errors +//! Defines error types. use pyo3::*; use std::error; diff --git a/src/lib.rs b/src/lib.rs index 9d71b691a..a1c126b0c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,35 @@ +//! `rust-numpy` provides Rust interfaces for [NumPy C APIs](https://docs.scipy.org/doc/numpy/reference/c-api.html), +//! especially for [ndarray](https://www.numpy.org/devdocs/reference/arrays.ndarray.html) class. +//! +//! It uses [pyo3](https://github.com/PyO3/pyo3) for rust bindings to cpython, and uses +//! [ndarray](https://github.com/bluss/ndarray) for rust side matrix library. +//! +//! For numpy dependency, it calls `import numpy.core` internally. So you just need numpy +//! installed by `pip install numpy` or other ways in your python environment. +//! You can use both system environment and `virtualenv`. +//! +//! # Example +//! +//! ``` +//! #[macro_use] +//! extern crate ndarray; +//! extern crate numpy; +//! #[macro_use] +//! extern crate pyo3; +//! use pyo3::prelude::*; +//! use numpy::*; +//! fn main() { +//! let gil = Python::acquire_gil(); +//! let py = gil.python(); +//! let np = PyArrayModule::import(py).unwrap(); +//! let py_array = array![[1i64, 2], [3, 4]].into_pyarray(py, &np); +//! assert_eq!( +//! py_array.as_array().unwrap(), +//! array![[1i64, 2], [3, 4]].into_dyn(), +//! ); +//! } +//! ``` + #![feature(specialization)] #[macro_use] diff --git a/src/types.rs b/src/types.rs index 32cc5b943..fd49eaec0 100644 --- a/src/types.rs +++ b/src/types.rs @@ -1,3 +1,5 @@ +//! Implements conversion utitlities. + pub use num_complex::Complex32 as c32; pub use num_complex::Complex64 as c64;