From e925eb7c81f34f97fda6fbd49623caabb3f457e8 Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 7 Mar 2023 11:15:45 +0000 Subject: [PATCH 1/7] Add a post-run warning hook, and test for macOS Terminal.app This will change, this is more of a placeholder to test things. I'm next going to write a FAQ and then we'll point to that. --- src/textual/cli/cli.py | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/textual/cli/cli.py b/src/textual/cli/cli.py index 16ca139cb..05a79646d 100644 --- a/src/textual/cli/cli.py +++ b/src/textual/cli/cli.py @@ -38,6 +38,34 @@ 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 + + console = Console() + + warnings = [ + ( + platform.system() == "Darwin" + and os.environ.get("TERM_PROGRAM") == "Apple_Terminal", + "The default terminal app is limited to 256 colors. We recommend installing a newer terminal " + "such as iTerm2, Kitty, or WezTerm.", + ) + ] + + for concering, concern in warnings: + if concering: + console.print(f"[bold yellow]{concern}[/]") + + @run.command( "run", context_settings={ @@ -119,6 +147,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(): From 56ba7d9cc7b5429e7c6f360959121fce1a1f3c53 Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 7 Mar 2023 11:26:03 +0000 Subject: [PATCH 2/7] Add a FAQ about the default macOS terminal.app --- FAQ.md | 10 ++++++++++ questions/why-looks-bad-on-macos.question.md | 17 +++++++++++++++++ 2 files changed, 27 insertions(+) create mode 100644 questions/why-looks-bad-on-macos.question.md diff --git a/FAQ.md b/FAQ.md index 239d53570..11d514b54 100644 --- a/FAQ.md +++ b/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) @@ -104,6 +105,15 @@ Greetings(to_greet="davep").run() Greetings("Well hello", "there").run() ``` + +## Why doesn't Textual look good on macOS? + +The default macOS `Terminal.app` is getting rather old now, and has problems +such as being limited to just 256 colors. We recommend installing a newer +terminal such as [iTerm2](https://iterm2.com/), +[Kitty](https://sw.kovidgoyal.net/kitty/) or +[WezTerm](https://wezfurlong.org/wezterm/). + ## Why doesn't Textual support ANSI themes? diff --git a/questions/why-looks-bad-on-macos.question.md b/questions/why-looks-bad-on-macos.question.md new file mode 100644 index 000000000..dada43b62 --- /dev/null +++ b/questions/why-looks-bad-on-macos.question.md @@ -0,0 +1,17 @@ +--- +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, and has problems +such as being limited to just 256 colors. We recommend installing a newer +terminal such as [iTerm2](https://iterm2.com/), +[Kitty](https://sw.kovidgoyal.net/kitty/) or +[WezTerm](https://wezfurlong.org/wezterm/). From ff532227d65aa872d3f9ad5912898b5c22a7e2f2 Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 7 Mar 2023 11:51:08 +0000 Subject: [PATCH 3/7] Reword the warning and link it to the FAQ entry --- src/textual/cli/cli.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/textual/cli/cli.py b/src/textual/cli/cli.py index 05a79646d..4ac6da2c3 100644 --- a/src/textual/cli/cli.py +++ b/src/textual/cli/cli.py @@ -49,6 +49,7 @@ def _post_run_warnings() -> None: import platform from rich.console import Console + from rich.panel import Panel console = Console() @@ -56,14 +57,14 @@ def _post_run_warnings() -> None: ( platform.system() == "Darwin" and os.environ.get("TERM_PROGRAM") == "Apple_Terminal", - "The default terminal app is limited to 256 colors. We recommend installing a newer terminal " - "such as iTerm2, Kitty, or WezTerm.", + "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 concering, concern in warnings: if concering: - console.print(f"[bold yellow]{concern}[/]") + console.print(Panel.fit(f"⚠️ [bold green] {concern}[/]", style="cyan")) @run.command( From 3039a3fc6214426cfffe222fb59abbda01acbbe4 Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 7 Mar 2023 12:50:35 +0000 Subject: [PATCH 4/7] Add a comment to explain the content of the warning list --- src/textual/cli/cli.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/textual/cli/cli.py b/src/textual/cli/cli.py index 4ac6da2c3..a2c8a5849 100644 --- a/src/textual/cli/cli.py +++ b/src/textual/cli/cli.py @@ -53,6 +53,9 @@ def _post_run_warnings() -> None: 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" From c049888f5503e009da346708818f5ff2cc47f3a2 Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 7 Mar 2023 12:52:43 +0000 Subject: [PATCH 5/7] Flesh out the list of problems with Terminal.app --- questions/why-looks-bad-on-macos.question.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/questions/why-looks-bad-on-macos.question.md b/questions/why-looks-bad-on-macos.question.md index dada43b62..9808a3c0e 100644 --- a/questions/why-looks-bad-on-macos.question.md +++ b/questions/why-looks-bad-on-macos.question.md @@ -10,8 +10,9 @@ alt_titles: - "macOS terminal" --- -The default macOS `Terminal.app` is getting rather old now, and has problems -such as being limited to just 256 colors. We recommend installing a newer +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/). From 2047fda57d4d23ad22e7598dc8965b82af6b1589 Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 7 Mar 2023 12:56:27 +0000 Subject: [PATCH 6/7] Rebuild the FAQ --- FAQ.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/FAQ.md b/FAQ.md index 11d514b54..29265366d 100644 --- a/FAQ.md +++ b/FAQ.md @@ -108,8 +108,9 @@ Greetings("Well hello", "there").run() ## Why doesn't Textual look good on macOS? -The default macOS `Terminal.app` is getting rather old now, and has problems -such as being limited to just 256 colors. We recommend installing a newer +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/). From 858d228da93745128e040426c864cd58bdf6a8f0 Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 7 Mar 2023 13:02:01 +0000 Subject: [PATCH 7/7] Fix a concerning typo --- src/textual/cli/cli.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/textual/cli/cli.py b/src/textual/cli/cli.py index a2c8a5849..c4d1da0a1 100644 --- a/src/textual/cli/cli.py +++ b/src/textual/cli/cli.py @@ -65,8 +65,8 @@ def _post_run_warnings() -> None: ) ] - for concering, concern in warnings: - if concering: + for concerning, concern in warnings: + if concerning: console.print(Panel.fit(f"⚠️ [bold green] {concern}[/]", style="cyan"))