From 109bf418b08ab020668e971f498a6fb8a7d68d79 Mon Sep 17 00:00:00 2001
From: Keith Gaughan <k@stereochro.me>
Date: Sun, 24 Nov 2024 19:40:00 +0000
Subject: [PATCH] Add a proper test for the --app flag and docs.

---
 docs/runner.rst             | 12 +++++++++++-
 src/waitress/adjustments.py |  2 ++
 src/waitress/runner.py      |  8 +++++++-
 tests/test_adjustments.py   | 10 ++++++++++
 4 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/docs/runner.rst b/docs/runner.rst
index 6d687f88..d6dbee1a 100644
--- a/docs/runner.rst
+++ b/docs/runner.rst
@@ -20,6 +20,10 @@ Is equivalent to::
 
     waitress-serve --port=8041 --url-scheme=https myapp:wsgifunc
 
+Or:
+
+    waitress-serve --port=8041 --url-scheme=https --app=myapp:wsgifunc
+
 The full argument list is :ref:`given below <invocation>`.
 
 Boolean arguments are represented by flags. If you wish to explicitly set a
@@ -64,13 +68,19 @@ Invocation
 
 Usage::
 
-    waitress-serve [OPTS] MODULE:OBJECT
+    waitress-serve [OPTS] [MODULE:OBJECT]
 
 Common options:
 
 ``--help``
     Show this information.
 
+``--app=MODULE:OBJECT``
+    Run the given callable object the WSGI application.
+
+    You can specify the WSGI application using this flag or as a positional
+    argument.
+
 ``--call``
     Call the given object to get the WSGI application.
 
diff --git a/src/waitress/adjustments.py b/src/waitress/adjustments.py
index 4354ec45..6049c914 100644
--- a/src/waitress/adjustments.py
+++ b/src/waitress/adjustments.py
@@ -480,6 +480,8 @@ def parse_args(cls, argv):
                 kw[param] = "false"
             elif param in ("help", "call"):
                 kw[param] = True
+            elif param == "app":
+                kw[param] = value
             elif cls._param_map[param] is asbool:
                 kw[param] = "true"
             else:
diff --git a/src/waitress/runner.py b/src/waitress/runner.py
index cc13f275..25b8a8c0 100644
--- a/src/waitress/runner.py
+++ b/src/waitress/runner.py
@@ -29,13 +29,19 @@
 HELP = """\
 Usage:
 
-    {0} [OPTS] MODULE:OBJECT
+    {0} [OPTS] [MODULE:OBJECT]
 
 Standard options:
 
     --help
         Show this information.
 
+    --app=MODULE:OBJECT
+        Run the given callable object the WSGI application.
+
+        You can specify the WSGI application using this flag or as a positional
+        argument.
+
     --call
         Call the given object to get the WSGI application.
 
diff --git a/tests/test_adjustments.py b/tests/test_adjustments.py
index e7f4b713..fa6fe110 100644
--- a/tests/test_adjustments.py
+++ b/tests/test_adjustments.py
@@ -414,6 +414,16 @@ def test_both(self):
         self.assertDictEqual(opts, {"call": True, "help": True, "app": None})
         self.assertSequenceEqual(args, [])
 
+    def test_app_flag(self):
+        opts, args = self.parse(["--app=fred:wilma", "barney:betty"])
+        self.assertEqual(opts["app"], "fred:wilma")
+        self.assertSequenceEqual(args, ["barney:betty"])
+
+    def test_app_arg(self):
+        opts, args = self.parse(["barney:betty"])
+        self.assertEqual(opts["app"], "barney:betty")
+        self.assertSequenceEqual(args, [])
+
     def test_positive_boolean(self):
         opts, args = self.parse(["--expose-tracebacks"])
         self.assertDictContainsSubset({"expose_tracebacks": "true"}, opts)