|
1 | 1 |
|
2 | 2 | # Frequently Asked Questions |
3 | | -- [Why does emoji break alignment in a Table or Panel?](#why-does-emoji-break-alignment-in-a-table-or-panel) |
4 | | -- [Why does content in square brackets disappear?](#why-does-content-in-square-brackets-disappear) |
5 | | -- [python -m rich.spinner shows extra lines](#python--m-rich.spinner-shows-extra-lines) |
6 | 3 | - [How do I log a renderable?](#how-do-i-log-a-renderable) |
7 | | -- [Strange colors in console output.](#strange-colors-in-console-output.) |
| 4 | +- [How do I render console markup in RichHandler?](#how-do-i-render-console-markup-in-richhandler) |
| 5 | +- [Natively inserted ANSI escape sequence characters break alignment of Panel.](#natively-inserted-ansi-escape-sequence-characters-break-alignment-of-panel) |
| 6 | +- [python -m rich.spinner shows extra lines.](#python--m-richspinner-shows-extra-lines) |
| 7 | +- [Rich is automatically installing traceback handler.](#rich-is-automatically-installing-traceback-handler) |
| 8 | +- [Strange colors in console output.](#strange-colors-in-console-output) |
| 9 | +- [Why does content in square brackets disappear?](#why-does-content-in-square-brackets-disappear) |
| 10 | +- [Why does emoji break alignment in a Table or Panel?](#why-does-emoji-break-alignment-in-a-table-or-panel) |
8 | 11 |
|
9 | | -<a name="why-does-emoji-break-alignment-in-a-table-or-panel"></a> |
10 | | -## Why does emoji break alignment in a Table or Panel? |
| 12 | +<a name="how-do-i-log-a-renderable"></a> |
| 13 | +## How do I log a renderable? |
11 | 14 |
|
12 | | -Certain emoji take up double space within the terminal. Unfortunately, terminals don't always agree how wide a given character should be. |
| 15 | +Python's logging module is designed to work with strings. Consequently you won't be able to log Rich renderables (Table, Tree, etc) by calling `logger.debug` or other similar method. |
13 | 16 |
|
14 | | -Rich has no way of knowing how wide a character will be on any given terminal. This can break alignment in containers like Table and Panel, where Rich needs to know the width of the content. |
| 17 | +You could use the [capture](https://rich.readthedocs.io/en/latest/console.html#capturing-output) API to convert the renderable to a string and log that. However I would advise against it. |
15 | 18 |
|
16 | | -There are also *multiple codepoints* characters, such as country flags, and emoji modifiers, which produce wildly different results across terminal emulators. |
| 19 | +Logging supports configurable back-ends, which means that a log message could go somewhere other than the terminal -- which may not correctly render the formatting and style produced by Rich. |
17 | 20 |
|
18 | | -Fortunately, most characters will work just fine. But you may have to avoid using the emojis that break alignment. You will get good results if you stick to emoji released on or before version 9 of the Unicode database, |
| 21 | +If you are only logging with a file-handler to stdout, then you probably don't need to use the logging module at all. Consider using [Console.log](https://rich.readthedocs.io/en/latest/reference/console.html#rich.console.Console.log) which will render anything that you can print with Rich, with a timestamp. |
19 | 22 |
|
20 | | -<a name="why-does-content-in-square-brackets-disappear"></a> |
21 | | -## Why does content in square brackets disappear? |
| 23 | +<a name="how-do-i-render-console-markup-in-richhandler"></a> |
| 24 | +## How do I render console markup in RichHandler? |
22 | 25 |
|
23 | | -Rich will treat text within square brackets as *markup tags*, for instance `"[bold]This is bold[/bold]"`. |
| 26 | +Console markup won't work anywhere else, other than `RichHandler` -- which is why they are disabled by default. |
24 | 27 |
|
25 | | -If you are printing strings with literally square brackets you can either disable markup, or escape your strings. |
26 | | -See the docs on [console markup](https://rich.readthedocs.io/en/latest/markup.html) for how to do this. |
| 28 | +See the docs if you want to [enable console markup](https://rich.readthedocs.io/en/latest/logging.html#logging-handler) in the logging handler. |
27 | 29 |
|
28 | | -<a name="python--m-rich.spinner-shows-extra-lines"></a> |
29 | | -## python -m rich.spinner shows extra lines |
| 30 | +<a name="natively-inserted-ansi-escape-sequence-characters-break-alignment-of-panel"></a> |
| 31 | +## Natively inserted ANSI escape sequence characters break alignment of Panel. |
30 | 32 |
|
31 | | -The spinner example is know to break on some terminals (Windows in particular). |
| 33 | +If you print ansi escape sequences for color and style you may find the output breaks your output. |
| 34 | +You may find that border characters in Panel and Table are in the wrong place, for example. |
32 | 35 |
|
33 | | -Some terminals don't display emoji with the correct width, which means Rich can't always align them accurately inside a panel. |
| 36 | +As a general rule, you should allow Rich to generate all ansi escape sequences, so it can correctly account for these invisible characters. |
| 37 | +If you can't avoid a string with escape codes, you can convert it to an equivalent `Text` instance with `Text.from_ansi`. |
34 | 38 |
|
35 | | -<a name="how-do-i-log-a-renderable"></a> |
36 | | -## How do I log a renderable? |
| 39 | +<a name="python--m-richspinner-shows-extra-lines"></a> |
| 40 | +## python -m rich.spinner shows extra lines. |
37 | 41 |
|
38 | | -Python's logging module is designed to work with strings. Consequently you won't be able to log Rich renderables (Table, Tree, etc) by calling `logger.debug` or other similar method. |
| 42 | +The spinner example is know to break on some terminals (Windows in particular). |
39 | 43 |
|
40 | | -You could use the [capture](https://rich.readthedocs.io/en/latest/console.html#capturing-output) API to convert the renderable to a string and log that. However I would advise against it. |
| 44 | +Some terminals don't display emoji with the correct width, which means Rich can't always align them accurately inside a panel. |
41 | 45 |
|
42 | | -Logging supports configurable back-ends, which means that a log message could go somewhere other than the terminal -- which may not correctly render the formatting and style produced by Rich. |
| 46 | +<a name="rich-is-automatically-installing-traceback-handler"></a> |
| 47 | +## Rich is automatically installing traceback handler. |
43 | 48 |
|
44 | | -If you are only logging with a file-handler to stdout, then you probably don't need to use the logging module at all. Consider using [Console.log](https://rich.readthedocs.io/en/latest/reference/console.html#rich.console.Console.log) which will render anything that you can print with Rich, with a timestamp. |
| 49 | +Rich will never install the traceback handler automatically. |
| 50 | + |
| 51 | +If you are getting Rich tracebacks and you don't want them, then some other piece of software is calling `rich.traceback.install()`. |
45 | 52 |
|
46 | | -<a name="strange-colors-in-console-output."></a> |
| 53 | +<a name="strange-colors-in-console-output"></a> |
47 | 54 | ## Strange colors in console output. |
48 | 55 |
|
49 | 56 | Rich will highlight certain patterns in your output such as numbers, strings, and other objects like IP addresses. |
50 | 57 |
|
51 | 58 | Occasionally this may also highlight parts of your output you didn't intend. See the [docs on highlighting](https://rich.readthedocs.io/en/latest/highlighting.html) for how to disable highlighting. |
52 | 59 |
|
| 60 | +<a name="why-does-content-in-square-brackets-disappear"></a> |
| 61 | +## Why does content in square brackets disappear? |
| 62 | + |
| 63 | +Rich will treat text within square brackets as *markup tags*, for instance `"[bold]This is bold[/bold]"`. |
| 64 | + |
| 65 | +If you are printing strings with literally square brackets you can either disable markup, or escape your strings. |
| 66 | +See the docs on [console markup](https://rich.readthedocs.io/en/latest/markup.html) for how to do this. |
| 67 | + |
| 68 | +<a name="why-does-emoji-break-alignment-in-a-table-or-panel"></a> |
| 69 | +## Why does emoji break alignment in a Table or Panel? |
| 70 | + |
| 71 | +Certain emoji take up double space within the terminal. Unfortunately, terminals don't always agree how wide a given character should be. |
| 72 | + |
| 73 | +Rich has no way of knowing how wide a character will be on any given terminal. This can break alignment in containers like Table and Panel, where Rich needs to know the width of the content. |
| 74 | + |
| 75 | +There are also *multiple codepoints* characters, such as country flags, and emoji modifiers, which produce wildly different results across terminal emulators. |
| 76 | + |
| 77 | +Fortunately, most characters will work just fine. But you may have to avoid using the emojis that break alignment. You will get good results if you stick to emoji released on or before version 9 of the Unicode database, |
| 78 | + |
53 | 79 | <hr> |
54 | 80 |
|
55 | 81 | Generated by [FAQtory](https://github.com/willmcgugan/faqtory) |
0 commit comments