DOC: Improve rec.array function documentation (#15853) (#16260)

Anthony Byuraev · rossbar · web-flow · commit 7cbd822ffcc1 · 2020-06-26T11:38:38.000-07:00
Add complete docstring with parameters and examples to numpy.core.records.array (gh-15853). Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>
diff --git a/numpy/core/records.py b/numpy/core/records.py
@@ -954,7 +954,86 @@ def fromfile(fd, dtype=None, shape=None, offset=0, formats=None,
 
 def array(obj, dtype=None, shape=None, offset=0, strides=None, formats=None,
           names=None, titles=None, aligned=False, byteorder=None, copy=True):
-    """Construct a record array from a wide-variety of objects.
+    """
+    Construct a record array from a wide-variety of objects.
+
+    A general-purpose record array constructor that dispatches to the 
+    appropriate `recarray` creation function based on the inputs (see Notes).
+
+    Parameters
+    ----------
+    obj: any
+        Input object. See Notes for details on how various input types are
+        treated.
+    dtype: data-type, optional
+        Valid dtype for array.
+    shape: int or tuple of ints, optional
+        Shape of each array.
+    offset: int, optional
+        Position in the file or buffer to start reading from.
+    strides: tuple of ints, optional
+        Buffer (`buf`) is interpreted according to these strides (strides
+        define how many bytes each array element, row, column, etc.
+        occupy in memory).
+    formats, names, titles, aligned, byteorder :
+        If `dtype` is ``None``, these arguments are passed to
+        `numpy.format_parser` to construct a dtype. See that function for
+        detailed documentation.
+    copy: bool, optional
+        Whether to copy the input object (True), or to use a reference instead.
+        This option only applies when the input is an ndarray or recarray.
+        Defaults to True.
+
+    Returns
+    -------
+    np.recarray
+        Record array created from the specified object.
+
+    Notes
+    -----
+    If `obj` is ``None``, then call the `~numpy.recarray` constructor. If
+    `obj` is a string, then call the `fromstring` constructor. If `obj` is a
+    list or a tuple, then if the first object is an `~numpy.ndarray`, call
+    `fromarrays`, otherwise call `fromrecords`. If `obj` is a
+    `~numpy.recarray`, then make a copy of the data in the recarray 
+    (if ``copy=True``) and use the new formats, names, and titles. If `obj`
+    is a file, then call `fromfile`. Finally, if obj is an `ndarray`, then
+    return ``obj.view(recarray)``, making a copy of the data if ``copy=True``.
+
+    Examples
+    --------
+    >>> a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    array([[1, 2, 3],
+           [4, 5, 6],
+           [7, 8, 9]])
+
+    >>> np.core.records.array(a)
+    rec.array([[1, 2, 3],
+               [4, 5, 6],
+               [7, 8, 9]],
+        dtype=int32)
+
+    >>> b = [(1, 1), (2, 4), (3, 9)]
+    >>> c = np.core.records.array(b, formats = ['i2', 'f2'], names = ('x', 'y'))
+    >>> c
+    rec.array([(1, 1.0), (2, 4.0), (3, 9.0)],
+              dtype=[('x', '<i2'), ('y', '<f2')])
+
+    >>> c.x
+    rec.array([1, 2, 3], dtype=int16)
+
+    >>> c.y
+    rec.array([ 1.0,  4.0,  9.0], dtype=float16)
+
+    >>> r = np.rec.array(['abc','def'], names=['col1','col2'])
+    >>> print(r.col1)
+    abc
+
+    >>> r.col1
+    array('abc', dtype='<U3')
+
+    >>> r.col2
+    array('def', dtype='<U3')
     """
 
     if ((isinstance(obj, (type(None), str)) or isfileobj(obj)) and
