How to Configure Logging Levels in Outfancy: A Complete Guide

You can configure outfancy's logging levels at runtime by accessing the standard Python logger named outfancy via logging.getLogger('outfancy') and calling setLevel() with logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, or logging.CRITICAL.

The carlosplanchon/outfancy library formats terminal tables using Python's standard logging module for internal diagnostics. By default, only warnings and errors appear, but you can adjust the verbosity to capture debug information or silence output entirely. Understanding how to configure logging levels for outfancy ensures you receive the appropriate diagnostic detail during development and production operations.

Understanding Outfancy's Logging Architecture

Logger Initialization in table.py

The logging system initializes when you import outfancy.table. In outfancy/table.py (lines 14-18), the library creates a module-level logger with specific default parameters:

logger = logging.getLogger('outfancy')
logger.setLevel(logging.WARNING)          # default level

logger.propagate = False                  # avoid duplicate root logs

Setting propagate to False prevents duplicate messages from bubbling up to the root logger. This ensures clean output unless you explicitly configure additional handlers.

Default Handler Configuration

The library attaches a single StreamHandler with a timestamped formatter if no handlers exist (lines 19-27 in outfancy/table.py):

if not logger.handlers:
    handler = logging.StreamHandler()
    formatter = logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
        datefmt='%Y-%m-%d %H:%M:%S')
    handler.setFormatter(formatter)
    logger.addHandler(handler)

This conditional check prevents duplicate handlers when the module reloads or imports multiple times.

How to Set Logging Levels for Outfancy

Runtime Level Adjustment

Since outfancy uses the standard library's logging module, adjust verbosity at any point after importing the library:

import logging

# Enable debug output (most verbose)

logging.getLogger('outfancy').setLevel(logging.DEBUG)

# Show informational messages

logging.getLogger('outfancy').setLevel(logging.INFO)

# Default behavior - warnings and above

logging.getLogger('outfancy').setLevel(logging.WARNING)

# Errors only

logging.getLogger('outfancy').setLevel(logging.ERROR)

# Critical messages only (minimal output)

logging.getLogger('outfancy').setLevel(logging.CRITICAL)

Practical Examples

Enable detailed debugging to trace internal calculations and configuration values:

import logging, outfancy.table
from outfancy.example_dataset import dataset

logging.getLogger('outfancy').setLevel(logging.DEBUG)

table = outfancy.table.Table()
result = table.render(dataset[:2])   # Debug messages now appear in console

Use default settings for production environments where only warnings and errors matter:

import outfancy.table

# No additional configuration needed - WARNING level is active by default

table = outfancy.table.Table()
result = table.render(dataset[:3])

Advanced Logging Configuration

Custom Formatters

Change the output format by clearing default handlers and attaching a custom StreamHandler with your preferred Formatter:

import logging, outfancy.table

logger = logging.getLogger('outfancy')
logger.setLevel(logging.INFO)

# Remove default handler to prevent duplicate messages

logger.handlers.clear()

# Add custom formatting

handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter('[%(levelname)s] %(message)s'))
logger.addHandler(handler)

File Logging Setup

Route diagnostic output to a file while maintaining console visibility by adding a FileHandler to the outfancy logger:

import logging, outfancy.table
from outfancy.example_dataset import dataset

logger = logging.getLogger('outfancy')
logger.setLevel(logging.DEBUG)

file_handler = logging.FileHandler('outfancy.log')
file_handler.setFormatter(
    logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
)
logger.addHandler(file_handler)

table = outfancy.table.Table()
result = table.render(dataset[:2])

# Logs now write to both console and outfancy.log

Disabling Logging Entirely

To completely suppress all output from the library, disable the logger rather than just raising the level:

import logging
logging.getLogger('outfancy').disabled = True   # No output regardless of level

Summary

• Outfancy creates a dedicated logger named outfancy in outfancy/table.py with a default level of WARNING.
• The default configuration uses a StreamHandler with a timestamped format (YYYY-MM-DD HH:MM:SS) and disables propagation to prevent duplicate logs.
• You can configure logging levels for outfancy at runtime using standard Python logging APIs: logging.getLogger('outfancy').setLevel().
• Advanced configurations support custom formatters, file handlers, and complete disablement using standard library patterns documented in LOGGING.md.
• Working implementations appear in logging_example.py, demonstrating practical applications of these configuration options.

Frequently Asked Questions

What is the default logging level in outfancy?

The default logging level is WARNING, as explicitly set in outfancy/table.py (line 15) during logger initialization. Only warnings, errors, and critical messages appear in the console unless you explicitly lower the threshold using setLevel().

How do I enable debug output to troubleshoot outfancy rendering issues?

Call logging.getLogger('outfancy').setLevel(logging.DEBUG) after importing the library. This setting emits DEBUG level messages that trace function entry points, configuration values, and internal calculations according to the implementation in outfancy/table.py.

Can I redirect outfancy logs to a file instead of the console?

Yes. Add a FileHandler to the outfancy logger using standard Python logging APIs. The library supports multiple simultaneous handlers, allowing you to write to a file while maintaining console output, or to replace the default StreamHandler entirely by clearing logger.handlers first.

Where is the logging configuration documented in the repository?

Official documentation resides in LOGGING.md at the repository root, which details level options, custom configuration patterns, and advanced handler setups. Working code examples are available in logging_example.py, demonstrating practical implementations of the patterns described in the documentation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}