pythonLogs
pythonLogs

Table of Contents

Features

Installation

pip install pythonLogs

Logger Types

Basic Logger

Usage

from pythonLogs import BasicLog
logger = BasicLog(
 name="my_app",
 level="debug", # "debug", "info", "warning", "error", "critical"
 timezone="America/Sao_Paulo",
 showlocation=False
)
logger.warning("This is a warning example")

Example Output

Size Rotating Logger

Usage

from pythonLogs import SizeRotatingLog
logger = SizeRotatingLog(
 name="my_app",
 level="debug", # "debug", "info", "warning", "error", "critical"
 directory="/app/logs",
 filenames=["main.log", "app1.log"],
 maxmbytes=5,
 daystokeep=7,
 timezone="America/Chicago",
 streamhandler=True,
 showlocation=False
)
logger.warning("This is a warning example")

Example Output

Timed Rotating Logger

Usage

from pythonLogs import TimedRotatingLog
logger = TimedRotatingLog(
 name="my_app",
 level="debug", # "debug", "info", "warning", "error", "critical"
 directory="/app/logs",
 filenames=["main.log", "app2.log"],
 when="midnight", # "midnight", "H", "D", "W0"-"W6"
 daystokeep=7,
 timezone="UTC",
 streamhandler=True,
 showlocation=False
)
logger.warning("This is a warning example")

Example Output

Context Manager Support

Usage Examples

from pythonLogs import LogLevel
from pythonLogs.basic_log import BasicLog
from pythonLogs.size_rotating import SizeRotatingLog
from pythonLogs.timed_rotating import TimedRotatingLog
# Automatic cleanup with context managers
with BasicLog(name="app", level=LogLevel.INFO) as logger:
 logger.info("This is automatically cleaned up")
 # Handlers are automatically closed on exit
with SizeRotatingLog(name="app", directory="/logs", filenames=["app.log"]) as logger:
 logger.info("File handlers cleaned up automatically")
 # File handlers closed and resources freed
# Exception safety - cleanup happens even if exceptions occur
try:
 with TimedRotatingLog(name="app", directory="/logs") as logger:
 logger.error("Error occurred")
 raise ValueError("Something went wrong")
except ValueError:
 pass # Logger was still cleaned up properly

Using With Multiple Log Levels and Files

from pythonLogs import SizeRotatingLog, TimedRotatingLog, LogLevel, RotateWhen
# Application logger
app_logger = SizeRotatingLog(
 name="production_app",
 directory="/var/log/myapp",
 filenames=["app.log"],
 maxmbytes=50, # 50MB files
 daystokeep=30, # Keep 30 days
 level=LogLevel.INFO,
 streamhandler=True, # Also log to console
 showlocation=True, # Show file:function:line
 timezone="UTC"
)
# Error logger with longer retention
error_logger = SizeRotatingLog(
 name="production_errors",
 directory="/var/log/myapp",
 filenames=["errors.log"],
 maxmbytes=10,
 daystokeep=90, # Keep errors longer
 level=LogLevel.ERROR,
 streamhandler=False
)
# Audit logger with daily rotation
audit_logger = TimedRotatingLog(
 name="audit_log",
 directory="/var/log/myapp",
 filenames=["audit.log"],
 when=RotateWhen.MIDNIGHT,
 level=LogLevel.INFO
)
# Use the loggers
app_logger.info("Application started")
error_logger.error("Database connection failed")
audit_logger.info("User admin logged in")

Env Variables (Optional)

from pythonLogs import TimedRotatingLog
log = TimedRotatingLog()

LOG_LEVEL=DEBUG
LOG_TIMEZONE=UTC
LOG_ENCODING=UTF-8
LOG_APPNAME=app
LOG_FILENAME=app.log
LOG_DIRECTORY=/app/logs
LOG_DAYS_TO_KEEP=30
LOG_DATE_FORMAT=%Y-%m-%dT%H:%M:%S
LOG_STREAM_HANDLER=True
LOG_SHOW_LOCATION=False
LOG_MAX_LOGGERS=50
LOG_LOGGER_TTL_SECONDS=1800
# SizeRotatingLog
LOG_MAX_FILE_SIZE_MB=10
# TimedRotatingLog
LOG_ROTATE_WHEN=midnight
LOG_ROTATE_AT_UTC=True
LOG_ROTATE_FILE_SUFIX="%Y%m%d"

Flexible Configuration Options

from pythonLogs import LogLevel, RotateWhen
# Option 1: Type-safe enums (recommended)
LogLevel.DEBUG # "DEBUG"
LogLevel.INFO # "INFO"
LogLevel.WARNING # "WARNING"
LogLevel.ERROR # "ERROR"
LogLevel.CRITICAL # "CRITICAL"
# Option 2: String values (case-insensitive)
"debug" # Same as LogLevel.DEBUG
"info" # Same as LogLevel.INFO
"warning" # Same as LogLevel.WARNING
"warn" # Same as LogLevel.WARN (alias)
"error" # Same as LogLevel.ERROR
"critical" # Same as LogLevel.CRITICAL
"crit" # Same as LogLevel.CRIT (alias)
# Also supports: "DEBUG", "Info", "Warning", etc.
# RotateWhen values
RotateWhen.MIDNIGHT # "midnight"
RotateWhen.HOURLY # "H"
RotateWhen.DAILY # "D"
RotateWhen.MONDAY # "W0"
# ... through SUNDAY # "W6"
# String equivalents: "midnight", "H", "D", "W0"-"W6"

Development

Create DEV Environment, Running Tests and Building Wheel

uv sync --all-extras
poe linter
poe test
poe build

Optionals

Create a cprofile.prof file from unit tests

poe profile

License

Support