Merge branch 'master' into v10.15.0

Author: willmcgugan

CHANGELOG.md

@@ -41,6 +41,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Allowed `__rich__` to work recursively
 - Allowed Text classes to work with sep in print https://github.com/willmcgugan/rich/issues/1689
 
+### Added
+
+- Added a `rich.text.Text.from_ansi` helper method for handling pre-formatted input strings https://github.com/willmcgugan/rich/issues/1670
+
 ## [10.13.0] - 2021-11-07
 
 ### Added

CONTRIBUTORS.md

@@ -23,4 +23,5 @@ The following people have contributed to the development of Rich:
 - [Clément Robert](https://github.com/neutrinoceros)
 - [Tushar Sadhwani](https://github.com/tusharsadhwani)
 - [Tim Savage](https://github.com/timsavage)
+- [Nicolas Simonds](https://github.com/0xDEC0DE)
 - [Gabriele N. Tornetta](https://github.com/p403n1x87)

README.pt-br.md

@@ -125,7 +125,7 @@ Confira a [documentação do inspect](https://rich.readthedocs.io/en/latest/refe
 
 # A biblioteca Rich
 
-O Rich possui vários _renderizaveis_ nativos que podem ser usados para criar outputs elegantes no seu CLI e ajudar a debugar o código.
+O Rich possui vários _renderizáveis_ nativos que podem ser usados para criar outputs elegantes no seu CLI e ajudar a debugar o código.
 
 Clique nos itens a seguir para expandir os detalhes:
 

docs/source/live.rst

@@ -5,7 +5,7 @@ Live Display
 
 Progress bars and status indicators use a *live* display to animate parts of the terminal. You can build custom live displays with the :class:`~rich.live.Live` class. 
 
-For a demonstration of a live display, run the following command:
+For a demonstration of a live display, run the following command::
 
     python -m rich.live
 

docs/source/text.rst

@@ -26,6 +26,11 @@ Alternatively, you can construct styled text by calling :meth:`~rich.text.Text.a
     text.append(" World!")
     console.print(text)
 
+If you would like to use text that is already formatted with ANSI codes, call :meth:`~rich.text.Text.from_ansi` to convert it to a ``Text`` object:
+
+    text = Text.from_ansi("\033[1mHello, World!\033[0m")
+    console.print(text.spans)
+
 Since building Text instances from parts is a common requirement, Rich offers :meth:`~rich.text.Text.assemble` which will combine strings or pairs of string and Style, and return a Text instance. The follow example is equivalent to the code above::
 
     text = Text.assemble(("Hello", "bold magenta"), " World!")

poetry.lock

@@ -40,7 +40,7 @@ jupyter = ["ipywidgets"]
 
 [tool.poetry.dev-dependencies]
 pytest = "^6.2.5"
-black = "^21.10b0"
+black = "^21.11b1"
 mypy = "^0.910"
 pytest-cov = "^3.0.0"
 attrs = "^21.2.0"

pyproject.toml

@@ -242,6 +242,40 @@ def from_markup(
         rendered_text.overflow = overflow
         return rendered_text
 
+    @classmethod
+    def from_ansi(
+        cls,
+        text: str,
+        *,
+        style: Union[str, Style] = "",
+        justify: Optional["JustifyMethod"] = None,
+        overflow: Optional["OverflowMethod"] = None,
+        no_wrap: Optional[bool] = None,
+        end: str = "\n",
+        tab_size: Optional[int] = 8,
+    ) -> "Text":
+        """Create a Text object from pre-formatted ANSI.
+
+        Args:
+            text (str): A string containing ANSI color codes.
+            style (Union[str, Style], optional): Base style for text. Defaults to "".
+            justify (str, optional): Justify method: "left", "center", "full", "right". Defaults to None.
+            overflow (str, optional): Overflow method: "crop", "fold", "ellipsis". Defaults to None.
+            no_wrap (bool, optional): Disable text wrapping, or None for default. Defaults to None.
+            end (str, optional): Character to end text with. Defaults to "\\\\n".
+            tab_size (int): Number of spaces per tab, or ``None`` to use ``console.tab_size``. Defaults to 8.
+        """
+        from .ansi import AnsiDecoder
+
+        decoded_text = AnsiDecoder().decode_line(text)
+        decoded_text.justify = justify
+        decoded_text.overflow = overflow
+        decoded_text.no_wrap = no_wrap
+        decoded_text.end = end
+        decoded_text.tab_size = tab_size
+        decoded_text.stylize(style)
+        return decoded_text
+
     @classmethod
     def styled(
         cls,

rich/text.py

@@ -95,6 +95,15 @@ def test_from_markup():
     assert text._spans == [Span(7, 13, "bold")]
 
 
+def test_from_ansi():
+    text = Text.from_ansi("Hello, \033[1mWorld!\033[0m")
+    text2 = Text.from_ansi("Hello, \033[1mWorld!\033[0m", style="red")
+    assert str(text) == "Hello, World!"
+    assert text._spans == [Span(7, 13, Style(bold=True))]
+    assert str(text2) == "Hello, World!"
+    assert text2._spans == [Span(7, 13, Style(bold=True)), Span(0, 13, "red")]
+
+
 def test_copy():
     test = Text()
     test.append("Hello", "bold")