# NAPI API documentation

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

`nxs.napi` needs to know the location of the libNeXus C-library in order to load it via `ctypes`. It looks in the following places in order:

Environment | Platforms
--- | ---
`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
`LIBDIR` | 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.1`

- `NEXUSDIR` defaults to `C:\Program Files\NeXus Data Format`.

- `LIBDIR` defaults to `/usr/local/lib`, but is replaced by the value of `--libdir` 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 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:

Flag | Character representation
--- | ---
nxs.napi.ACC_READ | ‘r’
nxs.napi.ACC_RDWR | ‘rw’
nxs.napi.ACC_CREATE | ‘w’
nxs.napi.ACC_CREATE4 | ‘w4’
nxs.napi.ACC_CREATE5 | ‘w5’
nxs.napi.ACC_CREATEXML | ‘wx’

Dimension constants:

Constant | Description
--- | ---
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:

Type string | Description
--- | ---
`'float32'` | 32Bit floating point number
`'float64'` | 64Bit floating point number
`'int8'` | 8Bit singed integer
`'int16'` | 16Bit signed integer
`'int32'` | 32Bit signed integer
`'int64'` | 64Bit signed integer
`'uint8'` | 8Bit unsigned integer
`'uint16'` | 16Bit unsigned integer
`'uint32'` | 32Bit unsigned integer
`'uint64'` | 64Bit unsigned integer
`'char'` | used for string data

To retrieve the type of a `numpy` array one can use its `dtype` attribute.

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:

Constant | Description
--- | ---
`nxs .napi.MAXNAMEL EN` | names must be shorter than this
nxs.napi.MAXPA THLEN | total path length must be shorter than this
nxs.napi.H4SKI P | class names that may appear in HDF4 files but can be ignored

## 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.

class nxs.napi.NeXus(filename, mode='r', encoding='UTF-8')
  attrs()

    Iterate over attributes.

    for name,value in file.attrs():

      process(name,value)

    This automatically reads the attributes of the group/data. Do not change the active group/data while processing the list.

    This does not correspond to an existing NeXus API function, but combines the work of attrinfo/initattrdir/getnextattr/getattr.

  close()

    Close the NeXus file associated with handle.

    Raises NeXusError if file could not be closed.

    Corresponds to NXclose(&handle)

  closedata()

    Close the currently open data set.

    Raises NeXusError if this fails (e.g., because no dataset is open).

    Corresponds to NXclosedata(handle)

  closegroup()

    Close the currently open group.

    Raises NeXusError if the group could not be closed.

    Corresponds to NXclosegroup(handle)

  compmakedata(name, dtype=None, shape=None, mode='lzw', chunks=None)

    Create a data element of the given dimensions and type. See getinfo for details on types. Compression mode is one of ‘none’, ‘lzw’, ‘rle’ or ‘huffman’. chunks gives the alignment of the compressed chunks in the data file. There should be one chunk size for each dimension in the data.

    Defaults to mode=’lzw’ with chunk size set to the length of the fastest varying dimension.

    Raises ValueError if it fails.

    Corresponds to NXmakedata(handle,name,type,rank,dims).

  entries()

    Iterator of entries.

    for name,nxclass in nxs.entries():

      process(name,nxclass)

    This automatically opens the corresponding group/data for you, and closes it when you are done. Do not rely on any paths remaining open between entries as we restore the current path each time.

    This does not correspond to an existing NeXus API function, but instead combines the work of initgroupdir/getnextentry and open/close on data and group. Entries in nxs.H4SKIP are ignored.

  flush()

    Flush all data to the NeXus file.

    Raises NeXusError if this fails.

    Corresponds to NXflush(&handle)

  getattr(name, length, dtype)

    Returns the value of the named attribute. Requires length and data type from getnextattr to allocate the appropriate amount of space for the attribute.

    Corresponds to NXgetattr(handle,name,data,&length,&storage)

  getattrinfo()

    Returns the number of attributes for the currently open group/data object. Do not call getnextattr() more than this number of times.

    Raises NeXusError if this fails.

    Corresponds to NXgetattrinfo(handl, &n)

  getattrs()

    Returns a dicitonary of the attributes on the current node.

    This is a second form of attrs(self).

  getdata()

    Return the data. If data is a string (1-D char array), a python string is returned. If data is a scalar (1-D numeric array of length 1), a python scalar is returned. If data is a string array, a numpy array of type ‘S#’ where # is the maximum string length is returned. If data is a numeric array, a numpy array is returned.

    Raises ValueError if this fails.

    Corresponds to NXgetdata(handle, data)

  getdataID()

    Return the id of the current data so we can link to it later.

    Raises NeXusError

    Corresponds to NXgetdataID(handle, &ID)

  getentries()

    Return a dictionary of the groups[name]=type below the existing open one.

    Raises NeXusError if this fails.

  getgroupID()

    Return the id of the current group so we can link to it later.

    Raises NeXusError

    Corresponds to NXgetgroupID(handle, &ID)

  getgroupinfo()

    Query the currently open group returning the tuple numentries, name, nxclass.

    Raises ValueError if the group could not be opened.

    Corresponds to NXgetgroupinfo(handle)

    Note: corrects error in HDF5 where getgroupinfo returns the entire path rather than the group name. Use the path attribute to get a sensible value of path.

  getinfo()

    Returns the tuple dimensions,type for the currently open dataset. Dimensions is an integer array whose length corresponds to the rank of the dataset and whose elements are the size of the individual dimensions. Storage type is returned as a string, with ‘char’ for a stored string, ‘[u]int[8|16|32]’ for various integer values or ‘float[32|64]’ for floating point values. No support for complex values.

    Unlike getrawinfo(), the length of the stored string is returned rather than the size of the string storage area.

    Raises NeXusError if this fails.

    Note that this is the recommended way to establish if you have a dataset open.

    Corresponds to NXgetinfo(handle, &rank, dims, &storage), but with storage converted from HDF values to numpy compatible strings, and rank implicit in the length of the returned dimensions.

  getnextattr()

    Returns the name, length, and data type for the next attribute. Call getattrinfo to determine the number of attributes before calling getnextattr. Data type is returned as a string. See getinfo for details. Length is the number of elements in the attribute.

    Raises NeXusError if NeXus returns ERROR or EOD.

    Corresponds to NXgetnextattr(handle,name,&length,&storage) but with storage converted from HDF values to numpy compatible strings.

    Note: NeXus API documentation seems to say that length is the number of bytes required to store the entire attribute.

  getnextentry()

    Return the next entry in the group as name,nxclass tuple. If end of data is reached this returns the tuple (None, None)

    Raises NeXusError if this fails.

    Corresponds to NXgetnextentry(handle,name,nxclass,&storage).

    This function doesn’t return the storage class for data entries since getinfo returns shape and storage, both of which are required to read the data.

    Note that HDF4 files can have entries in the file with classes that don’t need to be processed. If the file follows the standard NeXus DTDs then skip any entry for which nxclass.startswith(‘NX’) is False. For non-conforming files, skip those entries with nxclass in nxs.H4SKIP.

  getrawinfo()

    Returns the tuple dimensions,type for the currently open dataset. Dimensions is an integer array whose length corresponds to the rank of the dataset and whose elements are the size of the individual dimensions. Storage type is returned as a string, with ‘char’ for a stored string, ‘[u]int[8|16|32]’ for various integer values or ‘float[32|64]’ for floating point values. No support for complex values.

    Unlike getinfo(), the size of the string storage area is returned rather than the length of the stored string.

    Raises NeXusError if this fails.

    Corresponds to NXgetrawinfo(handle, &rank, dims, &storage), but with storage converted from HDF values to numpy compatible strings, and rank implicit in the length of the returned dimensions.

  getslab(slab_offset, slab_shape)

    Get a slab from the data array.

    Offsets are 0-origin. Shape can be inferred from the data. Offset and shape must each have one entry per dimension.

    Raises ValueError if this fails.

    Corresponds to NXgetslab(handle,data,offset,shape)

  initattrdir()

    Reset the getnextattr list to the first attribute.

    Raises NeXusError if this fails.

    Corresponds to NXinitattrdir(handle)

  initgroupdir()

    Reset getnextentry to return the first entry in the group.

    Raises NeXusError if this fails.

    Corresponds to NXinitgroupdir(handle)

  inquirefile(maxnamelen=1024)

    Return the filename for the current file. This may be different from the file that was opened (file.filename) if the current group is an external link to another file.

    Raises NeXusError if this fails.

    Corresponds to NXinquirefile(&handle,file,len)

  isexternalgroup(name, nxclass, maxnamelen=1024)

    Return the filename for the external link if there is one, otherwise return None.

    Corresponds to NXisexternalgroup(&handle,name,nxclass,file,len)

  link()

    Returns the item which the current item links to, or None if the current item is not linked. This is equivalent to scanning the attributes for target and returning it if target is not equal to self.

    This does not correspond to an existing NeXus API function, but combines the work of attrinfo/initattrdir/getnextattr/getattr.

  linkexternal(name, nxclass, url)

    Return the filename for the external link if there is one, otherwise return None.

    Raises NeXusError if link fails.

    Corresponds to NXisexternalgroup(&handle,name,nxclass,file,len)

  property longpath

    Unix-style path including nxclass to the node

  makedata(name, dtype=None, shape=None)

    Create a data element of the given type and shape. See getinfo for details on types. This does not open the data for writing.

    Set the first dimension to nxs.UNLIMITED, for extensible data sets, and use putslab to write individual slabs.

    Raises ValueError if it fails.

    Corresponds to NXmakedata(handle,name,type,rank,dims)

  makegroup(name, nxclass)

    Create the group nxclass:name.

    Raises NeXusError if the group could not be created.

    Corresponds to NXmakegroup(handle, name, nxclass)

  makelink(ID)

    Link the previously captured group/data ID into the currently open group.

    Raises NeXusError

    Corresponds to NXmakelink(handle, &ID)

  makenamedlink(name, ID)

    Link the previously captured group/data ID into the currently open group, but under a different name.

    Raises NeXusError

    Corresponds to NXmakenamedlink(handle,name,&ID)

  open()

    Opens the NeXus file handle if it is not already open.

    Raises NeXusError if the file could not be opened.

    Corresponds to NXopen(filename,mode,&handle)

  opendata(name)

    Open the named data set within the current group.

    Raises ValueError if could not open the dataset.

    Corresponds to NXopendata(handle, name)

  opengroup(name, nxclass=None)

    Open the group nxclass:name. If the nxclass is not specified this will search for it.

    Raises NeXusError if the group could not be opened.

    Corresponds to NXopengroup(handle, name, nxclass)

  opengrouppath(path)

    Open a particular group ‘/path/to/group’, or the dataset containing the group if the path refers to a dataset. Paths can be relative to the currently open group.

    Raises ValueError.

    Corresponds to NXopengrouppath(handle, path)

  openpath(path)

    Open a particular group ‘/path/to/group’. Paths can be absolute or relative to the currently open group. If openpath fails, then currently open path may not be different from the starting path. For better performation the types can be specified as well using ‘/path:type1/to:type2/group:type3’ which will prevent searching the file for the types associated with the supplied names.

    Raises ValueError.

    Corresponds to NXopenpath(handle, path)

  opensourcegroup()

    If the current node is a linked to another group or data, then open the group or data that it is linked to.

    Note: it is unclear how can we tell if we are linked, other than perhaps the existence of a ‘target’ attribute in the current item.

    Raises NeXusError.

    Corresponds to NXopensourcegroup(handle)

  property path

    Unix-style path to node

  putattr(name, value, dtype=None)

    Saves the named attribute. The attribute value is a string or a scalar.

    Raises TypeError if the value type is incorrect. Raises NeXusError if the attribute could not be saved.

    Corresponds to NXputattr(handle,name,data,length,storage)

    Note length is the number of elements to write rather than the number of bytes to write.

  putdata(data)

    Write data into the currently open data block.

    Raises ValueError if this fails.

    Corresponds to NXputdata(handle, data)

  putslab(data, slab_offset, slab_shape)

    Put a slab into the data array.

    Offsets are 0-origin. Shape can be inferred from the data. Offset and shape must each have one entry per dimension.

    Raises ValueError if this fails.

    Corresponds to NXputslab(handle,data,offset,shape)

  sameID(ID1, ID2)

    Return True of ID1 and ID2 point to the same group/data.

    This should not raise any errors.

    Corresponds to NXsameID(handle,&ID1,&ID2)

  setnumberformat(type, format)

    Set the output format for the numbers of the given type (only applies to XML).

    Raises ValueError if the number format is incorrect.

    Corresponds to NXsetnumberformat(&handle,type,format)

  show(path=None, indent=0)

    Print the structure of a NeXus file from the current node.

    TODO: Break this into a tree walker and a visitor.

exception nxs.napi.NeXusError

  NeXus Error

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

  Returns a NeXus file object.