Principle:Huggingface Optimum Library Logging Configuration
| Knowledge Sources | |
|---|---|
| Domains | Logging, Infrastructure |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Pattern for implementing a centralized, configurable logging system for Python libraries with namespace isolation, thread-safe initialization, and user-controllable verbosity.
Description
Library Logging Configuration addresses the problem of providing useful log output from a library without interfering with the application's logging setup. Key design decisions include:
- Namespace isolation — All loggers live under the library's root namespace (`optimum.*`)
- Thread-safe lazy initialization — The root handler is created exactly once using a lock
- Propagation disabled by default — Prevents duplicate messages when users configure their own root logger
- Environment variable override — The `TRANSFORMERS_VERBOSITY` env var can set the default level
- Programmatic control — Functions to set verbosity, add/remove handlers, and configure formatting
- warn_once mechanism — LRU-cached function to emit a warning only the first time
This follows the same pattern established by Transformers and adopted by the HuggingFace ecosystem.
Usage
Apply this principle when building a Python library that needs to emit structured log output without conflicting with user applications. Users control verbosity through environment variables or programmatic API calls.
Theoretical Basis
The pattern follows Python logging best practices for libraries:
Pseudo-code Logic:
# Abstract algorithm (NOT real implementation)
# Library initialization (lazy, thread-safe)
lock = threading.Lock()
handler = None
def configure():
with lock:
if handler is not None: return
handler = StreamHandler(stderr)
root_logger = getLogger("library_name")
root_logger.addHandler(handler)
root_logger.setLevel(env_or_default_level())
root_logger.propagate = False
def get_logger(name):
configure()
return getLogger(name)
Key principles from Python logging guidelines:
- Libraries should add a NullHandler or a single StreamHandler
- Libraries should NOT configure the root logger
- Propagation should be disabled to avoid duplicate messages