Merge pull request #1964 from davep/devtools-terminal-warning

Add a post-run warning hook to `textual run`

FAQ.md

@@ -7,6 +7,7 @@
 - [How can I select and copy text in a Textual app?](#how-can-i-select-and-copy-text-in-a-textual-app)
 - [How do I center a widget in a screen?](#how-do-i-center-a-widget-in-a-screen)
 - [How do I pass arguments to an app?](#how-do-i-pass-arguments-to-an-app)
+- [Why doesn't Textual look good on macOS?](#why-doesn't-textual-look-good-on-macos)
 - [Why doesn't Textual support ANSI themes?](#why-doesn't-textual-support-ansi-themes)
 
 <a name="does-textual-support-images"></a>
@@ -172,6 +173,16 @@ Greetings(to_greet="davep").run()
 Greetings("Well hello", "there").run()
 ```
 
+<a name="why-doesn't-textual-look-good-on-macos"></a>
+## Why doesn't Textual look good on macOS?
+
+The default macOS `Terminal.app` is getting rather old now; it has problems
+such as being limited to just 256 colors, being slow to draw and not all
+box-drawing characters are fully-supported. We recommend installing a newer
+terminal such as [iTerm2](https://iterm2.com/),
+[Kitty](https://sw.kovidgoyal.net/kitty/) or
+[WezTerm](https://wezfurlong.org/wezterm/).
+
 <a name="why-doesn't-textual-support-ansi-themes"></a>
 ## Why doesn't Textual support ANSI themes?
 

questions/why-looks-bad-on-macos.question.md

@@ -0,0 +1,18 @@
+---
+title: "Why doesn't Textual look good on macOS?"
+alt_titles:
+  - "looks bad on macOS"
+  - "dashed lines on macOS"
+  - "broken borders on macOS"
+  - "pale colors on macOS"
+  - "pale colours on macOS"
+  - "mac terminal"
+  - "macOS terminal"
+---
+
+The default macOS `Terminal.app` is getting rather old now; it has problems
+such as being limited to just 256 colors, being slow to draw and not all
+box-drawing characters are fully-supported. We recommend installing a newer
+terminal such as [iTerm2](https://iterm2.com/),
+[Kitty](https://sw.kovidgoyal.net/kitty/) or
+[WezTerm](https://wezfurlong.org/wezterm/).

src/textual/cli/cli.py

@@ -38,6 +38,38 @@ def console(verbose: bool, exclude: list[str]) -> None:
         console.show_cursor(True)
 
 
+def _post_run_warnings() -> None:
+    """Look for and report any issues with the environment.
+
+    This is the right place to add code that looks at the terminal, or other
+    environmental issues, and if a problem is seen it should be printed so
+    the developer can see it easily.
+    """
+    import os
+    import platform
+
+    from rich.console import Console
+    from rich.panel import Panel
+
+    console = Console()
+
+    # Add any test/warning pair here. The list contains a tuple where the
+    # first item is `True` if a problem situation is detected, and the
+    # second item is a message to show the user on exit from `textual run`.
+    warnings = [
+        (
+            platform.system() == "Darwin"
+            and os.environ.get("TERM_PROGRAM") == "Apple_Terminal",
+            "The default terminal app on macOS is limited to 256 colors. See our FAQ for more details:\n\n"
+            "https://github.com/Textualize/textual/blob/main/FAQ.md#why-doesn't-textual-look-good-on-macos",
+        )
+    ]
+
+    for concerning, concern in warnings:
+        if concerning:
+            console.print(Panel.fit(f"⚠️ [bold green] {concern}[/]", style="cyan"))
+
+
 @run.command(
     "run",
     context_settings={
@@ -119,6 +151,8 @@ def run_app(import_name: str, dev: bool, press: str, screenshot: int | None) ->
         console.print("[b]The app returned:")
         console.print(Pretty(result))
 
+    _post_run_warnings()
+
 
 @run.command("borders")
 def borders():