Options tweaks

- Regularise presentation and wording
- Help is mandatory for all options
- Auto-generate wording to say that sequence options can be passed multiple
times on the command-line

mitmproxy/options.py

@@ -62,7 +62,7 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "onboarding_port", APP_PORT, int,
-            help="Port to serve the onboarding app from."
+            "Port to serve the onboarding app from."
         )
         self.add_option(
             "anticache", False, bool,
@@ -93,11 +93,17 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "server_replay_nopop", False, bool,
-            "Disable response pop from response flow. "
-            "This makes it possible to replay same response multiple times."
+            """
+            Disable response pop from response flow. This makes it possible to
+            replay same response multiple times.
+            """
         )
         self.add_option(
             "refresh_server_playback", True, bool,
+            """
+            Refresh server replay responses by adjusting date, expires and
+            last-modified headers, as well as adjusting cookie expiration.
+            """
         )
         self.add_option(
             "rfile", None, Optional[str],
@@ -106,8 +112,7 @@ class Options(optmanager.OptManager):
         self.add_option(
             "scripts", [], Sequence[str],
             """
-                Run a script. Surround with quotes to pass script arguments. Can
-                be passed multiple times.
+            Execute a script.
             """
         )
         self.add_option(
@@ -116,7 +121,10 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "replacements", [], Sequence[str],
-            "Replacement patterns."
+            """
+            Replacement patterns of the form "/pattern/regex/replacement", where
+            the separator can be any character.
+            """
         )
         self.add_option(
             "replacement_files", [], Sequence[str],
@@ -127,12 +135,14 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "server_replay_use_headers", [], Sequence[str],
-            "Request headers to be considered during replay. "
-            "Can be passed multiple times."
+            "Request headers to be considered during replay."
         )
         self.add_option(
             "setheaders", [], Sequence[str],
-            help="Header set pattern."
+            """
+            Header set pattern of the form "/pattern/header/value", where the
+            separator can be any character.
+            """
         )
         self.add_option(
             "server_replay", [], Sequence[str],
@@ -158,10 +168,13 @@ class Options(optmanager.OptManager):
             "verbosity", 2, int,
             "Log verbosity."
         )
-        self.add_option("default_contentview", "auto", str)
+        self.add_option(
+            "default_contentview", "auto", str,
+            "The default content view mode."
+        )
         self.add_option(
             "streamfile", None, Optional[str],
-            help="Write flows to file. Prefix path with + to append."
+            "Write flows to file. Prefix path with + to append."
         )
         self.add_option(
             "server_replay_ignore_content", False, bool,
@@ -170,22 +183,24 @@ class Options(optmanager.OptManager):
         self.add_option(
             "server_replay_ignore_params", [], Sequence[str],
             """
-                Request's parameters to be ignored while searching for a saved
-                flow to replay. Can be passed multiple times.
+            Request's parameters to be ignored while searching for a saved flow
+            to replay. Can be passed multiple times.
             """
         )
         self.add_option(
             "server_replay_ignore_payload_params", [], Sequence[str],
             """
-                Request's payload parameters (application/x-www-form-urlencoded
-                or multipart/form-data) to be ignored while searching for a
-                saved flow to replay. Can be passed multiple times.
+            Request's payload parameters (application/x-www-form-urlencoded or
+            multipart/form-data) to be ignored while searching for a saved flow
+            to replay.
             """
         )
         self.add_option(
             "server_replay_ignore_host", False, bool,
-            "Ignore request's destination host while searching for a saved"
-            " flow to replay"
+            """
+            Ignore request's destination host while searching for a saved flow
+            to replay.
+            """
         )
 
         # Proxy options
@@ -206,13 +221,17 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "add_upstream_certs_to_client_chain", False, bool,
-            "Add all certificates of the upstream server to the certificate chain "
-            "that will be served to the proxy client, as extras."
+            """
+            Add all certificates of the upstream server to the certificate chain
+            that will be served to the proxy client, as extras.
+            """
         )
         self.add_option(
             "body_size_limit", None, Optional[str],
-            "Byte size limit of HTTP request and response bodies."
-            " Understands k/m/g suffixes, i.e. 3m for 3 megabytes."
+            """
+            Byte size limit of HTTP request and response bodies. Understands
+            k/m/g suffixes, i.e. 3m for 3 megabytes.
+            """
         )
         self.add_option(
             "cadir", CA_DIR, str,
@@ -221,7 +240,7 @@ class Options(optmanager.OptManager):
         self.add_option(
             "certs", [], Sequence[str],
             """
-            Add an SSL certificate. SPEC is of the form "[domain=]path". The
+            SSL certificates. SPEC is of the form "[domain=]path". The
             domain may include a wildcard, and is equal to "*" if not specified.
             The file at path is a certificate in PEM format. If a private key is
             included in the PEM, it is used, else the default key in the conf
@@ -278,8 +297,10 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "keep_host_header", False, bool,
-            "Reverse Proxy: Keep the original host header instead of rewriting it"
-            " to the reverse proxy target."
+            """
+            Reverse Proxy: Keep the original host header instead of rewriting it
+            to the reverse proxy target.
+            """
         )
 
         self.add_option(
@@ -289,9 +310,11 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "http2_priority", False, bool,
-            "Enable/disable PRIORITY forwarding for HTTP/2 connections. "
-            "PRIORITY forwarding is disabled by default, "
-            "because some webservers fail to implement the RFC properly.",
+            """
+            PRIORITY forwarding for HTTP/2 connections. PRIORITY forwarding is
+            disabled by default, because some webservers fail to implement the
+            RFC properly.
+            """
         )
         self.add_option(
             "websocket", True, bool,
@@ -306,8 +329,10 @@ class Options(optmanager.OptManager):
 
         self.add_option(
             "spoof_source_address", False, bool,
-            "Use the client's IP for server-side connections. "
-            "Combine with --upstream-bind-address to spoof a fixed source address."
+            """
+            Use the client's IP for server-side connections. Combine with
+            --upstream-bind-address to spoof a fixed source address.
+            """
         )
         self.add_option(
             "upstream_auth", None, Optional[str],
@@ -318,16 +343,18 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "ssl_version_client", "secure", str,
-            "Set supported SSL/TLS versions for client connections. "
-            "SSLv2, SSLv3 and 'all' are INSECURE. Defaults to secure, which "
-            "is TLS1.0+.",
+            """
+            Set supported SSL/TLS versions for client connections. SSLv2, SSLv3
+            and 'all' are INSECURE. Defaults to secure, which is TLS1.0+.
+            """,
             choices=tcp.sslversion_choices.keys(),
         )
         self.add_option(
             "ssl_version_server", "secure", str,
-            "Set supported SSL/TLS versions for server connections. "
-            "SSLv2, SSLv3 and 'all' are INSECURE. Defaults to secure, "
-            "which is TLS1.0+.",
+            """
+            Set supported SSL/TLS versions for server connections. SSLv2, SSLv3
+            and 'all' are INSECURE. Defaults to secure, which is TLS1.0+.
+            """,
             choices=tcp.sslversion_choices.keys(),
         )
         self.add_option(
@@ -336,8 +363,10 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "ssl_verify_upstream_trusted_cadir", None, Optional[str],
-            "Path to a directory of trusted CA certificates for upstream "
-            "server verification prepared using the c_rehash tool."
+            """
+            Path to a directory of trusted CA certificates for upstream server
+            verification prepared using the c_rehash tool.
+            """
         )
         self.add_option(
             "ssl_verify_upstream_trusted_ca", None, Optional[str],
@@ -368,7 +397,7 @@ class Options(optmanager.OptManager):
         )
         self.add_option(
             "console_palette", "dark", Optional[str],
-            help="Select color palette: " + ", ".join(console_palettes),
+            "Color palette.",
             choices=sorted(console_palettes),
         )
         self.add_option(
@@ -384,7 +413,10 @@ class Options(optmanager.OptManager):
             "Flow sort order.",
             choices=view_orders,
         )
-        self.add_option("console_order_reversed", False, bool)
+        self.add_option(
+            "console_order_reversed", False, bool,
+            "Reverse the sorting order."
+        )
 
         self.add_option(
             "filter", None, Optional[str],
@@ -410,7 +442,10 @@ class Options(optmanager.OptManager):
         )
 
         # Dump options
-        self.add_option("filtstr", None, Optional[str])
+        self.add_option(
+            "filtstr", None, Optional[str],
+            "The filter string for mitmdump"
+        )
         self.add_option(
             "flow_detail", 1, int,
             "Flow detail display level"

mitmproxy/optmanager.py

@@ -28,7 +28,7 @@ class _Option:
         name: str,
         default: typing.Any,
         typespec: typing.Type,
-        help: typing.Optional[str],
+        help: str,
         choices: typing.Optional[typing.Sequence[str]]
     ) -> None:
         typecheck.check_type(name, default, typespec)
@@ -103,7 +103,7 @@ class OptManager:
         name: str,
         default: typing.Any,
         typespec: typing.Type,
-        help: typing.Optional[str] = None,
+        help: str,
         choices: typing.Optional[typing.Sequence[str]] = None
     ) -> None:
         if name in self._options:
@@ -404,7 +404,7 @@ class OptManager:
                 action="append",
                 type=str,
                 dest=optname,
-                help=o.help,
+                help=o.help + " May be passed multiple times.",
                 metavar=metavar,
                 choices=o.choices,
             )
@@ -421,7 +421,6 @@ def dump(opts):
     for k in sorted(opts.keys()):
         o = opts._options[k]
         s[k] = o.default
-        if o.help:
         s.yaml_set_comment_before_after_key(
             k,
             before = "\n" + "\n".join(textwrap.wrap(

mitmproxy/tools/cmdline.py

@@ -91,26 +91,12 @@ def common_options(parser, opts):
     opts.make_parser(group, "server_replay_nopop")
 
     # Replacements
-    group = parser.add_argument_group(
-        "Replacements",
-        """
-            Replacements are of the form "/pattern/regex/replacement", where
-            the separator can be any character. Please see the documentation
-            for more information.
-        """.strip()
-    )
+    group = parser.add_argument_group("Replacements")
     opts.make_parser(group, "replacements", metavar="PATTERN")
     opts.make_parser(group, "replacement_files", metavar="PATTERN")
 
     # Set headers
-    group = parser.add_argument_group(
-        "Set Headers",
-        """
-            Header specifications are of the form "/pattern/header/value",
-            where the separator can be any character. Please see the
-            documentation for more information.
-        """.strip()
-    )
+    group = parser.add_argument_group("Set Headers")
     opts.make_parser(group, "setheaders", metavar="PATTERN")
 
     # Proxy authentication
@@ -149,8 +135,8 @@ def mitmdump(opts):
         'filter_args',
         nargs="...",
         help="""
-            Filter view expression, used to only show flows that match a certain filter.
-            See help in mitmproxy for filter expression syntax.
+            Filter view expression, used to only show flows that match a certain
+            filter. See help in mitmproxy for filter expression syntax.
         """
     )
     return parser

test/mitmproxy/test_optmanager.py

@@ -13,36 +13,36 @@ from mitmproxy.test import tutils
 class TO(optmanager.OptManager):
     def __init__(self):
         super().__init__()
-        self.add_option("one", None, typing.Optional[int])
-        self.add_option("two", 2, typing.Optional[int])
-        self.add_option("bool", False, bool)
+        self.add_option("one", None, typing.Optional[int], "help")
+        self.add_option("two", 2, typing.Optional[int], "help")
+        self.add_option("bool", False, bool, "help")
 
 
 class TD(optmanager.OptManager):
     def __init__(self):
         super().__init__()
-        self.add_option("one", "done", str)
-        self.add_option("two", "dtwo", str)
+        self.add_option("one", "done", str, "help")
+        self.add_option("two", "dtwo", str, "help")
 
 
 class TD2(TD):
     def __init__(self):
         super().__init__()
-        self.add_option("three", "dthree", str)
-        self.add_option("four", "dfour", str)
+        self.add_option("three", "dthree", str, "help")
+        self.add_option("four", "dfour", str, "help")
 
 
 class TM(optmanager.OptManager):
     def __init__(self):
         super().__init__()
-        self.add_option("two", ["foo"], typing.Sequence[str])
-        self.add_option("one", None, typing.Optional[str])
+        self.add_option("two", ["foo"], typing.Sequence[str], "help")
+        self.add_option("one", None, typing.Optional[str], "help")
 
 
 def test_add_option():
     o = TO()
     with pytest.raises(ValueError, match="already exists"):
-        o.add_option("one", None, typing.Optional[int])
+        o.add_option("one", None, typing.Optional[int], "help")
 
 
 def test_defaults():
@@ -291,13 +291,13 @@ def test_dump():
 class TTypes(optmanager.OptManager):
     def __init__(self):
         super().__init__()
-        self.add_option("str", "str", str)
-        self.add_option("optstr", "optstr", typing.Optional[str])
-        self.add_option("bool", False, bool)
-        self.add_option("int", 0, int)
-        self.add_option("optint", 0, typing.Optional[int])
-        self.add_option("seqstr", [], typing.Sequence[str])
-        self.add_option("unknown", 0.0, float)
+        self.add_option("str", "str", str, "help")
+        self.add_option("optstr", "optstr", typing.Optional[str], "help", "help")
+        self.add_option("bool", False, bool, "help")
+        self.add_option("int", 0, int, "help")
+        self.add_option("optint", 0, typing.Optional[int], "help")
+        self.add_option("seqstr", [], typing.Sequence[str], "help")
+        self.add_option("unknown", 0.0, float, "help")
 
 
 def test_make_parser():