Metadata-Version: 2.4
Name: printer-logging
Version: 1.0.4
Summary: Libreria Python per logging/stampa formattata con prefissi coerenti, filtro visibilità, log strutturati JSON opzionali e gestione session/remote id.
Author: Marco
License: Copyright (c) 2025 Marco
        Tutti i diritti riservati.
        
        LICENZA PROPRIETARIA (USO INTERNO)
        
        Questo software e la relativa documentazione (il "Software") sono di proprietà
        esclusiva del titolare del copyright indicato sopra.
        
        È CONSENTITO:
        - usare il Software internamente (anche in ambienti di produzione) all’interno
          dell’organizzazione autorizzata dal titolare del copyright;
        - modificare il Software per esigenze interne, mantenendo intatti questi avvisi.
        
        NON È CONSENTITO, senza autorizzazione scritta del titolare del copyright:
        - copiare o redistribuire il Software, in tutto o in parte, a terzi;
        - pubblicare il Software (es. repository pubblici), venderlo, sublicenziarlo,
          noleggiarlo o trasferirne i diritti;
        - reverse engineering, decompilazione o disassemblaggio laddove vietato dalla legge.
        
        ESCLUSIONE DI GARANZIA
        Il Software è fornito "COSÌ COM’È", senza alcuna garanzia, espressa o implicita,
        incluse (a titolo esemplificativo) le garanzie di commerciabilità, idoneità per
        uno scopo particolare e non violazione. L’uso è a rischio dell’utilizzatore.
        
        LIMITAZIONE DI RESPONSABILITÀ
        In nessun caso il titolare del copyright potrà essere ritenuto responsabile per
        qualsiasi danno diretto o indiretto, incidentale, speciale o consequenziale
        derivante dall’uso o dall’impossibilità di usare il Software.
        
        
        
Keywords: logging,structured-logging,json-logging,debugging,print,logger,session-id,log-codes
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
pip install printer-logging
```

## Quickstart

### Uso diretto (classe Printer)

```python
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)

```python
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:

```python
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, ...)`

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

#### `info(message, ...)`

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

#### `warning(message, ...)`

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

#### `error(message, ...)`

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

#### `critical(message, ...)`

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

#### `success(message, ...)`

```python
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:

```python
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:

```python
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:

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

#### `plain(message, force=False)`

Stampa un messaggio senza formattazione:

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

### Metodi di Configurazione

#### `set_logger_name(name)`

Cambia il nome del logger:

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

#### `set_debugging_mode(mode)`

Cambia la modalità di debugging:

```python
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:

```python
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`:

```python
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:

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

#### `set_printer(printer)`

Imposta manualmente il singleton:

```python
from printer import Printer, DebuggingMode

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

#### `is_configured()`

Verifica se il singleton è configurato:

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

#### `reset_printer()`

Resetta il singleton (utile nei test):

```python
printer.reset_printer()
```

### Funzioni Utility

#### `set_session_id(session_id)`

Imposta il session ID nel contesto:

```python
from printer import set_session_id

set_session_id("abc-123")
```

#### `get_session_id()`

Ottiene il session ID corrente:

```python
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](https://github.com/tuo-repo/printer) nel repository.
