"""
NetCDF4 tools.
"""

def show( fname ) :

    """
    List contents of NetCDF file.
    """

    import netCDF4
    
    # type names:
    typenames = { 'int8' : 'byte', 'int16': 'short', 'int32' : 'int', 
                 'string8' : 'char', 'float32' : 'float','float64' : 'double' }
    
    # open file:
    ncid = netCDF4.Dataset( fname, 'r' )
    
    # start listing:
    print '%s %s {' % (ncid.file_format,fname)
    
    # dimensions:
    print 'dimensions:'
    for key in ncid.dimensions.keys() :
        print '        %s = %i ;' % (key,len(ncid.dimensions.get(key)))
    
    # variables:
    print 'variables:'
    # loop over variable names:
    for name in ncid.variables.keys() :
        # variable ojbect:
        varid = ncid.variables.get(name)
        # convert type description:
        typnam = typenames[varid.dtype.name]
        # show line:
        print '        %s %s%s ;' % (typnam,name,str(varid.shape))
        # loop over attribute names:
        for aname in varid.ncattrs() :
            # extract value:
            avalue = varid.getncattr(aname)
            # show line:
            print '                %s:%s = %s ;' % (name,aname,repr(avalue))
    
    # global atrributes:
    print ''
    print '// global attributes:'
    # loop over attributes:
    for aname in ncid.ncattrs() :
        ## 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 = getattr(ncid,aname)
        # show line:
        print '                :%s = %s ;' % (aname,repr(avalue))

    # closure:
    print '}'
    
    ncid.close()


# ***

def get_varnames( fname ) :

    """
    Return variable names found in data file.
    """

    import netCDF4
    
    # open file:
    ncid = netCDF4.Dataset( fname, 'r' )
    
    # variable names:
    varnames = ncid.variables.keys()

    # ok
    return varnames

# ***

#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
#    
#    # ok
#    return values
#
##enddef


# ***


def get_var( fname, vname, sample=None ) :

    """
    Read variable from NetCDF file.
    """
    import logging
    import netCDF4    

    if sample != None :
        logging.error( 'argument "sample" not supported for mdf_netCDF.get_var' )
        raise ValueError
    
    ncid = netCDF4.Dataset( fname )       # open
    varid = ncid.variables.get(vname)     # variable
        
    values = varid[:]                     # extract values
    
    # special
    if varid.dtype.name == 'string8' :
        # convert from n-D array of characters to (n-1)-D array of strings:
        if len(values) !=0 : values = netCDF4.chartostring(values)
    
    ncid.close()
    return values

# ***

def get_attr( fname, aname ) :

    """
    Read global attribute from NetCDF file.
    """
    
    import netCDF4

    # open file:
    ncid = netCDF4.Dataset( fname, 'r' )
    # extract value:
    avalue = ncid.getncattr(aname)
    # close file:
    ncid.close()
    
    # ok
    return avalue


# ***

def get_var_attr( fname, vname, aname ) :

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

    # open file:
    ncid = netCDF4.Dataset( fname, 'r' )
    # variable:
    varid = ncid.variables.get(vname)
    # extract value:
    avalue = varid.getncattr(aname)
    # close file:
    ncid.close()
    
    # ok
    return avalue
    
#enddef