Logguard provides a simple way to configure logging with sensible defaults. Just call setup() once and you're ready to go.

from logguard import AppLogger

AppLogger.setup(log_file="logs/app.log", console_level="INFO")
logger = AppLogger.get_logger(__name__)

logger.info("Application started")
logger.debug("Debug info")
logger.warning("Warning")
logger.error("Error occurred")

Logging will output to both console and file, with automatic rotation when files get too large.

Logguard provides environment-aware assertions that adapt their behavior based on APP_ENV:

from logguard import CHECK, ASSERT, ENSURE, VERIFY

# CHECK: Always raises - use for critical invariants
CHECK(config is not None, "Configuration required", component="auth")

# ASSERT: Raises in dev, ignored in prod - use for debugging
ASSERT(age > 0, "Age must be positive", age=age)

# ENSURE: Raises in dev, logs in prod - use for preconditions
def process_order(order):
    ENSURE(order.is_valid(), "Invalid order", order_id=order.id)

# VERIFY: Raises in dev, logs in prod - use for postconditions
result = calculate_total(items)
VERIFY(result >= 0, "Total cannot be negative", result=result)

Configure environment via APP_ENV variable:

• Development: dev, development, local, test
• Production: prod, production

Logguard includes helpers for common validation patterns:

from logguard import (
    ASSERT_NOT_NULL,
    ASSERT_TYPE,
    ASSERT_IN_RANGE,
    ASSERT_EQUALS,
    ASSERT_IN,
    ASSERT_NOT_EMPTY,
    ASSERT_GREATER,
    ASSERT_LESS,
)

# Null checks
ASSERT_NOT_NULL(user, "User is required")

# Type checking
ASSERT_TYPE(config, dict, "Expected dictionary")

# Range validation (inclusive)
ASSERT_IN_RANGE(percentage, 0, 100, "Invalid percentage")

# Equality
ASSERT_EQUALS(response.status, 200, "Expected success")

# Membership
ASSERT_IN(status, ["pending", "active"], "Invalid status")

# Non-empty
ASSERT_NOT_EMPTY(items, "Items list cannot be empty")

# Comparisons
ASSERT_GREATER(balance, 0, "Balance must be positive")
ASSERT_LESS(retry_count, max_retries, "Too many retries")

Each helper raises a specific exception type (NullError, TypeErrorAssert, RangeError, etc.) for precise error handling.

Logguard provides a semantic exception hierarchy for clearer error handling:

from logguard import (
    LogGuardError,
    ValidationError,
    AssertFailure,
    NullError,
    RangeError,
    ConfigurationError,
    ResourceNotFoundError,
    ForbiddenError,
)

# All exceptions include rich context
try:
    raise ValidationError("Invalid email", context={"field": "email", "value": "bad@"})
except LogGuardError as e:
    print(f"Error: {e}")
    print(f"Details: {e.to_dict()}")
    # {'type': 'ValidationError', 'message': 'Invalid email', 'context': {'field': 'email', 'value': 'bad@'}}

# Catch specific assertion failures
try:
    ASSERT_IN_RANGE(age, 0, 150)
except RangeError as e:
    handle_invalid_age(e.context)

# Resource errors
raise ResourceNotFoundError("User", identifier=123)
raise ForbiddenError("Access denied", user_id=456)

Exception Hierarchy:

LogGuardError
├── ConfigurationError
│   └── MissingConfigError
├── ValidationError
│   └── AssertFailure
│       ├── NullError
│       ├── RangeError
│       ├── TypeErrorAssert
│       ├── EmptyError
│       ├── EqualsError
│       ├── ComparisonError
│       └── MembershipError
└── ResourceError
    ├── ResourceNotFoundError
    └── ForbiddenError

Configure the assertion system programmatically:

from logguard import AssertionConfig, AssertionManager

# Switch to production mode (ASSERT becomes no-op)
AssertionManager.configure(
    AssertionConfig(environment="production", enable_asserts=True)
)

# Custom failure handlers
def my_raise_handler(message, context, exception_class):
    # Log to Sentry, then raise
    sentry.capture_message(message, extra=context)
    raise exception_class(message, context=context)

def my_log_handler(message, context, exception_class):
    # Custom logging
    metrics.increment("assertion_failures")
    logger.warning(f"{exception_class.__name__}: {message}")

AssertionManager.set_failure_strategy(
    raise_strategy=my_raise_handler,
    log_strategy=my_log_handler,
)

# Reset to defaults (useful for testing)
AssertionManager.reset()

For production environments, enable JSON logs for structured log aggregation:

from logguard import AppLogger

AppLogger.setup(json_logs=True, log_file="logs/app.json")
logger = AppLogger.get_logger(__name__)

logger.info("User logged in", extra={"user_id": 123})
logger.error("Database error", extra={"error_code": "DB_001"})

Requires: pip install py-logguard[json]

AppLogger is the main interface for logging. Configure it once and get loggers throughout your application.

Setup:

AppLogger.setup(
    log_file="logs/app.log",      # Path to log file
    console_level="INFO",          # Console output level
    file_level="DEBUG",            # File output level
    json_logs=False,               # Enable JSON formatting
    max_bytes=5_000_000,           # Max file size before rotation
    backup_count=3,                # Number of backups to keep
    delay=True,                    # Delay file creation until first log
)

HandlerType enum: use instead of plain strings to select which handlers an operation targets:

Methods:

• get_logger(name: str | None = None): Get or create a logger instance
• set_level(level, handler_type: HandlerType | str = HandlerType.ALL): Change log level on selected handlers at runtime
• set_format(format_string, handler_type: HandlerType | str = HandlerType.ALL, datefmt=None): Change the format string on selected handlers; RichHandler and JsonFormatter instances are skipped automatically
• silence_noisy_libraries(modules: list[str] | None = None): Suppress third-party logs
• reset(): Reset configuration (useful for testing)

from logguard import AppLogger, HandlerType

AppLogger.setup(log_file="logs/app.log", console_level="INFO")

# Drop file handler to DEBUG without touching the console
AppLogger.set_level("DEBUG", HandlerType.FILE)

# Apply a compact format to file logs only
AppLogger.set_format("%(asctime)s | %(levelname)s | %(message)s", HandlerType.FILE)

Core Assertions:

Specialized Helpers:

Configuration Classes:

• AssertionConfig(environment, enable_asserts) - Configuration dataclass
• AssertionManager - Central assertion engine with configure(), set_failure_strategy(), reset()

All exceptions inherit from LogGuardError and include rich context information.

Properties:

• message - Error description
• context - Additional context data (dict)
• .to_dict() - Serialize to dictionary for logging

Exception Types: