Skip to main content
xlogger (datamagix.xlogger) is a lightweight logging helper built on top of structlog with ANSI-coloured console output via colorama, JSON file sinks, and indentation helpers.

​
What it provides

  • Colourised human-readable console output via a custom _ColourRenderer.
  • Plain non-ANSI renderer for file sinks (_PlainRenderer) and a mirroring processor so file sinks receive a copy of events.
  • Simple global API via the Logger class: Logger.configure(...), Logger.get(name), Logger.add_file_sink(...), Logger.indent() / Logger.push() / Logger.pop().
  • Optional JSON lines output for structured logs.

​
Dependencies

pip install structlog colorama
Or in pyproject.toml: 
[tool.poetry.dependencies]
python = "^3.10"
structlog = "^25.4.0"
colorama = "^0.4.6"

​
Copying into another repo

1

Copy the file

Copy xlogger.py into your project’s package (for example myproj/logging/xlogger.py).
2

Add dependencies

Add structlog and colorama to your project’s dependencies.
3

Configure at startup

Import and configure early in your application’s startup, before other modules that log:
from myproj.logging.xlogger import Logger

Logger.configure(level="INFO", json=False)
Logger.add_file_sink("logs/errors.log", level="ERROR", rotate=True)

log = Logger.get(__name__)
log.info("started", foo="bar")
If you place xlogger.py at the top level (not inside a package), import with from xlogger import Logger.

​
API reference

​
Logger.configure

Logger.configure(*, level: str | int | None = None, json: bool = False, enabled: bool = True)
One-time global configuration. json=True emits JSONRenderer for console output.

​
Logger.get

Logger.get(name: str | None = None) → structlog.BoundLogger
Returns a bound logger. If name is provided it is bound as module and used for module colouring.

​
Logger.add_file_sink

Logger.add_file_sink(
    path: str,
    *,
    level: str | int = "ERROR",
    rotate: bool = True,
    use_json: bool = False,
    ...
) → logging.Handler
Mirrors events at or above level into the file. use_json=True writes JSON lines; otherwise uses a plain renderer.

​
Logger.remove_file_sink

Logger.remove_file_sink(handler)

​
Indentation helpers

Logger.indent()       # context manager
Logger.push(steps=1)
Logger.pop(steps=1)
Logger.set_indent_unit(unit)
Indentation is stored in a contextvars.ContextVar, so it is task-local and works correctly with async code.

​
Other

Logger.set_level(name, level)
Logger.disable()
Logger.enable(level=None)

​
Examples

from myproj.logging.xlogger import Logger

Logger.configure(level="DEBUG", json=False)
log = Logger.get("MYMOD")
log.info("Hello world", user="alice")

with Logger.indent():
    log.debug("Inside block")

​
Notes

  • colorama.init(autoreset=True) is called in the module to make colours work reliably on Windows.
  • Logger.configure() calls logging.basicConfig(force=True), which replaces existing root handlers. Configure once, early.
  • File sinks are attached to the root logging logger, so third-party libraries that emit standard logging records are also written to the sink.

​
Integration checklist

1

Copy xlogger.py

Copy xlogger.py to your package (myproj/logging/xlogger.py).
2

Add dependencies

Add structlog and colorama to your dependencies.
3

Configure at entrypoint

Call Logger.configure(...) before importing modules that log.
4

Add file sink (optional)

Call Logger.add_file_sink(...) to persist ERROR+ messages.
5

Replace getLogger calls

Replace logging.getLogger(...) with Logger.get(...) where you want the new format and colours.