Merge pull request #2423 from singingwolfboy/argcomplete

Support argcomplete as an optional dependency

docs/installation.rst

@@ -21,6 +21,27 @@ Installation
 
 3. Done! Now you can :ref:`create your first test <quickstart>`
 
+Optional: CLI tab completion
+----------------------------
+
+Locust uses the argcomplete_ module to provide tab completions for the ``locust`` command line interface.
+This is entirely optional; if you don't care about tab completion, you can skip this section entirely!
+If you do want to enable tab completion, first install the ``argcomplete`` module
+into the same environment where you installed ``locust``:
+
+.. code-block:: console
+
+    $ pip3 install argcomplete
+
+Then add this line to your shell config file
+(``~/.bashrc`` if you use ``bash``, ``~/.zshrc`` if you use ``zsh``):
+
+.. code-block:: console
+
+    eval "$(register-python-argcomplete locust)"
+
+Restart your shell, and you should have working tab completion for the ``locust`` CLI!
+If this doesn't work, `check the argcomplete documentation <https://kislyuk.github.io/argcomplete/>`_.
 
 Pre-release builds
 ------------------
@@ -37,3 +58,5 @@ Install for development
 -----------------------
 
 If you want to modify Locust, or contribute to the project, see :ref:`developing-locust`.
+
+.. _argcomplete: https://github.com/kislyuk/argcomplete

locust/argument_parser.py

@@ -5,6 +5,14 @@
 from typing import Dict, List, NamedTuple, Optional, Any
 import configargparse
 
+try:
+    from argcomplete import autocomplete
+except ImportError:
+
+    def autocomplete(parser):
+        return None
+
+
 import locust
 
 version = locust.__version__
@@ -606,6 +614,7 @@ def get_parser(default_config_files=DEFAULT_CONFIG_FILES) -> LocustArgumentParse
 
 def parse_options(args=None) -> configargparse.Namespace:
     parser = get_parser()
+    autocomplete(parser)
     parsed_opts = parser.parse_args(args=args)
     if parsed_opts.stats_history_enabled and (parsed_opts.csv_prefix is None):
         parser.error("'--csv-full-history' requires '--csv'.")
@@ -633,6 +642,7 @@ def ui_extra_args_dict(args=None) -> Dict[str, Dict[str, Any]]:
     locust_args = default_args_dict()
 
     parser = get_parser()
+    autocomplete(parser)
     all_args = vars(parser.parse_args(args))
 
     extra_args = {

pyproject.toml

@@ -42,6 +42,9 @@ classifiers = [
     "Topic :: System :: Distributed Computing",
 ]
 
+[project.optional-dependencies]
+completion = ["argcomplete"]
+
 [project.urls]
 Homepage = "https://locust.io/"
 Documentation = "https://docs.locust.io/"