pytermgui.pretty

  1"""This module calls `install()` on import, and defines `print` as `pprint`.
  2
  3It allows setting up pretty print functionality in only one line.
  4
  5Usage:
  6    ```python3
  7    >>> from pytermgui.pretty import print
  8    ```
  9"""
 10
 11from __future__ import annotations
 12
 13import builtins
 14import os
 15import sys
 16from typing import Any
 17
 18from .parser import tim
 19from .prettifiers import prettify
 20from .terminal import get_terminal
 21
 22try:
 23    # Try to get IPython instance. This function is provided by the
 24    # IPython runtime, so if running outside of that context a NameError
 25    # is raised.
 26    IPYTHON = get_ipython()  # type: ignore
 27    from IPython.core.formatters import BaseFormatter  # pylint: disable=import-error
 28
 29except NameError:
 30    IPYTHON = None
 31    BaseFormatter = object
 32
 33
 34NO_WELCOME = (
 35    os.getenv("PTG_SILENCE_PRETTY") is not None or not get_terminal().is_interactive()
 36)
 37
 38__all__ = ["pprint", "install"]
 39
 40
 41def pprint(
 42    *items: Any,
 43    indent: int = 2,
 44    expand_all: bool = False,
 45    force_markup: bool = False,
 46    parse: bool = True,
 47    **print_args: Any,
 48) -> None:
 49    r"""A wrapper to pretty-print any object.
 50
 51    This essentially just calls `prettify` on each given object, and passes the
 52    `**print_args` right through to print. Note that when the `sep` print argument is
 53    ommitted it is manually set to ", \n".
 54
 55    To customize any of the styles, see `MarkupLanguage.prettify`.
 56
 57    Args:
 58        *items: The items to print. These are passed in the same way they would be into
 59            builtin print.
 60        indent: The indentation value used for multi-line objects. This is ignored when
 61            the given object has a `len() < 2`, and `expand_all is not set.`
 62        force_tim: Turn all ANSI-sequences into tim before pretty printing.
 63        expand_all: Force-expand containers, even when they would normally be collapsed.
 64        **print_args: All arguments passed to builtin print.
 65    """
 66
 67    if "sep" not in print_args:
 68        print_args["sep"] = ", \n"
 69
 70    pretty = []
 71    for item in items:
 72        pretty.append(
 73            prettify(
 74                item,
 75                force_markup=force_markup,
 76                indent=indent,
 77                expand_all=expand_all,
 78                parse=parse,
 79            )
 80        )
 81
 82    get_terminal().print(*pretty, **print_args)
 83
 84
 85def install(
 86    indent: int = 2, force_markup: bool = False, expand_all: bool = False
 87) -> None:
 88    """Sets up `pprint` to print all REPL output. IPython is also supported.
 89
 90    This functions sets up a hook that will call `pprint` after every interactive
 91    return. The given arguments are passed directly to `pprint`, so for more information
 92    you can check out that function.
 93
 94    Usage is pretty simple:
 95
 96    ```python3
 97    >>> from pytermgui import pretty
 98    >>> tim.setup_displayhook()
 99    >>> # Any function output will now be prettified
100    ```
101
102    ...or alternatively, you can import `print` from `pytermgui.pretty`,
103    and have it automatically set up, and replace your namespace's `print`
104    function with `tim.pprint`:
105
106    ```python3
107    >>> from pytermgui.pretty import print
108    ... # Under the hood, the above is called and `tim.pprint` is set
109    ... # for the `print` name
110    >>> # Any function output will now be prettified
111    ```
112
113    Args:
114        indent: The indentation value used for multi-line objects. This is ignored when
115            the given object has a `len() < 2`, and `expand_all is not set.`
116        force_tim: Turn all ANSI-sequences into tim before pretty printing.
117        expand_all: Force-expand containers, even when they would normally be collapsed.
118    """
119
120    def _hook(value: Any) -> None:
121        if value is None:
122            return
123
124        pprint(value, force_markup=force_markup, indent=indent, expand_all=expand_all)
125
126        # Sets up "_" as a way to access return value,
127        # inkeeping with sys.displayhook
128        builtins._ = value  # type: ignore
129
130    if IPYTHON is not None:
131        IPYTHON.display_formatter.formatters["text/plain"] = PTGFormatter(
132            force_markup=force_markup, indent=indent, expand_all=expand_all
133        )
134
135    else:
136        sys.displayhook = _hook
137
138    if not NO_WELCOME:
139        with get_terminal().no_record():
140            print()
141            tim.print("[113 bold]Successfully set up prettification!")
142            tim.print("[245 italic]> All function returns will now be pretty-printed,")
143            print()
144            pprint("[245 italic]Including [/italic 210]Markup!")
145            print()
146
147    get_terminal().displayhook_installed = True
148
149
150class PTGFormatter(BaseFormatter):  # pylint: disable=too-few-public-methods
151    """An IPython formatter for PTG pretty printing."""
152
153    def __init__(self, **kwargs: Any) -> None:
154        """Initializes PTGFormatter, storing **kwargs."""
155
156        super().__init__()
157
158        self.kwargs = kwargs
159
160    def __call__(self, value: Any) -> None:
161        """Pretty prints the given value, as well as a leading newline.
162
163        The newline is needed since IPython output is prepended with
164        "Out[i]:", and it might mess alignments up.
165        """
166
167        print("\n")
168        pprint(value, **self.kwargs)
169
170        # Sets up "_" as a way to access return value,
171        # inkeeping with sys.displayhook
172        builtins._ = value  # type: ignore
173
174
175# I am normally violently against shadowing builtins, but this is an optional,
176# (hopefully always) REPL-only name, only provided for convenience.
177print = pprint  # pylint: disable=redefined-builtin
178
179install()