Module nxs

source code

Wrapper for the NeXus shared library.


Library Location
================

This wrapper needs the location of the libNeXus precompiled binary. It
looks in the following places in order:
    os.environ['NEXUSLIB']                  - All
    directory containing nxs.py             - All
    os.environ['NEXUSDIR']in              - Windows
    os.environ['LD_LIBRARY_PATH']           - Unix
    os.environ['DYLD_LIBRARY_PATH']         - Darwin
    PREFIX/lib                              - Unix and Darwin
    /usr/local/lib                          - Unix and Darwin
    /usr/lib                                - Unix and Darwin

On Windows it looks for libNeXus.dll and libNeXus-0.dll;
NEXUSDIR defaults to r'C:\Program Files\NeXus Data Format'
On OS X it looks for libNeXus.dylib
On Unix it looks for libNeXus.so
PREFIX defaults to /usr/local, but is replaced by the value of
--prefix during configure.

The import will raise an OSError exception if the library wasn't found
or couldn't be loaded.  Note that on Windows in particular this may be
because the supporting HDF5 dlls were not available in the usual places.

If you are extracting the nexus library from a bundle at runtime, set
os.environ['NEXUSLIB'] to the path where it is extracted before the
first import of nxs.

Interface
=========

Full documentation of the NeXus API is available at nexusformat.org.

This wrapper differs from napi in several respects:
  - Data values are loaded/stored directly from numpy arrays.
  - Return codes are turned into exceptions.
  - The file handle is stored in a file object
  - Constants are handled somewhat differently (see below)
  - Type checking on data/parameter storage
  - Adds iterators file.entries() and file.attrs()
  - Adds link() function to return the name of the linked to group, if any
  - NXmalloc/NXfree are not needed.

Example:

  import nxs
  file = nxs.open('filename.nxs','rw')
  file.opengroup('entry1')
  file.opendata('definition')
  print file.getdata()
  file.close()

  See nxstest.py for a more complete example.

File open modes can be constants or strings:

  nxs.ACC_READ      'r'
  nxs.ACC_RDWR      'rw'
  nxs.ACC_CREATE    'w'
  nxs.ACC_CREATE4   'w4'
  nxs.ACC_CREATE5   'w5'
  nxs.ACC_CREATEXML 'wx'

Dimension constants:

  nxs.UNLIMITED  - for the extensible data dimension
  nxs.MAXRANK    - for the number of possible dimensions

Data types are strings corresponding to the numpy data types:

  'float32' 'float64'
  'int8' 'int16' 'int32' 'int64'
  'uint8' 'uint16' 'uint32' 'uint64'

  Use 'char' for strings.  You can use the numpy dtype attribute for the
  data type.

Dimensions are lists of integers or numpy arrays.  You can use the
numpy shape attribute for the dimensions.

Compression codes are:

 'none' 'lzw' 'rle' 'huffman'

  As of this writing NeXus only supports 'none' and 'lzw'.

Miscellaneous constants:

  nxs.MAXNAMELEN  - names must be shorter than this
  nxs.MAXPATHLEN  - total path length must be shorter than this


Caveats
=======

TODO: NOSTRIP constant is probably not handled properly,
TODO: Embedded nulls in strings is not supported

WARNING:  We have a memory leak.  Calling open/close costs about 90k a pair.
This is an eigenbug:
   - if I test ctypes on a simple library it does not leak
   - if I use the leak_test1 code in the nexus distribution it doesn't leak
   - if I remove the open/close call in the wrapper it doesn't leak.