StreamHandler?

StreamHandler 類(lèi)位于核心 logging 包，它可將日志記錄輸出發(fā)送到數據流例如 sys.stdout, sys.stderr 或任何文件類(lèi)對象（或者更精確地說(shuō)，任何支持 write() 和 flush() 方法的對象）。

class logging.StreamHandler(stream=None)?

返回一個(gè)新的 StreamHandler 類(lèi)。 如果指定了 stream，則實(shí)例將用它作為日志記錄輸出；在其他情況下將使用 sys.stderr。

emit(record)?

如果指定了一個(gè)格式化器，它會(huì )被用來(lái)格式化記錄。 隨后記錄會(huì )被寫(xiě)入到 terminator 之后的流中。 如果存在異常信息，則會(huì )使用 traceback.print_exception() 來(lái)格式化并添加到流中。

flush()?

通過(guò)調用流的 flush() 方法來(lái)刷新它。 請注意 close() 方法是繼承自 Handler 的所以沒(méi)有輸出，因此有時(shí)可能需要顯式地調用 flush()。

setStream(stream)?

將實(shí)例的流設為指定值，如果兩者不一致的話(huà)。 舊的流會(huì )在設置新的流之前被刷新。

參數

stream -- 處理程序應當使用的流。

返回

舊的流，如果流已被改變的話(huà)，如果未被改變則為 None。

3.7 新版功能.

terminator?

當將已格式化的記錄寫(xiě)入到流時(shí)被用作終止符的字符串。 默認值為 '\n'。

如果你不希望以換行符終止，你可以將處理程序類(lèi)實(shí)例的 terminator 屬性設為空字符串。

在較早的版本中，終止符被硬編碼為 '\n'。

3.2 新版功能.

FileHandler?

FileHandler 類(lèi)位于核心 logging 包，它可將日志記錄輸出到磁盤(pán)文件中。 它從 StreamHandler 繼承了輸出功能。

class logging.FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)?

返回一個(gè) FileHandler 類(lèi)的新實(shí)例。 將打開(kāi)指定的文件并將其用作日志記錄流。 如果未指定 mode，則會(huì )使用 'a'。 如果 encoding 不為 None，則會(huì )將其用作打開(kāi)文件的編碼格式。 如果 delay 為真值，則文件打開(kāi)會(huì )被推遲至第一次調用 emit() 時(shí)。 默認情況下，文件會(huì )無(wú)限增長(cháng)。 如果指定了 errors，它會(huì )被用于確定編碼格式錯誤的處理方式。

在 3.6 版更改: 除了字符串值，也接受 Path 對象作為 filename 參數。

在 3.9 版更改: 增加了 errors 形參。

close()?

關(guān)閉文件。

emit(record)?

將記錄輸出到文件。

Note that if the file was closed due to logging shutdown at exit and the file mode is 'w', the record will not be emitted (see bpo-42378).

NullHandler?

NullHandler 類(lèi)位于核心 logging 包，它不執行任何格式化或輸出。 它實(shí)際上是一個(gè)供庫開(kāi)發(fā)者使用的‘無(wú)操作’處理程序。

class logging.NullHandler?

返回一個(gè) NullHandler 類(lèi)的新實(shí)例。

emit(record)?

此方法不執行任何操作。

handle(record)?

此方法不執行任何操作。

createLock()?

此方法會(huì )對鎖返回 None，因為沒(méi)有下層 I/O 的訪(fǎng)問(wèn)需要被序列化。

請參閱 配置庫的日志記錄 了解有關(guān)如何使用 NullHandler 的更多信息。

WatchedFileHandler?

WatchedFileHandler 類(lèi)位于 logging.handlers 模塊，這個(gè) FileHandler 用于監視它所寫(xiě)入日志記錄的文件。 如果文件發(fā)生變化，它會(huì )被關(guān)閉并使用文件名重新打開(kāi)。

發(fā)生文件更改可能是由于使用了執行文件輪換的程序例如 newsyslog 和 logrotate。 這個(gè)處理程序在 Unix/Linux 下使用，它會(huì )監視文件來(lái)查看自上次發(fā)出數據后是否有更改。 （如果文件的設備或 inode 發(fā)生變化就認為已被更改。） 如果文件被更改，則會(huì )關(guān)閉舊文件流，并再打開(kāi)文件以獲得新文件流。

這個(gè)處理程序不適合在 Windows 下使用，因為在 Windows 下打開(kāi)的日志文件無(wú)法被移動(dòng)或改名 —— 日志記錄會(huì )使用排他的鎖來(lái)打開(kāi)文件 —— 因此這樣的處理程序是沒(méi)有必要的。 此外，ST_INO 在 Windows 下不受支持；stat() 將總是為該值返回零。

class logging.handlers.WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)?

返回一個(gè) WatchedFileHandler 類(lèi)的新實(shí)例。 將打開(kāi)指定的文件并將其用作日志記錄流。 如果未指定 mode，則會(huì )使用 'a'。 如果 encoding 不為 None，則會(huì )將其用作打開(kāi)文件的編碼格式。 如果 delay 為真值，則文件打開(kāi)會(huì )被推遲至第一次調用 emit() 時(shí)。 默認情況下，文件會(huì )無(wú)限增長(cháng)。 如果提供了 errors，它會(huì )被用于確定編碼格式錯誤的處理方式。

在 3.6 版更改: 除了字符串值，也接受 Path 對象作為 filename 參數。

在 3.9 版更改: 增加了 errors 形參。

reopenIfNeeded()?

檢查文件是否已更改。 如果已更改，則會(huì )刷新并關(guān)閉現有流然后重新打開(kāi)文件，這通常是將記錄輸出到文件的先導操作。

3.6 新版功能.

emit(record)?

將記錄輸出到文件，但如果文件已更改則會(huì )先調用 reopenIfNeeded() 來(lái)重新打開(kāi)它。

BaseRotatingHandler?

BaseRotatingHandler 類(lèi)位于 logging.handlers 模塊中，它是輪換文件處理程序類(lèi) RotatingFileHandler 和 TimedRotatingFileHandler 的基類(lèi)。 你不需要實(shí)例化此類(lèi)，但它具有你可能需要重載的屬性和方法。

class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)?

類(lèi)的形參與 FileHandler 的相同。 其屬性有:

namer?

如果此屬性被設為一個(gè)可調用對象，則 rotation_filename() 方法會(huì )委托給該可調用對象。 傳給該可調用對象的形參與傳給 rotation_filename() 的相同。

備注

namer 函數會(huì )在輪換期間被多次調用，因此它應當盡可能的簡(jiǎn)單快速。 它還應當對給定的輸入每次都返回相同的輸出，否則輪換行為可能無(wú)法按預期工作。

It's also worth noting that care should be taken when using a namer to preserve certain attributes in the filename which are used during rotation. For example, RotatingFileHandler expects to have a set of log files whose names contain successive integers, so that rotation works as expected, and TimedRotatingFileHandler deletes old log files (based on the backupCount parameter passed to the handler's initializer) by determining the oldest files to delete. For this to happen, the filenames should be sortable using the date/time portion of the filename, and a namer needs to respect this. (If a namer is wanted that doesn't respect this scheme, it will need to be used in a subclass of TimedRotatingFileHandler which overrides the getFilesToDelete() method to fit in with the custom naming scheme.)

3.3 新版功能.

rotator?

如果此屬性被設為一個(gè)可調用對象，則 rotate() 方法會(huì )委托給該可調用對象。 傳給該可調用對象的形參與傳給 rotate() 的相同。

3.3 新版功能.

rotation_filename(default_name)?

當輪換時(shí)修改日志文件的文件名。

提供該屬性以便可以提供自定義文件名。

默認實(shí)現會(huì )調用處理程序的 'namer' 屬性，如果它是可調用對象的話(huà)，并傳給它默認的名稱(chēng)。 如果該屬性不是可調用對象 (默認值為 None)，則將名稱(chēng)原樣返回。

參數

default_name -- 日志文件的默認名稱(chēng)。

3.3 新版功能.

rotate(source, dest)?

當執行輪換時(shí)，輪換當前日志。

默認實(shí)現會(huì )調用處理程序的 'rotator' 屬性，如果它是可調用對象的話(huà)，并傳給它 source 和 dest 參數。 如果該屬性不是可調用對象 (默認值為 None)，則將源簡(jiǎn)單地重命名為目標。

參數

• source -- 源文件名。 這通常為基本文件名，例如 'test.log'。

• dest -- 目標文件名。 這通常是源被輪換后的名稱(chēng)，例如 'test.log.1'。

3.3 新版功能.

該屬性存在的理由是讓你不必進(jìn)行子類(lèi)化 —— 你可以使用與 RotatingFileHandler 和 TimedRotatingFileHandler 的實(shí)例相同的可調用對象。 如果 namer 或 rotator 可調用對象引發(fā)了異常，將會(huì )按照與 emit() 調用期間的任何其他異常相同的方式來(lái)處理，例如通過(guò)處理程序的 handleError() 方法。

如果你需要對輪換進(jìn)程執行更多的修改，你可以重載這些方法。

請參閱 利用 rotator 和 namer 自定義日志輪換操作 獲取具體示例。

RotatingFileHandler?

RotatingFileHandler 類(lèi)位于 logging.handlers 模塊，它支持磁盤(pán)日志文件的輪換。

class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)?

返回一個(gè) RotatingFileHandler 類(lèi)的新實(shí)例。 將打開(kāi)指定的文件并將其用作日志記錄流。 如果未指定 mode，則會(huì )使用 'a'。 如果 encoding 不為 None，則會(huì )將其用作打開(kāi)文件的編碼格式。 如果 delay 為真值，則文件打開(kāi)會(huì )被推遲至第一次調用 emit()。 默認情況下，文件會(huì )無(wú)限增長(cháng)。 如果提供了 errors，它會(huì )被用于確定編碼格式錯誤的處理方式。

你可以使用 maxBytes 和 backupCount 值來(lái)允許文件以預定的大小執行 rollover。 當即將超出預定大小時(shí)，將關(guān)閉舊文件并打開(kāi)一個(gè)新文件用于輸出。 只要當前日志文件長(cháng)度接近 maxBytes 就會(huì )發(fā)生輪換；但是如果 maxBytes 或 backupCount 兩者之一的值為零，就不會(huì )發(fā)生輪換，因此你通常要設置 backupCount 至少為 1，而 maxBytes 不能為零。 當 backupCount 為非零值時(shí)，系統將通過(guò)為原文件名添加擴展名 '.1', '.2' 等來(lái)保存舊日志文件。 例如，當 backupCount 為 5 而基本文件名為 app.log 時(shí)，你將得到 app.log, app.log.1, app.log.2 直至 app.log.5。 當前被寫(xiě)入的文件總是 app.log。 當此文件寫(xiě)滿(mǎn)時(shí)，它會(huì )被關(guān)閉并重戶(hù)名為 app.log.1，而如果文件 app.log.1, app.log.2 等存在，則它們會(huì )被分別重命名為 app.log.2, app.log.3 等等。

在 3.6 版更改: 除了字符串值，也接受 Path 對象作為 filename 參數。

在 3.9 版更改: 增加了 errors 形參。

doRollover()?

執行上文所描述的輪換。

emit(record)?

將記錄輸出到文件，以適應上文所描述的輪換。

TimedRotatingFileHandler?

TimedRotatingFileHandler 類(lèi)位于 logging.handlers 模塊，它支持基于特定時(shí)間間隔的磁盤(pán)日志文件輪換。

class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)?

返回一個(gè)新的 TimedRotatingFileHandler 類(lèi)實(shí)例。 指定的文件會(huì )被打開(kāi)并用作日志記錄的流。 對于輪換操作它還會(huì )設置文件名前綴。 輪換的發(fā)生是基于 when 和 interval 的積。

你可以使用 when 來(lái)指定 interval 的類(lèi)型。 可能的值列表如下。 請注意它們不是大小寫(xiě)敏感的。

值	間隔類(lèi)型	如果/如何使用 atTime
'S'	秒	忽略
'M'	分鐘	忽略
'H'	小時(shí)	忽略
'D'	天	忽略
'W0'-'W6'	工作日(0=星期一)	用于計算初始輪換時(shí)間
'midnight'	如果未指定 atTime 則在午夜執行輪換，否則將使用 atTime。	用于計算初始輪換時(shí)間

當使用基于星期的輪換時(shí)，星期一為 'W0'，星期二為 'W1'，以此類(lèi)推直至星期日為 'W6'。 在這種情況下，傳入的 interval 值不會(huì )被使用。

系統將通過(guò)為文件名添加擴展名來(lái)保存舊日志文件。 擴展名是基于日期和時(shí)間的，根據輪換間隔的長(cháng)短使用 strftime 格式 %Y-%m-%d_%H-%M-%S 或是其中有變動(dòng)的部分。

當首次計算下次輪換的時(shí)間時(shí)（即當處理程序被創(chuàng )建時(shí)），現有日志文件的上次被修改時(shí)間或者當前時(shí)間會(huì )被用來(lái)計算下次輪換的發(fā)生時(shí)間。

如果 utc 參數為真值，將使用 UTC 時(shí)間；否則會(huì )使用本地時(shí)間。

如果 backupCount 不為零，則最多將保留 backupCount 個(gè)文件，而如果當輪換發(fā)生時(shí)創(chuàng )建了更多的文件，則最舊的文件會(huì )被刪除。 刪除邏輯使用間隔時(shí)間來(lái)確定要刪除的文件，因此改變間隔時(shí)間可能導致舊文件被繼續保留。

如果 delay 為真值，則會(huì )將文件打開(kāi)延遲到首次調用 emit() 的時(shí)候。

如果 atTime 不為 None，則它必須是一個(gè) datetime.time 的實(shí)例，該實(shí)例指定輪換在一天內的發(fā)生時(shí)間，用于輪換被設為“在午夜”或“在每星期的某一天”之類(lèi)的情況。 請注意在這些情況下，atTime 值實(shí)際上會(huì )被用于計算 初始 輪換，而后續輪換將會(huì )通過(guò)正常的間隔時(shí)間計算來(lái)得出。

如果指定了 errors，它會(huì )被用來(lái)確定編碼錯誤的處理方式。

備注

初始輪換時(shí)間的計算是在處理程序被初始化時(shí)執行的。 后續輪換時(shí)間的計算則僅在輪換發(fā)生時(shí)執行，而只有當提交輸出時(shí)輪換才會(huì )發(fā)生。 如果不記住這一點(diǎn)，你就可能會(huì )感到困惑。 例如，如果設置時(shí)間間隔為“每分鐘”，那并不意味著(zhù)你總會(huì )看到（文件名中）帶有間隔一分鐘時(shí)間的日志文件；如果在應用程序執行期間，日志記錄輸出的生成頻率高于每分鐘一次，那么 你可以預期看到間隔一分鐘時(shí)間的日志文件。 另一方面，如果（假設）日志記錄消息每五分鐘才輸出一次，那么文件時(shí)間將會(huì )存在對應于沒(méi)有輸出（因而沒(méi)有輪換）的缺失。

在 3.4 版更改: 添加了 atTime 形參。

在 3.6 版更改: 除了字符串值，也接受 Path 對象作為 filename 參數。

在 3.9 版更改: 增加了 errors 形參。

doRollover()?

執行上文所描述的輪換。

emit(record)?

將記錄輸出到文件，以適應上文所描述的輪換。

getFilesToDelete()?

Returns a list of filenames which should be deleted as part of rollover. These are the absolute paths of the oldest backup log files written by the handler.

SocketHandler?

SocketHandler 類(lèi)位于 logging.handlers 模塊，它會(huì )將日志記錄輸出發(fā)送到網(wǎng)絡(luò )套接字。 基類(lèi)所使用的是 TCP 套接字。

class logging.handlers.SocketHandler(host, port)?

返回一個(gè) SocketHandler 類(lèi)的新實(shí)例，該實(shí)例旨在與使用 host 與 port 給定地址的遠程主機進(jìn)行通信。

在 3.4 版更改: 如果 port 指定為 None，會(huì )使用 host 中的值來(lái)創(chuàng )建一個(gè) Unix 域套接字 —— 在其他情況下，則會(huì )創(chuàng )建一個(gè) TCP 套接字。

close()?

關(guān)閉套接字。

emit()?

對記錄的屬性字典執行封存并以二進(jìn)制格式將其寫(xiě)入套接字。 如果套接字存在錯誤，則靜默地丟棄數據包。 如果連接在此之前丟失，則重新建立連接。 要在接收端將記錄解封并輸出到 LogRecord，請使用 makeLogRecord() 函數。

handleError()?

處理在 emit() 期間發(fā)生的錯誤。 最可能的原因是連接丟失。 關(guān)閉套接字以便我們能在下次事件時(shí)重新嘗試。

makeSocket()?

這是一個(gè)工廠(chǎng)方法，它允許子類(lèi)定義它們想要的套接字的準確類(lèi)型。 默認實(shí)現會(huì )創(chuàng )建一個(gè) TCP 套接字 (socket.SOCK_STREAM)。

makePickle(record)?

將記錄的屬性字典封存為帶有長(cháng)度前綴的二進(jìn)制格式，并將其返回以準備通過(guò)套接字進(jìn)行傳輸。 此操作在細節上相當于:

data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data

請注意封存操作不是絕對安全的。 如果你關(guān)心安全問(wèn)題，你可能會(huì )想要重載此方法以實(shí)現更安全的機制。 例如，你可以使用 HMAC 對封存對象進(jìn)行簽名然后在接收端驗證它們，或者你也可以在接收端禁用全局對象的解封操作。

send(packet)?

將封存后的字節串 packet 發(fā)送到套接字。 所發(fā)送字節串的格式與 makePickle() 文檔中的描述一致。

此函數允許部分發(fā)送，這可能會(huì )在網(wǎng)絡(luò )繁忙時(shí)發(fā)生。

createSocket()?

嘗試創(chuàng )建一個(gè)套接字；失敗時(shí)將使用指數化回退算法處理。 在失敗初次發(fā)生時(shí)，處理程序將丟棄它正嘗試發(fā)送的消息。 當后續消息交由同一實(shí)例處理時(shí)，它將不會(huì )嘗試連接直到經(jīng)過(guò)一段時(shí)間以后。 默認形參設置為初始延遲一秒，如果在延遲之后連接仍然無(wú)法建立，處理程序將每次把延遲翻倍直至達到 30 秒的最大值。

此行為由下列處理程序屬性控制:

• retryStart (初始延遲，默認為 1.0 秒)。

• retryFactor (倍數，默認為 2.0)。

• retryMax (最大延遲，默認為 30.0 秒)。

這意味著(zhù)如果遠程監聽(tīng)器在處理程序被使用 之后 啟動(dòng)，你可能會(huì )丟失消息（因為處理程序在延遲結束之前甚至不會(huì )嘗試連接，而在延遲期間靜默地丟棄消息）。

DatagramHandler?

DatagramHandler 類(lèi)位于 logging.handlers 模塊，它繼承自 SocketHandler，支持通過(guò) UDP 套接字發(fā)送日志記錄消息。

class logging.handlers.DatagramHandler(host, port)?

返回一個(gè) DatagramHandler 類(lèi)的新實(shí)例，該實(shí)例旨在與使用 host 與 port 給定地址的遠程主機進(jìn)行通信。

在 3.4 版更改: 如果 port 指定為 None，會(huì )使用 host 中的值來(lái)創(chuàng )建一個(gè) Unix 域套接字 —— 在其他情況下，則會(huì )創(chuàng )建一個(gè) UDP 套接字。

emit()?

對記錄的屬性字典執行封存并以二進(jìn)制格式將其寫(xiě)入套接字。 如果套接字存在錯誤，則靜默地丟棄數據包。 要在接收端將記錄解封并輸出到 LogRecord，請使用 makeLogRecord() 函數。

makeSocket()?

SocketHandler 的工廠(chǎng)方法會(huì )在此被重載以創(chuàng )建一個(gè) UDP 套接字 (socket.SOCK_DGRAM)。

send(s)?

將封存后的字節串發(fā)送到套接字。 所發(fā)送字節串的格式與 SocketHandler.makePickle() 文檔中的描述一致。

SysLogHandler?

SysLogHandler 類(lèi)位于 logging.handlers 模塊，它支持將日志記錄消息發(fā)送到遠程或本地 Unix syslog。

class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)?

返回一個(gè) SysLogHandler 類(lèi)的新實(shí)例用來(lái)與通過(guò) address 以 (host, port) 元組形式給出地址的遠程 Unix 機器進(jìn)行通訊。 如果未指定 address，則使用 ('localhost', 514)。 該地址會(huì )被用于打開(kāi)套接字。 提供 (host, port) 元組的一種替代方式是提供字符串形式的地址，例如 '/dev/log'。 在這種情況下，會(huì )使用 Unix 域套接字將消息發(fā)送到 syslog。 如果未指定 facility，則使用 LOG_USER。 打開(kāi)的套接字類(lèi)型取決于 socktype 參數，該參數的默認值為 socket.SOCK_DGRAM 即打開(kāi)一個(gè) UDP 套接字。 要打開(kāi)一個(gè) TCP 套接字（用來(lái)配合較新的 syslog 守護程序例如 rsyslog 使用），請指定值為 socket.SOCK_STREAM。

請注意如果你的服務(wù)器不是在 UDP 端口 514 上進(jìn)行偵聽(tīng)，則 SysLogHandler 可能無(wú)法正常工作。 在這種情況下，請檢查你應當為域套接字所使用的地址 —— 它依賴(lài)于具體的系統。 例如，在 Linux 上通常為 '/dev/log' 而在 OS/X 上則為 '/var/run/syslog'。 你需要檢查你的系統平臺并使用適當的地址（如果你的應用程序需要在多個(gè)平臺上運行則可能需要在運行時(shí)進(jìn)行這樣的檢查）。 在 Windows 上，你大概必須要使用 UDP 選項。

在 3.2 版更改: 添加了 socktype。

close()?

關(guān)閉連接遠程主機的套接字。

emit(record)?

記錄會(huì )被格式化，然后發(fā)送到 syslog 服務(wù)器。 如果存在異常信息，則它 不會(huì ) 被發(fā)送到服務(wù)器。

在 3.2.1 版更改: (參見(jiàn): bpo-12168。) 在較早的版本中，發(fā)送至 syslog 守護程序的消息總是以一個(gè) NUL 字節結束，因為守護程序的早期版本期望接收一個(gè)以 NUL 結束的消息 —— 即使它不包含于對應的規范說(shuō)明 (RFC 5424)。 這些守護程序的較新版本不再期望接收 NUL 字節，如果其存在則會(huì )將其去除，而最新的守護程序（更緊密地遵循 RFC 5424）會(huì )將 NUL 字節作為消息的一部分傳遞出去。

為了在面對所有這些不同守護程序行為時(shí)能夠更方便地處理 syslog 消息，通過(guò)使用類(lèi)層級屬性 append_nul，添加 NUL 字節的操作已被作為可配置項。 該屬性默認為 True (保留現有行為) 但可在 SysLogHandler 實(shí)例上設為 False 以便讓實(shí)例 不會(huì ) 添加 NUL 結束符。

在 3.3 版更改: (參見(jiàn): bpo-12419。) 在較早的版本中，沒(méi)有 "ident" 或 "tag" 前綴工具可以用來(lái)標識消息的來(lái)源。 現在則可以使用一個(gè)類(lèi)層級屬性來(lái)設置它，該屬性默認為 "" 表示保留現有行為，但可在 SysLogHandler 實(shí)例上重載以便讓實(shí)例不會(huì )為所處理的每條消息添加標識。 請注意所提供的標識必須為文本而非字節串，并且它會(huì )被原封不動(dòng)地添加到消息中。

encodePriority(facility, priority)?

將功能和優(yōu)先級編碼為一個(gè)整數。 你可以傳入字符串或者整數 —— 如果傳入的是字符串，則會(huì )使用內部的映射字典將其轉換為整數。

符號 LOG_ 的值在 SysLogHandler 中定義并且是 sys/syslog.h 頭文件中所定義值的鏡像。

優(yōu)先級

名稱(chēng)（字符串）	符號值
alert	LOG_ALERT
crit 或 critical	LOG_CRIT
debug	LOG_DEBUG
emerg 或 panic	LOG_EMERG
err 或 error	LOG_ERR
info	LOG_INFO
notice	LOG_NOTICE
warn 或 warning	LOG_WARNING

設備

名稱(chēng)（字符串）	符號值
auth	LOG_AUTH
authpriv	LOG_AUTHPRIV
cron	LOG_CRON
daemon	LOG_DAEMON
ftp	LOG_FTP
kern	LOG_KERN
lpr	LOG_LPR
mail	LOG_MAIL
news	LOG_NEWS
syslog	LOG_SYSLOG
user	LOG_USER
uucp	LOG_UUCP
local0	LOG_LOCAL0
local1	LOG_LOCAL1
local2	LOG_LOCAL2
local3	LOG_LOCAL3
local4	LOG_LOCAL4
local5	LOG_LOCAL5
local6	LOG_LOCAL6
local7	LOG_LOCAL7

mapPriority(levelname)?

將日志記錄級別名稱(chēng)映射到 syslog 優(yōu)先級名稱(chēng)。 如果你使用自定義級別，或者如果默認算法不適合你的需要，你可能需要重載此方法。 默認算法將 DEBUG, INFO, WARNING, ERROR 和 CRITICAL 映射到等價(jià)的 syslog 名稱(chēng)，并將所有其他級別名稱(chēng)映射到 'warning'。

NTEventLogHandler?

NTEventLogHandler 類(lèi)位于 logging.handlers 模塊，它支持將日志記錄消息發(fā)送到本地 Windows NT, Windows 2000 或 Windows XP 事件日志。 在你使用它之前，你需要安裝 Mark Hammond 的 Python Win32 擴展。

class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')?

返回一個(gè) NTEventLogHandler 類(lèi)的新實(shí)例。 appname 用來(lái)定義出現在事件日志中的應用名稱(chēng)。 將使用此名稱(chēng)創(chuàng )建適當的注冊表條目。 dllname 應當給出要包含在日志中的消息定義的 .dll 或 .exe 的完整限定路徑名稱(chēng)（如未指定則會(huì )使用 'win32service.pyd' —— 此文件隨 Win32 擴展安裝且包含一些基本的消息定義占位符。 請注意使用這些占位符將使你的事件日志變得很大，因為整個(gè)消息源都會(huì )被放入日志。 如果你希望有較小的日志，你必須自行傳入包含你想要在事件日志中使用的消息定義的 .dll 或 .exe 名稱(chēng)）。 logtype 為 'Application', 'System' 或 'Security' 之一，且默認值為 'Application'。

close()?

這時(shí)，你就可以從注冊表中移除作為事件日志條目來(lái)源的應用名稱(chēng)。 但是，如果你這樣做，你將無(wú)法如你所預期的那樣在事件日志查看器中看到這些事件 —— 它必須能訪(fǎng)問(wèn)注冊表來(lái)獲取 .dll 名稱(chēng)。 當前版本并不會(huì )這樣做。

emit(record)?

確定消息 ID，事件類(lèi)別和事件類(lèi)型，然后將消息記錄到 NT 事件日志中。

getEventCategory(record)?

返回記錄的事件類(lèi)別。 如果你希望指定你自己的類(lèi)別就要重載此方法。 此版本將返回 0。

getEventType(record)?

返回記錄的事件類(lèi)型。 如果你希望指定你自己的類(lèi)型就要重載此方法。 此版本將使用處理程序的 typemap 屬性來(lái)執行映射，該屬性在 __init__() 被設置為一個(gè)字典，其中包含 DEBUG, INFO, WARNING, ERROR 和 CRITICAL 的映射。 如果你使用你自己的級別，你將需要重載此方法或者在處理程序的 typemap 屬性中放置一個(gè)合適的字典。

getMessageID(record)?

返回記錄的消息 ID。 如果你使用你自己的消息，你可以通過(guò)將 msg 傳給日志記錄器作為 ID 而非格式字符串實(shí)現此功能。 然后，你可以在這里使用字典查找來(lái)獲取消息 ID。 此版本將返回 1，是 win32service.pyd 中的基本消息 ID。

SMTPHandler?

SMTPHandler 類(lèi)位于 logging.handlers 模塊，它支持將日志記錄消息通過(guò) SMTP 發(fā)送到一個(gè)電子郵件地址。

class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)?

返回一個(gè) SMTPHandler 類(lèi)的新實(shí)例。 該實(shí)例使用電子郵件的發(fā)件人、收件人地址和主題行進(jìn)行初始化。 toaddrs 應當為字符串列表。 要指定一個(gè)非標準 SMTP 端口，請使用 (host, port) 元組格式作為 mailhost 參數。 如果你使用一個(gè)字符串，則會(huì )使用標準 SMTP 端口。 如果你的 SMTP 服務(wù)器要求驗證，你可以指定一個(gè) (username, password) 元組作為 credentials 參數。

要指定使用安全協(xié)議 (TLS)，請傳入一個(gè)元組作為 secure 參數。 這將僅在提供了驗證憑據時(shí)才能被使用。 元組應當或是一個(gè)空元組，或是一個(gè)包含密鑰文件名的單值元組，或是一個(gè)包含密鑰文件和證書(shū)文件的 2 值元組。 （此元組會(huì )被傳給 smtplib.SMTP.starttls() 方法。）

可以使用 timeout 參數為與 SMTP 服務(wù)器的通信指定超時(shí)限制。

3.3 新版功能: 增加了 timeout 參數。

emit(record)?

對記錄執行格式化并將其發(fā)送到指定的地址。

getSubject(record)?

如果你想要指定一個(gè)基于記錄的主題行，請重載此方法。

MemoryHandler?

MemoryHandler 類(lèi)位于 logging.handlers 模塊，它支持在內存中緩沖日志記錄，并定期將其刷新到 target 處理程序中。 刷新會(huì )在緩沖區滿(mǎn)的時(shí)候，或是在遇到特定或更高嚴重程度事件的時(shí)候發(fā)生。

MemoryHandler 是更通用的 BufferingHandler 的子類(lèi)，后者屬于抽象類(lèi)。 它會(huì )在內存中緩沖日志記錄。 當每條記錄被添加到緩沖區時(shí)，會(huì )通過(guò)調用 shouldFlush() 來(lái)檢查緩沖區是否應當刷新。 如果應當刷新，則要使用 flush() 來(lái)執行刷新。

class logging.handlers.BufferingHandler(capacity)?

使用指定容量的緩沖區初始化處理程序。 這里，capacity 是指緩沖的日志記錄數量。

emit(record)?

將記錄添加到緩沖區。 如果 shouldFlush() 返回真值，則會(huì )調用 flush() 來(lái)處理緩沖區。

flush()?

你可以重載此方法來(lái)實(shí)現自定義的刷新行為。 此版本只是將緩沖區清空。

shouldFlush(record)?

如果緩沖區容量已滿(mǎn)則返回 True。 可以重載此方法以實(shí)現自定義的刷新策略。

class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True)?

返回一個(gè) MemoryHandler 類(lèi)的新實(shí)例。 該實(shí)例使用 capacity 指定的緩沖區大?。ㄒ彌_的記錄數量）來(lái)初始化。 如果 flushLevel 未指定，則使用 ERROR。 如果未指定 target，則需要在此處理程序執行任何實(shí)際操作之前使用 setTarget() 來(lái)設置目標。 如果 flushOnClose 指定為 False，則當處理程序被關(guān)閉時(shí) 不會(huì ) 刷新緩沖區。 如果未指定或指定為 True，則當處理程序被關(guān)閉時(shí)將會(huì )發(fā)生之前的緩沖區刷新行為。

在 3.6 版更改: 增加了 flushOnClose 形參。

close()?

調用 flush()，設置目標為 None 并清空緩沖區。

flush()?

對于 MemoryHandler，刷新是指將緩沖的記錄發(fā)送到目標，如果存在目標的話(huà)。 當此行為發(fā)生時(shí)緩沖區也將被清空。 如果你想要不同的行為請重載此方法。

setTarget(target)?

設置此處理程序的目標處理程序。

shouldFlush(record)?

檢測緩沖區是否已滿(mǎn)或是有記錄為 flushLevel 或更高級別。

HTTPHandler?

HTTPHandler 類(lèi)位于 logging.handlers 模塊，它支持使用 GET 或 POST 語(yǔ)義將日志記錄消息發(fā)送到 Web 服務(wù)器。

class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None, context=None)?

返回一個(gè) HTTPHandler 類(lèi)的新實(shí)例。 host 可以為 host:port 的形式，如果你需要使用指定端口號的話(huà)。 如果沒(méi)有指定 method，則會(huì )使用 GET。 如果 secure 為真值，則將使用 HTTPS 連接。 context 形參可以設為一個(gè) ssl.SSLContext 實(shí)例以配置用于 HTTPS 連接的 SSL 設置。 如果指定了 credentials，它應當為包含 userid 和 password 的二元組，該元組將被放入使用 Basic 驗證的 HTTP 'Authorization' 標頭中。 如果你指定了 credentials，你還應當指定 secure=True 這樣你的 userid 和 password 就不會(huì )以明文在線(xiàn)路上傳輸。

在 3.5 版更改: 增加了 context 形參。

mapLogRecord(record)?

基于 record 提供一個(gè)字典，它將被執行 URL 編碼并發(fā)送至 Web 服務(wù)器。 默認實(shí)現僅返回 record.__dict__。 在只需將 LogRecord 的某個(gè)子集發(fā)送至 Web 服務(wù)器，或者需要對發(fā)送至服務(wù)器的內容進(jìn)行更多定制時(shí)可以重載此方法。

emit(record)?

將記錄以 URL 編碼字典的形式發(fā)送至 Web 服務(wù)器。 mapLogRecord() 方法會(huì )被用來(lái)將要發(fā)送的記錄轉換為字典。

備注

由于記錄發(fā)送至 Web 服務(wù)器所需的預處理與通用的格式化操作不同，使用 setFormatter() 來(lái)指定一個(gè) Formatter 用于 HTTPHandler 是沒(méi)有效果的。 此處理程序不會(huì )調用 format()，而是調用 mapLogRecord() 然后再調用 urllib.parse.urlencode() 來(lái)以適合發(fā)送至 Web 服務(wù)器的形式對字典進(jìn)行編碼。

QueueHandler?

QueueHandler 類(lèi)位于 logging.handlers 模塊，它支持將日志記錄消息發(fā)送到一個(gè)隊列，例如在 queue 或 multiprocessing 模塊中實(shí)現的隊列。

配合 QueueListener 類(lèi)使用，QueueHandler 可被用來(lái)使處理程序在與執行日志記錄的線(xiàn)程不同的線(xiàn)程上完成工作。 這對 Web 應用程序以及其他服務(wù)于客戶(hù)端的線(xiàn)程需要盡可能快地響應的服務(wù)應用程序來(lái)說(shuō)很重要，任何潛在的慢速操作（例如通過(guò) SMTPHandler 發(fā)送郵件）都要在單獨的線(xiàn)程上完成。

class logging.handlers.QueueHandler(queue)?

返回一個(gè) QueueHandler 類(lèi)的新實(shí)例。 該實(shí)例使用隊列來(lái)初始化以向其發(fā)送消息。 queue 可以為任何隊列類(lèi)對象；它由 enqueue() 方法來(lái)使用，該方法需要知道如何向其發(fā)送消息。 隊列 不要求 具有任務(wù)跟蹤 API，這意味著(zhù)你可以為 queue 使用 SimpleQueue 實(shí)例。

emit(record)?

將準備 LogRecord 的結果排入隊列。 如果發(fā)生了異常（例如由于有界隊列已滿(mǎn)），則會(huì )調用 handleError() 方法來(lái)處理錯誤。 這可能導致記錄被靜默地丟棄 (如果 logging.raiseExceptions 為 False) 或者消息被打印到 sys.stderr (如果 logging.raiseExceptions 為 True)。

prepare(record)?

準備用于隊列的記錄。 此方法返回的對象會(huì )被排入隊列。

The base implementation formats the record to merge the message, arguments, and exception information, if present. It also removes unpickleable items from the record in-place. Specifically, it overwrites the record's msg and message attributes with the merged message (obtained by calling the handler's format() method), and sets the args, exc_info and exc_text attributes to None.

如果你想要將記錄轉換為 dict 或 JSON 字符串，或者發(fā)送記錄被修改后的副本而讓初始記錄保持原樣，則你可能會(huì )想要重載此方法。

enqueue(record)?

使用 put_nowait() 將記錄排入隊列；如果你想要使用阻塞行為，或超時(shí)設置，或自定義的隊列實(shí)現，則你可能會(huì )想要重載此方法。

QueueListener?

QueueListener 類(lèi)位于 logging.handlers 模塊，它支持從一個(gè)隊列接收日志記錄消息，例如在 queue 或 multiprocessing 模塊中實(shí)現的隊列。 消息是在內部線(xiàn)程中從隊列接收并在同一線(xiàn)程上傳遞到一個(gè)或多個(gè)處理程序進(jìn)行處理的。 盡管 QueueListener 本身并不是一個(gè)處理程序，但由于它要與 QueueHandler 配合工作，因此也在此處介紹。

配合 QueueHandler 類(lèi)使用，QueueListener 可被用來(lái)使處理程序在與執行日志記錄的線(xiàn)程不同的線(xiàn)程上完成工作。 這對 Web 應用程序以及其他服務(wù)于客戶(hù)端的線(xiàn)程需要盡可能快地響應的服務(wù)應用程序來(lái)說(shuō)很重要，任何潛在的慢速動(dòng)作（例如通過(guò) SMTPHandler 發(fā)送郵件）都要在單獨的線(xiàn)程上完成。

class logging.handlers.QueueListener(queue, *handlers, respect_handler_level=False)?

返回一個(gè) QueueListener 類(lèi)的新實(shí)例。 該實(shí)例初始化時(shí)要傳入一個(gè)隊列以向其發(fā)送消息，還要傳入一個(gè)處理程序列表用來(lái)處理放置在隊列中的條目。 隊列可以是任何隊列類(lèi)對象；它會(huì )被原樣傳給 dequeue() 方法，該方法需要知道如何從其獲取消息。 隊列 不要求 具有任務(wù)跟蹤 API（但如提供則會(huì )使用它），這意味著(zhù)你可以為 queue 使用 SimpleQueue 實(shí)例。

如果 respect_handler_level 為 True，則在決定是否將消息傳遞給處理程序之前會(huì )遵循處理程序的級別（與消息的級別進(jìn)行比較）；在其他情況下，其行為與之前的 Python 版本一致 —— 總是將每條消息傳遞給每個(gè)處理程序。

在 3.5 版更改: 增加了 respect_handler_level 參數。

dequeue(block)?

從隊列移出一條記錄并將其返回，可以選擇阻塞。

基本實(shí)現使用 get()。 如果你想要使用超時(shí)設置或自定義的隊列實(shí)現，則你可能會(huì )想要重載此方法。

prepare(record)?

準備一條要處理的記錄。

該實(shí)現只是返回傳入的記錄。 如果你想要對記錄執行任何自定義的 marshal 操作或在將其傳給處理程序之前進(jìn)行調整，則你可能會(huì )想要重載此方法。

handle(record)?

處理一條記錄。

此方法簡(jiǎn)單地循環(huán)遍歷處理程序，向它們提供要處理的記錄。 實(shí)際傳給處理程序的對象就是從 prepare() 返回的對象。

start()?

啟動(dòng)監聽(tīng)器。

此方法啟動(dòng)一個(gè)后臺線(xiàn)程來(lái)監視 LogRecords 隊列以進(jìn)行處理。

stop()?

停止監聽(tīng)器。

此方法要求線(xiàn)程終止，然后等待它完成終止操作。 請注意在你的應用程序退出之前如果你沒(méi)有調用此方法，則可能會(huì )有一些記錄在留在隊列中，它們將不會(huì )被處理。

enqueue_sentinel()?

將一個(gè)標記寫(xiě)入隊列以通知監聽(tīng)器退出。 此實(shí)現會(huì )使用 put_nowait()。 如果你想要使得超時(shí)設置或自定義的隊列實(shí)現，則你可能會(huì )想要重載此方法。

3.3 新版功能.