diff --git a/cmd2/__init__.py b/cmd2/__init__.py index d36aa1461..dbfb5faa0 100644 --- a/cmd2/__init__.py +++ b/cmd2/__init__.py @@ -99,7 +99,7 @@ # String Utils 'stylize', # Styles, - "Cmd2Style", + 'Cmd2Style', # Utilities 'categorize', 'CustomCompletionSettings', diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index 844ae83eb..68494f276 100644 --- a/cmd2/cmd2.py +++ b/cmd2/cmd2.py @@ -84,6 +84,7 @@ from prompt_toolkit.shortcuts import CompleteStyle, PromptSession, choice, set_title from rich.console import ( Group, + JustifyMethod, RenderableType, ) from rich.highlighter import ReprHighlighter @@ -1344,6 +1345,7 @@ def print_to( end: str = "\n", style: StyleType | None = None, soft_wrap: bool = True, + justify: JustifyMethod | None = None, emoji: bool = False, markup: bool = False, highlight: bool = False, @@ -1369,6 +1371,7 @@ def print_to( Tables, Panels, or Columns to ensure they render as expected. For example, when soft_wrap is True Panels truncate text which is wider than the terminal. + :param justify: justify method ("left", "center", "right", "full"). Defaults to None. :param emoji: If True, Rich will replace emoji codes (e.g., :smiley:) with their corresponding Unicode characters. Defaults to False. :param markup: If True, Rich will interpret strings with tags (e.g., [bold]hello[/bold]) @@ -1395,6 +1398,7 @@ def print_to( sep=sep, end=end, style=style, + justify=justify, soft_wrap=soft_wrap, **(rich_print_kwargs if rich_print_kwargs is not None else {}), ) @@ -1414,6 +1418,7 @@ def poutput( end: str = "\n", style: StyleType | None = None, soft_wrap: bool = True, + justify: JustifyMethod | None = None, emoji: bool = False, markup: bool = False, highlight: bool = False, @@ -1431,6 +1436,7 @@ def poutput( end=end, style=style, soft_wrap=soft_wrap, + justify=justify, emoji=emoji, markup=markup, highlight=highlight, @@ -1444,6 +1450,7 @@ def perror( end: str = "\n", style: StyleType | None = Cmd2Style.ERROR, soft_wrap: bool = True, + justify: JustifyMethod | None = None, emoji: bool = False, markup: bool = False, highlight: bool = False, @@ -1463,6 +1470,7 @@ def perror( end=end, style=style, soft_wrap=soft_wrap, + justify=justify, emoji=emoji, markup=markup, highlight=highlight, @@ -1475,6 +1483,7 @@ def psuccess( sep: str = " ", end: str = "\n", soft_wrap: bool = True, + justify: JustifyMethod | None = None, emoji: bool = False, markup: bool = False, highlight: bool = False, @@ -1491,6 +1500,7 @@ def psuccess( end=end, style=Cmd2Style.SUCCESS, soft_wrap=soft_wrap, + justify=justify, emoji=emoji, markup=markup, highlight=highlight, @@ -1503,6 +1513,7 @@ def pwarning( sep: str = " ", end: str = "\n", soft_wrap: bool = True, + justify: JustifyMethod | None = None, emoji: bool = False, markup: bool = False, highlight: bool = False, @@ -1519,6 +1530,7 @@ def pwarning( end=end, style=Cmd2Style.WARNING, soft_wrap=soft_wrap, + justify=justify, emoji=emoji, markup=markup, highlight=highlight, @@ -1597,6 +1609,7 @@ def pfeedback( end: str = "\n", style: StyleType | None = None, soft_wrap: bool = True, + justify: JustifyMethod | None = None, emoji: bool = False, markup: bool = False, highlight: bool = False, @@ -1618,6 +1631,7 @@ def pfeedback( end=end, style=style, soft_wrap=soft_wrap, + justify=justify, emoji=emoji, markup=markup, highlight=highlight, @@ -1630,6 +1644,7 @@ def pfeedback( end=end, style=style, soft_wrap=soft_wrap, + justify=justify, emoji=emoji, markup=markup, highlight=highlight, @@ -1644,6 +1659,7 @@ def ppaged( style: StyleType | None = None, chop: bool = False, soft_wrap: bool = True, + justify: JustifyMethod | None = None, emoji: bool = False, markup: bool = False, highlight: bool = False, @@ -1700,6 +1716,7 @@ def ppaged( sep=sep, end=end, style=style, + justify=justify, soft_wrap=soft_wrap, **(rich_print_kwargs if rich_print_kwargs is not None else {}), ) @@ -1748,6 +1765,7 @@ def ppaged( end=end, style=style, soft_wrap=soft_wrap, + justify=justify, emoji=emoji, markup=markup, highlight=highlight, diff --git a/cmd2/rich_utils.py b/cmd2/rich_utils.py index dda625a2f..4aafa5b95 100644 --- a/cmd2/rich_utils.py +++ b/cmd2/rich_utils.py @@ -101,16 +101,18 @@ def set_theme(styles: Mapping[str, StyleType] | None = None) -> None: class RichPrintKwargs(TypedDict, total=False): - """Keyword arguments that can be passed to rich.console.Console.print() via cmd2's print methods. + """Infrequently used Rich Console.print() keyword arguments. - See Rich's Console.print() documentation for full details on these parameters. + These arguments are supported by cmd2's print methods (e.g., poutput()) + via their ``rich_print_kwargs`` parameter. + + See Rich's Console.print() documentation for full details: https://rich.readthedocs.io/en/stable/reference/console.html#rich.console.Console.print - Note: All fields are optional (total=False). If a key is not present in the - dictionary, Rich's default behavior for that argument will apply. + Note: All fields are optional (total=False). If a key is not present, + Rich's default behavior for that argument will apply. """ - justify: JustifyMethod | None overflow: OverflowMethod | None no_wrap: bool | None width: int | None diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index 0f9c83092..8610b30b0 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -162,7 +162,7 @@ each line is aligned independently. !!! tip "Advanced alignment customization" - You can also control output alignment using the `rich_print_kwargs.justify` member when calling + You can also control output alignment using the `justify` parameter when calling `cmd2`'s print methods. ## Columnar Output diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py index 7bd349a31..c07d70d04 100644 --- a/tests/test_cmd2.py +++ b/tests/test_cmd2.py @@ -2466,11 +2466,12 @@ def test_poutput_emoji(outsim_app): @with_ansi_style(ru.AllowStyle.ALWAYS) def test_poutput_justify_and_width(outsim_app): - rich_print_kwargs = RichPrintKwargs(justify="right", width=10) + rich_print_kwargs = RichPrintKwargs(width=10) # Use a styled-string when justifying to check if its display width is correct. outsim_app.poutput( su.stylize("Hello", style="blue"), + justify="right", rich_print_kwargs=rich_print_kwargs, ) out = outsim_app.stdout.getvalue() @@ -2504,7 +2505,6 @@ def test_poutput_pretty_print(outsim_app): def test_poutput_all_keyword_args(outsim_app): """Test that all fields in RichPrintKwargs are recognized by Rich's Console.print().""" rich_print_kwargs = RichPrintKwargs( - justify="center", overflow="ellipsis", no_wrap=True, width=40,