BUG: core: Enabled keyword argument for 'order' parameter where it was missing, and tweaked some docs (#1581)

4 files changed, 53 insertions, 26 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 3557c00a3..14cd2a890 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -2421,8 +2421,9 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('flatten',
 
     Parameters
     ----------
-    order : {'C', 'F'}, optional
-        Whether to flatten in C (row-major) or Fortran (column-major) order.
+    order : {'C', 'F', 'A'}, optional
+        Whether to flatten in C (row-major), Fortran (column-major) order,
+        or preserve the C/Fortran ordering from `a`.
         The default is 'C'.
 
     Returns
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index 39bb8b348..e97e50c87 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -117,9 +117,10 @@ def reshape(a, newshape, order='C'):
         an integer, then the result will be a 1-D array of that length.
         One shape dimension can be -1. In this case, the value is inferred
         from the length of the array and remaining dimensions.
-    order : {'C', 'F'}, optional
+    order : {'C', 'F', 'A'}, optional
         Determines whether the array data should be viewed as in C
-        (row-major) order or FORTRAN (column-major) order.
+        (row-major) order, FORTRAN (column-major) order, or the C/FORTRAN
+        order should be preserved.
 
     Returns
     -------
@@ -1052,9 +1053,10 @@ def ravel(a, order='C'):
     a : array_like
         Input array.  The elements in `a` are read in the order specified by
         `order`, and packed as a 1-D array.
-    order : {'C','F'}, optional
-        The elements of `a` are read in this order.  It can be either
-        'C' for row-major order, or `F` for column-major order.
+    order : {'C','F', 'A'}, optional
+        The elements of `a` are read in this order.  It can be
+        'C' for row-major order, `F` for column-major order, or
+        'A' to preserve the order of `a` when possible.
         By default, row-major order is used.
 
     Returns
@@ -1078,21 +1080,24 @@ def ravel(a, order='C'):
 
     Examples
     --------
-    If an array is in C-order (default), then `ravel` is equivalent
-    to ``reshape(-1)``:
+    It is equivalent to ``reshape(-1, order=order)``.
 
     >>> x = np.array([[1, 2, 3], [4, 5, 6]])
-    >>> print x.reshape(-1)
-    [1  2  3  4  5  6]
-
     >>> print np.ravel(x)
-    [1  2  3  4  5  6]
+    [1 2 3 4 5 6]
 
-    When flattening using Fortran-order, however, we see
+    >>> print x.reshape(-1)
+    [1 2 3 4 5 6]
 
     >>> print np.ravel(x, order='F')
     [1 4 2 5 3 6]
 
+    When `order` is 'A', it will preserve the array's 'C' or 'F' ordering:
+
+    >>> print np.ravel(x.T)
+    [1 4 2 5 3 6]
+    >>> print np.ravel(x.T, order='A')
+    [1 2 3 4 5 6]
     """
     return asarray(a).ravel(order)
 
diff --git a/numpy/core/src/multiarray/methods.c b/numpy/core/src/multiarray/methods.c
index 0290c9c39..6ccac9f6e 100644
--- a/numpy/core/src/multiarray/methods.c
+++ b/numpy/core/src/multiarray/methods.c
@@ -912,11 +912,13 @@ array_getarray(PyArrayObject *self, PyObject *args)
 
 
 static PyObject *
-array_copy(PyArrayObject *self, PyObject *args)
+array_copy(PyArrayObject *self, PyObject *args, PyObject *kwds)
 {
     PyArray_ORDER fortran=PyArray_CORDER;
-    if (!PyArg_ParseTuple(args, "|O&", PyArray_OrderConverter,
-                          &fortran)) {
+    static char *kwlist[] = {"order", NULL};
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|O&", kwlist,
+                            PyArray_OrderConverter, &fortran)) {
         return NULL;
     }
 
@@ -2000,11 +2002,13 @@ array_diagonal(PyArrayObject *self, PyObject *args, PyObject *kwds)
 
 
 static PyObject *
-array_flatten(PyArrayObject *self, PyObject *args)
+array_flatten(PyArrayObject *self, PyObject *args, PyObject *kwds)
 {
     PyArray_ORDER fortran = PyArray_CORDER;
+    static char *kwlist[] = {"order", NULL};
 
-    if (!PyArg_ParseTuple(args, "|O&", PyArray_OrderConverter, &fortran)) {
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|O&", kwlist,
+                            PyArray_OrderConverter, &fortran)) {
         return NULL;
     }
     return PyArray_Flatten(self, fortran);
@@ -2012,12 +2016,13 @@ array_flatten(PyArrayObject *self, PyObject *args)
 
 
 static PyObject *
-array_ravel(PyArrayObject *self, PyObject *args)
+array_ravel(PyArrayObject *self, PyObject *args, PyObject *kwds)
 {
     PyArray_ORDER fortran = PyArray_CORDER;
+    static char *kwlist[] = {"order", NULL};
 
-    if (!PyArg_ParseTuple(args, "|O&", PyArray_OrderConverter,
-                          &fortran)) {
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|O&", kwlist,
+                            PyArray_OrderConverter, &fortran)) {
         return NULL;
     }
     return PyArray_Ravel(self, fortran);
@@ -2140,7 +2145,7 @@ NPY_NO_EXPORT PyMethodDef array_methods[] = {
     /* for the copy module */
     {"__copy__",
         (PyCFunction)array_copy,
-        METH_VARARGS, NULL},
+        METH_VARARGS | METH_KEYWORDS, NULL},
     {"__deepcopy__",
         (PyCFunction)array_deepcopy,
         METH_VARARGS, NULL},
@@ -2198,7 +2203,7 @@ NPY_NO_EXPORT PyMethodDef array_methods[] = {
         METH_VARARGS, NULL},
     {"copy",
         (PyCFunction)array_copy,
-        METH_VARARGS, NULL},
+        METH_VARARGS | METH_KEYWORDS, NULL},
     {"cumprod",
         (PyCFunction)array_cumprod,
         METH_VARARGS | METH_KEYWORDS, NULL},
@@ -2216,7 +2221,7 @@ NPY_NO_EXPORT PyMethodDef array_methods[] = {
         METH_VARARGS, NULL},
     {"flatten",
         (PyCFunction)array_flatten,
-        METH_VARARGS, NULL},
+        METH_VARARGS | METH_KEYWORDS, NULL},
     {"getfield",
         (PyCFunction)array_getfield,
         METH_VARARGS | METH_KEYWORDS, NULL},
@@ -2252,7 +2257,7 @@ NPY_NO_EXPORT PyMethodDef array_methods[] = {
         METH_VARARGS | METH_KEYWORDS, NULL},
     {"ravel",
         (PyCFunction)array_ravel,
-        METH_VARARGS, NULL},
+        METH_VARARGS | METH_KEYWORDS, NULL},
     {"repeat",
         (PyCFunction)array_repeat,
         METH_VARARGS | METH_KEYWORDS, NULL},
diff --git a/numpy/core/tests/test_multiarray.py b/numpy/core/tests/test_multiarray.py
index 7c38fcf56..79a76d53b 100644
--- a/numpy/core/tests/test_multiarray.py
+++ b/numpy/core/tests/test_multiarray.py
@@ -549,6 +549,22 @@ class TestMethods(TestCase):
         assert_equal(np.dot(a, b), a.dot(b))
         assert_equal(np.dot(np.dot(a, b), c), a.dot(b).dot(c))
 
+    def test_ravel(self):
+        a = np.array([[0,1],[2,3]])
+        assert_equal(a.ravel(), [0,1,2,3])
+        assert_equal(a.ravel('F'), [0,2,1,3])
+        assert_equal(a.ravel(order='C'), [0,1,2,3])
+        assert_equal(a.ravel(order='F'), [0,2,1,3])
+        assert_equal(a.ravel(order='A'), [0,1,2,3])
+        assert_equal(a.ravel(), a.reshape(-1))
+
+        a = np.array([[0,1],[2,3]], order='F')
+        assert_equal(a.ravel(), [0,1,2,3])
+        assert_equal(a.ravel(order='A'), [0,2,1,3])
+        assert_equal(a.ravel(), a.reshape(-1))
+        assert_equal(a.ravel(order='A'), a.reshape(-1, order='A'))
+
+
 class TestSubscripting(TestCase):
     def test_test_zero_rank(self):
         x = array([1,2,3])