6.28.7.2 Formato del file di configurazione

Il formato del file di configurazione esaminato da fileConfig() è basato sulla funzionalità di ConfigParser. Il file deve contenere le sezioni [loggers], [handlers] e [formatters] che identificano per nome le entità di ogni tipo che è definito nel file. Per ciascuna entità, c'è una sezione separata che identifica il modo in cui l'entità viene configurata. Quindi per un logger chiamato log01 nella sezione [loggers], i dettagli rilevati vengono mantenuti nella sezione [logger_log01]. Similmente, un handler chiamato hand01 avrà la propria configurazione mantenuta in una sezione chiamata [handler_hand01], quando un formatter chiamato form01 avrà nella sezione [formatters] la propria configurazione specificata in una sezione chiamata [formatter_form01]. La configurazione del logger principale deve essere inserita nella sezione chiamata [logger_root].

[loggers]
keys=root,log02,log03,log04,log05,log06,log07

[handlers]
keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09

[formatters]
keys=form01,form02,form03,form04,form05,form06,form07,form08,form09

Il logger principale deve specificare un livello e una lista di handler. Un esempio della sezione di un root logger è fornita a seguito.

[logger_root]
level=NOTSET
handlers=hand01

La voce level può essere una tra DEBUG, INFO, WARNING, ERROR, CRITICAL o NOTSET. Solo per il logger principale, il root logger, NOTSET indica che tutti i messaggi verranno loggati. I valori di livello vengono valutati (eval()) nel contesto dello spazio dei nomi del package di logging.

La voce handlers è una lista separata da virgole di nomi di handler, che devono apparire nella sezione [handlers]. Questi nomi devono apparire nella sezione [handlers] e devono avere una corrispondente sezione nel file di configurazione.

Per i logger diversi dal logger principale (root logger), vengono richieste alcune ulteriori informazioni. Queste vengono illustrate con l'esempio seguente:

[logger_parser]
level=DEBUG
handlers=hand01
propagate=1
qualname=compiler.parser

Le voci degli handlers e di level vengono interpretate come per il logger principale, eccezion fatta laddove il livello del logger non principale è specificato come NOTSET. Il sistema consulta il logger più in alto nella gerarchia per determinare l'effettivo livello del logger. La voce propagate viene impostata a 1 per indicare che i messaggi devono essere propagati fino all'handler più alto nella gerarchia, o 0 per indicare che i messaggi non si devono propagare agli handler superiori nella gerarchia. La voce qualname è gerarchicamente il nome del canale del logger, per esempio, il nome usato dall'applicazione per ottenere il logger.

Le sezioni che specificano la configurazione per l'handler sono esemplificate di seguito.

[handler_hand01]
class=StreamHandler
level=NOTSET
formatter=form01
args=(sys.stdout,)

La voce class indica la classe dell'handler (come determinata da eval() nello spazio dei nomi del package logging). level viene interpretato come per i logger, e NOTSET viene interpretato come "registra ogni cosa".

La voce formatter indica il nome della chiave del formatter per questo handler. Se vuoto, viene utilizzato un formatter predefinito (logging._defaultFormatter). Se viene specificato un nome, deve apparire nella sezione [formatters] e possedere una corrispondente sezione nel file di configurazione.

La voce args, quando valutata (attraverso eval()), nel contesto dello spazio dei nomi del package logging, è la lista degli argomenti per il costruttore della classe di handler. Riferitevi ai costruttori per l'handler principale, o all'esempio qui di seguito, per vedere quali voci tipiche vengono utilizzate.

[handler_hand02]
class=FileHandler
level=DEBUG
formatter=form02
args=('python.log', 'w')

[handler_hand03]
class=handlers.SocketHandler
level=INFO
formatter=form03
args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)

[handler_hand04]
class=handlers.DatagramHandler
level=WARN
formatter=form04
args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)

[handler_hand05]
class=handlers.SysLogHandler
level=ERROR
formatter=form05
args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)

[handler_hand06]
class=NTEventLogHandler
level=CRITICAL
formatter=form06
args=('Python Application', '', 'Application')

[handler_hand07]
class=SMTPHandler
level=WARN
formatter=form07
args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')

[handler_hand08]
class=MemoryHandler
level=NOTSET
formatter=form08
target=
args=(10, ERROR)

[handler_hand09]
class=HTTPHandler
level=NOTSET
formatter=form09
args=('localhost:9022', '/log', 'GET')

Le sezioni che specificano la configurazione del formatter sono presentate di seguito.

[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s
datefmt=

La voce format è la stringa di formato principale, e la voce datefmt è la stringa di formato strftime()-compatibile data/ora. Se vuota, il package lo sostituisce con data/ora formato ISO8601, che è all'incirca equivalente alla specifica stringa di formato "Il formato ISO8601 specifica anche i millisecondi, che vengono aggiunti al risultato utilizzando la stringa di formato sopra, con un separatore ",". Un ora d'esempio in formato ISO8601 è 2003-01-23 00:29:50,411.