doc/records.rst.txt

The ndarray supports records intrinsically.  None of the default
descriptors have fields defined, but you can create new descriptors
easily.  The ndarray even supports nested arrays of records inside of
a record.  Any record that the array protocol can describe can be
represented.  The ndarray also supports partial field descriptors.
Not every byte has to be accounted for.

This was done by adding to the established ``PyArray_Descr *`` structure:

1. A PyObject ``*fields`` member which contains a dictionary of "field
   name" : (``PyArray_Descr`` ``*field-type``, ``offset``, [optional field
   title]).  If a title is given, then it is also inserted into the
   dictionary and used to key the same entry.

2. A byteorder member.  By default this is '=' (native), or '|'
   (not-applicable).

3. An additional ``PyArray_ArrDescr`` ``*member`` of the structure which
   contains a simple representation of an array of another base-type.
   types. The ``PyArray_ArrayDescr`` structure has members
   ``PyArray_Descr *``, ``PyObject *``, for holding a reference to
   the base-type and the shape of the sub-array.

4. The ``PyArray_Descr *`` as official Python object that fully describes
   a region of memory for the data


Data type conversions
---------------------

We can support additional data-type
conversions.  The data-type passed in is converted to a
``PyArray_Descr *`` object.

New possibilities for the "data-type"
`````````````````````````````````````

**List [data-type 1, data-type 2, ..., data-type n]**
  Equivalent to  {'names':['f1','f2',...,'fn'],
	        'formats': [data-type 1, data-type 2, ..., data-type n]}

  This is a quick way to specify a record format with default field names.


**Tuple  (flexible type, itemsize) (fixed type, shape)**
  Get converted to a new ``PyArray_Descr *`` object with a flexible
  type. The latter structure also sets the ``PyArray_ArrayDescr`` field of the
  returned ``PyArray_Descr *``.


**Dictionary (keys "names", "titles", and "formats")**
  This will be converted to a ``NPY_VOID`` type with corresponding
  fields parameter (the formats list will be converted to actual
  ``PyArray_Descr *`` objects).


**Objects (anything with an .itemsize and .fields attribute)**
  If its an instance of (a sub-class of) void type, then a new
  ``PyArray_Descr*`` structure is created corresponding to its
  typeobject (and ``NPY_VOID``) typenumber.  If the type is
  registered, then the registered type-number is used.

  Otherwise a new ``NPY_VOID PyArray_Descr*`` structure is created
  and filled ->elsize and ->fields filled in appropriately.

  The itemsize attribute must return a number > 0. The fields
  attribute must return a dictionary with at least "names" and
  "formats" entries.  The "formats" entry will be converted to a
  "proper" descr->fields entry (all generic data-types converted to
  ``PyArray_Descr *`` structure).


Reference counting for ``PyArray_Descr *`` objects.
```````````````````````````````````````````````````

Most functions that take ``PyArary_Descr *`` as arguments and return a
``PyObject *`` steal the reference unless otherwise noted in the code:

Functions that return ``PyArray_Descr *`` objects return a new
reference.

.. tip::

  There is a new function  and a new method of array objects both labelled
  dtypescr which can be used to try out the ``PyArray_DescrConverter``.