printer-logging 1.0.4

Libreria Python per logging/stampa formattata con prefissi coerenti, filtro visibilità, log strutturati JSON opzionali e gestione session/remote id.

Printer Logging

Libreria Python per logging/stampa formattata con prefissi coerenti, filtro di visibilità, log strutturati JSON opzionali e gestione session/remote id.

Caratteristiche

• Prefissi coerenti: custom logs, session id, log_code
• Filtro di visibilità: controllo tramite DebuggingMode (NORMAL, VERBOSE, DEBUG)
• Output flessibile: stdout/stderr o logging.Logger integrato
• Log strutturati JSON: opzionali quando use_structured_logging=True
• Gestione log_code: risoluzione automatica con fallback e mapping configurabile

Installazione

pip install printer-logging

Quickstart

Uso diretto (classe Printer)

from printer import Printer, DebuggingMode, set_session_id

set_session_id("abc-123")

p = Printer(
    debugging_mode=DebuggingMode.DEBUG,
    name="MyApp",
    use_structured_logging=False,
)

p.info("Hello")                      # default: print
p.warning("Bad request", log_code=400)
p.error("Boom", log_code=500)

Uso con API funzionale (singleton)

import printer
from printer import DebuggingMode

printer.configure_printer(
    debugging_mode=DebuggingMode.DEBUG,
    name="MyApp",
    use_structured_logging=True,
    default_output_type="log",
)

printer.info("Hello", log_code=200, category="REQUEST_RECEIVED")
printer.warning("Bad request", log_code=400)
printer.error("Error occurred", log_code=500)

DebuggingMode

Controlla la visibilità dei log:

• NORMAL: mostra solo WARNING/ERROR/CRITICAL
• VERBOSE: mostra INFO+ (esclude DEBUG)
• PRODUCTION: equivalente a VERBOSE
• DEBUG: mostra tutto

Log strutturati JSON

Quando use_structured_logging=True e output_type="log", viene emesso anche un JSON per ogni evento con:

• timestamp, level, logger, message, log_code
• custom_logs_prefix, session_id
• context (state/phase/category) se presenti
• exception quando applicabile

Session ID

Gestito via contextvars, funziona anche in async:

from printer import set_session_id, get_session_id

set_session_id("abc-123")
assert get_session_id() == "abc-123"

API Reference

Metodi di Livello

Tutti i metodi di livello supportano i seguenti parametri comuni:

• message (str): Messaggio da loggare
• output_type (str, opzionale): "print" o "log". Se None, usa default_output_type
• log_code (int, opzionale): Codice numerico (100-999) per il log
• state (str, opzionale): Stato corrente (influenza la risoluzione del log_code)
• force (bool): Se True, bypassa il filtro DebuggingMode
• use_emoji (bool): Se True, mostra emoji se configurata per il codice
• **properties: Metadati aggiuntivi (es. category, phase, user_id, ecc.)

debug(message, ...)

p.debug("Debug message", log_code=200, state="initializing")
printer.debug("Debug info", category="startup", phase="boot")

info(message, ...)

p.info("Application started", log_code=200)
printer.info("Request received", log_code=200, category="request", user_id=123)

warning(message, ...)

p.warning("Deprecated API used", log_code=400)
printer.warning("Rate limit approaching", log_code=429, remaining=5)

error(message, ...)

p.error("Failed to connect", log_code=500)
printer.error("Database error", log_code=503, db="primary", retry_count=3)

critical(message, ...)

p.critical("System failure", log_code=500)
printer.critical("Out of memory", log_code=500, memory_usage="99%")

success(message, ...)

p.success("Operation completed", log_code=200)
printer.success("User created", log_code=201, user_id=456)

Metodi Utility

header(message, char="=", length=80, force=False, **properties)

Stampa un'intestazione formattata:

p.header("Application Startup", char="=", length=50)
printer.header("Configuration", char="-", length=60)

section(title, content, force=False)

Stampa una sezione con titolo e contenuto:

p.section("Database", "Connected to PostgreSQL 14.2")
printer.section("Settings", "Debug mode: ON\nLog level: INFO")

custom(message, prefix="➡️", force=False)

Stampa un messaggio custom con prefisso:

p.custom("Custom log message", prefix="📝")
printer.custom("Processing started", prefix="⚙️")

plain(message, force=False)

Stampa un messaggio senza formattazione:

p.plain("Raw output without formatting")
printer.plain("Simple text message")

Metodi di Configurazione

set_logger_name(name)

Cambia il nome del logger:

p.set_logger_name("MyNewLogger")
printer.set_logger_name("AppLogger")

set_debugging_mode(mode)

Cambia la modalità di debugging:

from printer import DebuggingMode

p.set_debugging_mode(DebuggingMode.VERBOSE)
printer.set_debugging_mode(DebuggingMode.DEBUG)

API Funzionale (Singleton)

Quando usi import printer, puoi configurare un singleton condiviso:

configure_printer(...)

Configura il singleton con parametri:

import printer
from printer import DebuggingMode

printer.configure_printer(
    debugging_mode=DebuggingMode.DEBUG,
    custom_logs_prefix=True,
    session_id_prefix=True,
    name="MyApp",
    use_structured_logging=True,
    default_output_type="log",
    log_codes_path="log_codes.json",  # opzionale
    stacktrace_mode="exception_only",
)

configure_printer_config(config)

Configura usando un oggetto PrinterConfig:

from printer import PrinterConfig, DebuggingMode

config = PrinterConfig(
    debugging_mode=DebuggingMode.DEBUG,
    name="MyApp",
    use_structured_logging=True,
)
printer.configure_printer_config(config)

get_printer()

Ottiene l'istanza singleton configurata:

p = printer.get_printer()
p.info("Using singleton instance")

set_printer(printer)

Imposta manualmente il singleton:

from printer import Printer, DebuggingMode

my_printer = Printer(debugging_mode=DebuggingMode.DEBUG)
printer.set_printer(my_printer)

is_configured()

Verifica se il singleton è configurato:

if printer.is_configured():
    printer.info("Ready to log")
else:
    printer.configure_printer(...)

reset_printer()

Resetta il singleton (utile nei test):

printer.reset_printer()

Funzioni Utility

set_session_id(session_id)

Imposta il session ID nel contesto:

from printer import set_session_id

set_session_id("abc-123")

get_session_id()

Ottiene il session ID corrente:

from printer import get_session_id

session = get_session_id()  # "abc-123" o None

Requisiti

• Python >= 3.9

Documentazione completa

Per dettagli completi, esempi avanzati e configurazione, consulta il README completo nel repository.