nebulog 0.1.0

Rich output spectacularly merged into Loguru to serve as the cradle of your stellar logs

Nebulog

Rich output spectacularly merged into Loguru to serve as the cradle of your stellar logs :dizzy:

:tools: Installation

Use pip to install Nebulog:

pip install -U nebulog

:black_joker: How to Use

Nebulog extends Loguru by adding support for rich-formatted output through a modular custom sink. The integration with the Rich library is seamless, you simply import the logger and start using it:

from nebulog import logger

logger.info("Rich and Loguru spectacularly merged into a single body")

The logger is the only object you'll need for your logging calls, being fully compatible with Loguru's API. In fact, Nebulog's logger is the same as Loguru's, making migration straightforward: only your import statements need to change, all existing logger configuration and logging calls will work as before.

The custom sink provided by Nebulog leverages Rich for more readable logs while maitaining the option for developers to use their own formatting solutions downstream:

logger.info(
    "This is a plain message",
    rich="This will be [b]bold[/b] if Nebulog has been imported",
)

logger.warning(
    "Plain messages make Rich markup entirely optional",
    alt="The [i]alt[/i] keyword can also be used instead of [reverse]rich[/reverse]",
)

logger.success(
    "The plain message can be used with and without Nebulog",
    style="on red",  # Specifying the style will markup the entire message if Nebulog has been imported
)

By default, Nebulog's sink offers features like configurable timestamps and terminal-aware message wrapping. You can further customise this behaviour by configuring parameters through the install function:

from nebulog import install, logger
from nebulog.examples import (
    SAMPLE_CONSOLE,
    SampleMessageFormatter,
    SampleTimeRenderer,
    SemverHighlighter,
)
from nebulog.renderers import InlineTimeRenderer, SimpleGridFormatter

install(
    rich_console=SAMPLE_CONSOLE,  # Bring your own Rich console and theme
    level=0,  # Override the default level at which to catch logs, defaults to "DEBUG"
    time_format="[b][[/b]%x [b]%X][/b]",  # A strftime format with optional Rich markup for the timestamp
    time_display_mode="separate",  # Choose whether to render the timestamp in a separate line, inline or don't render at all
    time_renderer=SampleTimeRenderer,  # Declare your own Rich ConsoleRenderable for the timestamp
    message_renderer=SampleMessageFormatter,  # Declare your own Rich ConsoleRenderable for the message
    traceback_mode="rich",  # Choose whether to show exception tracebacks or not
    keywords=["SEE"],  # Define your custom RichHandler keywords to highlight
)

# You can also specify custom Rich highlighters per call!
logger.info(
    "SEE how v1.2.3-pre.2025+build.3 is rendered",
    highlighter=SemverHighlighter,
)

For advanced customisation, Nebulog provides abstract base classes (ABCs) that allow you to extend its functionality for timestamp formatting or message processing:

from nebulog.interfaces import BaseMessageFormatter, TimeRenderer

TL;DR This library will help you write stellar logs to your terminal! :star_struck:

:abacus: Reasoning

We've created Nebulog during development of Galactipy. Being the perfectionists we are, we wanted to ensure projects generated with our template had tools that could be integrated via a "batteries included" approach in their TUI/CLI applications.

While Loguru provides a clean API to configure and render logging calls, combining it with Rich required significant setup and custom plumbing. Our goal was to provide developers with an effortless way to achieve beautiful logs without delving into the complexities of such setup. Nebulog acts as a drop-in extension for Loguru, enabling the Rich-formatted output by default while maintaining an acceptable degree of customisation through its options.

If you're building TUI/CLI applications and want your users to enjoy clear, well-structured logs with minimal effort, then Nebulog is particularly well-suited to meet those needs. :wink:

:reminder_ribbon: Contributing

There are several ways to contribute to Nebulog. Refer to our CONTRIBUTING guide for all relevant details.

:chart_with_upwards_trend: Releases

You can see the list of available releases on the GitLab Releases page.

We follow EffVer specification.

We use GitLab Changelog entries to track changes. You can categorise commits and Merge Requests made to this project using git trailers in your commit messages.

List of trailers and corresponding categories

Git trailer	Category in CHANGELOG
enhancement, feature	:rocket: Features
bug, refactoring, bugfix, fix	:wrench: Fixes & Refactoring
build, ci, testing	:package: Build System & CI/CD
breaking	:boom: Breaking Changes
documentation	:memo: Documentation
dependencies	:arrow_up: Dependencies updates

:shield: Licence

This project is licenced under the terms of the MIT licence. See LICENCE for more details.

:page_with_curl: Citation

@misc{Nebulog,
  author = {The Galactipy Contributors},
  title = {Rich output spectacularly merged into Loguru to serve as the cradle of your stellar logs},
  year = {2025},
  publisher = {GitLab},
  journal = {GitLab repository},
  howpublished = {\url{https://gitlab.com/galactipy/nebulog}}
}

Credits

Building upon the foundation set by the Richuru library, Nebulog enhances logging capabilities with modern features.

The project has also been heavily inspired by Kedro's approach logging calls with structured layout, wrapping and clutter reduction.

Along with Rich and Loguru, these projects have laid the groundwork that allowed Nebulog to become a reality. Give them your :star2:!

---

This project was generated with Galactipy.