diff --git a/docs/installation.rst b/docs/installation.rst index 4bb78a1193..00bb2781e0 100644 --- a/docs/installation.rst +++ b/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 \ No newline at end of file diff --git a/locust/argument_parser.py b/locust/argument_parser.py index f6d524a77d..5fe9ba6373 100644 --- a/locust/argument_parser.py +++ b/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 = { diff --git a/pyproject.toml b/pyproject.toml index 6427931ce3..88625abde7 100644 --- a/pyproject.toml +++ b/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/"