From a93b86217e9ff8cc1060aaf362cd682b518cfb7b Mon Sep 17 00:00:00 2001
From: Allan Haldane <allan.haldane@gmail.com>
Date: Fri, 5 Jun 2015 12:10:25 -0400
Subject: BUG: automatically convert recarray dtype to np.record

Viewing an ndarray as a np.recarray now automatically converts
the dtype to np.record.

This commit also fixes assignment to MaskedArray's dtype attribute,
fixes the repr of recarrays with non-structured dtype, and removes
recarray.view so that viewing a recarray as a non-structured dtype
no longer converts to ndarray type.

Fixes #3581
---
 numpy/doc/structured_arrays.py | 40 +++++++++++++---------------------------
 1 file changed, 13 insertions(+), 27 deletions(-)

(limited to 'numpy/doc/structured_arrays.py')

diff --git a/numpy/doc/structured_arrays.py b/numpy/doc/structured_arrays.py
index 73bf3b317..fe17c133e 100644
--- a/numpy/doc/structured_arrays.py
+++ b/numpy/doc/structured_arrays.py
@@ -258,6 +258,19 @@ appropriate :ref:`view`: ::
  >>> recordarr = arr.view(dtype=dtype((np.record, arr.dtype)), 
  ...                      type=np.recarray)
 
+For convenience, viewing an ndarray as type `np.recarray` will automatically
+convert to `np.record` datatype, so the dtype can be left out of the view: ::
+
+ >>> recordarr = arr.view(np.recarray)
+ >>> recordarr.dtype
+ dtype((numpy.record, [('foo', '<i4'), ('bar', '<f4'), ('baz', 'S10')]))
+
+To get back to a plain ndarray both the dtype and type must be reset. The
+following view does so, taking into account the unusual case that the
+recordarr was not a structured type: ::
+
+ >>> arr2 = recordarr.view(recordarr.dtype.fields or recordarr.dtype, np.ndarray)
+
 Record array fields accessed by index or by attribute are returned as a record
 array if the field has a structured type but as a plain ndarray otherwise. ::
 
@@ -272,33 +285,6 @@ Note that if a field has the same name as an ndarray attribute, the ndarray
 attribute takes precedence. Such fields will be inaccessible by attribute but
 may still be accessed by index.
 
-Partial Attribute Access
-------------------------
-
-The differences between record arrays and plain structured arrays induce a
-small performance penalty. It is possible to apply one or the other view
-independently if desired. To allow field access by attribute only on the array
-object it is sufficient to view an array as a recarray: ::
-
- >>> recarr = arr.view(np.recarray)
-
-This type of view is commonly used, for example in np.npyio and
-np.recfunctions. Note that unlike full record arrays the individual elements of
-such a view do not have field attributes::
-
- >>> recarr[0].foo
- AttributeError: 'numpy.void' object has no attribute 'foo'
-
-To use the np.record dtype only, convert the dtype using the (base_class,
-dtype) form described in numpy.dtype.  This type of view is rarely used. ::
-
- >>> arr_records = arr.view(dtype((np.record, arr.dtype)))
-
-In documentation, the term 'structured array' will refer to objects of type
-np.ndarray with structured dtype, 'record array' will refer to structured
-arrays subclassed as np.recarray and whose dtype is of type np.record, and
-'recarray' will refer to arrays subclassed as np.recarray but whose dtype is
-not of type np.record.
 
 """
 from __future__ import division, absolute_import, print_function
-- 
cgit v1.2.1