Logger

Logger

The sierra.internal.logger module provides the UniversalLogger class for structured, leveled logging throughout Sierra‑SDK.

Using UniversalLogger

from sierra.internal.logger import UniversalLogger, LogLevel

# Create a logger that writes DEBUG+ messages
logger = UniversalLogger(name="Sierra", level=LogLevel.DEBUG)

# Log messages at various levels
logger.log("Starting application", "info")
logger.log("Detailed debug info", "debug")
logger.log("A warning occurred", "warning")
logger.log("An error occurred", "error")

sierra.internal.logger

Attributes

LogTypeLiteral module-attribute

Python

LogTypeLiteral = typing.Literal['info', 'warning', 'debug', 'error']

Classes

LogLevel

Bases: enum.StrEnum

Logging verbosity levels.

ATTRIBUTE	DESCRIPTION
NO_ERROR	Suppress all messages. TYPE: str
BASIC	Log "info" and "warning". TYPE: str
STANDARD	Log "info", "warning", and "error". TYPE: str
DEBUG	Log all levels including "debug". TYPE: str

Attributes

NO_ERROR class-attribute instance-attribute

Python

NO_ERROR = 'no-error'

BASIC class-attribute instance-attribute

Python

BASIC = 'basic'

STANDARD class-attribute instance-attribute

Python

STANDARD = 'standard'

DEBUG class-attribute instance-attribute

Python

DEBUG = 'debug'

LogType

Bases: enum.StrEnum

Types of log messages.

ATTRIBUTE	DESCRIPTION
INFO	Informational messages. TYPE: str
WARNING	Warning messages. TYPE: str
DEBUG	Debug messages. TYPE: str
ERROR	Error messages. TYPE: str

Attributes

INFO class-attribute instance-attribute

Python

INFO = 'info'

WARNING class-attribute instance-attribute

Python

WARNING = 'warning'

DEBUG class-attribute instance-attribute

Python

DEBUG = 'debug'

ERROR class-attribute instance-attribute

Python

ERROR = 'error'

LoggerConfig

Bases: typing.TypedDict

Configuration for UniversalLogger.

Keys

name : str Prefix for each log message. (required) level : LogLevel Minimum log level to emit. (default LogLevel.BASIC) log_file : pathlib.Path | str | None File path for persistent logging. (default None) clean_logs : bool If True, uses stdout.write for performance. (default True) enable_colors : bool If True, ANSI colors are applied. (default True) timestamp_format : str Format specifier for datetime. (default "%Y-%m-%d %H:%M:%S") buffer_size : int Max messages retained in buffer. (default 1000) auto_flush : bool Flush buffer when full. (default True)

Attributes

name instance-attribute

Python

name: str

level instance-attribute

Python

level: LogLevel

log_file instance-attribute

Python

log_file: str | pathlib.Path | None

clean_logs instance-attribute

Python

clean_logs: bool

enable_colors instance-attribute

Python

enable_colors: bool

timestamp_format instance-attribute

Python

timestamp_format: str

buffer_size instance-attribute

Python

buffer_size: int

auto_flush instance-attribute

Python

auto_flush: bool

LogColor dataclass

Python

LogColor(INFO: str = colorama.Fore.GREEN, WARNING: str = colorama.Fore.YELLOW, DEBUG: str = colorama.Fore.LIGHTBLACK_EX, ERROR: str = colorama.Fore.RED, TIMESTAMP: str = colorama.Fore.CYAN, RESET: str = colorama.Fore.RESET, ICON_INFO: str = '✅', ICON_WARNING: str = '⚠️', ICON_DEBUG: str = '🔍', ICON_ERROR: str = '❌')

ANSI color codes and emoji icons for log message components.

Attributes

INFO class-attribute instance-attribute

Python

INFO: str = colorama.Fore.GREEN

WARNING class-attribute instance-attribute

Python

WARNING: str = colorama.Fore.YELLOW

DEBUG class-attribute instance-attribute

Python

DEBUG: str = colorama.Fore.LIGHTBLACK_EX

ERROR class-attribute instance-attribute

Python

ERROR: str = colorama.Fore.RED

TIMESTAMP class-attribute instance-attribute

Python

TIMESTAMP: str = colorama.Fore.CYAN

RESET class-attribute instance-attribute

Python

RESET: str = colorama.Fore.RESET

ICON_INFO class-attribute instance-attribute

Python

ICON_INFO: str = '✅'

ICON_WARNING class-attribute instance-attribute

Python

ICON_WARNING: str = '⚠️'

ICON_DEBUG class-attribute instance-attribute

Python

ICON_DEBUG: str = '🔍'

ICON_ERROR class-attribute instance-attribute

Python

ICON_ERROR: str = '❌'

LogBuffer

Python

LogBuffer(max_size: int = 1000)

In-memory FIFO buffer for log entries.

PARAMETER	DESCRIPTION
max_size	Maximum entries to retain. TYPE: int DEFAULT: 1000

Attributes

messages instance-attribute

Python

messages: list[str] = []

max_size instance-attribute

Python

max_size: int = max_size

Functions

add

Python

add(message: str) -> None

Add a log entry to the buffer.

PARAMETER	DESCRIPTION
message	Formatted log message. TYPE: str

flush

Python

flush() -> list[str]

Clear buffer and return all entries.

RETURNS	DESCRIPTION
list[str]	All buffered messages before clearing.

get_all

Python

get_all() -> list[str]

Retrieve buffer contents without clearing.

RETURNS	DESCRIPTION
list[str]	Current buffered messages.

UniversalLogger

Python

UniversalLogger(**kwargs: typing.Unpack[LoggerConfig])

Main logger class integrating console, file, and buffer outputs.

ATTRIBUTE	DESCRIPTION
name	Logger name (required in init kwargs). TYPE: str
level	Minimum log level to display. TYPE: LogLevel
clean_logs	Whether to use emoji-free output. TYPE: bool

RAISES	DESCRIPTION
ValueError	If 'name' is missing or empty.
OSError	If log file directory or file cannot be created.

Attributes

name instance-attribute

Python

name: str = name

level instance-attribute

Python

level: LogLevel = kwargs.get('level', LogLevel.BASIC)

log_file_path instance-attribute

Python

log_file_path: pathlib.Path | None = pathlib.Path(raw_log_file) if raw_log_file else None

clean_logs instance-attribute

Python

clean_logs: bool = kwargs.get('clean_logs', True)

enable_colors instance-attribute

Python

enable_colors: bool = kwargs.get('enable_colors', True)

timestamp_format instance-attribute

Python

timestamp_format: str = kwargs.get('timestamp_format', '%Y-%m-%d %H:%M:%S')

buffer_size instance-attribute

Python

buffer_size: int = kwargs.get('buffer_size', 1000)

auto_flush instance-attribute

Python

auto_flush: bool = kwargs.get('auto_flush', True)

colors instance-attribute

Python

colors: LogColor = LogColor()

buffer instance-attribute

Python

buffer: LogBuffer = LogBuffer(self.buffer_size)

Functions

log

Python

log(message: str, log_type: LogTypeLiteral) -> None

Emit a log entry.

PARAMETER	DESCRIPTION
message	Content of the log. TYPE: str
log_type	Severity level. TYPE: Literal[info, warning, debug, error]

flush_buffer

Python

flush_buffer() -> list[str]

Flush and retrieve buffered messages.

RETURNS	DESCRIPTION
list[str]	All buffered lines before flush.

get_logs

Python

get_logs() -> list[str]

Get buffered messages without flushing.

RETURNS	DESCRIPTION
list[str]	Current buffer contents.

clear_console staticmethod

Python

clear_console() -> None

Clear the terminal screen.