Merge pull request #37 from rust-numpy/version-up

Bump version to 0.3

Author: kngwyu

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "numpy"
-version = "0.2.1"
+version = "0.3.0"
 authors = ["Toshiki Teramura <[email protected]>"]
 
 description = "Rust binding of NumPy C-API"

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<f64>, y: ArrayViewD<f64>) -> ArrayD<f64> {
-    a * &x + &y
-}
-
-// mutable example (no return)
-fn mult(a: f64, mut x: ArrayViewMutD<f64>) {
-    x *= a;
-}
-
-/* rust-cpython wrappers (to be exposed) */
-
-// wrapper of `axpy`
-fn axpy_py(py: Python, a: f64, x: PyArray, y: PyArray) -> PyResult<PyArray> {
-    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<PyObject> {
-    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<f64>, y: ArrayViewD<f64>) -> ArrayD<f64> {
+        a * &x + &y
+    }
+
+    // mutable example (no return)
+    fn mult(a: f64, mut x: ArrayViewMutD<f64>) {
+        x *= a;
+    }
+
+    // wrapper of `axpy`
+    #[pyfn(m, "axpy")]
+    fn axpy_py(py: Python, a: f64, x: &PyArray, y: &PyArray) -> PyResult<PyArray> {
+        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

src/convert.rs

@@ -1,3 +1,5 @@
+//! Defines conversion trait between rust types and numpy data types.
+
 use ndarray::*;
 use pyo3::Python;
 

src/error.rs

@@ -1,4 +1,4 @@
-//! Define Errors
+//! Defines error types.
 
 use pyo3::*;
 use std::error;

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]

src/types.rs

@@ -1,3 +1,5 @@
+//! Implements conversion utitlities.
+
 pub use num_complex::Complex32 as c32;
 pub use num_complex::Complex64 as c64;