# $Id: HDF.py,v 1.3 2005-07-14 01:36:41 gosselin_a Exp $
# $Log: not supported by cvs2svn $
# Revision 1.2 2004/08/02 15:36:04 gosselin
# pyhdf-0.7-1
#
# Revision 1.1 2004/08/02 15:22:59 gosselin
# Initial revision
#
# Author: Andre Gosselin
# Maurice-Lamontagne Institute
# gosselina@dfo-mpo.gc.ca
"""
Basic API (:mod:`pyhdf.HDF`)
============================
A module of the pyhdf package implementing the basic API of the
NCSA HDF4 library.
Introduction
------------
The role of the HDF module is to provide support to other modules of the
pyhdf package. It defines constants specifying file opening modes and
various data types, methods for accessing files, plus a few utility
functions to query library version and check if a file is an HDF one.
It should be noted that, among the modules of the pyhdf package, SD is
special in the sense that it is self-contained and does not need support
from the HDF module. For example, SD provides its own file opening and
closing methods, whereas VS uses methods of the HDF.HDF class for that.
Functions and classes summary
-----------------------------
The HDF module provides the following classes.
HC
The HC class holds constants defining opening modes and
various data types.
HDF
The HDF class provides methods to open and close an HDF file,
and return instances of the major HDF APIs (except SD).
To instantiate an HDF class, call the HDF() constructor.
methods:
constructors:
HDF() open an HDF file, creating the file if necessary,
and return an HDF instance
vstart() initialize the VS (Vdata) API over the HDF file and
return a VS instance
vgstart() initialize the V (Vgroup) interface over the HDF file
and return a V instance.
closing file
close() close the HDF file
inquiry
getfileversion() return info about the version of the HDF file
The HDF module also offers the following functions.
inquiry
getlibversion() return info about the version of the library
ishdf() determine whether a file is an HDF file
"""
import os, sys, types
from . import hdfext as _C
from .six.moves import xrange
from .HC import HC
# NOTE: The vstart() and vgstart() modules need to access the
# VS and V modules, resp. We could simply import those
# two modules, but then they would always be loaded and this
# may not be what the user wants. Instead of forcing the
# systematic import, we import the package `pyhdf',
# and access the needed constructors by writing
# 'pyhdf.VS.VS()' and 'pyhdf.V.V()'. Until the VS or
# V modules are imported, those statements will give an
# error (undefined attribute). Once the user has imported
# the modules, the error will disappear.
import pyhdf
from .error import HDF4Error, _checkErr
# List of names we want to be imported by an "from pyhdf.HDF import *"
# statement
__all__ = ['HDF', 'HDF4Error',
'HC',
'getlibversion', 'ishdf']
[docs]def getlibversion():
"""Get the library version info.
Args:
no argument
Returns:
4-element tuple with the following components:
-major version number (int)
-minor version number (int)
-complete library version number (int)
-additional information (string)
C library equivalent : Hgetlibversion
"""
status, major_v, minor_v, release, info = _C.Hgetlibversion()
_checkErr('getlibversion', status, "cannot get lib version")
return major_v, minor_v, release, info
[docs]def ishdf(filename):
"""Determine whether a file is an HDF file.
Args:
filename name of the file to check
Returns:
1 if the file is an HDF file, 0 otherwise
C library equivalent : Hishdf
"""
return _C.Hishdf(filename)
[docs]class HDF(object):
"""The HDF class encapsulates the basic HDF functions.
Its main use is to open and close an HDF file, and return
instances of the major HDF APIs (except for SD).
To instantiate an HDF class, call the HDF() constructor. """
def __init__(self, path, mode=HC.READ, nblocks=0):
"""HDF constructor: open an HDF file, creating the file if
necessary.
Args:
path name of the HDF file to open
mode file opening mode; this mode is a set of binary flags
which can be ored together
HC.CREATE combined with HC.WRITE to create file
if it does not exist
HC.READ open file in read-only access (default)
HC.TRUNC if combined with HC.WRITE, overwrite
file if it already exists
HC.WRITE open file in read-write mode; if file
exists it is updated, unless HC.TRUNC is
set, in which case it is erased and
recreated; if file does not exist, an
error is raised unless HC.CREATE is set,
in which case the file is created
Note an important difference in the way CREATE is
handled by the HDF C library and the pyhdf package.
In the C library, CREATE indicates that a new file should
always be created, overwriting an existing one if
any. For pyhdf, CREATE indicates a new file should be
created only if it does not exist, and the overwriting
of an already existing file must be explicitly asked
for by setting the TRUNC flag.
Those differences were introduced so as to harmonize
the way files are opened in the pycdf and pyhdf
packages. Also, this solves a limitation in the
hdf (and netCDF) library, where there is no easy way
to implement the frequent requirement that an existent
file be opened in read-write mode, or created
if it does not exist.
nblocks number of data descriptor blocks in a block with which
to create the file; the parameter is ignored if the file
is not created; 0 asks to use the default
Returns:
an HDF instance
C library equivalent : Hopen
"""
# Private attributes:
# _id: file id (NOTE: not compatile with the SD file id)
# See if file exists.
exists = os.path.exists(path)
if HC.WRITE & mode:
if exists:
if HC.TRUNC & mode:
try:
os.remove(path)
except Exception as msg:
raise HDF4Error(msg)
mode = HC.CREATE
else:
mode = HC.WRITE
else:
if HC.CREATE & mode:
mode = HC.CREATE
else:
raise HDF4Error("HDF: no such file")
else:
if exists:
if mode & HC.READ:
mode = HC.READ # clean mode
else:
raise HDF4Error("HDF: invalid mode")
else:
raise HDF4Error("HDF: no such file")
id = _C.Hopen(path, mode, nblocks)
_checkErr('HDF', id, "cannot open %s" % path)
self._id = id
def __del__(self):
"""Delete the instance, first calling the end() method
if not already done. """
try:
if self._id:
self.close()
except:
pass
[docs] def close(self):
"""Close the HDF file.
Args:
no argument
Returns:
None
C library equivalent : Hclose
"""
_checkErr('close', _C.Hclose(self._id), "cannot close file")
self._id = None
[docs] def getfileversion(self):
"""Get file version info.
Args:
no argument
Returns:
4-element tuple with the following components:
-major version number (int)
-minor version number (int)
-complete library version number (int)
-additional information (string)
C library equivalent : Hgetlibversion
"""
status, major_v, minor_v, release, info = _C.Hgetfileversion(self._id)
_checkErr('getfileversion', status, "cannot get file version")
return major_v, minor_v, release, info
[docs] def vstart(self):
"""Initialize the VS API over the file and return a VS instance.
Args:
no argument
Returns:
VS instance
C library equivalent : Vstart (in fact: Vinitialize)
"""
# See note at top of file.
return pyhdf.VS.VS(self)
[docs] def vgstart(self):
"""Initialize the V API over the file and return a V instance.
Args:
no argument
Returns:
V instance
C library equivalent : Vstart (in fact: Vinitialize)
"""
# See note at top of file.
return pyhdf.V.V(self)
###########################
# Support functions
###########################
def _array_to_ret(buf, nValues):
# Convert array 'buf' to a scalar or a list.
if nValues == 1:
ret = buf[0]
else:
ret = []
for i in xrange(nValues):
ret.append(buf[i])
return ret
def _array_to_str(buf, nValues):
# Convert array of bytes 'buf' to a string.
# Return empty string if there is no value.
if nValues == 0:
return ""
# When there is just one value, _array_to_ret returns a scalar
# over which we cannot iterate.
if nValues == 1:
chrs = [chr(buf[0])]
else:
chrs = [chr(b) for b in _array_to_ret(buf, nValues)]
# Strip NULL at end
if chrs[-1] == '\0':
del chrs[-1]
return ''.join(chrs)