locust 2.18.5.dev16__py3-none-any.whl → 2.18.5.dev32__py3-none-any.whl

locust/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.18.5.dev16'
-__version_tuple__ = version_tuple = (2, 18, 5, 'dev16')
+__version__ = version = '2.18.5.dev32'
+__version_tuple__ = version_tuple = (2, 18, 5, 'dev32')

locust/argument_parser.py

@@ -146,22 +146,32 @@ def get_empty_argument_parser(add_help=True, default_config_files=DEFAULT_CONFIG
         usage=configargparse.SUPPRESS,
         description=textwrap.dedent(
             """
-            Usage: locust [OPTIONS] [UserClass ...]
-
+Usage: locust [options] [UserClass ...]
         """
         ),
-        # epilog="",
+        epilog="""Examples:
+
+    locust -f my_test.py -H https://www.example.com
+
+    locust -u 100 -t 20m --headless --process 4 MyHttpUser AnotherUser
+
+See documentation for more details, including how to set options using a file or environment variables: https://docs.locust.io/en/stable/configuration.html""",
     )
     parser.add_argument(
         "-f",
         "--locustfile",
+        metavar="<filename>",
         default="locustfile",
-        help="Python module to import, e.g. '../other_test.py'. Either a .py file, multiple comma-separated .py files or a package "
-        "directory. Defaults to 'locustfile'.",
+        help="The Python file or module that contains your test, e.g. 'my_test.py'. Also accepts multiple comma-separated .py files or a package name/directory. Defaults to 'locustfile'.",
         env_var="LOCUST_LOCUSTFILE",
     )
 
-    parser.add_argument("--config", is_config_file_arg=True, help="Config file path")
+    parser.add_argument(
+        "--config",
+        is_config_file_arg=True,
+        help="File to read additional configuration from. See https://docs.locust.io/en/stable/configuration.html#configuration-file",
+        metavar="<filename>",
+    )
 
     return parser
 
@@ -251,13 +261,15 @@ def setup_parser_arguments(parser):
     parser.add_argument(
         "-H",
         "--host",
-        help="Host to load test in the following format: http://10.21.32.33",
+        metavar="<base url>",
+        help="Host to load test, in the following format: https://www.example.com",
         env_var="LOCUST_HOST",
     )
     parser.add_argument(
         "-u",
         "--users",
         type=int,
+        metavar="<int>",
         dest="num_users",
         help="Peak number of concurrent Locust users. Primarily used together with --headless or --autostart. Can be changed during a test by keyboard inputs w, W (spawn 1, 10 users) and s, S (stop 1, 10 users)",
         env_var="LOCUST_USERS",
@@ -266,12 +278,14 @@ def setup_parser_arguments(parser):
         "-r",
         "--spawn-rate",
         type=float,
+        metavar="<float>",
         help="Rate to spawn users at (users per second). Primarily used together with --headless or --autostart",
         env_var="LOCUST_SPAWN_RATE",
     )
     parser.add_argument(
         "--hatch-rate",
         env_var="LOCUST_HATCH_RATE",
+        metavar="<float>",
         type=float,
         default=0,
         help=configargparse.SUPPRESS,
@@ -279,6 +293,7 @@ def setup_parser_arguments(parser):
     parser.add_argument(
         "-t",
         "--run-time",
+        metavar="<time string>",
         help="Stop after the specified amount of time, e.g. (300s, 20m, 3h, 1h30m, etc.). Only used together with --headless or --autostart. Defaults to run forever.",
         env_var="LOCUST_RUN_TIME",
     )
@@ -294,6 +309,7 @@ def setup_parser_arguments(parser):
     web_ui_group.add_argument(
         "--web-host",
         default="",
+        metavar="<ip>",
         help="Host to bind the web interface to. Defaults to '*' (all interfaces)",
         env_var="LOCUST_WEB_HOST",
     )
@@ -301,6 +317,7 @@ def setup_parser_arguments(parser):
         "--web-port",
         "-P",
         type=int,
+        metavar="<port number>",
         default=8089,
         help="Port on which to run web host",
         env_var="LOCUST_WEB_PORT",
@@ -320,6 +337,7 @@ def setup_parser_arguments(parser):
     web_ui_group.add_argument(
         "--autoquit",
         type=int,
+        metavar="<seconds>",
         default=-1,
         help="Quits Locust entirely, X seconds after the run is finished. Only used together with --autostart. The default is to keep Locust running until you shut it down using CTRL+C",
         env_var="LOCUST_AUTOQUIT",
@@ -335,19 +353,22 @@ def setup_parser_arguments(parser):
         "--web-auth",
         type=str,
         dest="web_auth",
+        metavar="<username:password>",
         default=None,
-        help="Turn on Basic Auth for the web interface. Should be supplied in the following format: username:password",
+        help="DEPRECATED Turn on Basic Auth for the web interface. Should be supplied in the following format: username:password",
         env_var="LOCUST_WEB_AUTH",
     )
     web_ui_group.add_argument(
         "--tls-cert",
         default="",
+        metavar="<filename>",
         help="Optional path to TLS certificate to use to serve over HTTPS",
         env_var="LOCUST_TLS_CERT",
     )
     web_ui_group.add_argument(
         "--tls-key",
         default="",
+        metavar="<filename>",
         help="Optional path to TLS private key to use to serve over HTTPS",
         env_var="LOCUST_TLS_KEY",
     )
@@ -374,37 +395,40 @@ def setup_parser_arguments(parser):
     master_group.add_argument(
         "--master",
         action="store_true",
-        help="Set locust to run in distributed mode with this process as master",
+        help="Launch locust as a master node, to which worker nodes connect.",
         env_var="LOCUST_MODE_MASTER",
     )
     master_group.add_argument(
         "--master-bind-host",
         default="*",
-        help="Interfaces (hostname, ip) that locust master should bind to. Only used when running with --master. Defaults to * (all available interfaces).",
+        metavar="<ip>",
+        help="IP address for the master to listen on, e.g '192.168.1.1'. Defaults to * (all available interfaces).",
         env_var="LOCUST_MASTER_BIND_HOST",
     )
     master_group.add_argument(
         "--master-bind-port",
         type=int,
+        metavar="<port number>",
         default=5557,
-        help="Port that locust master should bind to. Only used when running with --master. Defaults to 5557.",
+        help="Port for the master to listen on. Defaults to 5557.",
         env_var="LOCUST_MASTER_BIND_PORT",
     )
     master_group.add_argument(
         "--expect-workers",
         type=int,
+        metavar="<int>",
         default=1,
-        help="How many workers master should expect to connect before starting the test (only when --headless/autostart is used).",
+        help="Delay starting the test until this number of workers have connected (only used in combination with --headless/--autostart).",
         env_var="LOCUST_EXPECT_WORKERS",
     )
     master_group.add_argument(
         "--expect-workers-max-wait",
         type=int,
+        metavar="<int>",
         default=0,
         help="How long should the master wait for workers to connect before giving up. Defaults to wait forever",
         env_var="LOCUST_EXPECT_WORKERS_MAX_WAIT",
     )
-
     master_group.add_argument(
         "--expect-slaves",
         action="store_true",
@@ -414,9 +438,8 @@ def setup_parser_arguments(parser):
     worker_group = parser.add_argument_group(
         "Worker options",
         """Options for running a Locust Worker node when running Locust distributed.
-Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, since other options such as -u, -r, -t are specified on the Master node.""",
+Typically ONLY these options (and --locustfile) need to be specified on workers, since other options (-u, -r, -t, ...) are controlled by the master node.""",
     )
-    # if locust should be run in distributed mode as worker
     worker_group.add_argument(
         "--worker",
         action="store_true",
@@ -426,7 +449,8 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
     worker_group.add_argument(
         "--processes",
         type=int,
-        help="Number of times to fork the locust process, to enable using multiple CPU cores. Use -1 to launch one process per CPU core in your system. Combine with --worker flag or let it automatically set --worker and --master flags for an all-in-one-solution. Not available on Windows. Experimental.",
+        metavar="<int>",
+        help="Number of times to fork the locust process, to enable using system. Combine with --worker flag or let it automatically set --worker and --master flags for an all-in-one-solution. Not available on Windows. Experimental.",
         env_var="LOCUST_PROCESSES",
     )
     worker_group.add_argument(
@@ -434,21 +458,20 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
         action="store_true",
         help=configargparse.SUPPRESS,
     )
-    # master host options
     worker_group.add_argument(
         "--master-host",
         default="127.0.0.1",
-        help="Host or IP address of locust master for distributed load testing. Only used when running with --worker. Defaults to 127.0.0.1.",
+        help="Hostname of locust master node to connect to. Defaults to 127.0.0.1.",
         env_var="LOCUST_MASTER_NODE_HOST",
-        metavar="MASTER_NODE_HOST",
+        metavar="<hostname>",
     )
     worker_group.add_argument(
         "--master-port",
         type=int,
+        metavar="<port number>",
         default=5557,
-        help="The port to connect to that is used by the locust master for distributed load testing. Only used when running with --worker. Defaults to 5557.",
+        help="Port to connect to on master node. Defaults to 5557.",
         env_var="LOCUST_MASTER_NODE_PORT",
-        metavar="MASTER_NODE_PORT",
     )
 
     tag_group = parser.add_argument_group(
@@ -459,7 +482,7 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
         "-T",
         "--tags",
         nargs="*",
-        metavar="TAG",
+        metavar="<tag>",
         env_var="LOCUST_TAGS",
         help="List of tags to include in the test, so only tasks with any matching tags will be executed",
     )
@@ -467,7 +490,7 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
         "-E",
         "--exclude-tags",
         nargs="*",
-        metavar="TAG",
+        metavar="<tag>",
         env_var="LOCUST_EXCLUDE_TAGS",
         help="List of tags to exclude from the test, so only tasks with no matching tags will be executed",
     )
@@ -476,6 +499,7 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
     stats_group.add_argument(
         "--csv",  # Name repeated in 'parse_options'
         dest="csv_prefix",
+        metavar="<string>",
         help="Store current request stats to files in CSV format. Setting this option will generate three files: [CSV_PREFIX]_stats.csv, [CSV_PREFIX]_stats_history.csv and [CSV_PREFIX]_failures.csv",
         env_var="LOCUST_CSV",
     )
@@ -507,6 +531,7 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
     )
     stats_group.add_argument(
         "--html",
+        metavar="<filename>",
         dest="html_file",
         help="Store HTML report to file path specified",
         env_var="LOCUST_HTML",
@@ -532,11 +557,13 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
         "-L",
         default="INFO",
         help="Choose between DEBUG/INFO/WARNING/ERROR/CRITICAL. Default is INFO.",
+        metavar="<level>",
         env_var="LOCUST_LOGLEVEL",
     )
     log_group.add_argument(
         "--logfile",
         help="Path to log file. If not set, log will go to stderr",
+        metavar="<filename>",
         env_var="LOCUST_LOGFILE",
     )
 
@@ -562,8 +589,9 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
     other_group.add_argument(
         "--exit-code-on-error",
         type=int,
+        metavar="<int>",
         default=1,
-        help="Sets the process exit code to use when a test result contain any failure or error",
+        help="Sets the process exit code to use when a test result contain any failure or error. Defaults to 1.",
         env_var="LOCUST_EXIT_CODE_ON_ERROR",
     )
     other_group.add_argument(
@@ -571,6 +599,7 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
         "--stop-timeout",
         action="store",
         dest="stop_timeout",
+        metavar="<number>",
         default="0",
         help="Number of seconds to wait for a simulated user to complete any executing task before exiting. Default is to terminate immediately. This parameter only needs to be specified for the master process when running Locust distributed.",
         env_var="LOCUST_STOP_TIMEOUT",
@@ -594,8 +623,8 @@ Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, si
     user_classes_group.add_argument(
         "user_classes",
         nargs="*",
-        metavar="UserClass",
-        help="Optionally specify which User classes that should be used (available User classes can be listed with -l or --list). LOCUST_USER_CLASSES environment variable can also be used to specify User classes",
+        metavar="<UserClass1 UserClass2>",
+        help="At the end of the command line, you can list User classes to be used (available User classes can be listed with --list). LOCUST_USER_CLASSES environment variable can also be used to specify User classes. Default is to use all available User classes",
         default=os.environ.get("LOCUST_USER_CLASSES", "").split(),
     )
 

locust/main.py

@@ -166,12 +166,21 @@ def main():
 
     if options.processes:
         if os.name == "nt":
-            raise Exception("--processes is not supported in Windows (except in WSL)")
+            sys.stderr.write("--processes is not supported in Windows (except in WSL)\n")
+            sys.exit(1)
         if options.processes == -1:
             options.processes = os.cpu_count()
-            assert options.processes, "couldnt detect number of cpus!?"
+            if not options.processes:
+                sys.stderr.write("--processes failed to detect number of cpus!?\n")
+                sys.exit(1)
         elif options.processes < -1:
-            raise Exception(f"invalid processes count {options.processes}")
+            sys.stderr.write(f"Invalid --processes count {options.processes}\n")
+            sys.exit(1)
+        elif options.master:
+            sys.stderr.write(
+                "--master cannot be combined with --processes. Remove --master, as it is implicit as long as --worker is not set.\n"
+            )
+            sys.exit(1)
         for _ in range(options.processes):
             child_pid = gevent.fork()
             if child_pid:

locust/test/test_main.py

@@ -72,9 +72,9 @@ class StandaloneIntegrationTests(ProcessIntegrationTest):
             timeout=5,
             text=True,
         ).strip()
-        self.assertTrue(output.startswith("Usage: locust [OPTIONS] [UserClass ...]"))
+        self.assertTrue(output.startswith("Usage: locust [options] [UserClass"))
         self.assertIn("Common options:", output)
-        self.assertIn("-f LOCUSTFILE, --locustfile LOCUSTFILE", output)
+        self.assertIn("-f <filename>, --locustfile <filename>", output)
         self.assertIn("Logging options:", output)
         self.assertIn("--skip-log-setup      Disable Locust's logging setup.", output)
 

{locust-2.18.5.dev16.dist-info → locust-2.18.5.dev32.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: locust
-Version: 2.18.5.dev16
+Version: 2.18.5.dev32
 Summary: Developer friendly load testing framework
 License: MIT
 Project-URL: Homepage, https://locust.io/

{locust-2.18.5.dev16.dist-info → locust-2.18.5.dev32.dist-info}/RECORD

@@ -1,7 +1,7 @@
 locust/__init__.py,sha256=Q6sqz7YDUaMKPEqcDjWcXEFG2ilVRQR7kl0fG0yK_5A,1402
 locust/__main__.py,sha256=vBQ82334kX06ImDbFlPFgiBRiLIinwNk3z8Khs6hd74,31
-locust/_version.py,sha256=40SZdxSyeRG6nnBD1GZhE7y7w3ZWm9hnZd0JRckzsWo,428
-locust/argument_parser.py,sha256=mgFirGQccbUzbmuEMBX3QNf2FjhWkKq70f1YI1lQyEs,25511
+locust/_version.py,sha256=Ygv5XVePgs9a2_Wq3oEYoTCN31yfH2PVoE7VG_vP2UI,428
+locust/argument_parser.py,sha256=SFu6MwAaLnx7nbZUJ7mW_spK30lcHIvp8KtotuN7xgc,26331
 locust/clients.py,sha256=GJXTWcyBAepE6O-o-V92WboV8XKOXxWR-AixlcL74_w,14768
 locust/debug.py,sha256=pEnZ74679vCdDODEMTNvjYcVdWCe4sWolHDJvdXh9dU,4818
 locust/dispatch.py,sha256=nVWXBkUzpqsVeVp5sw3sYSjR1dD5AAUiFLqutqsrlm4,18634
@@ -11,7 +11,7 @@ locust/exception.py,sha256=aGCx5TQmkYZn8P_uDD3Z4ZwxxRoA7R3ml0WJO-nHgFQ,1942
 locust/html.py,sha256=Bd-XQG-5V1u5Ati30mbDz7NnsZUEPZ6Zcr_Q8Qdyy7o,5770
 locust/input_events.py,sha256=ARmzf5K_t4OnsNilkx0adDnNqvU9-NxtQvKOOjwgA_A,3048
 locust/log.py,sha256=dNPBbuIW96IYRi2AsBtapTmwoOekb6gMa0PsQJgFsbY,3113
-locust/main.py,sha256=mr6T5D4bVTivBItIOwbxqX6QZsMjK7DuA-cs7J_tFao,24776
+locust/main.py,sha256=NoQgiiDNHe9iyaS-ECWeYPeNGrOWAJnEb7-j2CeE8bM,25140
 locust/py.typed,sha256=gkWLl8yD4mIZnNYYAIRM8g9VarLvWmTAFeUfEbxJLBw,65
 locust/runners.py,sha256=omkM2ZLFyQkA898KTgNwjPqKVJlnd9n8HUaTOOOdFOo,64529
 locust/shape.py,sha256=SrKDabGtZ5bqMopJDdivvLbPencaYfAPUv1qzQiAgiA,1969
@@ -60,7 +60,7 @@ locust/test/test_http.py,sha256=XOFRvI6ibbtM3_IRDV-kENGjDEAukNdQwK1T-NmkCa0,1176
 locust/test/test_load_locustfile.py,sha256=EytaJZP35l28M-ekWEai4WXi6v9W-oJYAHR84_8qEhU,7509
 locust/test/test_locust_class.py,sha256=16HONn6DWQG8E4x0nL1rXpLVfLbEdmezM7AUr21syuE,25546
 locust/test/test_log.py,sha256=p2QHAfL2-cJCItIkyKR3C3Rd7ADmnSaD1s4zjeShEno,7552
-locust/test/test_main.py,sha256=MTS8P7OuEhtyEtXf-nL4bDD1pa_9tM66ELZVLx3-E-s,71933
+locust/test/test_main.py,sha256=jJFok2ryNyGwVB7I4pqE_u0ANHt63pEB2OwDBFXmFM8,71928
 locust/test/test_old_wait_api.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 locust/test/test_parser.py,sha256=1YQMAJuNTXbq78FnXhCthxvnq0sgKDmOhf5lYdhml9s,17337
 locust/test/test_runners.py,sha256=6X3z_dlADfmzk_zoKI4gj0n9PBAYFA9Z5vsRwjXneaE,156619
@@ -93,9 +93,9 @@ locust/webui/dist/report.html,sha256=Vyi9LIAjBNiAsvn6LVFkdAZ9R4Fa8UjHnqscjAeOFp8
 locust/webui/dist/assets/favicon.ico,sha256=IUl-rYqfpHdV38e-s0bkmFIeLS-n3Ug0DQxk-h202hI,8348
 locust/webui/dist/assets/index-8ad54eaa.js,sha256=2p0-EIqVZbPDS8yakeol4jMx7KUNeFhyA8HGJ2dLJEw,1616557
 locust/webui/dist/assets/logo.png,sha256=lPCYhpDsPXYY3gUMlq3bzABI5WBtdBOvtay8R9hRFv4,2943
-locust-2.18.5.dev16.dist-info/LICENSE,sha256=78XGpIn3fHVBfaxlPNUfjVufSN7QsdhpJMRJHv2AFpo,1095
-locust-2.18.5.dev16.dist-info/METADATA,sha256=_ElQtjKafMQ5ue4KMI7Vrf7ZpEls9nlPuauS40dGfnI,7150
-locust-2.18.5.dev16.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
-locust-2.18.5.dev16.dist-info/entry_points.txt,sha256=RAdt8Ku-56m7bFjmdj-MBhbF6h4NX7tVODR9QNnOg0E,44
-locust-2.18.5.dev16.dist-info/top_level.txt,sha256=XSsjgPA8Ggf9TqKVbkwSqZFuPlZ085X13M9orDycE20,7
-locust-2.18.5.dev16.dist-info/RECORD,,
+locust-2.18.5.dev32.dist-info/LICENSE,sha256=78XGpIn3fHVBfaxlPNUfjVufSN7QsdhpJMRJHv2AFpo,1095
+locust-2.18.5.dev32.dist-info/METADATA,sha256=SAuDzAxkhh7KQ1H2dtrJ6It0bNi-lSkc02PB7WANi34,7150
+locust-2.18.5.dev32.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
+locust-2.18.5.dev32.dist-info/entry_points.txt,sha256=RAdt8Ku-56m7bFjmdj-MBhbF6h4NX7tVODR9QNnOg0E,44
+locust-2.18.5.dev32.dist-info/top_level.txt,sha256=XSsjgPA8Ggf9TqKVbkwSqZFuPlZ085X13M9orDycE20,7
+locust-2.18.5.dev32.dist-info/RECORD,,