Configurable Rendering Format (LogRender)

[AndreasBackx]

This follows #2520, it was a PR to implement the console parameter in rich.reconfigure as it was added but never implemented. The PR was closed as it would not be the ideal solution, the conversation hopefully can continue here. 🙂

The premise is that we have a internal libraries to simplify and standardise many parts of a CLI. An example is for stderr to be the default instead of stdout. This is achievable with the current implementation of rich.reconfigure. However, we additionally want to change the format of messages/renderables. This is currently controlled by a private _log_render.LogRender. If this is to be configured, Console needs to be subclassed and changed to "fake" LogRender which is not ideal. I propose something along the lines below to perhaps make this configurable? This is just an idea, I thought that would hopefully get the conversation started.

1. Introduce LogRenderer(Protocol[LogRenderOptions], ConsoleRenderable) to replace LogRender. This would determine how a particular "log" is rendered.
2. Introduce Log to contain all of the information that needs to be logged. Making it a dataclass allows us to add fields in the future without breaking compatibility.
3. Create TableLogRenderOptions with the same implementation as the current LogRender and replace it in Console.

This will allow custom formatting via LogRenderer and allow tweaking as well as LogRenderOptions is configurable from the Console level.

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime
from typing import Generic, Iterable, Protocol, Type, TypeVar

from rich import TextType
from rich.console import Console, ConsoleOptions, ConsoleRenderable, RenderResult

LogRenderOptions = TypeVar("LogRenderOptions")


@dataclass
class Log:
    """
    Use a dataclass to pass data to the LogRenderer so when someone has
    a LogRenderer implemented, it doesn't break their implementation when
    something gets added.

    These are the copied arguments from the original LogRender class. They
    can be renamed.
    """

    renderables: Iterable[ConsoleRenderable]
    log_time: datetime | None = None
    time_format: str | None = None
    level: TextType = ""
    path: str | None = None
    line_no: int | None = None
    link_path: str | None = None


class LogRenderer(Protocol[LogRenderOptions], ConsoleRenderable):

    # What needs to be renderered.
    log: Log
    # How it needs to be rendered.
    options: LogRenderOptions

    # The actual rendering.
    def __rich_console__(
        self, console: Console, options: ConsoleOptions
    ) -> RenderResult:
        ...


class Console(Generic[LogRenderOptions]):
    def __init__(
        self,
        # [...] Existing arguments here
        log_renderer: Type[LogRenderer] = TableLogRenderer,
        # For backwards compatibility, the old arguments can stil be used as
        # well to create a TableLogRenderOptions by default.
        log_render_options: LogRenderOptions | None = None,
    ) -> None:
        log_render_options = log_render_options or TableLogRenderOptions(
            show_time=True,
        )

        # Replace `self._log_render` uses in the entire class with the above.

@dataclass
class TableLogRenderOptions:
    # The fields that LogRender uses.
    show_time: bool
    show_level: bool
    show_path: bool


class TableLogRenderer(LogRenderer[TableLogRenderOptions]):
    def __rich_console__(
        self, console: Console, options: ConsoleOptions
    ) -> RenderResult:
        # Original implementation here.
        pass

There also have been some other discussions and issues that want to change the format of Rich. These could be made possible with a custom renderer, whether they write that themselves, the default one is updated, or multiple renderers are included in Rich by default.

1. Discussions: https://github.com/Textualize/rich/discussions?discussions_q=LogRender
2. Issues: https://github.com/Textualize/rich/issues?q=LogRender

Let me know what you think. How would you tackle it or have you thought about this in the past? 😊

[willmcgugan]

This would shift the burden to the Rich, but the functionality belongs in the application's code.

Don't rely on console.log if it doesn't do what you need. Define your own log method and have it write in whatever format you like.

[AndreasBackx]

If rich.get_console is not used, using the standard library's logging will give "syncing" problems. Below is an example of what happens after a progress bar is used while logging occurs. These show the screenshots after the fact and not during, but there are issues there as well.

Without using rich.get_console:

Using rich.get_console:

This "fix"(/feature?) was added in a PR, I cannot find it right now.

This code is used in a test of ours, should be testable with (though CLIConsole is our custom Console class and this doesn't include logging and RichHandler setup).

# console = get_console()
console = CLIConsole(
    stderr=True,
    soft_wrap=True,
)

with Progress(
    TextColumn("[progress.description]{task.description}"),
    BarColumn(),
    TaskProgressColumn(),
) as progress:
    task = progress.add_task("This is a task", total=5)
    progress.advance(task)

    foo = "bar"

    console.log(foo)
    console.log(log_locals=True)

    progress.advance(task)
    time.sleep(1)

    console.print("This is a message")

    logger.debug("Debug")
    progress.advance(task)

    logger.info("Info")
    logger.warning("Warning")
    logger.error("Error")

    progress.advance(task)
    logger.critical("Critical")

    try:
        raise Exception("Exception")
    except Exception:
        logger.exception("Oh no!")

    progress.advance(task)

raise Exception("Uncaught")

[willmcgugan]

You can pass your custom console in to the Progress constructor, and RichHandler if you are using that.

[AndreasBackx]

That is right, the problem however is that we provide an internal library to provide some niceties for CLIs. We try to standardise CLIs across the entire company which is a different perspective from the single CLI use perspective.

For example, we have a Click wrapper and the users of the library don't have access to this Console object. It would be nice if we could recommend the use of rich.get_console as most might already be familiar with that and that is also the purpose of said function. It's important to leverage what is already available and keep it simple for the users of said library.

There have been a few requests regarding the formatting Rich uses. This solution could be a way to also deal with those issues? Rich has its own implementation that many have always enjoyed. If someone does not agree, it remains relatively easy for them to implement their own thanks to this abstraction. Is this something that Rich could offer? Configurability if desired, with minimal overhead in the codebase.

[willmcgugan]

I'm not on board with updating the global console like this, which was only ever intended as a convenience so that you wouldn't have to pass it in to things like progress and the logging handler.

If you update the global console you update it for everything. You may be able to change things easily, but you can break things just as easily. You also make it harder to unit test if you can't override this global console. I regret not making get_console private as it has many of the same downsides as global variables. The intention was for apps to create their own Console at module scope and pass that to code and libs that need it (which is what the docs recommend).

If you really can't live without this, you could monkey patch it relatively easily. See _console in rich/__init__.py. It's private, but isn't going to change.

DM me on Twitter if you would like to jump on a zoom call to discuss.

[AndreasBackx]

Thanks again @willmcgugan for your time. For future reference to anyone else. These changes are unlikely to make it into Rich and we'll likely be using our own wrapper libraries for some of the functionalities desired.

Feel free to close/lock the discussion, I'm not entirely sure what the custom is. 🙂