numpy.lib.format
index
/usr/lib/python2.6/dist-packages/numpy/lib/format.py

Define a simple format for saving numpy arrays to disk with the full
information about them.
 
WARNING: Due to limitations in the interpretation of structured dtypes, dtypes
with fields with empty names will have the names replaced by 'f0', 'f1', etc.
Such arrays will not round-trip through the format entirely accurately. The
data is intact; only the field names will differ. We are working on a fix for
this.  This fix will not require a change in the file format. The arrays with
such structures can still be saved and restored, and the correct dtype may be
restored by using the `loadedarray.view(correct_dtype)` method.
 
Format Version 1.0
------------------
 
The first 6 bytes are a magic string: exactly "\\x93NUMPY".
 
The next 1 byte is an unsigned byte: the major version number of the file
format, e.g. \\x01.
 
The next 1 byte is an unsigned byte: the minor version number of the file
format, e.g. \\x00. Note: the version of the file format is not tied to the
version of the numpy package.
 
The next 2 bytes form a little-endian unsigned short int: the length of the
header data HEADER_LEN.
 
The next HEADER_LEN bytes form the header data describing the array's format.
It is an ASCII string which contains a Python literal expression of a
dictionary. It is terminated by a newline ('\\n') and padded with spaces
('\\x20') to make the total length of the magic string + 4 + HEADER_LEN be
evenly divisible by 16 for alignment purposes.
 
The dictionary contains three keys:
 
    "descr" : dtype.descr
        An object that can be passed as an argument to the numpy.dtype()
        constructor to create the array's dtype.
    "fortran_order" : bool
        Whether the array data is Fortran-contiguous or not. Since
        Fortran-contiguous arrays are a common form of non-C-contiguity, we
        allow them to be written directly to disk for efficiency.
    "shape" : tuple of int
        The shape of the array.
 
For repeatability and readability, the dictionary keys are sorted in alphabetic
order. This is for convenience only. A writer SHOULD implement this if
possible. A reader MUST NOT depend on this.
 
Following the header comes the array data. If the dtype contains Python objects
(i.e. dtype.hasobject is True), then the data is a Python pickle of the array.
Otherwise the data is the contiguous (either C- or Fortran-, depending on
fortran_order) bytes of the array. Consumers can figure out the number of bytes
by multiplying the number of elements given by the shape (noting that shape=()
means there is 1 element) by dtype.itemsize.

 
Modules
       
cPickle
numpy

 
Functions
       
dtype_to_descr(dtype)
Get a serializable descriptor from the dtype.
 
The .descr attribute of a dtype object cannot be round-tripped through
the dtype() constructor. Simple types, like dtype('float32'), have
a descr which looks like a record array with one field with '' as
a name. The dtype() constructor interprets this as a request to give
a default name.  Instead, we construct descriptor that can be passed to
dtype().
 
Parameters
----------
dtype : dtype
    The dtype of the array that will be written to disk.
 
Returns
-------
descr : object
    An object that can be passed to `numpy.dtype()` in order to
    replicate the input dtype.
header_data_from_array_1_0(array)
Get the dictionary of header metadata from a numpy.ndarray.
 
Parameters
----------
array : numpy.ndarray
 
Returns
-------
d : dict
    This has the appropriate entries for writing its string representation
    to the header of the file.
magic(major, minor)
Return the magic string for the given file format version.
 
Parameters
----------
major : int in [0, 255]
minor : int in [0, 255]
 
Returns
-------
magic : str
 
Raises
------
ValueError if the version cannot be formatted.
open_memmap(filename, mode='r+', dtype=None, shape=None, fortran_order=False, version=(1, 0))
Open a .npy file as a memory-mapped array.
 
This may be used to read an existing file or create a new one.
 
Parameters
----------
filename : str
    The name of the file on disk. This may not be a file-like object.
mode : str, optional
    The mode to open the file with. In addition to the standard file modes,
    'c' is also accepted to mean "copy on write". See `numpy.memmap` for
    the available mode strings.
dtype : dtype, optional
    The data type of the array if we are creating a new file in "write"
    mode.
shape : tuple of int, optional
    The shape of the array if we are creating a new file in "write"
    mode.
fortran_order : bool, optional
    Whether the array should be Fortran-contiguous (True) or
    C-contiguous (False) if we are creating a new file in "write" mode.
version : tuple of int (major, minor)
    If the mode is a "write" mode, then this is the version of the file
    format used to create the file.
 
Returns
-------
marray : numpy.memmap
    The memory-mapped array.
 
Raises
------
ValueError
    If the data or the mode is invalid.
IOError
    If the file is not found or cannot be opened correctly.
 
See Also
--------
numpy.memmap
read_array(fp)
Read an array from an NPY file.
 
Parameters
----------
fp : filelike object
    If this is not a real file object, then this may take extra memory and
    time.
 
Returns
-------
array : numpy.ndarray
    The array from the data on disk.
 
Raises
------
ValueError
    If the data is invalid.
read_array_header_1_0(fp)
Read an array header from a filelike object using the 1.0 file format
version.
 
This will leave the file object located just after the header.
 
Parameters
----------
fp : filelike object
    A file object or something with a `.read()` method like a file.
 
Returns
-------
shape : tuple of int
    The shape of the array.
fortran_order : bool
    The array data will be written out directly if it is either C-contiguous
    or Fortran-contiguous. Otherwise, it will be made contiguous before
    writing it out.
dtype : dtype
    The dtype of the file's data.
 
Raises
------
ValueError :
    If the data is invalid.
read_magic(fp)
Read the magic string to get the version of the file format.
 
Parameters
----------
fp : filelike object
 
Returns
-------
major : int
minor : int
write_array(fp, array, version=(1, 0))
Write an array to an NPY file, including a header.
 
If the array is neither C-contiguous or Fortran-contiguous AND if the
filelike object is not a real file object, then this function will have
to copy data in memory.
 
Parameters
----------
fp : filelike object
    An open, writable file object or similar object with a `.write()`
    method.
array : numpy.ndarray
    The array to write to disk.
version : (int, int), optional
    The version number of the format.
 
Raises
------
ValueError
    If the array cannot be persisted.
Various other errors
    If the array contains Python objects as part of its dtype, the
    process of pickling them may raise arbitrary errors if the objects
    are not picklable.
write_array_header_1_0(fp, d)
Write the header for an array using the 1.0 format.
 
Parameters
----------
fp : filelike object
d : dict
    This has the appropriate entries for writing its string representation
    to the header of the file.

 
Data
        MAGIC_LEN = 8
MAGIC_PREFIX = '\x93NUMPY'
__file__ = '/usr/lib/python2.6/dist-packages/numpy/lib/format.pyc'
__name__ = 'numpy.lib.format'
__package__ = 'numpy.lib'