----------------------------------------------------
lines 6-85 of file: python/dismod_at/create_table.py
----------------------------------------------------

# {xrst_begin create_table}
# {xrst_spell
#     tbl
# }
# {xrst_comment_ch #}
#
# Create a Database Table
# #######################
#
# Syntax
# ******
#
# | ``dismod_at.create_table`` (
# | |tab| *connection* , *tbl_name* , *col_name* , *col_type* , *row_list*
# | )
#
# connection
# **********
# is a :ref:`create_connection@connection` for this database.
#
# tbl_name
# ********
# is a ``str`` that specifies the name of the table.
#
# col_name
# ********
# is a ``list`` of ``str``
# where the elements are the column names in the table that is created.
# The column name for the primary key, *tbl_name* _ ``id`` must
# not be included in the list.
#
# unique
# ======
# If the column name *tbl_name* _ ``name`` is in the list,
# the corresponding column will have the ``unique`` constraint.
#
# col_type
# ********
# is a ``list`` of ``str`` where the elements are the column types
# in the same order as *col_name* .
# The valid types are
# ``integer`` , ``real`` , ``text`` .
#
# row_list
# ********
# is a possibly empty ``list`` of rows contain data that is written
# to the table.
# Each row is itself a list containing the data for one row of the
# table in the same order as *col_name* .
#
# #.  The primary key column is not included in *row_list* .
# #.  The value in each column gets converted to unicode
#     before being written to the database.
# #.  The special value ``None``
#     gets converted to ``null`` in the database.
# #.  If a column has type real, its values cannot be nan.
#
# tbl_name_id
# ***********
# A column with name *tbl_name* _ ``id`` and type
# ``integer primary key`` is included as the first column in the table.
# Its values start with zero (for the first row) and
# increment by one for each row.
#
# Side Effects
# ************
# This routine does a
#
#     *connection* . ``commit`` ()
#
# to make sure the table exists before returning.
# {xrst_toc_hidden
#    example/table/create_table.py
# }
# Example
# *******
# The file :ref:`create_table.py-name` is an example use of
# ``create_table`` .
#
# {xrst_end create_table}