---------------------------------------------------------
lines 6-51 of file: python/dismod_at/create_connection.py
---------------------------------------------------------

# {xrst_begin create_connection}
# {xrst_spell
#     readonly
# }
# {xrst_comment_ch #}
#
# Create a Python sqlite3 Database Connection
# ###########################################
#
# Prototype
# *********
# {xrst_literal
#     BEGIN_PROTOTYPE
#     END_PROTOTYPE
# }
#
# file_name
# *********
# is the name of the file where the data base is stored.
#
# new
# ***
# If *new* is true, a new data base is created with the specified file name.
# If an old version of the file exists, its contents are lost.
# If *new* if false,
# the existing data base corresponding to the file name is used.
#
# readonly
# ********
# If *readonly* is true, the database is opened in read only mode.
#
# connection
# **********
# The return value is an sqlite3
# `connection object <https://docs.python.org/2/library/sqlite3.html#connection-objects>`_
#
# Close
# *****
# You must close this connection when you are done with it by executing
# *connection*\ .\ ``close``\ ()
#
# One Thread
# **********
# The connection can only be used the thread that created it.
#
# {xrst_end create_connection}