python db: fix output of db_table_in_vector and changed db.droptable.py behaviour; some pep8 and doctest fix

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@61898 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/python/script/db.py

@@ -1,4 +1,4 @@
-"""!@package grass.script.db
+"""@package grass.script.db
 
 @brief GRASS Python scripting module (database functions)
 
@@ -6,12 +6,12 @@ Database related functions to be used in Python scripts.
 
 Usage:
 
-@code
-from grass.script import db as grass
+::
 
-grass.db_describe(table)
-...
-@endcode
+    from grass.script import db as grass
+
+    grass.db_describe(table)
+    ...
 
 (C) 2008-2009, 2012 by the GRASS Development Team
 This program is free software under the GNU General Public
@@ -22,33 +22,26 @@ for details.
 @author Martin Landa <landa.martin gmail.com>
 """
 
-import tempfile as pytempfile # conflict with core.tempfile
-
 from core import *
 from utils import try_remove
 
 
 def db_describe(table, **args):
-    """!Return the list of columns for a database table
+    """Return the list of columns for a database table
     (interface to `db.describe -c'). Example:
 
-    \code
-    >>> grass.db_describe('lakes')
-    {'nrows': 15279, 'cols': [['cat', 'INTEGER', '11'], ['AREA', 'DOUBLE PRECISION', '20'],
-    ['PERIMETER', 'DOUBLE PRECISION', '20'], ['FULL_HYDRO', 'DOUBLE PRECISION', '20'],
-    ['FULL_HYDR2', 'DOUBLE PRECISION', '20'], ['FTYPE', 'CHARACTER', '24'],
-    ['FCODE', 'INTEGER', '11'], ['NAME', 'CHARACTER', '99']], 'ncols': 8}
-    \endcode
+    >>> db_describe('firestations')  # doctest: +ELLIPSIS
+    {'nrows': 71, 'cols': [['cat', 'INTEGER', '20'], ... 'ncols': 22}
 
-    @param table table name
-    @param args
+    :param str table: table name
+    :param list args:
 
-    @return parsed module output
+    :return: parsed module output
     """
-    s = read_command('db.describe', flags = 'c', table = table, **args)
+    s = read_command('db.describe', flags='c', table=table, **args)
     if not s:
         fatal(_("Unable to describe table <%s>") % table)
-    
+
     cols = []
     result = {}
     for l in s.splitlines():
@@ -63,77 +56,67 @@ def db_describe(table, **args):
         else:
             result[key] = f[1:]
     result['cols'] = cols
-    
+
     return result
 
-# run "db.connect -g" and parse output
 
 def db_table_exist(table, **args):
-    """!Check if table exists.
+    """Check if table exists.
 
     If no driver or database are given, then default settings is used
     (check db_connection()).
 
-    @param table table name
-    @param driver DB driver 
-    @param database DB to check
+    >>> db_table_exist('firestations')
+    True
+
+    :param str table: table name
+    :param args:
 
-    @return True for success, False otherwise
+    :return: True for success, False otherwise
     """
     nuldev = file(os.devnull, 'w+')
-    ret = run_command('db.describe', flags = 'c', table = table,
-                      stdout = nuldev, stderr = nuldev, **args)
+    ret = run_command('db.describe', flags='c', table=table,
+                      stdout=nuldev, stderr=nuldev, **args)
     nuldev.close()
-    
+
     if ret == 0:
         return True
     return False
 
+
 def db_connection():
-    """!Return the current database connection parameters
+    """Return the current database connection parameters
     (interface to `db.connect -g'). Example:
 
-    \code
-    >>> grass.db_connection()
-    {'group': 'x', 'schema': '', 'driver': 'dbf', 'database': '$GISDBASE/$LOCATION_NAME/$MAPSET/dbf/'}
-    \endcode
+    >>> db_connection()
+    {'group': '', 'schema': '', 'driver': 'sqlite', 'database': '$GISDBASE/$LOCATION_NAME/$MAPSET/sqlite/sqlite.db'}
 
-    @return parsed output of db.connect
+    :return: parsed output of db.connect
     """
-    return parse_command('db.connect', flags = 'g')
+    return parse_command('db.connect', flags='g')
+
 
-def db_select(sql = None, filename = None, table = None, **args):
-    """!Perform SQL select statement
+def db_select(sql=None, filename=None, table=None, **args):
+    """Perform SQL select statement
 
     Note: one of <em>sql</em>, <em>filename</em>, or <em>table</em>
     arguments must be provided.
-    
+
     Examples:
-    
-    \code
-    grass.db_select(sql = 'SELECT cat,CAMPUS FROM busstopsall WHERE cat < 4')
 
+    >>> db_select(sql = 'SELECT cat,CITY FROM firestations WHERE cat < 4')
     (('1', 'Vet School'), ('2', 'West'), ('3', 'North'))
-    \endcode
-    
-    \code
-     grass.db_select(filename = '/path/to/sql/file')
-    \endcode
-
-    Simplyfied usage 
-    
-    \code
-    grass.db_select(table = 'busstopsall')
-    \endcode
-
-    performs <tt>SELECT * FROM busstopsall</tt>.
-
-    @param sql SQL statement to perform (or None)
-    @param filename name of file with SQL statements (or None)
-    @param table name of table to query (or None)
-    @param args  see \gmod{db.select} arguments
+
+    Simplyfied usage (it performs <tt>SELECT * FROM busstopsall</tt>.)
+
+    >>> db_select(table = 'firestations')
+
+    :param str sql: SQL statement to perform (or None)
+    :param str filename: name of file with SQL statements (or None)
+    :param str table: name of table to query (or None)
+    :param str args:  see \gmod{db.select} arguments
     """
-    fname = tempfile(create = False)
+    fname = tempfile(create=False)
     if sql:
         args['sql'] = sql
     elif filename:
@@ -143,34 +126,36 @@ def db_select(sql = None, filename = None, table = None, **args):
     else:
         fatal(_("Programmer error: '%(sql)s', '%(filename)s', or '%(table)s' must be provided") %
               {'sql': 'sql', 'filename': 'filename', 'table': 'table'} )
-    
+
     if 'sep' not in args:
         args['sep'] = '|'
-    
-    ret = run_command('db.select', quiet = True,
-                      flags = 'c',
-                      output = fname,
-                      **args)
-    
+
+    ret = run_command('db.select', quiet=True, flags='c',
+                      output=fname, **args)
+
     if ret != 0:
         fatal(_("Fetching data failed"))
-    
+
     ofile = open(fname)
     result = map(lambda x: tuple(x.rstrip(os.linesep).split(args['sep'])),
                  ofile.readlines())
     ofile.close()
     try_remove(fname)
-        
+
     return tuple(result)
 
 
 def db_table_in_vector(table):
     """Return the name of vector connected to the table.
-       It returns False if no vectors are connected to the table.
+    It returns None if no vectors are connected to the table.
+
+    >>> db_table_in_vector('geology')
+    ['geology@PERMANENT']
+    >>> db_table_in_vector('geologies')
 
-       Example
 
-       @params table name of table to query
+    :param str table: name of table to query
+
 
     """
     from vector import vector_db
@@ -184,4 +169,7 @@ def db_table_in_vector(table):
             if f['table'] == table:
                 used.append(vect)
                 break
-    return used
+    if len(used) > 0:
+        return used
+    else:
+        return None

scripts/db.droptable/db.droptable.py

@@ -75,7 +75,7 @@ def main():
 
     # check if table is used somewhere (connected to vector map)
     used = grass.db.db_table_in_vector(table)
-    if len(used) > 0:
+    if used:
         grass.warning(_("Deleting table <%s> which is attached to following map(s):") % table)
         for vect in used:
             grass.warning("%s" % vect)