LucidLogger

A Python library for standardized terminal logging with ANSI color support, progress bars, spinners, and timed rotating file output.

---

Features

• Colored log output per level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• Custom log levels with configurable colors
• Inline progress/loading bars that coexist with log output
• Indeterminate spinner for operations with unknown duration
• Auto-resizing progress bars based on terminal width
• Cross-platform (Windows CMD, PowerShell, Bash)
• Timed rotating file handler with dated filenames
• File logs strip ANSI — clean output for log aggregators

---

Installation

pip install lucid-logger

---

Quick Start

from lucid_logger import get_logger

logger = get_logger("app")
logger.info("Server started")
logger.warning("High memory usage")
logger.error("Failed to connect")

get_logger creates a LucidLogger with a colored stream handler and a timed rotating file handler in one call.

With a Progress Bar (wrap)

from lucid_logger import get_logger, LucidLoadingBar

logger = get_logger("app")
bar = LucidLoadingBar(name="import")
logger.add_loading_bar(bar)

for item in bar.wrap(items, prefix="Importing"):
    process(item)
    logger.info(f"Processed {item}")

With a Spinner

from lucid_logger import get_logger, LucidSpinner

logger = get_logger("app")
spinner = LucidSpinner(name="fetch", prefix="Fetching data")
logger.add_spinner(spinner)

with spinner:
    result = requests.get(url)

logger.info("Fetch complete")

Manual setup (advanced)

from lucid_logger import LucidLogger

logger = LucidLogger(name="app", log_lowest_level=10, colored_logs=True)
logger.basic_config()

---

API Reference

get_logger(name, ...)

Factory function — the recommended way to create a logger.

Parameter	Type	Default	Description
name	str	—	Logger name
level	int	logging.DEBUG	Minimum log level
colored	bool	True	Enable ANSI color on stream output
log_dir	str	'./logs/'	Directory for rotating log files
stream	bool	True	Attach a stream handler to stdout
file	bool	True	Attach a rotating file handler

---

LucidLogger

Extends logging.Logger.

Parameter	Type	Description
name	str	Logger name
log_lowest_level	int	Minimum log level (e.g. 10 = DEBUG)
colored_logs	bool	Enable ANSI color output

Methods:

Method	Description
basic_config()	Attach default stream and file handlers
add_loading_bar(bar)	Register a LucidLoadingBar with the stream handler
get_loading_bar(name)	Retrieve a registered bar by name
add_spinner(spinner)	Register a LucidSpinner with the stream handler
add_logging_level(level_name, level_num, color)	Register a custom log level with a color

---

LucidLoadingBar

A terminal progress bar that renders inline with log output.

Parameter	Type	Default	Description
name	str	—	Unique identifier
iterable	iterable	None	Collection to iterate over
prefix	str	'Loading...'	Label shown before the bar
suffix	str	''	Label shown after the bar
colored_logs	bool	True	Enable ANSI color
fill	str	█	Fill character
decimals	int	1	Decimal places on the percent
length	int	100	Bar width in characters

Methods:

Method	Description
init_bar(iterable, prefix, total)	Start the bar, auto-sizes to terminal width
wrap(iterable, prefix)	Iterate over iterable while auto-advancing the bar
progress_bar()	Advance progress by one step
finish_loading()	Mark the bar complete and clear it
get_bar()	Return the current formatted bar string

---

LucidSpinner

An indeterminate progress indicator that animates in place on a background thread. Log output from LucidLogger will pause the spinner frame, write the log line, then let the spinner resume — no interleaving.

Uses Unicode braille frames (⠋ ⠙ ⠹ …) where supported, falls back to ASCII (| / - \).

Parameter	Type	Default	Description
name	str	—	Unique identifier
prefix	str	''	Label shown before the spinner frame
colored_logs	bool	True	Enable ANSI color
color	str	grey	ANSI escape string for the spinner color
interval	float	0.1	Seconds between frame advances

Methods:

Method	Description
start()	Begin animation on a daemon thread
stop()	Stop animation, clear the line, join the thread
__enter__ / __exit__	Use as a context manager

---

LucidStreamFormatter

Custom logging.Formatter that injects ANSI color codes per log level.

Levels below detailed_view_threshold omit the filename/line number from the output to keep routine logs terse. Warnings and above include the source location.

---

LucidTimedRotatingFileHandler

Extends TimedRotatingFileHandler. Rotates at midnight and names files by date (YYYY-MM-DD.log). Creates the log directory automatically if it does not exist.

Parameter	Default	Description
directory	'./logs/'	Output directory
when	'midnight'	Rotation schedule
file_extension	'log'	File extension

---

Color Reference

Built-in named colors available for custom levels and bar/spinner segments:

Name	Hex
grey	#C8C8C8
white	#FFFFFF
red	#FF0000
yellow	#FFFF00
green	#009600
lime	#00FF00
cyan	#00FFFF
blue	#0000FF
purple	#000096

---

Custom Log Levels

from lucid_logger import get_logger, cyan

logger = get_logger("app")
logger.add_logging_level("TRACE", 5, cyan)
logger.trace("Entering request handler")

---

Log Output Format

Stream (colored):

[MM/DD/YYYY HH:MM:SS][LEVEL] message
[MM/DD/YYYY HH:MM:SS][WARNING][filename.py:42] message

File (plain):

[MM/DD/YYYY HH:MM:SS][INFO] message
[MM/DD/YYYY HH:MM:SS][ERROR][filename.py:42] message

---

License

MIT