# How to Configure Logging Levels in Outfancy: A Complete Guide

> Configure Outfancy logging levels easily at runtime. Access the Python logger and set DEBUG INFO WARNING ERROR or CRITICAL levels for detailed insights.

- Repository: [Carlos A. Planchón/outfancy](https://github.com/carlosplanchon/outfancy)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py) (lines 14-18), the library creates a module-level logger with specific default parameters:

```python
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`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py)):

```python
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:

```python
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:

```python
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:

```python
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**:

```python
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:

```python
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:

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

```

## Summary

- Outfancy creates a dedicated logger named **`outfancy`** in [`outfancy/table.py`](https://github.com/carlosplanchon/outfancy/blob/main/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`](https://github.com/carlosplanchon/outfancy/blob/main/LOGGING.md).
- Working implementations appear in [`logging_example.py`](https://github.com/carlosplanchon/outfancy/blob/main/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`](https://github.com/carlosplanchon/outfancy/blob/main/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`](https://github.com/carlosplanchon/outfancy/blob/main/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`](https://github.com/carlosplanchon/outfancy/blob/main/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`](https://github.com/carlosplanchon/outfancy/blob/main/logging_example.py)**, demonstrating practical implementations of the patterns described in the documentation.