Package nxs.napi

Wrapper for the NeXus shared library. More...

Classes
class	_NXlink
class	NeXusError
	NeXus Error. More...
class	NeXus
Functions
def	open
	Returns a NeXus file object.
Variables
list	__all__
tuple	c_void_pp = ctypes.POINTER(c_void_p)
tuple	c_int_p = ctypes.POINTER(c_int)
tuple	c_int64_p = ctypes.POINTER(c_int64)
tuple	c_NXlink_p = ctypes.POINTER(_NXlink)
tuple	_nxopen_mode = dict(r=1,rw=2,w=3,w4=4,w5=5,wx=6)
int	NOSTRIP = 128
int	UNLIMITED = 1
int	MAXRANK = 32
int	MAXNAMELEN = 64
int	MAXPATHLEN = 1024
list	H4SKIP
tuple	_nxtype_code
tuple	_pytype_code = (lambda : dict([(v,k) for (k,v) in _nxtype_code.iteritems()]))
tuple	_compression_code
tuple	nxlib = _init()
string	__id__ = "$ID$"

---

Detailed Description

Wrapper for the NeXus shared library.

Use this interface when converting code from other languages which do not support the natural view of the hierarchy.

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']\\bin              - 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 one of libNeXus.dll or libNeXus-0.dll.
• On OS X it looks for libNeXus.0.dylib
• On Unix it looks for libNeXus.so.0
• NEXUSDIR defaults to 'C:\Program Files\NeXus Data Format'.
• 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.

Example =======

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

See

See also:

nxstest.py for a more complete example.

Interface =========

When converting code to python from other languages you do not necessarily want to redo the file handling code. The nxs provides an interface which more closely follows the NeXus application programming interface (NAPI_).

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.

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 string data.

You can use the numpy A.dtype attribute for the type of array A.

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

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
• nxs.H4SKIP - class names that may appear in HDF4 files but can be ignored

Caveats =======

Todo:

NOSTRIP constant is probably not handled properly,

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.

---

Function Documentation

def nxs.napi.open	(		filename,
			mode = 'r'
	)

Returns a NeXus file object.

Definition at line 279 of file napi.py.

---

Variable Documentation

list nxs::napi.__all__

Initial value:

['UNLIMITED', 'MAXRANK', 'MAXNAMELEN','MAXPATHLEN','H4SKIP',
           'NeXus','NeXusError','open']

Definition at line 132 of file napi.py.

string nxs::napi.__id__ = "$ID$"

Definition at line 1529 of file napi.py.

tuple nxs::napi._compression_code

Initial value:

dict(
    none=100,
    lzw=200,
    rle=300,
    huffman=400)

Definition at line 187 of file napi.py.

tuple nxs::napi._nxopen_mode = dict(r=1,rw=2,w=3,w4=4,w5=5,wx=6)

Definition at line 155 of file napi.py.

tuple nxs::napi._nxtype_code

Initial value:

dict(
    char=4,
    float32=5,float64=6,
    int8=20,uint8=21,
    int16=22,uint16=23,
    int32=24,uint32=25,
    int64=26,uint64=27,
    )

Definition at line 172 of file napi.py.

tuple nxs::napi._pytype_code = (lambda : dict([(v,k) for (k,v) in _nxtype_code.iteritems()]))

Definition at line 184 of file napi.py.

tuple nxs::napi.c_int64_p = ctypes.POINTER(c_int64)

Definition at line 142 of file napi.py.

tuple nxs::napi.c_int_p = ctypes.POINTER(c_int)

Definition at line 141 of file napi.py.

tuple nxs::napi.c_NXlink_p = ctypes.POINTER(_NXlink)

Definition at line 149 of file napi.py.

tuple nxs::napi.c_void_pp = ctypes.POINTER(c_void_p)

Definition at line 140 of file napi.py.

list nxs::napi.H4SKIP

Initial value:

['CDF0.0','_HDF_CHK_TBL_','Attr0.0',
          'RIG0.0','RI0.0', 'RIATTR0.0N','RIATTR0.0C']

Definition at line 168 of file napi.py.

int nxs::napi.MAXNAMELEN = 64

Definition at line 164 of file napi.py.

int nxs::napi.MAXPATHLEN = 1024

Definition at line 165 of file napi.py.

int nxs::napi.MAXRANK = 32

Definition at line 163 of file napi.py.

int nxs::napi.NOSTRIP = 128

Definition at line 156 of file napi.py.

tuple nxs::napi.nxlib = _init()

Definition at line 272 of file napi.py.

int nxs::napi.UNLIMITED = 1

Definition at line 162 of file napi.py.