run/README: Configuration infrastructure to enable/disable transparency.

This hooks up the underlying feature from the previous commit to
new configuration options possible in the zuliprc file, which can be
overridden by command-line options.

These take the same form as for notifications and autohide, with
- `transparency=enabled|disabled` in zuliprc
- `--transparency` or `-no-transparency` on the command-line

The default value for this option is to be disabled.

This value is not currently passed to the Controller, since the theme is
generated in run.py.

README updated to indicate new transparency configuration option.

Tests updated.

Author: neiljp

README.md

@@ -246,6 +246,11 @@ notify=disabled
 
 ## Color-depth: set to one of 1 (for monochrome), 16, 256, or 24bit
 color-depth=256
+
+## Transparency: set to 'enabled' to allow background transparency
+## This is highly dependent on a suitable terminal emulator, and support in the selected theme
+## Terminal emulators without this feature may show an arbitrary solid background color
+transparency=disabled
 ```
 
 > **NOTE:** Most of these configuration settings may be specified on the

tests/cli/test_run.py

@@ -143,6 +143,8 @@ def test_main_help(capsys: CaptureFixture[str], options: str) -> None:
         "--color-depth",
         "--notify",
         "--no-notify",
+        "--transparency",
+        "--no-transparency",
     }
     optional_argument_lines = {
         line[2:] for line in lines if len(line) > 2 and line[2] == "-"
@@ -203,6 +205,7 @@ def test_valid_zuliprc_but_no_connection(
         "   maximum footlinks value '3' specified from default config.",
         "   color depth setting '256' specified from default config.",
         "   notify setting 'disabled' specified from default config.",
+        "   transparency setting 'disabled' specified from default config.",
         "\x1b[91m",
         f"Error connecting to Zulip server: {server_connection_error}.\x1b[0m",
     ]
@@ -262,6 +265,7 @@ def test_warning_regarding_incomplete_theme(
         "   maximum footlinks value '3' specified from default config.",
         "   color depth setting '256' specified from default config.",
         "   notify setting 'disabled' specified from default config.",
+        "   transparency setting 'disabled' specified from default config.",
         "\x1b[91m",
         f"Error connecting to Zulip server: {server_connection_error}.\x1b[0m",
     ]
@@ -481,6 +485,7 @@ def test_successful_main_function_with_config(
         f"   maximum footlinks value {footlinks_output}",
         "   color depth setting '256' specified in zuliprc file.",
         "   notify setting 'enabled' specified in zuliprc file.",
+        "   transparency setting 'disabled' specified from default config.",
     ]
     assert lines == expected_lines
 

zulipterminal/cli/run.py

@@ -62,6 +62,7 @@ class SettingData(NamedTuple):
     "autohide": ("autohide", "no_autohide"),
     "notify": ("enabled", "disabled"),
     "exit_confirmation": ("enabled", "disabled"),
+    "transparency": ("enabled", "disabled"),
 }
 
 COLOR_DEPTH_ARGS_TO_DEPTHS: Dict[str, int] = {
@@ -80,13 +81,15 @@ class SettingData(NamedTuple):
     "color-depth": "256",
     "maximum-footlinks": "3",
     "exit_confirmation": "enabled",
+    "transparency": "disabled",
 }
 assert DEFAULT_SETTINGS["autohide"] in VALID_BOOLEAN_SETTINGS["autohide"]
 assert DEFAULT_SETTINGS["notify"] in VALID_BOOLEAN_SETTINGS["notify"]
 assert DEFAULT_SETTINGS["color-depth"] in COLOR_DEPTH_ARGS_TO_DEPTHS
 assert (
     DEFAULT_SETTINGS["exit_confirmation"] in VALID_BOOLEAN_SETTINGS["exit_confirmation"]
 )
+assert DEFAULT_SETTINGS["transparency"] in VALID_BOOLEAN_SETTINGS["transparency"]
 
 
 def in_color(color: str, text: str) -> str:
@@ -155,6 +158,22 @@ def parse_args(argv: List[str]) -> argparse.Namespace:
         help="do not mark messages as read in the session",
     )
 
+    transparency_group = parser.add_mutually_exclusive_group()
+    transparency_group.add_argument(
+        "--transparency",
+        dest="transparency",
+        action="store_const",
+        const="enabled",
+        help="enable transparent background (if supported by theme and terminal)",
+    )
+    transparency_group.add_argument(
+        "--no-transparency",
+        dest="transparency",
+        action="store_const",
+        const="disabled",
+        help="disable transparent background",
+    )
+
     notify_group = parser.add_mutually_exclusive_group()
     notify_group.add_argument(
         "--notify",
@@ -496,6 +515,11 @@ def main(options: Optional[List[str]] = None) -> None:
             theme_to_use = SettingData(real_theme_name, theme_to_use.source)
 
         ### Load overrides & validate remaining settings
+        if args.transparency:
+            zterm["transparency"] = SettingData(
+                args.transparency, ConfigSource.COMMANDLINE
+            )
+
         if args.autohide:
             zterm["autohide"] = SettingData(args.autohide, ConfigSource.COMMANDLINE)
 
@@ -553,22 +577,27 @@ def print_setting(setting: str, data: SettingData, suffix: str = "") -> None:
             print_setting("maximum footlinks value", zterm["maximum-footlinks"])
         print_setting("color depth setting", zterm["color-depth"])
         print_setting("notify setting", zterm["notify"])
+        print_setting("transparency setting", zterm["transparency"])
 
         ### Generate data not output to user, but into Controller
+        # Translate valid strings for boolean values into True/False
+        boolean_settings: Dict[str, bool] = dict()
+        for setting, valid_values in VALID_BOOLEAN_SETTINGS.items():
+            boolean_settings[setting] = zterm[setting].value == valid_values[0]
+
         # Generate urwid palette
         color_depth_str = zterm["color-depth"].value
         color_depth = COLOR_DEPTH_ARGS_TO_DEPTHS[color_depth_str]
+        transparency_enabled = boolean_settings["transparency"]
 
         theme_data = generate_theme(
             theme_to_use.value,
             color_depth=color_depth,
-            transparent_background=False,
+            transparent_background=transparency_enabled,
         )
 
-        # Translate valid strings for boolean values into True/False
-        boolean_settings: Dict[str, bool] = dict()
-        for setting, valid_boolean_values in VALID_BOOLEAN_SETTINGS.items():
-            boolean_settings[setting] = zterm[setting].value == valid_boolean_values[0]
+        # Avoid passing this to the Controller
+        boolean_settings.pop("transparency")
 
         Controller(
             config_file=zuliprc_path,