moonlogger 0.9.5

moon-logger, a Python logging library

Moon Logger

The Moon Logger is a Python logging utility with customizable features for handling both stream and file logging.

Requirements

• Git
• Python ^3.7

Table of Contents

• Installation
• Usage
  • Initializing Moon
  • Log Levels
  • Archiving Logs
  • Custom Formatting
  • Logger Methods
• Examples

Installation

Install the Moon Logger using git:

git clone https://github.com/reslaid/moon.git

Installing the Moon Logger using PyPI:

• NT:

  pip install moonlogger
  

• Posix:

  pip3 install moonlogger
  

Usage

Initializing Moon

from moon.logger import Moon
from moon.formats import Formats
from moon._types import LogLevel

# Create an instance of the Moon logger
moon = Moon(
    name=__name__,                  # Name of the logger (defaults to the name of the current module)
    log_file='moon.json',           # Path to the log file (defaults to 'moon.json')
    stream_handler=True,            # Whether to use a stream handler (defaults to True)
    file_handler=True,              # Whether to use a file handler (defaults to True)
    disabled=False,                 # Whether the logger is disabled (defaults to False)
    stream_level=LogLevel.DEBUG,    # Log level for the stream handler (defaults to DEBUG)
    file_level=LogLevel.DEBUG,      # Log level for the file handler (defaults to DEBUG)
    stream_format=Formats.CLang(),  # Log format for the stream handler (default is Formats.CLang())
    file_format=Formats.JsonIndented()  # Log format for the file handler (default is Formats.JsonIndented())
)

Log Levels

The Moon Logger supports the following log levels:

• LogLevel.DEBUG
• LogLevel.INFO
• LogLevel.WARNING
• LogLevel.ERROR
• LogLevel.CRITICAL

Archiving Logs:

# Archive the log file into a ZIP file and remove the original log file
moon.archive()

Custom Formatting:

# Set a custom log format for all handlers in the Moon logger
moon.set_log_format("[{name}] - [{levelname}]: {message}")

Formats built into moon logger:

• CLang
• Json
• Csv
• Table
• Html
• Xml
• Markdown
• Yaml
• Syslog
• JsonIndented
• Logstash
• ShortJson
• ColoredConsole
• DelimiterSeparatedJson
• Traceback
• TracebackV2
• HexDump
• Base64
• Binary
• Emoji

Logger Methods:

• moon.set_formatter(formatter): Set a custom formatter for the logger.
• moon.add_formatter(formatter): Add a formatter to the logger.
• moon.del_formatters(): Remove all formatters from the logger.
• moon.del_formatter(formatter): Remove a specific formatter from the logger.
• moon.edit_format(new_log_format): Edit the log format, ensuring required placeholders are present.
• moon.reset_format(): Reset the log format to the default.
• moon.base_logger(): Getting the base logger.

Examples

• Logging Message:

# Import the Moon logger and Formats module
from moon.logger import Moon
from moon.formats import Formats

# Initialize the Moon logger
logger = Moon(
    name=__name__,
    file_handler=False,  # Disable file handler
    stream_format=Formats.CLang()  # Use CLang format for stream handler
).base_logger()

# Log a debug message
logger.debug(
    msg="message"
)

# Log an informational message
logger.info(
    msg="message"
)

# Log a warning message
logger.warning(
    msg="message"
)

# Log an error message
logger.error(
    msg="message"
)

# Log a critical message
logger.critical(
    msg="message"
)

# Log a fatal message
logger.fatal(
    msg="message"
)

• Custom log format:

from moon.logger import Moon, logging

# Define a custom log format string
custom_log_format = logging.Formatter(
    "[{levelname}] [{asctime}] - {message}",
    style="{"
)

# Initialize the Moon logger with the custom log format
logger = Moon(
    name=__name__,
    file_handler=False,
    stream_format=custom_log_format
).base_logger()

# Log a message using the custom format
logger.info(
    msg="Custom log message"
)

• Built-in log format:

from moon.logger import Moon
from moon.formats import Formats 


# Initialize the Moon logger with the built-in log format
logger = Moon(
    name=__name__,
    file_handler=False,
    stream_format=Formats.CLang() # You can choose any built-in log format
).base_logger()

# Log a message using the built-in log format
logger.info(
    msg="Custom log message"
)

• Archiving a file:

from moon.logger import Moon
from moon.formats import Formats 

# Initialize the Moon logger with a file handler and JsonIndented format
moon = Moon(
    name=__name__,
    log_file="moon.json",
    file_handler=True,
    file_format=Formats.JsonIndented()
)

# Get the base logger from the Moon logger instance
logger = moon.base_logger()

# Log a custom message with an informational level
logger.info(
    msg="Custom log message"
)

# Archive log file
moon.archive()

• Changing Log Format Dynamically:

from moon.logger import Moon

# Create an instance of Moon Logger with a file handler
moon = Moon(name="dynamic_format_logger", file_handler=True)
logger = moon.base_logger()

# Log an error message
logger.error(msg="An error occurred.")

# Change the log format
moon.edit_format("[{levelname}] {message} ({asctime})")

# Log another message with the updated format
logger.info(msg="Updated log format.")

• Removing All Formatters:

from moon.logger import Moon

# Create an instance of Moon Logger with a file handler
moon = Moon(name="remove_all_formatters_logger", file_handler=True)
logger = moon.base_logger()

# Add two formatters
moon.add_formatter(Moon.formats.CLang())
moon.add_formatter(Moon.formats.JsonIndented())

# Remove all formatters
moon.del_formatters()

# Log a message with DEBUG level
logger.debug(msg="Logging after removing formatters.")

• Removing a Specific Formatter:

from moon.logger import Moon
from moon.formats import Formats

# Create an instance of Moon Logger with a file handler
moon = Moon(name="remove_formatter_logger", file_handler=True)
logger = moon.base_logger()

# Add two formatters
formatter1 = Formats.Table()
formatter2 = Formats.Json()

moon.add_formatter(formatter1)
moon.add_formatter(formatter2)

# Remove one of the formatters
moon.del_formatter(formatter1)

# Log a message with INFO level
logger.info(msg="Logging after removing one formatter.")

• Conditional Logging Based on Environment:

from moon.logger import Moon
from moon.formats import Formats
import os

# Create an instance of Moon Logger with conditional file handler
enable_file_logging = os.environ.get("ENABLE_FILE_LOGGING", "False").lower() == "true"
logger = Moon(
    name="conditional_logger",
    file_handler=enable_file_logging,
    file_format=Formats.JsonIndented()
).base_logger()

# Log a message with INFO level
logger.info(msg="Conditional log message.")

• Adding a custom file handler:

import logging
from moon.logger import Moon, LogLevel
from moon.formats import Formats

# Create an instance of the Moon logger
moon = Moon(
    file_handler=False,  # Set to True if you want to include a file handler
    stream_handler=False  # Set to True if you want to include a stream (console) handler
)

# Create a FileHandler with specific configuration
file_handler = logging.FileHandler(
    'moon.json',
    mode="a",
    encoding="utf-8",
    delay=False,
    errors=None
)

# Set the formatter for the FileHandler (e.g., JSON format)
file_handler.formatter = Formats.Json()

# Set the logging level for the FileHandler (e.g., DEBUG)
file_handler.setLevel(LogLevel.DEBUG)

# Add the custom handler to the Moon logger
moon.add_handler(handler=file_handler)

# Get Logger Instance
logger = moon.base_logger()

# Log Messages
logger.debug('Hello, Custom Handlers!')

• Adding a custom stream handler:

import logging
from moon.logger import Moon, LogLevel
from moon.formats import Formats

# Create a Moon logger instance without default handlers
moon = Moon(file_handler=False, stream_handler=False)

# Create a StreamHandler
stream_handler = logging.StreamHandler()

# Set the formatter for the StreamHandler (e.g., GNU Logs format)
stream_handler.formatter = Formats.CLang()

# Set the logging level for the StreamHandler (e.g., DEBUG)
stream_handler.setLevel(LogLevel.DEBUG)

# Add the stream handler to the Moon logger
moon.add_handler(handler=stream_handler)

# Log Messages to Stream Handler
logger.debug('Hello, Custom Handlers!')