logkiss 2.2.3

A Simple and Colorful Python Logging Library

LOGKISS (Keep It Simple and Stupid Logger) is a user-friendly logging library for Python. Built on top of the standard logging module, it provides an interface with sensible defaults out of the box.

Features

• Colorful by Default: LOGKISS uses KissConsoleHandler by default, which outputs logs in different colors based on log levels.
• Drop-in Replacement: Use it as a drop-in replacement for the standard logging module with import logkiss as logging.
• Flexible Switching: Easily switch back to the standard ConsoleHandler when needed.

Installation

pip install logkiss

Usage

Minimal Example (Standard logging & logkiss compatibility)

# examples/minimal_warning.py
import logging
logging.warning("Minimal example for beginners")

The same code works with logkiss:

# examples/minimal_warning.py
import logkiss as logging
logging.warning("Minimal example for beginners")

LOGKISS provides three different ways to enhance your logging experience:

1. Colorful Console Logging

Use LOGKISS directly to get beautiful colored log output with minimal setup:

# examples/quickstart_1.py
import logkiss

logger = logkiss.getLogger("example1")
logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message")
logger.critical("Critical error message")

2. Using as a logging module replacement:

# examples/quickstart_2.py
import logkiss as logging

logger2 = logging.getLogger("example2")
logger2.debug("Debug message")
logger2.info("Info message")
logger2.warning("Warning message")
logger2.error("Error message")
logger2.critical("Critical error message")

3. Using custom handler configuration:

# examples/quickstart_3.py
import logging
import logkiss

Get a logger with standard logging module

# examples/quickstart_3.py
logger3 = logging.getLogger("example3")
logger3.setLevel(logging.DEBUG)
logger3.debug("Debug message")
logger3.info("Info message")
logger3.warning("Warning message")
logger3.error("Error message")
logger3.critical("Critical error message")

Clear existing handlers

logger3.handlers.clear()

Add logkiss custom handler

handler = logkiss.KissConsoleHandler()  # カラフルな出力用のハンドラー
handler.setFormatter(logkiss.ColoredFormatter(use_color=True))
logger3.addHandler(handler)

Log with customized handler

logger3.error("Customized colorful output")

Sample Output

When you run the above code, you will see output similar to the following:

# Output from logger1.info():
2025-04-08 12:27:43,215 INFO  | example.py:5   | Colorful output

# Output from logger2.warning():
2025-04-08 12:27:43,219 WARN  | example.py:11  | Also colorful output

# Output from logger3.error():
2025-04-08 12:27:43,224,123 ERROR | example.py:21 | Standard monochrome output

The first two log messages will be displayed with color formatting in your terminal, while the third message will use the standard logging format without colors.

Environment Variables

LOGKISS can be configured using the following environment variables:

• LOGKISS_DEBUG: Enable debug mode by setting to 1, true, or yes. When enabled:
  • Root logger's level is set to DEBUG instead of INFO
  • More detailed logging information is displayed
• LOGKISS_DISABLE_COLOR: Disable colored output by setting to 1, true, or yes
• NO_COLOR: variable to disable colors (any value)

Example:

# Enable debug mode
export LOGKISS_DEBUG=1

# Run your Python script
python your_script.py

Behavior with Modules and Libraries

Logkiss modifies the behavior of the Python logging system. This has some implications you should be aware of:

Module Interactions

• When you import logkiss in a module, it affects the global logging configuration for the entire Python process
• If you import logkiss in module A, and then import standard logging in module B, the logging in module B will also use logkiss's colorful output
• To switch a specific logger back to standard behavior, use logkiss.use_console_handler(logger)

Third-Party Library Compatibility

• Most Python libraries that use the standard logging module will automatically benefit from logkiss's colorful output
• However, libraries that define custom handlers or formatters (like matplotlib) may not display colored output
• Libraries that redirect their logs or use advanced logging configurations might have varying results

Best Practices

• In simple applications, importing logkiss at the entry point will colorize logs throughout the application
• For more complex applications, you may want to be more selective about which loggers use colorful output

Configuration

For detailed configuration options, please refer to CONFIG.md.

Acknowledgments

The output format of logkiss is inspired by deigan / loguru

License

This project is licensed under the MIT License - see the LICENSE file for details.

Other Languages

• 日本語