logging — tapahtumien lokitus

Tämä moduuli tarjoaa kevyen osajoukon vakio-Pythonin logging-paketista MicroPythonille mukautettuna. Se tukee tasoperusteista lokitusta hierarkkisesti nimettyjen Logger-objektien kautta, pientä joukkoa käsittelijöitä (StreamHandler, FileHandler), printf-tyylistä muotoilua Formatter-luokan avulla sekä moduulitason apufunktioita, jotka vastaavat juurilokittajaan kohdistuvia toimintoja.

Moduuli noudattaa tuttua CPython-API:a riittävän tarkasti, jotta yksinkertaiset vakiokirjastolle kirjoitetut sovellukset toimivat sellaisinaan. Suodattimia, monen prosessin lukitusta, asetustiedostomuotoa ja useimpia käsittelijäluokkia ei tarjota.

Tasovakiot

logging.CRITICAL: int

Numeerinen arvo 50. Käytetään korjaamattomiin virheisiin.

logging.ERROR: int

Numeerinen arvo 40. Käytetään vakaviin ongelmiin.

logging.WARNING: int

Numeerinen arvo 30. Vasta määritetyn juurilokittajan oletustaso.

logging.INFO: int

Numeerinen arvo 20. Käytetään vahvistusviesteihin.

logging.DEBUG: int

Numeerinen arvo 10. Käytetään hienojakoiseen diagnostiseen tulosteeseen.

logging.NOTSET: int

Numeerinen arvo 0. Ilmaisee lokittajan, jolle ei ole määritetty tasoa (efektiivinen taso peritään tällöin juurilokittajalta tai arvosta WARNING).

Funktiot

logging.getLogger(name: str | None = None) → Logger

Palauttaa nimellä name rekisteröidyn Logger-objektin ja luo sen ensimmäisellä käyttökerralla. Jos name on None, palautetaan juurilokittaja. Ensimmäinen kutsu arvolla name="root" (tai kun name on asettamatta) kutsuu implisiittisesti funktiota basicConfig, joka liittää oletusarvoisen StreamHandler-käsittelijän kirjoittamaan kohteeseen sys.stderr.

logging.log(level: int, msg: str, *args) → None

Kirjaa viesti tasolla level juurilokittajaan. args interpoloidaan viestiin msg printf-tyylisellä %-muotoilulla; yksittäistä sanakirja-argumenttia käytetään kuvauksena.

logging.debug(msg: str, *args) → None

Vastaa kutsua getLogger().debug(msg, *args).

logging.info(msg: str, *args) → None

Vastaa kutsua getLogger().info(msg, *args).

logging.warning(msg: str, *args) → None

Vastaa kutsua getLogger().warning(msg, *args).

logging.error(msg: str, *args) → None

Vastaa kutsua getLogger().error(msg, *args).

logging.critical(msg: str, *args) → None

Vastaa kutsua getLogger().critical(msg, *args).

logging.exception(msg: str, *args, exc_info: bool | BaseException = True) → None

Vastaa kutsua getLogger().exception(msg, *args, exc_info=exc_info). Kirjaa viestin tasolla ERROR ja muotoilee lisäksi aktiivisen poikkeuksen jäljityksen, kun exc_info on tosi. Jos exc_info on itse BaseException, käytetään kyseisen poikkeuksen jäljitystä; muutoin tarkistetaan sys.exc_info(), kun se on saatavilla.

logging.shutdown() → None

Sulkee jokaiseen tunnettuun lokittajaan liitetyn käsittelijän ja unohtaa lokittajat. Rekisteröidään automaattisesti kautta sys.atexit, kun kyseinen koukku on saatavilla.

logging.addLevelName(level: int, name: str) → None

Yhdistää tekstimuotoisen nimen name numeeriseen tasoon level, jotta Formatter voi esittää sen muodossa %(levelname)s.

logging.basicConfig(filename: str | None = None, filemode: str = 'a', format: str | None = None, datefmt: str | None = None, level: int = WARNING, stream=None, encoding: str = 'UTF-8', force: bool = False) → None

Määrittää juurilokittajan yhdellä käsittelijällä.

Jos filename annetaan, luodaan FileHandler käyttäen arvoja filemode ja encoding; muutoin käytetään StreamHandler-käsittelijää, joka kirjoittaa kohteeseen stream (oletuksena sys.stderr).

format ja datefmt välitetään uudelle Formatter-objektille.

level asettaa sekä käsittelijän tason että juurilokittajan tason.

Jos juurilokittajalla on jo käsittelijöitä, tämä funktio ei tee mitään, ellei force ole True, jolloin olemassa olevat käsittelijät suljetaan ja korvataan.

Luokat

class logging.Logger(name: str, level: int = NOTSET)

Nimetty lokittaja. Luo lokittajat funktiolla getLogger suoran instansoinnin sijaan, jotta getLogger voi palauttaa saman instanssin samalle nimelle.

name: str

Lokittajan pisteellä erotettu nimi.

level: int

Määritetty numeerinen taso. 0 (NOTSET) tarkoittaa ”peri”.

handlers: list

Tähän lokittajaan liitettyjen Handler-instanssien lista. Kun lista on tyhjä, viestit lähetetään juurilokittajan käsittelijöille.

setLevel(level: int) → None

Asettaa lokittajan kynnystason.

isEnabledFor(level: int) → bool

Palauttaa True, jos tämä lokittaja käsittelisi tasolla level olevan viestin.

getEffectiveLevel() → int

Palauttaa seuraavista ensimmäisen nollasta poikkeavan: tämän lokittajan taso, juurilokittajan taso tai WARNING.

log(level: int, msg: str, *args) → None

Kirjaa viestin msg tasolla level. args interpoloidaan viestiin msg %-operaattorilla; jos ensimmäinen positionaalinen argumentti on sanakirja, sitä käytetään kuvauksena.

debug(msg: str, *args) → None

Kirjaa viestin msg tasolla DEBUG.

info(msg: str, *args) → None

Kirjaa viestin msg tasolla INFO.

warning(msg: str, *args) → None

Kirjaa viestin msg tasolla WARNING.

error(msg: str, *args) → None

Kirjaa viestin msg tasolla ERROR.

critical(msg: str, *args) → None

Kirjaa viestin msg tasolla CRITICAL.

exception(msg: str, *args, exc_info: bool | BaseException = True) → None

Kirjaa viestin msg tasolla ERROR ja, kun exc_info on tosi, liittää muotoillun jäljityksen. Jos exc_info on BaseException-instanssi, esitetään kyseisen poikkeuksen jäljitys; muutoin aktiivinen poikkeus tarkistetaan kutsulla sys.exc_info().

addHandler(handler: Handler) → None

Liittää käsittelijän handler tähän lokittajaan.

hasHandlers() → bool

Palauttaa True, jos tähän lokittajaan on liitetty käsittelijöitä.

class logging.Handler(level: int = NOTSET)

Kaikkien käsittelijöiden kantaluokka. Aliluokat toteuttavat metodin emit().

level: int

Käsittelijän kynnystaso.

formatter: 'Formatter | None'

Aktiivinen Formatter tai None.

setLevel(level: int) → None

Asettaa käsittelijän kynnystason.

setFormatter(formatter: Formatter) → None

Liittää muotoilijan formatter tähän käsittelijään.

format(record: LogRecord) → str

Esittää tietueen record käyttäen määritettyä muotoilijaa.

close() → None

Vapauttaa käsittelijän varaamat resurssit. Kutsutaan funktiosta shutdown ja luokasta FileHandler sen sulkemisen yhteydessä.

class logging.StreamHandler(stream=None)

Käsittelijä, joka kirjoittaa muotoillut tietueet ja niiden perään merkin self.terminator (oletuksena "\n") kohteeseen stream. stream on oletuksena sys.stderr.

stream

Kohdevirtaobjekti.

terminator: str

Jokaisen muotoillun tietueen perään liitettävä merkkijono. Oletuksena "\n".

emit(record: LogRecord) → None

Kirjoittaa tietueen record kohteeseen stream, jos sen taso ylittää käsittelijän kynnyksen.

close() → None

Tyhjentää alla olevan virran, kun se tarjoaa flush-metodin.

class logging.FileHandler(filename: str, mode: str = 'a', encoding: str = 'UTF-8')

StreamHandler-aliluokka, joka avaa tiedoston filename annetulla tilalla mode ja koodauksella encoding ja kirjoittaa muotoillut tietueet siihen. Alla oleva tiedosto suljetaan metodilla close().

class logging.Formatter(fmt: str | None = None, datefmt: str | None = None)

Esittää LogRecord-instanssit merkkijonoina.

fmt on printf-tyylinen malli. Tunnistetut avaimet ovat %(name)s, %(message)s, %(msecs)d, %(asctime)s ja %(levelname)s. Kun arvoa ei aseteta, oletuksena on "%(levelname)s:%(name)s:%(message)s".

datefmt on time.strftime-malli, jota käytetään esittämään %(asctime)s. Oletuksena "%Y-%m-%d %H:%M:%S".

usesTime() → bool

Palauttaa True, jos muotoilumalli viittaa avaimeen asctime.

formatTime(datefmt: str, record: LogRecord) → str | None

Muotoilee arvon record.ct käyttäen funktiota time.strftime ja mallia datefmt. Palauttaa None alustoilla, joilla time.strftime ei ole saatavilla.

format(record: LogRecord) → str

Esittää tietueen record. Jos malli käyttää avainta asctime, metodia formatTime() kutsutaan ensin täyttämään record.asctime.

class logging.LogRecord

Säiliö Logger-objektilta sen käsittelijöille välitettävälle datalle. Instanssit täytetään metodilla set(); lokittajatoteutukset käyttävät uudelleen yhtä tietuetta lokittajaa kohden vähentääkseen muistinvarauksia.

name: str

Lähteenä olevan lokittajan nimi.

levelno: int

Tämän tietueen numeerinen taso.

levelname: str

Tekstimuotoinen tason nimi.

message: str

Täysin muotoiltu lokiviesti.

ct: float

Luontiaika funktion time.time() palauttamana.

msecs: int

Arvon ct millisekuntikomponentti.

asctime: str | None

Ihmisluettava aikaleima; Formatter täyttää sen laiskasti.

set(name: str, level: int, message: str) → None

Alustaa tietueen annetuilla arvoilla ja tallentaa nykyisen ajan.