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: str, enum.Enum

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: str, enum.Enum

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: typing.Union[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,
)

ANSI color codes 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

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.

PARAMETER	DESCRIPTION
**config	Configuration options unpacked via typing.Unpack[LoggerConfig]. TYPE: LoggerConfig

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: typing.Optional[pathlib.Path] = (
    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.