napi
index
/isis2/nexus_temp/bindings/python/nxs/napi.py

@package nxs.napi
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::
 
@verbatim
   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
@endverbatim
 
- 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'.
- 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
=======
@code
  import nxs
  file = nxs.open('filename.nxs','rw')
  file.opengroup('entry1')
  file.opendata('definition')
  print file.getdata()
  file.close()
@endcode
 
  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::
 
@verbatim
 nxs.ACC_READ      'r'
 nxs.ACC_RDWR      'rw'
 nxs.ACC_CREATE    'w'
 nxs.ACC_CREATE4   'w4'
 nxs.ACC_CREATE5   'w5'
 nxs.ACC_CREATEXML 'wx'
@endverbatim
 
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,
@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.

 
Modules
       
ctypes
numpy
os
sys

 
Classes
       
__builtin__.object
NeXus
exceptions.Exception(exceptions.BaseException)
NeXusError

 
class NeXus(__builtin__.object)
     Methods defined here:
__del__(self)
Be sure to close the file before deleting the last reference.
__init__(self, filename, mode='r')
Open the NeXus file returning a handle.
 
mode can be one of the following:
    nxs.ACC_READ      'r'     open a file read-only
    nxs.ACC_RDWR      'rw'    open a file read/write
    nxs.ACC_CREATE    'w'     open a file write
    nxs.ACC_CREATE4   'w4'    open a Nexus file with HDF4
    nxs.ACC_CREATE5   'w5'    open a Nexus file with HDF5
    nxs.ACC_CREATEXML 'wx'    open a Nexus file with XML
 
Raises ValueError if the open mode is invalid.
 
Raises NeXusError if the file could not be opened, with the
filename as part of the error message.
 
Corresponds to NXopen(filename,mode,&handle)
__str__(self)
Return a string representation of the NeXus file handle.
attrs(self)
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(self)
Close the NeXus file associated with handle.
 
Raises NeXusError if file could not be closed.
 
Corresponds to NXclose(&handle)
closedata(self)
Close the currently open data set.
 
Raises NeXusError if this fails (e.g., because no
dataset is open).
 
Corresponds to NXclosedata(handle)
closegroup(self)
Close the currently open group.
 
Raises NeXusError if the group could not be closed.
 
Corresponds to NXclosegroup(handle)
compmakedata(self, 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(self)
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(self)
Flush all data to the NeXus file.
 
Raises NeXusError if this fails.
 
Corresponds to NXflush(&handle)
getattr(self, 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(self)
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(self)
Returns a dicitonary of the attributes on the current node.
 
This is a second form of attrs(self).
getdata(self)
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(self)
Return the id of the current data so we can link to it later.
 
Raises NeXusError
 
Corresponds to NXgetdataID(handle, &ID)
getentries(self)
Return a dictionary of the groups[name]=type below the
existing open one.
 
Raises NeXusError if this fails.
getgroupID(self)
Return the id of the current group so we can link to it later.
 
Raises NeXusError
 
Corresponds to NXgetgroupID(handle, &ID)
getgroupinfo(self)
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(self)
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(self)
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(self)
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(self)
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(self, 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(self)
Reset the getnextattr list to the first attribute.
 
Raises NeXusError if this fails.
 
Corresponds to NXinitattrdir(handle)
initgroupdir(self)
Reset getnextentry to return the first entry in the group.
 
Raises NeXusError if this fails.
 
Corresponds to NXinitgroupdir(handle)
inquirefile(self, 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(self, 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(self)
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(self, 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)
makedata(self, 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(self, name, nxclass)
Create the group nxclass:name.
 
Raises NeXusError if the group could not be created.
 
Corresponds to NXmakegroup(handle, name, nxclass)
makelink(self, ID)
Link the previously captured group/data ID into the currently
open group.
 
Raises NeXusError
 
Corresponds to NXmakelink(handle, &ID)
makenamedlink(self, 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(self)
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(self, name)
Open the named data set within the current group.
 
Raises ValueError if could not open the dataset.
 
Corresponds to NXopendata(handle, name)
opengroup(self, 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(self, 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(self, 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(self)
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)
putattr(self, 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(self, data)
Write data into the currently open data block.
 
Raises ValueError if this fails.
 
Corresponds to NXputdata(handle, data)
putslab(self, 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(self, 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(self, 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(self, 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.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
longpath
Unix-style path including nxclass to the node
path
Unix-style path to node

 
class NeXusError(exceptions.Exception)
    NeXus Error
 
 
Method resolution order:
NeXusError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.Exception:
__init__(...)
x.__init__(...) initializes x; see help(type(x)) for signature

Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__str__(...)
x.__str__() <==> str(x)
__unicode__(...)

Data descriptors inherited from exceptions.BaseException:
__dict__
args
message

 
Functions
       
open(filename, mode='r')
Returns a NeXus file object.

 
Data
        H4SKIP = ['CDF0.0', '_HDF_CHK_TBL_', 'Attr0.0', 'RIG0.0', 'RI0.0', 'RIATTR0.0N', 'RIATTR0.0C']
MAXNAMELEN = 64
MAXPATHLEN = 1024
MAXRANK = 32
UNLIMITED = -1
__all__ = ['UNLIMITED', 'MAXRANK', 'MAXNAMELEN', 'MAXPATHLEN', 'H4SKIP', 'NeXus', 'NeXusError', 'open']
__id__ = '$ID$'