--config command line argument

[MattFisher]

This PR adds a --config command line argument to locust.

Fixes #1334

Includes tests and updates to docs.

The help text for the argument is a bit terse, I'd be happy to change that to something better.

[codecov]

Codecov Report

Merging #1359 into master will decrease coverage by 0.59%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master    #1359      +/-   ##
==========================================
- Coverage   80.74%   80.15%   -0.60%     
==========================================
  Files          24       24              
  Lines        2254     2212      -42     
  Branches      345      345              
==========================================
- Hits         1820     1773      -47     
- Misses        343      346       +3     
- Partials       91       93       +2     

Impacted Files	Coverage Δ
locust/argument_parser.py	75.47% <100.00%> (+0.23%)	⬆️
locust/core.py	95.37% <0.00%> (-0.95%)	⬇️
locust/runners.py	79.74% <0.00%> (-0.89%)	⬇️
locust/web.py	90.75% <0.00%> (-0.51%)	⬇️
locust/contrib/fasthttp.py	85.85% <0.00%> (-0.51%)	⬇️
locust/rpc/zmqrpc.py	86.20% <0.00%> (-0.46%)	⬇️
locust/stats.py	88.30% <0.00%> (-0.46%)	⬇️
locust/util/cache.py	90.90% <0.00%> (-0.40%)	⬇️
locust/rpc/protocol.py	100.00% <0.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5cad1cb...82e84de. Read the comment docs.

[MattFisher]

On further testing I've discovered you currently can't use a specified conf file to set the locustfile, because that's handled by the get_empty_argument_parser within parse_locustfile_option.

Since that parser is currently given the DEFAULT_CONFIG_FILES and can set the locustfile from those, I think it makes sense to include the --config option here too?

[cyberw]

On further testing I've discovered you currently can't use a specified conf file to set the locustfile, because that's handled by the get_empty_argument_parser within parse_locustfile_option.

Since that parser is currently given the DEFAULT_CONFIG_FILES and can set the locustfile from those, I think it makes sense to include the --config option here too?

Makes sense! Everything else looks about the PR looks good to me!

[heyman]

Since that parser is currently given the DEFAULT_CONFIG_FILES and can set the locustfile from those, I think it makes sense to include the --config option here too?

Yep! The reason we're going through some hoops with the get_empty_argument_parser is to allow third party plugins or end-users to add their own command line arguments from their own code (that is loaded through their locustfile). We should also add a test for this (set the locustfile in a custom config).

Otherwise I think this PR looks good!

What one could do is to add code for generating a table of all available configuration options that is automatically run when the docs are built. We have such table for all the environment variables, and the code that generates it can be seen here:

locust/docs/conf.py

Lines 27 to 57 in 6f80d63

	# Generate RST table with help/descriptions for all available environment variables
	def save_locust_env_variables():
	env_options_output_file = os.path.join(os.path.abspath(os.path.dirname(__file__)), "env-options.rst")
	print("Generating RST table for Locust environment variables and storing in %s" % env_options_output_file)
	parser = get_empty_argument_parser()
	setup_parser_arguments(parser)
	table_data = []
	for action in parser._actions:
	if action.env_var:
	table_data.append((
	action.env_var,
	", ".join(["``%s``" % c for c in action.option_strings]),
	action.help,
	))
	colsizes = [max(len(r[i]) for r in table_data) for i in range(len(table_data[0]))]
	formatter = ' '.join('{:<%d}' % c for c in colsizes)
	rows = [formatter.format(*row) for row in table_data]
	edge = formatter.format(*['=' * c for c in colsizes])
	divider = formatter.format(*['-' * c for c in colsizes])
	headline = formatter.format(*["Name", "Command line option", "Description"])
	output = "\n".join([
	edge,
	headline,
	divider,
	"\n".join(rows),
	edge,
	])
	with open(env_options_output_file, "w") as f:
	f.write(output)
	save_locust_env_variables()

The generated table is then included into the Configuration documentation page here:

locust/docs/configuration.rst

Line 29 in 6f80d63

.. include:: env-options.rst

[heyman]

Now merged! Thanks!

I changed the table with all available environment variables, to also include the configuration file setting keys. (e40edfe)