From 06279f760578f5721c9f66e4870d4b6e6daee6aa Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Mon, 2 Mar 2020 17:29:32 +0000 Subject: [PATCH] docs --- docs/source/console.rst | 2 +- docs/source/markup.rst | 4 ++-- docs/source/reference/theme.rst | 6 ++++++ docs/source/style.rst | 8 ++++---- docs/source/tables.rst | 2 +- docs/source/text.rst | 4 ++-- rich/console.py | 5 +---- rich/table.py | 12 +++++------- rich/theme.py | 13 ++++--------- 9 files changed, 26 insertions(+), 30 deletions(-) create mode 100644 docs/source/reference/theme.rst diff --git a/docs/source/console.rst b/docs/source/console.rst index d1a42bfe..0bcc6796 100644 --- a/docs/source/console.rst +++ b/docs/source/console.rst @@ -44,7 +44,7 @@ The :meth:`~rich.console.Console.log` methods offers the same capabilities as pr 
[16:32:08] Hello, World!                                         <stdin>:1
-To help with debugging, the log() method has a ``log_locals`` parameter. If you set this to ``True`` Rich will display a table of local variables where the method was called. +To help with debugging, the log() method has a ``log_locals`` parameter. If you set this to ``True``, Rich will display a table of local variables where the method was called. Exporting diff --git a/docs/source/markup.rst b/docs/source/markup.rst index f071ca2d..623f83ca 100644 --- a/docs/source/markup.rst +++ b/docs/source/markup.rst @@ -20,8 +20,8 @@ For strikethrough, wrap the text in tildes. e.g. ``~this has a line through it~` For code, wrap the text in backticks. e.g. ```import this``` -Styles ------- +Styling +------- For other styles and color, you can use a syntax similar to bbcode. If you write the style (see :ref:`styles`) in square brackets, i.e. ``[bold red]``, that style will apply until it is *closed* with a corresponding ``[/bold red]``. diff --git a/docs/source/reference/theme.rst b/docs/source/reference/theme.rst new file mode 100644 index 00000000..14fb919f --- /dev/null +++ b/docs/source/reference/theme.rst @@ -0,0 +1,6 @@ +rich.theme +========== + +.. automodule:: rich.theme + :members: Theme + diff --git a/docs/source/style.rst b/docs/source/style.rst index 2162d186..363eeb34 100644 --- a/docs/source/style.rst +++ b/docs/source/style.rst @@ -66,9 +66,9 @@ You can parse a style definition explicitly with the :meth:`~rich.style.Style.pa Style Themes ------------ -If you re-use styles it can be a maintenance headache if you ever want to modify an attribute or color -- you would have to change every line where the style is used. Rich provides a :class:`rich.theme.Theme` class which you can use to pre-define styles, so if you ever need to modify a style you only need change one file. +If you re-use styles it can be a maintenance headache if you ever want to modify an attribute or color -- you would have to change every line where the style is used. Rich provides a :class:`rich.theme.Theme` class which you can use to define custom styles that you can refer to by name. That way you only need update your styles in one place. -Style themes can also make your code more semantic, for instance a style called ``"warning"`` better expresses intent that ``"italic magenta underline"``. +Style themes can make your code more semantic, for instance a style called ``"warning"`` better expresses intent that ``"italic magenta underline"``. To use a style theme, construct a :class:`rich.theme.Theme` instance and pass it to the :class:`~rich.console.Console` constructor. Here's an example:: @@ -92,6 +92,6 @@ If you prefer you can write your styles in an external config file rather than i [styles] info = dim cyan warning = magenta - danger bold red + danger = bold red -You can read these files with the :method:`~rich.theme.Theme.read` method. +You can read these files with the :meth:`~rich.theme.Theme.read` method. diff --git a/docs/source/tables.rst b/docs/source/tables.rst index 66b93ac9..f5916bd6 100644 --- a/docs/source/tables.rst +++ b/docs/source/tables.rst @@ -3,7 +3,7 @@ Tables Rich's :class:`~rich.table.Table` class offers a variety ways of rendering tabular data to the terminal. -To render a table, construct a :class:`~rich.table.Table` object, add data, then call :meth:`~rich.console.Console.print` or :meth:`~rich.console.Console.log` to write it to the console. +To render a table, construct a :class:`~rich.table.Table` object, add columns with :meth:`~rich.table.Table.add_column`, and rows with :meth:`~rich.table.Table.add_row` -- then print it to the console. Here's an example:: diff --git a/docs/source/text.rst b/docs/source/text.rst index ea4e2f99..590619b9 100644 --- a/docs/source/text.rst +++ b/docs/source/text.rst @@ -3,11 +3,11 @@ Rich Text Rich has a :class:`~rich.text.Text` class for text that may be marked up with color and style attributes. You can consider this class to be like a mutable string with style information. The methods on the Text() instance are similar to a Python ``str`` but are designed to preserve any style information. -One way to add a style to Text is the :meth:`~tich.text.Text.styleize` method which applies a style to a start and end offset. Here is an example:: +One way to add a style to Text is the :meth:`~tich.text.Text.stylize` method which applies a style to a start and end offset. Here is an example:: from rich.text import Text text = Text("Hello, World!") - text.styleize(0, 6, "bold magenta") + text.stylize(0, 6, "bold magenta") console.print(text) This will print "Hello, World!" to the terminal, with the first word in bold magenta. diff --git a/rich/console.py b/rich/console.py index 95b27153..f02ee192 100644 --- a/rich/console.py +++ b/rich/console.py @@ -719,8 +719,6 @@ class Console: Returns: List[ConsoleRenderable]: A list of things to render. """ - from .text import Text - sep_text = Text(sep, end=end) renderables: List[ConsoleRenderable] = [] append = renderables.append @@ -753,7 +751,7 @@ class Console: check_text() append(Pretty(renderable, highlighter=_highlighter)) else: - append_text(_highlighter(repr(renderable))) + append_text(_highlighter(str(renderable))) check_text() return renderables @@ -788,7 +786,6 @@ class Console: r"""Print to the console. Args: - objects (positional args): Objects to log to the terminal. sep (str, optional): String to write between print data. Defaults to " ". end (str, optional): String to write at end of print data. Defaults to "\n". diff --git a/rich/table.py b/rich/table.py index a868a727..03202f2c 100644 --- a/rich/table.py +++ b/rich/table.py @@ -19,7 +19,6 @@ if TYPE_CHECKING: from .console import ( Console, ConsoleOptions, - ConsoleRenderable, JustifyValues, RenderableType, RenderResult, @@ -147,8 +146,8 @@ class Table: def add_column( self, - header: Union[str, "ConsoleRenderable"] = "", - footer: Union[str, "ConsoleRenderable"] = "", + header: "RenderableType" = "", + footer: "RenderableType" = "", header_style: Union[str, Style] = None, footer_style: Union[str, Style] = None, style: Union[str, Style] = None, @@ -160,9 +159,9 @@ class Table: """Add a column to the table. Args: - header (Union[str, ConsoleRenderable], optional): Text or renderable for the header. + header (RenderableType, optional): Text or renderable for the header. Defaults to "". - footer (Union[str, ConsoleRenderable], optional): Text or renderable for the footer. + footer (RenderableType, optional): Text or renderable for the footer. Defaults to "". header_style (Union[str, Style], optional): Style for the header. Defaults to "none". footer_style (Union[str, Style], optional): Style for the header. Defaults to "none". @@ -196,7 +195,6 @@ class Table: Raises: errors.NotRenderableError: If you add something that can't be rendered. """ - from .console import ConsoleRenderable def add_cell(column: Column, renderable: "RenderableType") -> None: column._cells.append(renderable) @@ -456,7 +454,7 @@ if __name__ == "__main__": # pragma: no cover from .console import Console from . import box - c = Console(markup=False) + c = Console(markup=True) table = Table( Column( "Foo", footer=Text("Total", justify="right"), footer_style="bold", ratio=1 diff --git a/rich/theme.py b/rich/theme.py index f5c6a5d7..566ecd0f 100644 --- a/rich/theme.py +++ b/rich/theme.py @@ -14,21 +14,16 @@ class Theme: """ def __init__(self, styles: Dict[str, Style] = None, inherit: bool = True): - if inherit: - self.styles = DEFAULT_STYLES.copy() - else: - self.styles = {} + self.styles = DEFAULT_STYLES.copy() if inherit else {} if styles is not None: self.styles.update(styles) @property def config(self) -> str: """Get contents of a config file for this theme.""" - config_lines = ["[styles]"] - append = config_lines.append - for name, style in sorted(self.styles.items()): - append(f"{name} = {style}") - config = "\n".join(config_lines) + config = "[styles]\n" + "\n".join( + f"{name} = {style}" for name, style in sorted(self.styles.items()) + ) return config @classmethod