logging — Loggningsfunktion för Python

Källkod: Lib/logging/__init__.py

Important

Den här sidan innehåller API-referensinformation. För information om handledning och diskussion om mer avancerade ämnen, se

• Grundläggande handledning

• Avancerad handledning

• Loggning av kokbok

---

Denna modul definierar funktioner och klasser som implementerar ett flexibelt händelseloggningssystem för applikationer och bibliotek.

Den största fördelen med att API:et för loggning tillhandahålls av en standardbiblioteksmodul är att alla Python-moduler kan delta i loggning, så att din applikationslogg kan innehålla dina egna meddelanden integrerade med meddelanden från tredjepartsmoduler.

Här är ett enkelt exempel på idiomatisk användning:

# myapp.py
import logging
import mylib
logger = logging.getLogger(__name__)

def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logger.info('Started')
    mylib.do_something()
    logger.info('Finished')

if __name__ == '__main__':
    main()

# mylib.py
import logging
logger = logging.getLogger(__name__)

def do_something():
    logger.info('Doing something')

Om du kör myapp.py bör du se detta i myapp.log:

INFO:__main__:Startade
INFO:mylib:Gör något
INFO:__main__:Avslutad

Den viktigaste egenskapen hos denna idiomatiska användning är att majoriteten av koden helt enkelt skapar en logger på modulnivå med getLogger(__name__) och använder den loggern för att göra all nödvändig loggning. Detta är kortfattat, samtidigt som det tillåter nedströmskod finkornig kontroll om det behövs. Loggade meddelanden till loggern på modulnivå vidarebefordras till hanterare av loggrar i moduler på högre nivåer, hela vägen upp till loggern på högsta nivå, känd som rotloggern; detta tillvägagångssätt kallas hierarkisk loggning.

För att loggning ska vara användbar måste den konfigureras: ange nivåer och destinationer för varje logger, eventuellt ändra hur specifika moduler loggar, ofta baserat på kommandoradsargument eller programkonfiguration. I de flesta fall, som i fallet ovan, är det bara rotloggaren som behöver konfigureras på detta sätt, eftersom alla loggar på lägre nivåer på modulnivå i slutändan vidarebefordrar sina meddelanden till dess hanterare. basicConfig() ger ett snabbt sätt att konfigurera rotloggaren som hanterar många användningsfall.

Modulen ger mycket funktionalitet och flexibilitet. Om du inte är bekant med loggning är det bästa sättet att komma igång att titta på handledningarna (se länkarna ovan och till höger).

De grundläggande klasser som definieras av modulen, tillsammans med deras attribut och metoder, listas i avsnitten nedan.

• Loggar exponerar det gränssnitt som applikationskoden använder direkt.

• Hanterare skickar loggposter (som skapats av loggar) till lämplig destination.

• Filter ger en mer finfördelad möjlighet att bestämma vilka loggposter som ska matas ut.

• Formatterare specificerar layouten för loggposter i den slutliga utskriften.

Logger-objekt

Loggrar har följande attribut och metoder. Observera att loggar ALDRIG ska instansieras direkt, utan alltid genom funktionen logging.getLogger(name) på modulnivå. Flera anrop till getLogger() med samma namn kommer alltid att returnera en referens till samma Logger-objekt.

Namnet kan vara ett periodseparerat hierarkiskt värde, t.ex. ”foo.bar.baz” (men det kan också vara bara ”foo”, till exempel). Loggar som ligger längre ner i den hierarkiska listan är barn till loggar högre upp i listan. Om du till exempel har en logger med namnet foo, är loggrar med namnen foo.bar, foo.bar.baz och foo.bam alla ättlingar till foo. Dessutom är alla loggrar ättlingar till rotloggaren. Loggarnas namnhierarki är analog med Pythons pakethierarki, och identisk med den om du organiserar dina loggar per modul med hjälp av den rekommenderade konstruktionen logging.getLogger(__name__). Det beror på att i en modul är __name__ modulens namn i Python-paketets namnrymd.

class logging.Logger

name

Detta är loggarens namn och är det värde som skickades till getLogger() för att hämta loggern.

Anteckning

Detta attribut bör behandlas som skrivskyddat.

level

Tröskelvärdet för denna logger, som anges med metoden setLevel().

Anteckning

Ställ inte in detta attribut direkt - använd alltid setLevel(), som kontrollerar den nivå som skickas till den.

parent

Den här loggarens överordnade logger. Den kan ändras beroende på senare instansiering av loggrar som ligger högre upp i namnrymdshierarkin.

Anteckning

Detta värde bör behandlas som skrivskyddat.

propagate

Om detta attribut utvärderas till true, kommer händelser som loggas i denna logger att skickas till hanterare av loggrar på högre nivå (förfäder), utöver eventuella hanterare som är kopplade till denna logger. Meddelanden skickas direkt till de överordnade loggarnas hanterare - varken nivån eller filtren för de överordnade loggarna i fråga beaktas.

Om detta utvärderas till false, skickas inte loggarnas meddelanden till hanterarna av förfädernas loggar.

Stava ut det med ett exempel: Om propagate-attributet för loggern med namnet A.B.C utvärderas till true, kommer alla händelser som loggas till A.B.C via ett metodanrop som logging.getLogger('A.B.C').error(...) [med förbehåll för att loggarens nivå- och filterinställningar passerar] att i sin tur passera till alla hanterare som är kopplade till loggar med namnen A.B, A och rotloggern, efter att först ha passerat till alla hanterare som är kopplade till A.B.C. Om någon logger i kedjan A.B.C, A.B, A har sitt propagate-attribut satt till false, så är det den sista loggern vars hanterare erbjuds händelsen att hantera, och spridningen stoppas vid den punkten.

Konstruktören sätter detta attribut till True.

Anteckning

Om du kopplar en hanterare till en logger och en eller flera av dess förfäder kan det hända att den skickar ut samma post flera gånger. I allmänhet behöver du inte koppla en hanterare till mer än en logger - om du bara kopplar den till den lämpliga logger som är högst upp i loggerhierarkin kommer den att se alla händelser som loggas av alla loggrar i nedstigande led, förutsatt att deras propagate-inställning är inställd på True. Ett vanligt scenario är att bifoga hanterare endast till rotloggaren och låta spridningen ta hand om resten.

handlers

Listan över handläggare som är direkt kopplade till denna loggerinstans.

Anteckning

Detta attribut bör behandlas som skrivskyddat; det ändras normalt via metoderna addHandler() och removeHandler(), som använder lås för att säkerställa trådsäker drift.

disabled

Detta attribut inaktiverar hantering av alla händelser. Det sätts till False i initialiseraren och ändras endast genom konfigurationskod för loggning.

Anteckning

Detta attribut bör behandlas som skrivskyddat.

setLevel(level)

Sätter tröskelvärdet för denna logger till level. Loggmeddelanden som är mindre allvarliga än level ignoreras; loggmeddelanden som har allvarlighetsgrad level eller högre kommer att skickas ut av den eller de hanterare som betjänar denna logger, såvida inte hanterarens nivå har ställts in på en högre allvarlighetsgrad än level.

När en logger skapas sätts nivån till NOTSET (vilket gör att alla meddelanden behandlas när loggern är rotlogger, eller delegeras till föräldern när loggern är en icke-rotlogger). Observera att rotloggaren skapas med nivån WARNING.

Termen ”delegering till överordnad” innebär att om en logger har nivån NOTSET, genomkorsas dess kedja av överordnade loggrar tills antingen en överordnad med en annan nivå än NOTSET hittas eller roten nås.

Om en förfader hittas med en annan nivå än NOTSET, behandlas den förfaderns nivå som den effektiva nivån för den logger där förfaderssökningen började och används för att avgöra hur en logghändelse ska hanteras.

Om roten nås och den har en nivå på NOTSET kommer alla meddelanden att behandlas. I annat fall kommer rotens nivå att användas som effektiv nivå.

Se Loggningsnivåer för en lista över nivåer.

Ändrad i version 3.2: Parametern level accepterar nu en strängrepresentation av nivån, t.ex. ’INFO’, som ett alternativ till heltalskonstanter som INFO. Observera dock att nivåer lagras internt som heltal, och metoder som t.ex. getEffectiveLevel() och isEnabledFor() returnerar/förväntar sig att få heltal skickade till sig.

isEnabledFor(level)

Anger om ett meddelande med allvarlighetsgrad level skulle behandlas av denna logger. Den här metoden kontrollerar först nivån på modulnivå som anges av logging.disable(level) och sedan loggarens effektiva nivå som bestäms av getEffectiveLevel().

getEffectiveLevel()

Anger den effektiva nivån för denna logger. Om ett annat värde än NOTSET har angetts med setLevel(), returneras det. I annat fall genomkorsas hierarkin mot roten tills ett annat värde än NOTSET hittas, och det värdet returneras. Värdet som returneras är ett heltal, vanligtvis ett av logging.DEBUG, logging.INFO etc.

getChild(suffix)

Returnerar en logger som är en ättling till denna logger, vilket bestäms av suffixet. Således skulle logging.getLogger('abc').getChild('def.ghi') returnera samma logger som skulle returneras av logging.getLogger('abc.def.ghi'). Detta är en bekvämlighetsmetod som är användbar när den överordnade loggern namnges med t.ex. __name__ i stället för en bokstavlig sträng.

Tillagd i version 3.2.

getChildren()

Returnerar en uppsättning loggrar som är omedelbara barn till denna logger. Så till exempel kan logging.getLogger().getChildren() returnera en uppsättning som innehåller loggrar med namnen foo och bar, men en logger med namnet foo.bar skulle inte ingå i uppsättningen. På samma sätt kan logging.getLogger('foo').getChildren() returnera en uppsättning som innehåller en logger med namnet foo.bar, men den skulle inte innehålla en med namnet foo.bar.baz.

Tillagd i version 3.12.

debug(msg, *args, **kwargs)

Loggar ett meddelande med nivån DEBUG på den här loggern. msg är meddelandets formatsträng och args är de argument som slås samman till msg med hjälp av strängformateringsoperatorn. (Observera att detta innebär att du kan använda nyckelord i formatsträngen tillsammans med ett enda ordboksargument) Ingen % formatering utförs på msg när inga args anges.

Det finns fyra nyckelordsargument i kwargs som inspekteras: exc_info, stack_info, stacklevel och extra.

Om exc_info inte utvärderas som false, läggs information om undantaget till i loggmeddelandet. Om en undantagstupel (i det format som returneras av sys.exc_info()) eller en undantagsinstans tillhandahålls, används den; annars anropas sys.exc_info() för att hämta undantagsinformationen.

Det andra valfria nyckelordsargumentet är stack_info, som har standardvärdet False. Om det är sant läggs stackinformation till i loggmeddelandet, inklusive det faktiska loggningsanropet. Observera att detta inte är samma stackinformation som den som visas om du anger exc_info: Den förstnämnda är stapelramar från botten av stacken fram till loggningsanropet i den aktuella tråden, medan den sistnämnda är information om stapelramar som har rullats upp efter ett undantag när man söker efter undantagshanterare.

Du kan ange stack_info oberoende av exc_info, t.ex. om du bara vill visa hur du kom till en viss punkt i din kod, även om inga undantag uppstod. Stackramarna skrivs ut efter en rubrikrad som säger:

Stack (senaste anropet senast):

Detta efterliknar Traceback (most recent call last): som används vid visning av undantagsramar.

Det tredje valfria nyckelordsargumentet är stacklevel, som har standardvärdet 1. Om det är större än 1 hoppas motsvarande antal stack frames över vid beräkning av radnummer och funktionsnamn som anges i LogRecord som skapats för loggningshändelsen. Detta kan användas i hjälpfunktioner för loggning så att det funktionsnamn, filnamn och radnummer som registreras inte är information för hjälpfunktionen/metoden, utan för den som anropar den. Namnet på denna parameter speglar motsvarande parameter i modulen warnings.

Det fjärde nyckelordsargumentet är extra som kan användas för att skicka en ordbok som används för att fylla i __dict__ i LogRecord som skapats för loggningshändelsen med användardefinierade attribut. Dessa anpassade attribut kan sedan användas som du vill. De kan t.ex. införlivas i loggade meddelanden. Till exempel:

FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)

skulle skriva ut något i stil med

2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset

Nycklarna i den ordbok som skickas till extra får inte krocka med de nycklar som används av loggningssystemet. (Se avsnittet om LogRecord-attribut för mer information om vilka nycklar som används av loggningssystemet)

Om du väljer att använda dessa attribut i loggade meddelanden måste du vara lite försiktig. I exemplet ovan har t.ex. Formatter konfigurerats med en formatsträng som förväntar sig att ’clientip’ och ’user’ finns i attributordlistan för LogRecord. Om dessa saknas kommer meddelandet inte att loggas eftersom ett undantag för strängformatering inträffar. Så i det här fallet måste du alltid skicka den extra ordlistan med dessa nycklar.

Även om detta kan vara irriterande är den här funktionen avsedd att användas under speciella omständigheter, t.ex. flertrådade servrar där samma kod körs i många sammanhang och intressanta villkor som uppstår är beroende av detta sammanhang (t.ex. fjärrklientens IP-adress och autentiserat användarnamn i exemplet ovan). Under sådana omständigheter är det troligt att specialiserade Formatter s skulle användas med särskilda Handler s.

Om ingen hanterare är kopplad till denna logger (eller någon av dess förfäder, med hänsyn till relevanta Logger.propagate-attribut), kommer meddelandet att skickas till den hanterare som är inställd på lastResort.

Ändrad i version 3.2: Parametern stack_info har lagts till.

Ändrad i version 3.5: Parametern exc_info kan nu acceptera undantagsinstanser.

Ändrad i version 3.8: Parametern stacklevel har lagts till.

info(msg, *args, **kwargs)

Loggar ett meddelande med nivå INFO på denna logger. Argumenten tolkas som för debug().

warning(msg, *args, **kwargs)

Loggar ett meddelande med nivå WARNING på denna logger. Argumenten tolkas som för debug().

Anteckning

Det finns en föråldrad metod warn som är funktionellt identisk med warning. Eftersom warn är föråldrad, använd den inte - använd warning istället.

error(msg, *args, **kwargs)

Loggar ett meddelande med nivån ERROR på denna logger. Argumenten tolkas som för debug().

critical(msg, *args, **kwargs)

Loggar ett meddelande med nivå CRITICAL på denna logger. Argumenten tolkas som för debug().

log(level, msg, *args, **kwargs)

Loggar ett meddelande med heltalsnivån level på denna logger. De andra argumenten tolkas som för debug().

exception(msg, *args, **kwargs)

Loggar ett meddelande med nivån ERROR på denna logger. Argumenten tolkas som för debug(). Undantagsinformation läggs till i logningsmeddelandet. Denna metod bör endast anropas från en undantagshanterare.

addFilter(filter)

Lägger till det angivna filtret filter till denna logger.

removeFilter(filter)

Tar bort det angivna filtret filter från den här loggern.

filter(record)

Tillämpa denna loggers filter på posten och returnera True om posten ska behandlas. Filtren konsulteras i tur och ordning tills ett av dem returnerar ett falskt värde. Om inget av dem returnerar ett falskt värde kommer posten att behandlas (skickas till handläggare). Om ett filter returnerar ett falskt värde sker ingen ytterligare behandling av posten.

addHandler(hdlr)

Lägger till den angivna hanteraren hdlr till denna logger.

removeHandler(hdlr)

Tar bort den angivna hanteraren hdlr från denna logger.

findCaller(stack_info=False, stacklevel=1)

Hittar anroparens källfilnamn och radnummer. Returnerar filnamn, radnummer, funktionsnamn och stackinformation som en tupel med 4 element. Stackinformationen returneras som None om inte stack_info är True.

Parametern stacklevel skickas från kod som anropar debug() och andra API:er. Om den är större än 1 används överskottet för att hoppa över stackrutor innan man bestämmer vilka värden som ska returneras. Detta är i allmänhet användbart när loggnings-API:er anropas från hjälp-/omslagskod, så att informationen i händelseloggen inte hänvisar till hjälp-/omslagskoden utan till den kod som anropar den.

handle(record)

Hanterar en post genom att skicka den till alla hanterare som är associerade med denna logger och dess förfäder (tills ett falskt värde för propagate hittas). Den här metoden används för obehandlade poster som tas emot från ett uttag, samt för poster som skapas lokalt. Filtrering på loggarnivå görs med filter().

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

Detta är en fabriksmetod som kan åsidosättas i underklasser för att skapa specialiserade LogRecord-instanser.

hasHandlers()

Kontrollerar om denna logger har några hanterare konfigurerade. Detta görs genom att leta efter hanterare i den här loggern och dess föräldrar i loggerhierarkin. Returnerar True om en hanterare hittades, annars False. Metoden slutar att söka uppåt i hierarkin när en logger med attributet ’propagate’ inställt på false hittas - det blir den sista loggern som kontrolleras för förekomsten av hanterare.

Tillagd i version 3.2.

Ändrad i version 3.7: Skogshuggare kan nu bli inlagda och oinlagda.

Loggningsnivåer

De numeriska värdena för loggningsnivåerna anges i följande tabell. Dessa är främst intressanta om du vill definiera dina egna nivåer och vill att de ska ha specifika värden i förhållande till de fördefinierade nivåerna. Om du definierar en nivå med samma numeriska värde, skriver den över det fördefinierade värdet; det fördefinierade namnet försvinner.

Nivå	Numeriskt värde	Vad det betyder / När det ska användas
logging.NOTSET	0	När den är inställd på en logger indikerar den att föregående loggar ska konsulteras för att bestämma den effektiva nivån. Om detta fortfarande resulterar i NOTSET, loggas alla händelser. När den är inställd på en hanterare hanteras alla händelser.
logging.DEBUG	10	Detaljerad information som vanligtvis bara är av intresse för en utvecklare som försöker diagnostisera ett problem.
logging.INFO	20	Bekräftelse på att saker och ting fungerar som förväntat.
logging.WARNING	30	En indikation på att något oväntat har hänt eller att ett problem kan uppstå inom en snar framtid (t.ex. ”lågt diskutrymme”). Programvaran fungerar fortfarande som förväntat.
logging.ERROR	40	På grund av ett mer allvarligt problem har programvaran inte kunnat utföra någon funktion.
logging.CRITICAL	50	Ett allvarligt fel som indikerar att själva programmet kanske inte kan fortsätta att köras.

Handläggarobjekt

Hanterare har följande attribut och metoder. Observera att Handler aldrig instansieras direkt; denna klass fungerar som en bas för mer användbara subklasser. Metoden __init__() i underklasser måste dock anropa Handler.__init__().

class logging.Handler

__init__(level=NOTSET)

Initialiserar Handler-instansen genom att ange dess nivå, ange listan med filter till den tomma listan och skapa ett lås (med createLock()) för serialisering av åtkomst till en I/O-mekanism.

createLock()

Initialiserar ett trådlås som kan användas för att serialisera åtkomst till underliggande I/O-funktionalitet som kanske inte är trådsäker.

acquire()

Förvärvar det trådlås som skapats med createLock().

release()

Frigör trådlåset som förvärvats med acquire().

setLevel(level)

Sätter tröskelvärdet för denna hanterare till level. Loggmeddelanden som är mindre allvarliga än level ignoreras. När en hanterare skapas sätts nivån till NOTSET (vilket gör att alla meddelanden behandlas).

Se Loggningsnivåer för en lista över nivåer.

Ändrad i version 3.2: Parametern level accepterar nu en strängrepresentation av nivån, t.ex. ’INFO’, som ett alternativ till heltalskonstanter, t.ex. INFO.

setFormatter(fmt)

Ställer in formateraren för denna hanterare till fmt. Argumentet fmt måste vara en instans av Formatter eller None.

addFilter(filter)

Lägger till det angivna filtret filter till denna hanterare.

removeFilter(filter)

Tar bort det angivna filtret filter från den här hanteraren.

filter(record)

Tillämpa den här hanterarens filter på posten och returnera True om posten ska behandlas. Filtren konsulteras i tur och ordning tills ett av dem returnerar ett falskt värde. Om inget av dem returnerar ett falskt värde kommer posten att sändas ut. Om ett av filtren returnerar ett falskt värde, kommer hanteraren inte att skicka ut posten.

flush()

Säkerställ att all loggningsutdata har rensats. Den här versionen gör ingenting och är avsedd att implementeras av underklasser.

close()

Städa upp alla resurser som används av hanteraren. Den här versionen gör ingen utmatning men tar bort hanteraren från en intern karta över hanterare, som används för att söka efter hanterare med namn.

Subklasser bör se till att detta anropas från åsidosatta close()-metoder.

handle(record)

Sänder villkorligt ut den angivna loggningsposten, beroende på filter som kan ha lagts till i hanteraren. Omsluter den faktiska utsändningen av posten med förvärv/lösen av I/O-trådens lås.

handleError(record)

Denna metod bör anropas från hanterare när ett undantag inträffar under ett anrop av emit(). Om modulnivåattributet raiseExceptions är False, ignoreras undantag i tysthet. Detta är vad som oftast önskas för ett loggningssystem - de flesta användare kommer inte att bry sig om fel i loggningssystemet, de är mer intresserade av applikationsfel. Du kan dock ersätta detta med en anpassad hanterare om du vill. Den angivna posten är den som höll på att bearbetas när undantaget inträffade. (Standardvärdet för raiseExceptions är True, eftersom det är mer användbart under utveckling).

format(record)

Gör formatering för en post - om en formaterare är inställd, använd den. Annars används standardformateringen för modulen.

emit(record)

Gör vad som krävs för att faktiskt logga den angivna loggningsposten. Denna version är avsedd att implementeras av underklasser och ger därför upphov till ett NotImplementedError.

Varning

Denna metod anropas efter att ett lås på hanterarnivå har förvärvats, vilket frigörs efter att denna metod returneras. När du åsidosätter den här metoden, observera att du bör vara försiktig när du anropar något som anropar andra delar av loggnings-API:t som kan göra låsning, eftersom det kan leda till ett dödläge. Specifikt för detta:

• API:er för loggningskonfiguration förvärvar låset på modulnivå och sedan lås på individuell hanterarnivå när dessa hanterare konfigureras.

• Många API:er för loggning låser låset på modulnivå. Om ett sådant API anropas från den här metoden kan det orsaka ett dödläge om ett konfigurationsanrop görs i en annan tråd, eftersom den tråden kommer att försöka förvärva låset på modulnivå före låset på hanterarnivå, medan den här tråden försöker förvärva låset på modulnivå efter låset på hanterarnivå (eftersom låset på hanterarnivå redan har förvärvats i den här metoden).

För en lista över de handlers som ingår som standard, se logging.handlers.

Formateringsobjekt

class logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Ansvarig för att omvandla en LogRecord till en utdatasträng som kan tolkas av en människa eller ett externt system.

Parametrar:

• fmt (str) – En formatsträng i den angivna stilen för den loggade utdata som helhet. De möjliga mappningsnycklarna hämtas från LogRecord-objektets LogRecord-attribut. Om inget anges används '%(message)s', vilket bara är det loggade meddelandet.

• datefmt (str) – En formatsträng i den angivna stilen för datum/tid-delen av den loggade utdata. Om inget anges används standardvärdet som beskrivs i formatTime().

• style (str) – Kan vara en av '%', '{' eller '$' och bestämmer hur formatsträngen ska slås samman med dess data: med hjälp av en av strängformatering i stil med printf (%), str.format() ({) eller string.Template ($). Detta gäller endast för fmt och datefmt (t.ex. '%(message)s' jämfört med '{message}'), inte för de faktiska loggmeddelanden som skickas till loggmetoderna. Det finns dock andra sätt att använda {- och $-formatering för loggmeddelanden.

• validate (bool) – Om True (standard) kommer felaktig eller ej matchande fmt och style att ge upphov till ett ValueError; till exempel logging.Formatter('%(asctime)s - %(message)s', style='{').

• defaults (dict[str, Any]) – En ordbok med standardvärden som ska användas i anpassade fält. Till exempel logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})

Ändrad i version 3.2: Lagt till parametern style.

Ändrad i version 3.8: Lagt till parametern validate.

Ändrad i version 3.10: Parametern defaults har lagts till.

format(record)

Postens attributordbok används som operand i en strängformateringsoperation. Returnerar den resulterande strängen. Innan ordlistan formateras utförs ett par förberedande steg. Attributet message för posten beräknas med hjälp av msg % args. Om formateringssträngen innehåller '(asctime)', anropas formatTime() för att formatera händelsetiden. Om det finns undantagsinformation formateras den med formatException() och läggs till i meddelandet. Observera att den formaterade undantagsinformationen cachelagras i attributet exc_text. Detta är användbart eftersom undantagsinformationen kan plockas ut och skickas över kabeln, men du bör vara försiktig om du har mer än en Formatter-underklass som anpassar formateringen av undantagsinformation. I så fall måste du rensa det cachade värdet (genom att sätta attributet exc_text till None) efter att en formaterare har gjort sin formatering, så att nästa formaterare som hanterar händelsen inte använder det cachade värdet, utan räknar om det på nytt.

Om stackinformation finns tillgänglig läggs den till efter undantagsinformationen, med hjälp av formatStack() för att omvandla den vid behov.

formatTime(record, datefmt=None)

Denna metod bör anropas från format() av en formaterare som vill använda en formaterad tid. Denna metod kan åsidosättas i formaterare för att tillgodose specifika krav, men det grundläggande beteendet är följande: om datefmt (en sträng) anges, används den med time.strftime() för att formatera skapelsetiden för posten. Annars används formatet ’%Y-%m-%d %H:%M:%S,uuu’, där uuu-delen är ett millisekundvärde och de andra bokstäverna är enligt dokumentationen för time.strftime(). Ett exempel på tid i detta format är 2003-01-23 00:29:50,411. Den resulterande strängen returneras.

Denna funktion använder en användarkonfigurerbar funktion för att konvertera skapelsetiden till en tupel. Som standard används time.localtime(); för att ändra detta för en viss formateringsinstans, ställ in attributet converter till en funktion med samma signatur som time.localtime() eller time.gmtime(). Om du vill ändra detta för alla formaterare, t.ex. om du vill att alla loggningstider ska visas i GMT, anger du attributet converter i klassen Formatter.

Ändrad i version 3.3: Tidigare var standardformatet hårdkodat som i det här exemplet: 2010-09-06 22:38:15,292 där delen före kommatecknet hanteras av en strptime-formatsträng ('%Y-%m-%d %H:%M:%S') och delen efter kommatecknet är ett millisekundvärde. Eftersom strptime inte har någon formatplatshållare för millisekunder läggs millisekundvärdet till med hjälp av en annan formatsträng, '%s,%03d' — och båda dessa formatsträngar har varit hårdkodade i den här metoden. I och med ändringen definieras dessa strängar som attribut på klassnivå som kan åsidosättas på instansnivå när så önskas. Namnen på attributen är default_time_format (för strptime-formatsträngen) och default_msec_format (för att lägga till millisekundvärdet).

Ändrad i version 3.9: Standard_msec_format kan vara ”ingen”.

formatException(exc_info)

Formaterar den angivna undantagsinformationen (en standardtupel för undantag som returneras av sys.exc_info()) som en sträng. Denna standardimplementering använder bara traceback.print_exception(). Den resulterande strängen returneras.

formatStack(stack_info)

Formaterar den angivna stackinformationen (en sträng som returneras av traceback.print_stack(), men med den sista nya raden borttagen) som en sträng. Denna standardimplementering returnerar bara inmatningsvärdet.

class logging.BufferingFormatter(linefmt=None)

En basformateringsklass som lämpar sig för underklassning när du vill formatera ett antal poster. Du kan skicka en Formatter-instans som du vill använda för att formatera varje rad (som motsvarar en enda post). Om inget anges används standardformateraren (som bara matar ut händelsemeddelandet) som radformaterare.

formatHeader(records)

Returnerar ett sidhuvud för en lista med poster. Basimplementeringen returnerar bara den tomma strängen. Du måste åsidosätta den här metoden om du vill ha ett specifikt beteende, t.ex. om du vill visa antalet poster, en titel eller en separationsrad.

formatFooter(records)

Returnerar en sidfot för en lista med poster. Basimplementeringen returnerar bara den tomma strängen. Du måste åsidosätta den här metoden om du vill ha ett specifikt beteende, t.ex. om du vill visa antalet poster eller en separationsrad.

format(records)

Returnerar formaterad text för en lista med poster. Basimplementeringen returnerar bara den tomma strängen om det inte finns några poster; annars returneras konkateneringen av rubriken, varje post som formaterats med radformateraren och sidfoten.

Filtrera objekt

Filters kan användas av Handlers och Loggers för mer sofistikerad filtrering än vad som tillhandahålls av levels. Basfilterklassen tillåter endast händelser som ligger under en viss punkt i loggerhierarkin. Exempelvis kommer ett filter som initieras med ”A.B” att tillåta händelser som loggas av loggrarna ”A.B”, ”A.B.C”, ”A.B.C.D”, ”A.B.D” etc. men inte ”A.BB”, ”B.A.B” etc. Om den initieras med en tom sträng skickas alla händelser vidare.

class logging.Filter(name='')

Returnerar en instans av klassen Filter. Om name anges, namnges en logger som, tillsammans med sina underordnade loggar, kommer att få sina händelser tillåtna genom filtret. Om name är en tom sträng tillåts alla händelser.

filter(record)

Ska den angivna posten loggas? Returnerar false för nej, true för ja. Filter kan antingen ändra loggposter på plats eller returnera en helt annan postinstans som kommer att ersätta den ursprungliga loggposten vid framtida behandling av händelsen.

Observera att filter som är kopplade till hanterare konsulteras innan en händelse sänds ut av hanteraren, medan filter som är kopplade till loggrar konsulteras när en händelse loggas (med debug(), info(), etc.), innan en händelse skickas till hanterare. Detta innebär att händelser som har genererats av loggar i nedstigande led inte filtreras av en loggers filterinställning, såvida inte filtret också har tillämpats på dessa loggar i nedstigande led.

Du behöver faktiskt inte underklassa Filter: du kan skicka vilken instans som helst som har en filter-metod med samma semantik.

Ändrad i version 3.2: Du behöver inte skapa specialiserade Filter-klasser eller använda andra klasser med en filter-metod: du kan använda en funktion (eller annan anropsbar) som ett filter. Filtreringslogiken kommer att kontrollera om filterobjektet har ett filter-attribut: om det gör det, antas det vara ett Filter och dess filter()-metod anropas. Annars antas den vara en callable och anropas med posten som enda parameter. Det returnerade värdet bör överensstämma med det som returneras av filter().

Ändrad i version 3.12: Du kan nu returnera en LogRecord-instans från filter för att ersätta loggposten i stället för att modifiera den på plats. Detta gör att filter som är kopplade till en Handler kan modifiera loggposten innan den sänds ut, utan att det får bieffekter på andra handlers.

Även om filter främst används för att filtrera poster baserat på mer sofistikerade kriterier än nivåer, får de se varje post som bearbetas av den hanterare eller logger de är kopplade till: detta kan vara användbart om du vill göra saker som att räkna hur många poster som bearbetades av en viss logger eller hanterare, eller lägga till, ändra eller ta bort attribut i LogRecord som bearbetas. Självklart måste ändring av LogRecord göras med viss försiktighet, men det gör det möjligt att injicera kontextuell information i loggar (se Använda filter för att ge kontextuell information).

LogRecord-objekt

LogRecord-instanser skapas automatiskt av Logger varje gång något loggas, och kan skapas manuellt via makeLogRecord() (t.ex. från en inlagd händelse som tas emot över kabeln).

class logging.LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

Innehåller all information som är relevant för den händelse som loggas.

Den primära informationen skickas i msg och args, som kombineras med hjälp av msg % args för att skapa attributet message för posten.

Parametrar:

• name (str) – Namnet på den logger som används för att logga den händelse som representeras av denna LogRecord. Observera att loggarens namn i LogRecord alltid kommer att ha detta värde, även om det kan sändas ut av en hanterare som är kopplad till en annan (förfaderlig) logger.

• level (int) – Den numeriska nivån för logghändelsen (till exempel 10 för DEBUG, 20 för INFO, etc). Observera att detta konverteras till två attribut i LogRecord: levelno för det numeriska värdet och levelname för motsvarande nivånamn.

• pathname (str) – Den fullständiga sökvägen till källfilen där loggningsanropet gjordes.

• lineno (int) – Radnumret i källfilen där loggningsanropet gjordes.

• msg (Any) – Händelsebeskrivningsmeddelandet, som kan vara en %-format sträng med platshållare för variabeldata, eller ett godtyckligt objekt (se Använda godtyckliga objekt som meddelanden).

• args (tuple | dict[str, Any]) – Variabel data som ska sammanfogas med msg-argumentet för att få en beskrivning av händelsen.

• exc_info (tuple[type[BaseException], BaseException, types.TracebackType] | None) – En exception-tupel med aktuell exceptioninformation, som returneras av sys.exc_info(), eller None om ingen exceptioninformation finns tillgänglig.

• func (str | None) – Namnet på den funktion eller metod från vilken anropet för loggning gjordes.

• sinfo (str | None) – En textsträng som representerar stackinformation från stackens bas i den aktuella tråden, fram till loggningsanropet.

getMessage()

Returnerar meddelandet för denna LogRecord-instans efter att ha slagit samman eventuella användartillhandahållna argument med meddelandet. Om det användartillhandahållna meddelandeargumentet till loggningsanropet inte är en sträng, anropas str() för att konvertera det till en sträng. Detta gör det möjligt att använda användardefinierade klasser som meddelanden, vars metod __str__ kan returnera den faktiska formatsträng som ska användas.

Ändrad i version 3.2: Skapandet av en LogRecord har gjorts mer konfigurerbar genom att tillhandahålla en fabrik som används för att skapa posten. Fabriken kan ställas in med hjälp av getLogRecordFactory() och setLogRecordFactory() (se detta för fabrikens signatur).

Denna funktionalitet kan användas för att injicera dina egna värden i en LogRecord vid skapandet. Du kan använda följande mönster:

old_factory = loggning.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    returnera record

logging.setLogRecordFactory(record_factory)

Med detta mönster kan flera fabriker kedjas, och så länge de inte skriver över varandras attribut eller oavsiktligt skriver över standardattributen som anges ovan, bör det inte finnas några överraskningar.

LogRecord-attribut

LogRecord har ett antal attribut, varav de flesta härleds från parametrarna till konstruktören. (Observera att namnen inte alltid överensstämmer exakt mellan parametrarna i LogRecord-konstruktören och LogRecord-attributen) Dessa attribut kan användas för att sammanfoga data från posten till formatsträngen. I följande tabell listas (i alfabetisk ordning) attributnamnen, deras betydelser och motsvarande platshållare i en %-style-formatsträng.

Om du använder {}-formatering (str.format()) kan du använda {attrname} som platshållare i formatsträngen. Om du använder $-formatering (string.Template), använd formen ${attrname}. I båda fallen ska du naturligtvis ersätta attrname med det faktiska attributnamn som du vill använda.

När det gäller {}-formatering kan du ange formateringsflaggor genom att placera dem efter attributnamnet, åtskilda från det med ett kolon. Till exempel: en platshållare på {msecs:03.0f} skulle formatera ett millisekundvärde på 4 som 004. Se str.format()-dokumentationen för fullständig information om de alternativ som finns tillgängliga för dig.

Attribut namn	Format	Beskrivning
args	Du ska inte behöva formatera detta själv.	Den tupel av argument som sammanfogas i msg för att producera message, eller en dict vars värden används för sammanfogningen (när det bara finns ett argument och det är en dictionary).
asctime	%(asctime)s	Humanläsbar tid när LogRecord skapades. Som standard är den av formen ’2003-07-08 16:49:45,896’ (siffrorna efter kommatecknet är millisekunddelar av tiden).
skapad	%(created)f	Tidpunkt då LogRecord skapades (returneras av time.time_ns() / 1e9).
exc_info	Du ska inte behöva formatera detta själv.	Exception tuple (à la sys.exc_info) eller, om inget undantag har inträffat, None.
filnamn	%(filename)s	Filnamnsdelen av pathname.
funcNamn	%(funcName)s	Namn på den funktion som innehåller loggningsanropet.
nivånamn	%(levelname)s	Textloggningsnivå för meddelandet ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').
nivåno	%(levelno)s	Numerisk loggningsnivå för meddelandet (DEBUG, INFO, WARNING, ERROR, CRITICAL).
lineno	%(lineno)d	Källans radnummer där loggningsanropet utfärdades (om tillgängligt).
Typ av meddelande	%(message)s	Det loggade meddelandet, beräknat som msg % args. Detta ställs in när Formatter.format() anropas.
modul	%(module)s	Modul (namndelen av filnamn).
msecs	%(msecs)d	Millisekund-del av tiden när LogRecord skapades.
msg	Du ska inte behöva formatera detta själv.	Den formatsträng som skickades i det ursprungliga loggningsanropet. Sammanslagen med args för att producera message, eller ett godtyckligt objekt (se Använda godtyckliga objekt som meddelanden).
namn	%(name)s	Namn på den logger som används för att logga samtalet.
sökvägsnamn	%(pathname)s	Fullständigt sökvägsnamn för källfilen där loggningsanropet gjordes (om tillgängligt).
process	%(process)d	Process-ID (om tillgängligt).
processnamn	%(processName)s	Processnamn (om tillgängligt).
relativt skapad	%(relativeCreated)d	Tid i millisekunder när LogRecord skapades, i förhållande till den tidpunkt då loggmodulen laddades.
stack_info	Du ska inte behöva formatera detta själv.	Stack frame-information (om sådan finns) från botten av stacken i den aktuella tråden, till och med stack frame för det logganrop som resulterade i att denna post skapades.
tråd	%(thread)d	Tråd-ID (om tillgängligt).
trådnamn	%(threadName)s	Trådnamn (om tillgängligt).
uppgiftsnamn	%(taskName)s	asyncio.Task namn (om tillgängligt).

Ändrad i version 3.1: processName har lagts till.

Ändrad i version 3.12: taskName lades till.

LoggerAdapter-objekt

LoggerAdapter-instanser används för att enkelt skicka kontextuell information till loggningsanrop. Ett exempel på användning finns i avsnittet om Lägga till kontextuell information i loggningsutdata.

class logging.LoggerAdapter(logger, extra, merge_extra=False)

Returnerar en instans av LoggerAdapter som initierats med en underliggande instans av Logger, ett diktliknande objekt (extra) och ett boolean (merge_extra) som anger om extra-argumentet för enskilda logganrop ska slås samman med LoggerAdapter extra eller inte. Standardbeteendet är att ignorera extra-argumentet för enskilda logganrop och endast använda det som finns i LoggerAdapter-instansen

process(msg, kwargs)

Ändrar argumenten för meddelande och/eller nyckelord som skickas till ett loggningsanrop för att infoga kontextuell information. Denna implementation tar det objekt som skickas som extra till konstruktören och lägger till det i kwargs med nyckeln ’extra’. Returvärdet är en (msg, kwargs) tupel som innehåller (eventuellt modifierade) versioner av de argument som skickats in.

manager

Delegerar till den underliggande manager på logger.

_log

Delegerar till den underliggande _log()-metoden på logger.

Utöver ovanstående stöder LoggerAdapter följande metoder i Logger: debug(), info(), warning(), error(), exception(), critical(), log(), isEnabledFor(), getEffectiveLevel(), setLevel() och hasHandlers(). Dessa metoder har samma signaturer som sina motsvarigheter i Logger, så du kan använda de två typerna av instanser omväxlande.

Ändrad i version 3.2: Metoderna isEnabledFor(), getEffectiveLevel(), setLevel() och hasHandlers() lades till i LoggerAdapter. Dessa metoder delegerar till den underliggande loggern.

Ändrad i version 3.6: Attributet manager och metoden _log() har lagts till, vilka delegerar till den underliggande loggern och tillåter att adaptrar nästlas.

Ändrad i version 3.13: Argumentet merge_extra har lagts till.

Säkerhet för trådar

Loggningsmodulen är avsedd att vara trådsäker utan att något särskilt arbete behöver utföras av dess klienter. Den uppnår detta genom att använda trådlås; det finns ett lås för att serialisera åtkomst till modulens delade data, och varje hanterare skapar också ett lås för att serialisera åtkomst till dess underliggande I/O.

Om du implementerar asynkrona signalhanterare med modulen signal kan det hända att du inte kan använda loggning från sådana hanterare. Detta beror på att låsimplementeringar i modulen threading inte alltid är re-entrant och därför inte kan anropas från sådana signalhanterare.

Funktioner på modulnivå

Förutom de klasser som beskrivs ovan finns det ett antal funktioner på modulnivå.

logging.getLogger(name=None)

Returnerar en logger med det angivna namnet eller, om namnet är None, hierarkins rotlogger. Om namnet anges är det vanligtvis ett punktseparerat hierarkiskt namn som ’a’, ’a.b’ eller ’a.b.c.d’. Valet av dessa namn är helt upp till utvecklaren som använder loggning, men det rekommenderas att __name__ används om du inte har en särskild anledning att inte göra det, som nämns i Logger-objekt.

Alla anrop till denna funktion med ett givet namn returnerar samma loggerinstans. Detta innebär att loggerinstanser aldrig behöver skickas mellan olika delar av en applikation.

logging.getLoggerClass()

Returnerar antingen standardklassen Logger, eller den sista klassen som skickades till setLoggerClass(). Denna funktion kan anropas från en ny klassdefinition för att säkerställa att installationen av en anpassad Logger-klass inte upphäver anpassningar som redan gjorts av annan kod. Till exempel:

klass MyLogger(logging.getLoggerClass()):
    # ... åsidosätt beteende här

logging.getLogRecordFactory()

Returnerar en callable som används för att skapa en LogRecord.

Tillagd i version 3.2: Denna funktion har tillkommit, tillsammans med setLogRecordFactory(), för att ge utvecklare mer kontroll över hur LogRecord som representerar en loggningshändelse konstrueras.

Se setLogRecordFactory() för mer information om hur fabriken anropas.

logging.debug(msg, *args, **kwargs)

Detta är en bekvämlighetsfunktion som anropar Logger.debug(), på rotloggaren. Hanteringen av argumenten är på alla sätt identisk med vad som beskrivs i den metoden.

Den enda skillnaden är att om rotloggaren inte har några hanterare anropas basicConfig() innan debug anropas på rotloggaren.

För mycket korta skript eller snabba demonstrationer av loggning kan debug och de andra modulnivåfunktionerna vara praktiska. De flesta program vill dock noggrant och uttryckligen kontrollera loggningskonfigurationen och bör därför föredra att skapa en logger på modulnivå och anropa Logger.debug() (eller andra nivåspecifika metoder) på den, enligt beskrivningen i början av den här dokumentationen.

logging.info(msg, *args, **kwargs)

Loggar ett meddelande med nivån INFO på rotloggaren. Argumenten och beteendet är i övrigt detsamma som för debug().

logging.warning(msg, *args, **kwargs)

Loggar ett meddelande med nivå WARNING på rotloggaren. Argumenten och beteendet är i övrigt samma som för debug().

Anteckning

Det finns en föråldrad funktion warn som är funktionellt identisk med warning. Eftersom warn är föråldrad, använd den inte - använd warning istället.

logging.error(msg, *args, **kwargs)

Loggar ett meddelande med nivå ERROR på rotloggaren. Argumenten och beteendet är i övrigt detsamma som för debug().

logging.critical(msg, *args, **kwargs)

Loggar ett meddelande med nivå CRITICAL på rotloggaren. Argumenten och beteendet är i övrigt samma som för debug().

logging.exception(msg, *args, **kwargs)

Loggar ett meddelande med nivå ERROR på rotloggaren. Argumenten och beteendet är i övrigt samma som för debug(). Undantagsinformation läggs till i loggmeddelandet. Denna funktion bör endast anropas från en undantagshanterare.

logging.log(level, msg, *args, **kwargs)

Loggar ett meddelande med nivån level på rotloggern. Argumenten och beteendet är i övrigt samma som för debug().

logging.disable(level=CRITICAL)

Ger en överordnad nivå level för alla loggrar som har företräde framför loggarens egen nivå. Denna funktion kan vara användbar när det uppstår ett behov av att tillfälligt strypa loggningsutmatningen i hela programmet. Dess effekt är att inaktivera alla loggningsanrop med allvarlighetsgrad nivå och lägre, så att om du anropar den med ett värde på INFO, kommer alla INFO- och DEBUG-händelser att kasseras, medan de med allvarlighetsgrad WARNING och högre kommer att behandlas enligt loggarens effektiva nivå. Om logging.disable(logging.NOTSET) anropas, tas denna överordnade nivå bort, så att loggningsutdata återigen beror på de enskilda loggarnas effektiva nivåer.

Observera att om du har definierat någon anpassad loggningsnivå som är högre än CRITICAL (detta rekommenderas inte), kan du inte förlita dig på standardvärdet för parametern level, utan måste uttryckligen ange ett lämpligt värde.

Ändrad i version 3.7: Parametern level var förvald till nivån CRITICAL. Se bpo-28524 för mer information om denna ändring.

logging.addLevelName(level, levelName)

Associerar nivån level med texten levelName i en intern ordbok, som används för att mappa numeriska nivåer till en textuell representation, t.ex. när en Formatter formaterar ett meddelande. Denna funktion kan också användas för att definiera egna nivåer. De enda begränsningarna är att alla nivåer som används måste registreras med hjälp av denna funktion, att nivåerna ska vara positiva heltal och att de ska öka i allvarlighetsgrad.

Anteckning

Om du funderar på att definiera dina egna nivåer, se avsnittet om Anpassade nivåer.

logging.getLevelNamesMapping()

Returnerar en mappning från nivånamn till motsvarande loggningsnivåer. Strängen ”CRITICAL” mappas till exempel till CRITICAL. Den returnerade mappningen kopieras från en intern mappning vid varje anrop till denna funktion.

Tillagd i version 3.11.

logging.getLevelName(level)

Returnerar den textuella eller numeriska representationen av loggningsnivån level.

Om level är en av de fördefinierade nivåerna CRITICAL, ERROR, WARNING, INFO eller DEBUG så får du motsvarande sträng. Om du har associerat nivåer med namn med hjälp av addLevelName() så returneras det namn du har associerat med level. Om ett numeriskt värde som motsvarar en av de definierade nivåerna skickas in, returneras motsvarande strängrepresentation.

Parametern level accepterar också en strängrepresentation av nivån, t.ex. ”INFO”. I sådana fall returnerar denna funktion motsvarande numeriska värde för nivån.

Om inget matchande numeriskt värde eller strängvärde skickas in returneras strängen ”Level %s” % level”.

Anteckning

Nivåerna är internt heltal (eftersom de måste jämföras i loggningslogiken). Den här funktionen används för att konvertera mellan en heltalsnivå och det nivånamn som visas i den formaterade loggutmatningen med hjälp av formatspecificeraren %(levelname)s (se LogRecord-attribut), och vice versa.

Ändrad i version 3.4: I Python-versioner tidigare än 3.4 kunde den här funktionen också ges en textnivå och returnera det motsvarande numeriska värdet för nivån. Detta odokumenterade beteende ansågs vara ett misstag och togs bort i Python 3.4, men återinfördes i 3.4.2 för att bibehålla bakåtkompatibilitet.

logging.getHandlerByName(name)

Returnerar en hanterare med det angivna namnet, eller None om det inte finns någon hanterare med det namnet.

Tillagd i version 3.12.

logging.getHandlerNames()

Returnerar en oföränderlig uppsättning av alla kända hanterarnamn.

Tillagd i version 3.12.

logging.makeLogRecord(attrdict)

Skapar och returnerar en ny LogRecord-instans vars attribut definieras av attrdict. Denna funktion är användbar för att ta en inlagd LogRecord attributordbok, skickad över en socket, och återskapa den som en LogRecord instans på mottagarsidan.

logging.basicConfig(**kwargs)

Gör grundläggande konfiguration för loggningssystemet genom att skapa en StreamHandler med en standard Formatter och lägga till den i rotloggaren. Funktionerna debug(), info(), warning(), error() och critical() anropar basicConfig() automatiskt om inga hanterare har definierats för rotloggaren.

Denna funktion gör ingenting om rotloggaren redan har konfigurerade hanterare, såvida inte nyckelordsargumentet force är inställt på True.

Anteckning

Denna funktion bör anropas från huvudtråden innan andra trådar startas. I versioner av Python före 2.7.1 och 3.2, om denna funktion anropas från flera trådar, är det möjligt (i sällsynta fall) att en hanterare läggs till root-loggern mer än en gång, vilket leder till oväntade resultat som att meddelanden dupliceras i loggen.

Följande nyckelordsargument stöds.

Format	Beskrivning
filnamn	Anger att en FileHandler ska skapas med det angivna filnamnet, i stället för en StreamHandler.
filemode	Om filnamn anges, öppnas filen i detta mode. Standard är 'a'.
format	Använd den angivna formatsträngen för hanteraren. Standard är attributen levelname, name och message åtskilda med kolon.
datefmt	Använd det angivna datum-/tidsformatet, som accepteras av time.strftime().
stil	Om format anges, används denna stil för formatsträngen. En av '%', '{' eller '$' för printf-style, str.format() respektive string.Template. Standardvärdet är '%'.
nivå	Ställ in root-loggernivån till den angivna level.
strömma	Använd den angivna strömmen för att initiera StreamHandler. Observera att detta argument är inkompatibelt med filnamn - om båda är närvarande kommer ett ValueError att uppstå.
handläggare	Om detta anges ska det vara en iterabel av redan skapade hanterare som ska läggas till rotloggaren. Alla hanterare som inte redan har en formateringsinställning kommer att tilldelas standardformateringen som skapas i den här funktionen. Observera att detta argument är inkompatibelt med filnamn eller ström - om båda är närvarande kommer ett ValueError att uppstå.
kraft	Om detta nyckelordsargument anges som true, tas alla befintliga hanterare som är kopplade till rotloggaren bort och stängs, innan konfigurationen utförs enligt de andra argumenten.
kodning	Om detta nyckelordsargument anges tillsammans med filnamn, används dess värde när FileHandler skapas, och används således när utdatafilen öppnas.
fel	Om detta nyckelordsargument anges tillsammans med filnamn, används dess värde när FileHandler skapas, och används därmed när utdatafilen öppnas. Om det inte anges används värdet ’backslashreplace’. Observera att om None anges kommer det att skickas som sådant till open(), vilket innebär att det kommer att behandlas på samma sätt som att skicka ’errors’.

Ändrad i version 3.2: Argumentet style har lagts till.

Ändrad i version 3.3: Argumentet handlers har lagts till. Ytterligare kontroller har lagts till för att fånga upp situationer där inkompatibla argument anges (t.ex. handlers tillsammans med stream eller filnamn, eller stream tillsammans med filnamn).

Ändrad i version 3.8: Argumentet force har lagts till.

Ändrad i version 3.9: Argumenten encoding och errors har lagts till.

logging.shutdown()

Informerar loggningssystemet om att utföra en ordnad avstängning genom att spola och stänga alla hanterare. Detta anrop bör göras när programmet avslutas och ingen ytterligare användning av loggningssystemet bör göras efter detta anrop.

När loggningsmodulen importeras registreras den här funktionen som en exit-hanterare (se atexit), så normalt sett behöver du inte göra det manuellt.

logging.setLoggerClass(klass)

Anger att loggningssystemet ska använda klassen klass vid instansiering av en logger. Klassen bör definiera __init__() så att endast ett namnargument krävs, och __init__() bör anropa Logger.__init__(). Den här funktionen anropas vanligtvis innan någon logger instansieras av program som behöver använda ett anpassat loggerbeteende. Efter detta anrop, liksom vid alla andra tillfällen, ska du inte instansiera loggrar direkt med hjälp av underklassen: fortsätt att använda logging.getLogger() API för att hämta dina loggrar.

logging.setLogRecordFactory(factory)

Ställ in en callable som används för att skapa en LogRecord.

Parametrar:

factory – Den factory callable som ska användas för att instansiera en loggpost.

Tillagd i version 3.2: Denna funktion har tillkommit tillsammans med getLogRecordFactory() för att ge utvecklare mer kontroll över hur LogRecord som representerar en loggningshändelse konstrueras.

Fabriken har följande signatur:

factory(namn, nivå, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)

namn:

Loggarens namn.

nivå:

Loggningsnivå (numerisk).

fn:

Det fullständiga sökvägsnamnet för den fil där loggningsanropet gjordes.

lno:

Radnumret i filen där loggningsanropet gjordes.

msg:

Loggningens meddelande.

args:

Argumenten för loggningsmeddelandet.

exc_info:

En undantags-tupel, eller None.

func:

Namnet på den funktion eller metod som anropade loggningsanropet.

sinfo:

En stack traceback som den som tillhandahålls av traceback.print_stack(), visar anropshierarkin.

kwargs:

Ytterligare nyckelordsargument.

Attribut på modulnivå

logging.lastResort

En ”hanterare av sista utväg” är tillgänglig via detta attribut. Detta är en StreamHandler som skriver till sys.stderr med en nivå av WARNING, och används för att hantera loggningshändelser i avsaknad av någon loggningskonfiguration. Slutresultatet är att bara skriva ut meddelandet till sys.stderr. Detta ersätter det tidigare felmeddelandet som sa att ”inga hanterare kunde hittas för logger XYZ”. Om du av någon anledning behöver det tidigare beteendet kan lastResort sättas till None.

Tillagd i version 3.2.

logging.raiseExceptions

Används för att se om undantag under hanteringen ska spridas.

Standard: True.

Om raiseExceptions är False, ignoreras undantag i tysthet. Detta är vad som oftast önskas för ett loggningssystem - de flesta användare bryr sig inte om fel i loggningssystemet, de är mer intresserade av applikationsfel.

Integration med varningsmodulen

Funktionen captureWarnings() kan användas för att integrera logging med modulen warnings.

logging.captureWarnings(capture)

Denna funktion används för att aktivera och inaktivera loggning av varningar.

Om capture är True kommer varningar som utfärdas av modulen warnings att omdirigeras till loggningssystemet. Specifikt kommer en varning att formateras med warnings.formatwarning() och den resulterande strängen loggas till en logger med namnet 'py.warnings' med allvarlighetsgraden WARNING.

Om capture är False kommer omdirigeringen av varningar till loggsystemet att upphöra och varningarna kommer att omdirigeras till sina ursprungliga destinationer (dvs. de som gällde innan captureWarnings(True) anropades).

Se även

Modul logging.config

Konfigurations-API för loggningsmodulen.

Modul logging.handlers

Användbara hanterare som ingår i loggningsmodulen.

PEP 282 - Ett loggningssystem

Förslaget som beskrev denna funktion för inkludering i Pythons standardbibliotek.

”Ursprungligt Python-loggningspaket <https://old.red-dove.com/python_logging.html>

Detta är den ursprungliga källan för paketet logging. Den version av paketet som är tillgänglig från den här webbplatsen är lämplig för användning med Python 1.5.2, 2.1.x och 2.2.x, som inte innehåller paketet logging i standardbiblioteket.