Add sample config files for commands

This commit adds a sample config file for each of the current 3
commands in subunit2sql. The files contain the current list of options
which can potentially be set in  a config file when using the command.
However for some of the arguments it doesn't make any sense to use them
outside of the cli.

The sample config files can be generated using the oslo-config-generator
utility with the config files added in the config-generator dir.

Change-Id: Ie578f99f27553e14fca4153a9ac5b5aa1c7eb49e

.gitignore

@@ -15,4 +15,4 @@ build
 .coverage*
 !.coveragerc
 cover/
-
+etc/*.conf

config-generator/sql2subunit.conf

@@ -0,0 +1,4 @@
+[DEFAULT]
+output_file = etc/sql2subunit.conf.sample
+namespace = oslo.db
+namespace = subunit2sql.write_subunit

config-generator/subunit2sql-db-manage.conf

@@ -0,0 +1,3 @@
+[DEFAULT]
+output_file = etc/subunit2sql-db-manage.conf.sample
+namespace = oslo.db

config-generator/subunit2sql.conf

@@ -0,0 +1,4 @@
+[DEFAULT]
+output_file = etc/subunit2sql.conf.sample
+namespace = oslo.db
+namespace = subunit2sql.shell

etc/sql2subunit.conf.sample

@@ -0,0 +1,117 @@
+[DEFAULT]
+
+#
+# From subunit2sql.write_subunit
+#
+
+# Path to write the subunit stream output, if none is specified STDOUT
+# will be used (string value)
+#out_path = <None>
+
+# Run id to use for creating a subunit stream (string value)
+#run_id = <None>
+
+
+[database]
+
+#
+# From oslo.db
+#
+
+# The back end to use for the database. (string value)
+# Deprecated group/name - [DEFAULT]/db_backend
+#backend = sqlalchemy
+
+# The SQLAlchemy connection string to use to connect to the database.
+# (string value)
+# Deprecated group/name - [DEFAULT]/sql_connection
+# Deprecated group/name - [DATABASE]/sql_connection
+# Deprecated group/name - [sql]/connection
+#connection = <None>
+
+# Verbosity of SQL debugging information: 0=None, 100=Everything.
+# (integer value)
+# Deprecated group/name - [DEFAULT]/sql_connection_debug
+#connection_debug = 0
+
+# Add Python stack traces to SQL as comment strings. (boolean value)
+# Deprecated group/name - [DEFAULT]/sql_connection_trace
+#connection_trace = false
+
+# If True, increases the interval between database connection retries
+# up to db_max_retry_interval. (boolean value)
+#db_inc_retry_interval = true
+
+# Maximum database connection retries before error is raised. Set to
+# -1 to specify an infinite retry count. (integer value)
+#db_max_retries = 20
+
+# If db_inc_retry_interval is set, the maximum seconds between
+# database connection retries. (integer value)
+#db_max_retry_interval = 10
+
+# Seconds between database connection retries. (integer value)
+#db_retry_interval = 1
+
+# Timeout before idle SQL connections are reaped. (integer value)
+# Deprecated group/name - [DEFAULT]/sql_idle_timeout
+# Deprecated group/name - [DATABASE]/sql_idle_timeout
+# Deprecated group/name - [sql]/idle_timeout
+#idle_timeout = 3600
+
+# If set, use this value for max_overflow with SQLAlchemy. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_max_overflow
+# Deprecated group/name - [DATABASE]/sqlalchemy_max_overflow
+#max_overflow = <None>
+
+# Maximum number of SQL connections to keep open in a pool. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_max_pool_size
+# Deprecated group/name - [DATABASE]/sql_max_pool_size
+#max_pool_size = <None>
+
+# Maximum db connection retries during startup. Set to -1 to specify
+# an infinite retry count. (integer value)
+# Deprecated group/name - [DEFAULT]/sql_max_retries
+# Deprecated group/name - [DATABASE]/sql_max_retries
+#max_retries = 10
+
+# Minimum number of SQL connections to keep open in a pool. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_min_pool_size
+# Deprecated group/name - [DATABASE]/sql_min_pool_size
+#min_pool_size = 1
+
+# The SQL mode to be used for MySQL sessions. This option, including
+# the default, overrides any server-set SQL mode. To use whatever SQL
+# mode is set by the server configuration, set this to no value.
+# Example: mysql_sql_mode= (string value)
+#mysql_sql_mode = TRADITIONAL
+
+# If set, use this value for pool_timeout with SQLAlchemy. (integer
+# value)
+# Deprecated group/name - [DATABASE]/sqlalchemy_pool_timeout
+#pool_timeout = <None>
+
+# Interval between retries of opening a SQL connection. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_retry_interval
+# Deprecated group/name - [DATABASE]/reconnect_interval
+#retry_interval = 10
+
+# The SQLAlchemy connection string to use to connect to the slave
+# database. (string value)
+#slave_connection = <None>
+
+# The file name to use with SQLite. (string value)
+# Deprecated group/name - [DEFAULT]/sqlite_db
+#sqlite_db = oslo.sqlite
+
+# If True, SQLite uses synchronous mode. (boolean value)
+# Deprecated group/name - [DEFAULT]/sqlite_synchronous
+#sqlite_synchronous = true
+
+# Enable the experimental use of database reconnect on connection
+# lost. (boolean value)
+#use_db_reconnect = false

etc/subunit2sql-db-manage.conf.sample

@@ -0,0 +1,106 @@
+[DEFAULT]
+
+
+[database]
+
+#
+# From oslo.db
+#
+
+# The back end to use for the database. (string value)
+# Deprecated group/name - [DEFAULT]/db_backend
+#backend = sqlalchemy
+
+# The SQLAlchemy connection string to use to connect to the database.
+# (string value)
+# Deprecated group/name - [DEFAULT]/sql_connection
+# Deprecated group/name - [DATABASE]/sql_connection
+# Deprecated group/name - [sql]/connection
+#connection = <None>
+
+# Verbosity of SQL debugging information: 0=None, 100=Everything.
+# (integer value)
+# Deprecated group/name - [DEFAULT]/sql_connection_debug
+#connection_debug = 0
+
+# Add Python stack traces to SQL as comment strings. (boolean value)
+# Deprecated group/name - [DEFAULT]/sql_connection_trace
+#connection_trace = false
+
+# If True, increases the interval between database connection retries
+# up to db_max_retry_interval. (boolean value)
+#db_inc_retry_interval = true
+
+# Maximum database connection retries before error is raised. Set to
+# -1 to specify an infinite retry count. (integer value)
+#db_max_retries = 20
+
+# If db_inc_retry_interval is set, the maximum seconds between
+# database connection retries. (integer value)
+#db_max_retry_interval = 10
+
+# Seconds between database connection retries. (integer value)
+#db_retry_interval = 1
+
+# Timeout before idle SQL connections are reaped. (integer value)
+# Deprecated group/name - [DEFAULT]/sql_idle_timeout
+# Deprecated group/name - [DATABASE]/sql_idle_timeout
+# Deprecated group/name - [sql]/idle_timeout
+#idle_timeout = 3600
+
+# If set, use this value for max_overflow with SQLAlchemy. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_max_overflow
+# Deprecated group/name - [DATABASE]/sqlalchemy_max_overflow
+#max_overflow = <None>
+
+# Maximum number of SQL connections to keep open in a pool. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_max_pool_size
+# Deprecated group/name - [DATABASE]/sql_max_pool_size
+#max_pool_size = <None>
+
+# Maximum db connection retries during startup. Set to -1 to specify
+# an infinite retry count. (integer value)
+# Deprecated group/name - [DEFAULT]/sql_max_retries
+# Deprecated group/name - [DATABASE]/sql_max_retries
+#max_retries = 10
+
+# Minimum number of SQL connections to keep open in a pool. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_min_pool_size
+# Deprecated group/name - [DATABASE]/sql_min_pool_size
+#min_pool_size = 1
+
+# The SQL mode to be used for MySQL sessions. This option, including
+# the default, overrides any server-set SQL mode. To use whatever SQL
+# mode is set by the server configuration, set this to no value.
+# Example: mysql_sql_mode= (string value)
+#mysql_sql_mode = TRADITIONAL
+
+# If set, use this value for pool_timeout with SQLAlchemy. (integer
+# value)
+# Deprecated group/name - [DATABASE]/sqlalchemy_pool_timeout
+#pool_timeout = <None>
+
+# Interval between retries of opening a SQL connection. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_retry_interval
+# Deprecated group/name - [DATABASE]/reconnect_interval
+#retry_interval = 10
+
+# The SQLAlchemy connection string to use to connect to the slave
+# database. (string value)
+#slave_connection = <None>
+
+# The file name to use with SQLite. (string value)
+# Deprecated group/name - [DEFAULT]/sqlite_db
+#sqlite_db = oslo.sqlite
+
+# If True, SQLite uses synchronous mode. (boolean value)
+# Deprecated group/name - [DEFAULT]/sqlite_synchronous
+#sqlite_synchronous = true
+
+# Enable the experimental use of database reconnect on connection
+# lost. (boolean value)
+#use_db_reconnect = false

etc/subunit2sql.conf.sample

@@ -0,0 +1,119 @@
+[DEFAULT]
+
+#
+# From subunit2sql.shell
+#
+
+# Location of run artifacts (string value)
+#artifacts = <None>
+
+# Dict of metadata about the run(s) (dict value)
+#run_meta = <None>
+
+# list of subunit files to put into the database (multi valued)
+#subunit_files =
+
+
+[database]
+
+#
+# From oslo.db
+#
+
+# The back end to use for the database. (string value)
+# Deprecated group/name - [DEFAULT]/db_backend
+#backend = sqlalchemy
+
+# The SQLAlchemy connection string to use to connect to the database.
+# (string value)
+# Deprecated group/name - [DEFAULT]/sql_connection
+# Deprecated group/name - [DATABASE]/sql_connection
+# Deprecated group/name - [sql]/connection
+#connection = <None>
+
+# Verbosity of SQL debugging information: 0=None, 100=Everything.
+# (integer value)
+# Deprecated group/name - [DEFAULT]/sql_connection_debug
+#connection_debug = 0
+
+# Add Python stack traces to SQL as comment strings. (boolean value)
+# Deprecated group/name - [DEFAULT]/sql_connection_trace
+#connection_trace = false
+
+# If True, increases the interval between database connection retries
+# up to db_max_retry_interval. (boolean value)
+#db_inc_retry_interval = true
+
+# Maximum database connection retries before error is raised. Set to
+# -1 to specify an infinite retry count. (integer value)
+#db_max_retries = 20
+
+# If db_inc_retry_interval is set, the maximum seconds between
+# database connection retries. (integer value)
+#db_max_retry_interval = 10
+
+# Seconds between database connection retries. (integer value)
+#db_retry_interval = 1
+
+# Timeout before idle SQL connections are reaped. (integer value)
+# Deprecated group/name - [DEFAULT]/sql_idle_timeout
+# Deprecated group/name - [DATABASE]/sql_idle_timeout
+# Deprecated group/name - [sql]/idle_timeout
+#idle_timeout = 3600
+
+# If set, use this value for max_overflow with SQLAlchemy. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_max_overflow
+# Deprecated group/name - [DATABASE]/sqlalchemy_max_overflow
+#max_overflow = <None>
+
+# Maximum number of SQL connections to keep open in a pool. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_max_pool_size
+# Deprecated group/name - [DATABASE]/sql_max_pool_size
+#max_pool_size = <None>
+
+# Maximum db connection retries during startup. Set to -1 to specify
+# an infinite retry count. (integer value)
+# Deprecated group/name - [DEFAULT]/sql_max_retries
+# Deprecated group/name - [DATABASE]/sql_max_retries
+#max_retries = 10
+
+# Minimum number of SQL connections to keep open in a pool. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_min_pool_size
+# Deprecated group/name - [DATABASE]/sql_min_pool_size
+#min_pool_size = 1
+
+# The SQL mode to be used for MySQL sessions. This option, including
+# the default, overrides any server-set SQL mode. To use whatever SQL
+# mode is set by the server configuration, set this to no value.
+# Example: mysql_sql_mode= (string value)
+#mysql_sql_mode = TRADITIONAL
+
+# If set, use this value for pool_timeout with SQLAlchemy. (integer
+# value)
+# Deprecated group/name - [DATABASE]/sqlalchemy_pool_timeout
+#pool_timeout = <None>
+
+# Interval between retries of opening a SQL connection. (integer
+# value)
+# Deprecated group/name - [DEFAULT]/sql_retry_interval
+# Deprecated group/name - [DATABASE]/reconnect_interval
+#retry_interval = 10
+
+# The SQLAlchemy connection string to use to connect to the slave
+# database. (string value)
+#slave_connection = <None>
+
+# The file name to use with SQLite. (string value)
+# Deprecated group/name - [DEFAULT]/sqlite_db
+#sqlite_db = oslo.sqlite
+
+# If True, SQLite uses synchronous mode. (boolean value)
+# Deprecated group/name - [DEFAULT]/sqlite_synchronous
+#sqlite_synchronous = true
+
+# Enable the experimental use of database reconnect on connection
+# lost. (boolean value)
+#use_db_reconnect = false

setup.cfg

@@ -25,6 +25,9 @@ console_scripts =
     subunit2sql = subunit2sql.shell:main
     sql2subunit = subunit2sql.write_subunit:main
     subunit2sql-db-manage = subunit2sql.migrations.cli:main
+oslo.config.opts =
+    subunit2sql.shell = subunit2sql.shell:list_opts
+    subunit2sql.write_subunit = subunit2sql.write_subunit:list_opts
 
 [build_sphinx]
 source-dir = doc/source

subunit2sql/shell.py

@@ -13,6 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import copy
 import sys
 
 from oslo.config import cfg
@@ -24,22 +25,30 @@ from subunit2sql import read_subunit as subunit
 
 CONF = cfg.CONF
 
+SHELL_OPTS = shell_opts = [
+    cfg.MultiStrOpt('subunit_files', positional=True,
+                    help='list of subunit files to put into the database'),
+    cfg.DictOpt('run_meta', short='r', default=None,
+                help='Dict of metadata about the run(s)'),
+    cfg.StrOpt('artifacts', short='a', default=None,
+               help='Location of run artifacts')
+]
+
 
 def cli_opts():
-    shell_opts = [
-        cfg.StrOpt('state_path', default='$pybasedir',
-                   help='Top level dir for maintaining subunit2sql state'),
-        cfg.MultiStrOpt('subunit_files', positional=True),
-        cfg.DictOpt('run_meta', short='r', default=None,
-                    help='Dict of metadata about the run(s)'),
-        cfg.StrOpt('artifacts', short='a', default=None,
-                   help='Location of run artifacts')
-    ]
-
-    for opt in shell_opts:
+    for opt in SHELL_OPTS:
         CONF.register_cli_opt(opt)
 
 
+def list_opts():
+    """Return a list of oslo.config options available.
+
+    The purpose of this is to allow tools like the Oslo sample config file
+    generator to discover the options exposed to users.
+    """
+    return [('DEFAULT', copy.deepcopy(SHELL_OPTS))]
+
+
 def parse_args(argv, default_config_files=None):
     cfg.CONF.register_cli_opts(options.database_opts, group='database')
     cfg.CONF(argv[1:], project='subunit2sql',

subunit2sql/write_subunit.py

@@ -12,6 +12,7 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+import copy
 import functools
 import sys
 
@@ -33,16 +34,17 @@ STATUS_CODES = frozenset([
 
 CONF = cfg.CONF
 
+SHELL_OPTS = [
+    cfg.StrOpt('run_id', required=True, positional=True,
+               help='Run id to use for creating a subunit stream'),
+    cfg.StrOpt('out_path', short='o', default=None,
+               help='Path to write the subunit stream output, if none '
+                    'is specified STDOUT will be used')
+]
+
 
 def cli_opts():
-    shell_opts = [
-        cfg.StrOpt('run_id', required=True, positional=True,
-                   help='Run id to use for creating a subunit stream'),
-        cfg.StrOpt('out_path', short='o', default=None,
-                   help='Path to write the subunit stream output, if none '
-                        'is specified STDOUT will be used')
-    ]
-    for opt in shell_opts:
+    for opt in SHELL_OPTS:
         cfg.CONF.register_cli_opt(opt)
 
 
@@ -84,6 +86,11 @@ def sql2subunit(run_id, output=sys.stdout):
     session.close()
 
 
+def list_opts():
+    opt_list = copy.deepcopy(SHELL_OPTS)
+    return [('DEFAULT', opt_list)]
+
+
 def main():
     cli_opts()
     shell.parse_args(sys.argv)

tox.ini

@@ -37,3 +37,10 @@ commands = python setup.py build_sphinx
 # H305 skipped because it is inconsistent between python versions
 ignore = E125,H402,E123,E129,H305
 exclude = .venv,.git,.tox,dist,doc,*egg,build
+
+[testenv:generate_samples]
+commands =
+    oslo-config-generator --config-file config-generator/subunit2sql.conf
+    oslo-config-generator --config-file config-generator/sql2subunit.conf
+    oslo-config-generator --config-file config-generator/subunit2sql-db-manage.conf
+