#! /usr/bin/env python

"""
NetCDF tools.
"""

def show( fname ) :

    """
    List contents of NetCDF file.
    """
    
    # external:
    import pycdf

    # type names:
    typenames = { pycdf.NC.BYTE : 'byte', pycdf.NC.SHORT : 'short', pycdf.NC.INT : 'int', 
                  pycdf.NC.CHAR : 'char', pycdf.NC.FLOAT : 'float' }

    # start listing:
    print 'netcdf %s {' %fname

    # open file:
    ncid = pycdf.CDF(fname,NC.NOWRITE)

    # dimensions:
    dd = ncid.dimensions()
    print 'dimensions:'
    for key in dd.keys() :
        print '        %s = %i ;' % (key,dd[key])
    #endfor

    # variables:
    vv = ncid.variables()
    print 'variables:'
    for name in vv.keys() :
        varid = ncid.var(name)
        typnam = typenames[varid.inq_type()]
        print '        %s %s%s ;' % (typnam,name,varid.dimensions())
        aa = varid.attributes()
        for key in aa.keys() :
            print '                %s:%s = \"%s\" ;' % (name,key,aa[key])
        #endfor
    #endfor

    # global variables:
    ndim,nvar,nattr,unlimid = ncid.inq()
    print ''
    print '// global attributes:'
    # loop over attributes:
    for i in range(nattr) :
        # extract attribute:
        attrid = ncid.attr(i)
        # extract name:
        aname = attrid.inq_name()
        # netcdf files created by 'ncrcat' have something strange 
        # in the history attribute which leads to a segmenation fault ...
        if aname == 'history' :
            print '                :%s = ... ;' % aname
            continue
        #endif
        # extract value:
        avalue = attrid.get()
        # show line:
        print '                :%s = \"%s\" ;' % (aname,repr(avalue))
    #endfor
    print '}'

    # close:
    ncid.close()

#enddef


# ***


def get_varnames( fname ) :

    """
    Return variable names found in data file.
    """
    
    # external:
    import pycdf

    # open file:
    ncid = pycdf.CDF(fname,NC.NOWRITE)

    # variables:
    vv = ncid.variables()
    # extract names:
    varnames = vv.keys()

    # ok
    return varnames

#enddef


# ***


def get_char( varid ) :

    # extract shape of character variable:
    shp = varid.shape()
    # print for single string (1D) or table (2D):
    if len(shp) == 1:
        # can only get single value without errors ...
        s = ''
        for i in range(shp[0]):
            c = varid.get_1( i )
            s = s+c
        #endfor
        # store:
        values = s.strip()
    elif len(shp) == 2:
        # init output:
        values = []
        # loop over strings:
        for j in range(shp[0]):
            # can only get single value without errors ...
            s = ''
            for i in range(shp[1]):
                c = varid.get_1( [j,i] )
                s = s+c
            #endfor
            # store:
            values.append(s.strip())
        #endfor
    else:
        # warning ..
        print "  sorry, not implemented for shape : ", shp
    #endif
    
    # ok
    return values

#enddef

  


# ***


def get_var( fname, vname ) :

    """
    Read variable from NetCDF file, return array in tzxy order:
        o3 = qnc.qget( 'output.nc', 'ozone' )
    """
    
    # external:
    import pycdf

    # open file:
    ncid = pycdf.CDF( fname )
    
    # variable:
    varid = ncid.var(vname)
    
    # extract variable type etc:
    info = varid.inq()
    # special for character ...
    if info[1] == pycdf.NC.CHAR :
        # get character variable:
        values = get_char( varid )
    else :
        # get variable:
        values = varid.get()
    #endif
    
    # close file:
    ncid.close()
    
    # ok
    return values
    
#enddef


# ***


def get_attr( fname, aname ) :

    """
    Read global attribute from NetCDF file.
    """
    
    # external:
    import pycdf

    # open file:
    ncid = pycdf.CDF( fname )

    # id:
    attrid = ncid.attr(aname)

    # extract value:
    avalue = attrid.get()
    
    # close file:
    ncid.close()
    
    # ok
    return avalue
    
#enddef


# ***


def get_var_attr( fname, vname, aname ) :

    """
    Read variable attribute from NetCDF file.
    """
    
    # external:
    import pycdf

    # open file:
    ncid = pycdf.CDF( fname )
    # variable:
    varid = ncid.var(vname)
    # attribute:
    attrid = varid.attr(aname)
    # extract value:
    avalue = attrid.get()
    # close file:
    ncid.close()
    
    # ok
    return avalue
    
#enddef