molcrafts-mollog 1.0.0

Zero-dependency structured logging library for the molcrafts ecosystem

mollog

mollog is a typed, dependency-free structured logging library for Python applications that want clear output, small surface area, and explicit control.

Version 1.0.0 focuses on the pieces needed in real projects: hierarchical loggers, structured context, JSON/text formatting, queue-based fan-out, optional Rich console output, and predictable shutdown/configuration hooks.

Highlights

• Zero required runtime dependencies
• Typed public API with py.typed
• configure() and shutdown() helpers for application setup
• Structured extra, bind(), and context-local fields via bind_context() / scoped_context()
• Text, JSON, file, rotating-file, timed-rotating, queue, and Rich handlers
• Exception and stack capture built into the record model

Installation

Core package:

pip install molcrafts-mollog

Development environment:

pip install -e ".[dev,docs,rich]"

Rich terminal support:

pip install "molcrafts-mollog[rich]"

Quickstart

from mollog import JSONFormatter, StreamHandler, configure, get_logger

handler = StreamHandler()
handler.set_formatter(JSONFormatter())
configure(level="info", handlers=[handler])

logger = get_logger("api")
logger.info("request complete", status=200, duration_ms=18)

Contextual logging

from mollog import bind_context, get_logger, scoped_context

logger = get_logger("worker")

with scoped_context(request_id="req-42", trace_id="trace-7"):
    logger.bind(component="ingest").info("started")

token = bind_context(batch="nightly")
try:
    logger.info("continuing")
finally:
    from mollog import reset_context

    reset_context(token)

Exception logging

from mollog import get_logger

logger = get_logger("api")

try:
    raise ValueError("bad payload")
except ValueError:
    logger.exception("request failed", request_id="req-17")

Rich console output

from mollog import RichHandler, configure, get_logger

configure(handlers=[RichHandler()], level="debug")
logger = get_logger("cli")
logger.warning("unexpected value", field="charge", observed="2+")

Release-ready API surface

Core exports include:

• get_logger()
• configure()
• shutdown()
• bind_context()
• scoped_context()
• clear_context()
• Logger, BoundLogger, LoggerManager
• TextFormatter, JSONFormatter
• StreamHandler, FileHandler, RotatingFileHandler, TimedRotatingFileHandler, QueueHandler
• RichHandler with molcrafts-mollog[rich]

Documentation

The repository includes a Zensical documentation site.

uv run zensical serve

Build the static site:

uv run zensical build

Main pages:

• Getting Started
• Configuration
• Context Propagation
• Behavior Notes
• Rich Console Logging
• API Reference
• Release Notes

Development

pip install ".[dev]"
pytest -q

See CONTRIBUTING.md for contribution workflow and RELEASING.md for the 1.x release process.