logging.handlers — Обработчики журналирования

StreamHandler

Класс StreamHandler, расположенный в основном пакете logging, отправляет журнальные данные в потоки, например sys.stdout, sys.stderr или любой файловый объект (точнее, любой объект, поддерживающий методы write() и flush()).

class logging.StreamHandler(stream=None)

Возвращает новый экземпляр класса StreamHandler. Если указан stream, экземпляр будет использовать его для вывода журнала; в противном случае будет использоваться sys.stderr.

emit(record)

Если указан форматтер, он используется для форматирования записи. Затем запись выводится в поток, за ней следует terminator. Если присутствуют сведения об исключении, они форматируются с помощью traceback.print_exception() и добавляются в поток.

flush()

Сбрасывает буфер потока, вызывая его метод flush(). Обратите внимание, что метод close() унаследован от Handler и поэтому ничего не выводит, так что иногда может потребоваться явный вызов flush().

setStream(stream)

Задаёт для экземпляра указанный поток, если он отличается от текущего. Перед установкой нового потока старый сбрасывается.

Параметры:

stream – Поток, который должен использовать обработчик.

Возвращает:

старый поток, если поток был изменён, или None, если изменений не было.

Добавлено в версии 3.7.

terminator

Строка, используемая в качестве завершающего символа при записи отформатированной записи в поток. Значение по умолчанию — '\n'.

Если завершающий символ новой строки не нужен, атрибуту экземпляра обработчика terminator можно присвоить пустую строку.

В предыдущих версиях завершающий символ был задан жёстко как '\n'.

Добавлено в версии 3.2.

FileHandler

Класс FileHandler, расположенный в основном пакете logging, отправляет журнальные данные в файл на диске. Функциональность вывода он наследует от StreamHandler.

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

Возвращает новый экземпляр класса FileHandler. Указанный файл открывается и используется в качестве потока для журналирования. Если mode не указан, используется 'a'. Если encoding не равен None, файл открывается с указанной кодировкой. Если delay имеет значение true, открытие файла откладывается до первого вызова emit(). По умолчанию файл растёт бесконечно. Если указан errors, он используется для определения способа обработки ошибок кодирования.

Изменено в версии 3.6: Помимо строк, для аргумента filename теперь также принимаются объекты Path.

Изменено в версии 3.9: Добавлен параметр errors.

close()

Закрывает файл.

emit(record)

Выводит запись в файл.

Обратите внимание: если файл был закрыт при завершении журналирования, а режим файла — ‘w’, запись не будет выведена (см. bpo-42378).

NullHandler

Класс NullHandler, расположенный в основном пакете logging, не выполняет форматирование и вывод. По сути, это обработчик-заглушка для разработчиков библиотек.

class logging.NullHandler

Возвращает новый экземпляр класса NullHandler.

emit(record)

Этот метод ничего не делает.

handle(record)

Этот метод ничего не делает.

createLock()

Этот метод возвращает None для блокировки, поскольку нет базового ввода-вывода, доступ к которому нужно сериализовать.

Дополнительные сведения об использовании NullHandler см. в разделе Настройка журналирования для библиотеки.

WatchedFileHandler

Класс WatchedFileHandler, расположенный в модуле logging.handlers, — это FileHandler, который отслеживает файл, в который ведётся журналирование. Если файл изменяется, он закрывается и снова открывается по имени файла.

Файл может измениться из-за использования таких программ, как newsyslog и logrotate, которые выполняют ротацию файлов журналов. Этот обработчик предназначен для использования в Unix/Linux и проверяет, изменился ли файл с момента последнего вывода. (Файл считается изменившимся, если изменились его устройство или inode.) Если файл изменился, старый файловый поток закрывается, а файл открывается заново для получения нового потока.

Этот обработчик не подходит для Windows, поскольку в Windows открытые файлы журналов нельзя перемещать или переименовывать: журналирование открывает их с эксклюзивными блокировками, поэтому такой обработчик не нужен. Кроме того, в Windows не поддерживается ST_INO; stat() всегда возвращает для этого значения ноль.

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

Возвращает новый экземпляр класса WatchedFileHandler. Указанный файл открывается и используется в качестве потока для журналирования. Если mode не указан, используется 'a'. Если encoding не равен None, файл открывается с указанной кодировкой. Если delay имеет значение true, открытие файла откладывается до первого вызова emit(). По умолчанию файл растёт бесконечно. Если указан errors, он определяет способ обработки ошибок кодирования.

Изменено в версии 3.6: Помимо строк, для аргумента filename теперь также принимаются объекты Path.

Изменено в версии 3.9: Добавлен параметр errors.

reopenIfNeeded()

Проверяет, изменился ли файл. Если да, существующий поток сбрасывается и закрывается, а файл открывается заново — обычно перед выводом записи в файл.

Добавлено в версии 3.6.

emit(record)

Выводит запись в файл, предварительно вызывая reopenIfNeeded(), чтобы заново открыть файл, если он изменился.

BaseRotatingHandler

Класс BaseRotatingHandler, расположенный в модуле logging.handlers, является базовым классом обработчиков ротации файлов журналов — RotatingFileHandler и TimedRotatingFileHandler. Обычно создавать экземпляры этого класса не требуется, однако в нём есть атрибуты и методы, которые может понадобиться переопределить.

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

Параметры те же, что и у FileHandler. Атрибуты:

namer

Если этому атрибуту присвоен вызываемый объект, метод rotation_filename() делегирует работу этому объекту. Ему передаются те же параметры, что и методу rotation_filename().

Примечание

Функция namer вызывается при ротации довольно часто, поэтому она должна быть как можно проще и быстрее. Для заданных входных данных она также должна каждый раз возвращать одинаковый результат, иначе ротация может работать не так, как ожидалось.

При использовании namer следует также позаботиться о сохранении в имени файла определённых атрибутов, которые используются при ротации. Например, RotatingFileHandler ожидает набор файлов журналов, имена которых содержат последовательные целые числа, чтобы ротация работала правильно, а TimedRotatingFileHandler удаляет старые файлы журналов (на основе параметра backupCount, переданного инициализатору обработчика), определяя самые старые файлы для удаления. Для этого имена файлов должны сортироваться по части имени, содержащей дату и время, поэтому namer должен учитывать это требование. (Если требуется namer, который не соблюдает эту схему, его нужно использовать в подклассе TimedRotatingFileHandler, переопределяющем метод getFilesToDelete() в соответствии с пользовательской схемой именования.)

Добавлено в версии 3.3.

rotator

Если этому атрибуту присвоен вызываемый объект, метод rotate() делегирует работу этому объекту. Ему передаются те же параметры, что и методу rotate().

Добавлено в версии 3.3.

rotation_filename(default_name)

Изменяет имя файла журнала при ротации.

Этот метод позволяет задать пользовательское имя файла.

Реализация по умолчанию вызывает атрибут обработчика ‘namer’, если он является вызываемым объектом, и передаёт ему имя по умолчанию. Если атрибут не является вызываемым объектом (по умолчанию это None), имя возвращается без изменений.

Параметры:

default_name – Имя файла журнала по умолчанию.

Добавлено в версии 3.3.

rotate(source, dest)

Выполняет ротацию текущего журнала.

Реализация по умолчанию вызывает атрибут обработчика ‘rotator’, если он является вызываемым объектом, и передаёт ему аргументы source и dest. Если атрибут не является вызываемым объектом (по умолчанию это None), исходный файл просто переименовывается в целевой.

Параметры:

• source – Имя исходного файла. Обычно это базовое имя файла, например ‘test.log’.
• dest – Имя целевого файла. Обычно это имя файла, в который перемещается исходный файл при ротации, например ‘test.log.1’.

Добавлено в версии 3.3.

Эти атрибуты позволяют обойтись без создания подкласса: одни и те же вызываемые объекты можно использовать для экземпляров RotatingFileHandler и TimedRotatingFileHandler. Если вызываемый объект namer или rotator вызывает исключение, оно обрабатывается так же, как и любое другое исключение во время вызова emit(), то есть с помощью метода handleError() обработчика.

Если для обработки ротации требуются более существенные изменения, можно переопределить методы.

Пример см. в разделе Использование rotator и namer для настройки обработки ротации журналов.

RotatingFileHandler

Класс RotatingFileHandler, расположенный в модуле logging.handlers, поддерживает ротацию файлов журналов на диске.

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

Возвращает новый экземпляр класса RotatingFileHandler. Указанный файл открывается и используется в качестве потока для журналирования. Если mode не указан, используется 'a'. Если encoding не равен None, файл открывается с указанной кодировкой. Если delay имеет значение true, открытие файла откладывается до первого вызова emit(). По умолчанию файл растёт бесконечно. Если указан errors, он определяет способ обработки ошибок кодирования.

Значения maxBytes и backupCount позволяют выполнять ротацию файла при достижении заданного размера. Когда размер файла становится близок к превышению предела, файл закрывается, а для вывода незаметно открывается новый. Ротация выполняется, когда текущий файл журнала почти достигает размера maxBytes; однако если maxBytes или backupCount равны нулю, ротация не выполняется. Поэтому обычно следует задать для backupCount значение не меньше 1, а для maxBytes — ненулевое значение. Если backupCount не равен нулю, система сохраняет старые файлы журналов, добавляя к имени расширения ‘.1’, ‘.2’ и т. д. Например, при значении backupCount, равном 5, и базовом имени файла app.log будут созданы файлы app.log, app.log.1, app.log.2 и далее до app.log.5. Файл, в который ведётся запись, всегда называется app.log. Когда этот файл заполняется, он закрывается и переименовывается в app.log.1; если существуют файлы app.log.1, app.log.2 и т. д., они переименовываются соответственно в app.log.2, app.log.3 и т. д.

Изменено в версии 3.6: Помимо строк, для аргумента filename теперь также принимаются объекты Path.

Изменено в версии 3.9: Добавлен параметр errors.

doRollover()

Выполняет ротацию, описанную выше.

emit(record)

Выводит запись в файл, выполняя при необходимости описанную выше ротацию.

TimedRotatingFileHandler

Класс TimedRotatingFileHandler, расположенный в модуле logging.handlers, поддерживает ротацию файлов журналов на диске через заданные интервалы времени.

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

Возвращает новый экземпляр класса TimedRotatingFileHandler. Указанный файл открывается и используется в качестве потока для журналирования. При ротации также задаётся суффикс имени файла. Ротация выполняется с интервалом, определяемым произведением when и interval.

Параметр when позволяет задать тип интервала. Список возможных значений приведён ниже. Обратите внимание: регистр букв значения не имеет.

Значение	Тип интервала	Если и как используется atTime
'S'	Секунды	Игнорируется
'M'	Минуты	Игнорируется
'H'	Часы	Игнорируется
'D'	Дни	Игнорируется
'W0'-'W6'	День недели (0 = понедельник)	Используется для вычисления времени первой ротации
'midnight'	Ротация в полночь, если atTime не указан, или в указанное в atTime время	Используется для вычисления времени первой ротации

Для ротации по дням недели укажите ‘W0’ для понедельника, ‘W1’ для вторника и так далее до ‘W6’ для воскресенья. В этом случае значение параметра interval не используется.

Система сохраняет старые файлы журналов, добавляя к имени расширения. Расширения формируются на основе даты и времени с использованием формата strftime %Y-%m-%d_%H-%M-%S или его начальной части — в зависимости от интервала ротации.

При первом вычислении времени следующей ротации (во время создания обработчика) для определения времени ротации используется время последнего изменения существующего файла журнала либо, если такого файла нет, текущее время.

Если аргумент utc имеет значение true, используется время UTC; в противном случае используется местное время.

Если backupCount не равен нулю, будет сохранено не более backupCount файлов; если при ротации создаётся больше файлов, самый старый удаляется. Логика удаления использует интервал для определения удаляемых файлов, поэтому при изменении интервала старые файлы могут остаться.

Если delay имеет значение true, открытие файла откладывается до первого вызова emit().

Если atTime не равен None, он должен быть экземпляром datetime.time, задающим время суток, в которое выполняется ротация, если ротация настроена «в полночь» или «в определённый день недели». Обратите внимание: в этих случаях значение atTime фактически используется для вычисления первой ротации, а последующие ротации рассчитываются обычным способом на основе интервала.

Если указан errors, он используется для определения способа обработки ошибок кодирования.

Примечание

Время первой ротации вычисляется при инициализации обработчика. Время последующих ротаций вычисляется только при выполнении ротации, а ротация выполняется лишь при выводе данных. Если не учитывать это, может возникнуть путаница. Например, если задан интервал «каждую минуту», это не означает, что имена файлов журналов всегда будут различаться временем на одну минуту. Если во время выполнения приложения журнальные данные выводятся чаще одного раза в минуту, тогда можно ожидать, что время в именах файлов будет различаться на минуту. Если же сообщения журнала выводятся, например, только раз в пять минут, во времени файлов будут пропуски для тех минут, когда не было вывода (и, следовательно, ротации).

Изменено в версии 3.4: Добавлен параметр atTime.

Изменено в версии 3.6: Помимо строк, для аргумента filename теперь также принимаются объекты Path.

Изменено в версии 3.9: Добавлен параметр errors.

doRollover()

Выполняет ротацию, описанную выше.

emit(record)

Выводит запись в файл, выполняя при необходимости описанную выше ротацию.

getFilesToDelete()

Возвращает список имён файлов, которые следует удалить при ротации. Это абсолютные пути к самым старым резервным файлам журналов, записанным обработчиком.

SocketHandler

Класс SocketHandler, расположенный в модуле logging.handlers, отправляет данные журналирования в сетевой сокет. Базовый класс использует сокет TCP.

class logging.handlers.SocketHandler(host, port)

Возвращает новый экземпляр класса SocketHandler, предназначенный для связи с удалённой машиной, адрес которой задаётся параметрами host и port.

Изменено в версии 3.4: Если port указано как None, создаётся доменный сокет Unix с использованием значения в host — в противном случае создаётся сокет TCP.

close()

Закрывает сокет.

emit()

Сериализует с помощью pickle словарь атрибутов записи и записывает его в сокет в двоичном формате. При ошибке сокета пакет молча отбрасывается. Если соединение было потеряно ранее, оно восстанавливается. Чтобы десериализовать запись на принимающей стороне в объект LogRecord, используйте функцию makeLogRecord().

handleError()

Обрабатывает ошибку, возникшую во время вызова emit(). Наиболее вероятная причина — потеря соединения. Закрывает сокет, чтобы повторить попытку при следующем событии.

makeSocket()

Это фабричный метод, позволяющий подклассам задавать конкретный тип требуемого сокета. Реализация по умолчанию создаёт сокет TCP (socket.SOCK_STREAM).

makePickle(record)

Сериализует с помощью pickle словарь атрибутов записи в двоичном формате с префиксом длины и возвращает его готовым к передаче через сокет. Эта операция эквивалентна следующему:

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

Обратите внимание, что сериализованные с помощью pickle данные не полностью безопасны. Если вас беспокоит безопасность, можно переопределить этот метод и реализовать более надёжный механизм. Например, можно подписывать данные pickle с помощью HMAC, а затем проверять подпись на принимающей стороне; либо отключить десериализацию глобальных объектов на принимающей стороне.

send(packet)

Отправляет в сокет сериализованный с помощью pickle байтовый пакет packet. Формат отправляемой байтовой строки описан в документации к makePickle().

Эта функция поддерживает частичную отправку, которая может происходить при высокой нагрузке на сеть.

createSocket()

Пытается создать сокет; в случае неудачи использует алгоритм экспоненциальной задержки. При первой неудаче обработчик отбросит сообщение, которое пытался отправить. При обработке последующих сообщений тем же экземпляром он не будет пытаться подключиться, пока не пройдёт некоторое время. Параметры по умолчанию задают начальную задержку в одну секунду. Если по истечении этой задержки соединение установить не удаётся, обработчик будет каждый раз удваивать задержку, пока она не достигнет максимума в 30 секунд.

Это поведение управляется следующими атрибутами обработчика:

• retryStart (начальная задержка, по умолчанию 1.0 секунды).
• retryFactor (множитель, по умолчанию 2.0).
• retryMax (максимальная задержка, по умолчанию 30.0 секунды).

Это означает, что если удалённый приёмник запустится после того, как обработчик уже использовался, вы можете потерять сообщения: обработчик даже не будет пытаться подключиться, пока не истечёт задержка, а в течение этого периода будет молча отбрасывать сообщения.

DatagramHandler

Класс DatagramHandler, расположенный в модуле logging.handlers, наследуется от SocketHandler и поддерживает отправку сообщений журнала через сокеты UDP.

class logging.handlers.DatagramHandler(host, port)

Возвращает новый экземпляр класса DatagramHandler, предназначенный для связи с удалённой машиной, адрес которой задаётся параметрами host и port.

Примечание

Поскольку UDP не является потоковым протоколом, между экземпляром этого обработчика и host не устанавливается постоянное соединение. Поэтому при использовании сетевого сокета поиск DNS может выполняться при каждом событии журналирования, что может увеличить задержку в системе. Если это для вас важно, можно выполнить поиск самостоятельно и инициализировать обработчик найденным IP-адресом вместо имени хоста.

Изменено в версии 3.4: Если port указано как None, создаётся доменный сокет Unix с использованием значения в host — в противном случае создаётся сокет UDP.

emit()

Сериализует с помощью pickle словарь атрибутов записи и записывает его в сокет в двоичном формате. При ошибке сокета пакет молча отбрасывается. Чтобы десериализовать запись на принимающей стороне в объект LogRecord, используйте функцию makeLogRecord().

makeSocket()

Здесь переопределён фабричный метод класса SocketHandler, чтобы создать сокет UDP (socket.SOCK_DGRAM).

send(s)

Отправляет в сокет байтовую строку, сериализованную с помощью pickle. Формат отправляемой байтовой строки описан в документации к SocketHandler.makePickle().

SysLogHandler

Класс SysLogHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журнала в удалённый или локальный Unix syslog.

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

Возвращает новый экземпляр класса SysLogHandler, предназначенный для связи с удалённой машиной Unix, адрес которой задаётся параметром address в виде кортежа (host, port). Если address не указан, используется ('localhost', 514). Адрес используется для открытия сокета. Вместо кортежа (host, port) можно указать адрес в виде строки, например «/dev/log». В этом случае для отправки сообщения в syslog используется доменный сокет Unix. Если facility не указан, используется LOG_USER. Тип открываемого сокета зависит от аргумента socktype, значение которого по умолчанию — socket.SOCK_DGRAM, поэтому открывается сокет UDP. Чтобы открыть сокет TCP (для использования с более новыми демонами syslog, такими как rsyslog), укажите значение socket.SOCK_STREAM.

Обратите внимание: если ваш сервер не прослушивает порт UDP 514, может показаться, что SysLogHandler не работает. В таком случае проверьте, какой адрес следует использовать для доменного сокета: он зависит от системы. Например, в Linux обычно используется «/dev/log», а в OS/X — «/var/run/syslog». Проверьте свою платформу и используйте соответствующий адрес (если приложение должно работать на нескольких платформах, эту проверку может потребоваться выполнять во время выполнения). В Windows практически единственный вариант — UDP.

Примечание

В macOS 12.x (Monterey) Apple изменила поведение демона syslog: теперь он не прослушивает доменный сокет. Поэтому не следует ожидать, что SysLogHandler будет работать в этой системе.

Дополнительные сведения см. в gh-91070.

Изменено в версии 3.2: Добавлен параметр socktype.

close()

Закрывает сокет удалённого узла.

createSocket()

Пытается создать сокет и, если это не дейтаграммный сокет, подключить его к другой стороне. Этот метод вызывается при инициализации обработчика, но отсутствие прослушивания на другой стороне в этот момент не считается ошибкой: метод будет вызван повторно при отправке события, если сокет к тому времени отсутствует.

Добавлено в версии 3.11.

emit(record)

Запись форматируется, а затем отправляется на сервер syslog. Если имеются сведения об исключении, они не отправляются на сервер.

Изменено в версии 3.2.1: (См.: bpo-12168.) В более ранних версиях сообщение, отправляемое демонам syslog, всегда завершалось байтом NUL, поскольку ранние версии этих демонов ожидали сообщение с завершающим байтом NUL, хотя этого требования нет в соответствующей спецификации (RFC 5424). Более поздние версии этих демонов не ожидают байт NUL, но удаляют его, если он присутствует. Ещё более новые демоны (которые точнее следуют RFC 5424) передают байт NUL как часть сообщения.

Чтобы упростить обработку сообщений syslog с учётом различий в поведении демонов, добавление байта NUL стало настраиваемым с помощью атрибута уровня класса append_nul. По умолчанию он имеет значение True (сохраняя прежнее поведение), но для экземпляра SysLogHandler его можно установить в False, чтобы этот экземпляр не добавлял завершающий байт NUL.

Изменено в версии 3.3: (См.: bpo-12419.) В более ранних версиях не было возможности добавить префикс «ident» или «tag» для указания источника сообщения. Теперь его можно задать с помощью атрибута уровня класса, значение которого по умолчанию — "" (для сохранения прежнего поведения). Для экземпляра SysLogHandler это значение можно переопределить, чтобы добавлять ident в начало каждого обрабатываемого сообщения. Обратите внимание: заданный ident должен быть текстом, а не байтами, и добавляется в начало сообщения без изменений.

encodePriority(facility, priority)

Кодирует facility и priority в целое число. Можно передавать строки или целые числа: если переданы строки, для преобразования в целые числа используются внутренние словари соответствий.

Символьные значения LOG_ определены в SysLogHandler и соответствуют значениям, определённым в заголовочном файле sys/syslog.h.

Приоритеты

Имя (строка)	Символьное значение
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

Категории

Имя (строка)	Символьное значение
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)

Сопоставляет имя уровня журналирования с именем приоритета syslog. Возможно, этот метод потребуется переопределить, если используются пользовательские уровни или алгоритм по умолчанию не подходит для ваших задач. Алгоритм по умолчанию сопоставляет DEBUG, INFO, WARNING, ERROR и CRITICAL с соответствующими именами syslog, а всем остальным именам уровней назначает «warning».

NTEventLogHandler

Класс NTEventLogHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журнала в локальный журнал событий Windows NT, Windows 2000 или Windows XP. Перед использованием необходимо установить расширения Win32 для Python от Марка Хаммонда.

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

Возвращает новый экземпляр класса NTEventLogHandler. Параметр appname используется для задания имени приложения, отображаемого в журнале событий. С этим именем создаётся соответствующая запись реестра. В параметре dllname следует указать полный путь к файлу .dll или .exe, содержащему описания сообщений, которые будут храниться в журнале (если параметр не указан, используется 'win32service.pyd' — он устанавливается вместе с расширениями Win32 и содержит несколько базовых описаний сообщений-заполнителей. Обратите внимание: использование этих заполнителей увеличит размер журналов событий, поскольку весь источник сообщения хранится в журнале. Чтобы уменьшить размер журналов, необходимо передать имя собственного файла .dll или .exe, содержащего описания сообщений, которые вы хотите использовать в журнале событий). Параметр logtype должен иметь одно из значений: 'Application', 'System' или 'Security'; по умолчанию используется 'Application'.

close()

На этом этапе можно удалить имя приложения из реестра как источник записей журнала событий. Однако в таком случае события не будут отображаться в средстве просмотра журнала событий так, как задумано: для получения имени .dll ему необходим доступ к реестру. Текущая версия этого не делает.

emit(record)

Определяет идентификатор сообщения, категорию и тип события, а затем записывает сообщение в журнал событий NT.

getEventCategory(record)

Возвращает категорию события для записи. Переопределите этот метод, если хотите задать собственные категории. Эта версия возвращает 0.

getEventType(record)

Возвращает тип события для записи. Переопределите этот метод, если хотите задать собственные типы. Эта версия выполняет сопоставление с использованием атрибута typemap обработчика, который настраивается в __init__() как словарь сопоставлений для DEBUG, INFO, WARNING, ERROR и CRITICAL. Если вы используете собственные уровни, потребуется переопределить этот метод или поместить подходящий словарь в атрибут typemap обработчика.

getMessageID(record)

Возвращает идентификатор сообщения для записи. Если вы используете собственные сообщения, можно передавать в качестве msg регистратору идентификатор, а не форматную строку. Затем здесь можно использовать поиск в словаре, чтобы получить идентификатор сообщения. Эта версия возвращает 1 — базовый идентификатор сообщения в win32service.pyd.

SMTPHandler

Класс SMTPHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журнала на адрес электронной почты через SMTP.

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

Возвращает новый экземпляр класса SMTPHandler. Экземпляр инициализируется адресами отправителя и получателей, а также темой письма. Параметр toaddrs должен быть списком строк. Чтобы задать нестандартный порт SMTP, используйте формат кортежа (host, port) для аргумента mailhost. Если указать строку, будет использоваться стандартный порт SMTP. Если SMTP-сервер требует аутентификации, можно указать для аргумента credentials кортеж (username, password).

Чтобы использовать защищённый протокол (TLS), передайте кортеж в аргумент secure. Он используется только при наличии учётных данных для аутентификации. Кортеж должен быть пустым либо содержать одно значение — имя файла ключа, либо два значения — имена файла ключа и файла сертификата. (Этот кортеж передаётся методу smtplib.SMTP.starttls().)

Время ожидания обмена данными с SMTP-сервером можно задать с помощью аргумента timeout.

Изменено в версии 3.3: Добавлен параметр timeout.

emit(record)

Форматирует запись и отправляет её указанным получателям.

getSubject(record)

Переопределите этот метод, если хотите задавать тему письма в зависимости от записи.

MemoryHandler

Класс MemoryHandler, расположенный в модуле logging.handlers, поддерживает буферизацию записей журнала в памяти и их периодическую передачу целевому обработчику target. Буфер сбрасывается, когда он заполнен или когда встречается событие с заданным уровнем серьёзности или выше.

MemoryHandler является подклассом более общего абстрактного класса BufferingHandler. Этот класс буферизует записи журнала в памяти. При добавлении каждой записи в буфер вызывается shouldFlush(), чтобы проверить, нужно ли сбросить буфер. Если сброс требуется, ожидается, что его выполнит flush().

class logging.handlers.BufferingHandler(capacity)

Инициализирует обработчик буфером заданной ёмкости. Здесь capacity означает количество буферизуемых записей журнала.

emit(record)

Добавляет запись в буфер. Если shouldFlush() возвращает true, вызывает flush() для обработки буфера.

flush()

Для экземпляра BufferingHandler сброс означает очистку буфера — он становится пустым списком. Этот метод можно переопределить, чтобы реализовать более полезное поведение при сбросе.

shouldFlush(record)

Возвращает True, если буфер заполнен. Этот метод можно переопределить, чтобы реализовать собственную стратегию сброса.

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

Возвращает новый экземпляр класса MemoryHandler. Экземпляр инициализируется буфером размером capacity (количество буферизуемых записей). Если flushLevel не указан, используется ERROR. Если параметр target не задан, его необходимо установить с помощью setTarget(), прежде чем обработчик сможет выполнять полезную работу. Если flushOnClose указан как False, при закрытии обработчика буфер не сбрасывается. Если параметр не указан или задан как True, при закрытии обработчика буфер сбрасывается, как и раньше.

Изменено в версии 3.6: Добавлен параметр flushOnClose.

close()

Вызывает flush(), устанавливает для целевого обработчика значение None и очищает буфер.

flush()

Для экземпляра MemoryHandler сброс означает отправку буферизованных записей целевому обработчику, если он задан. После отправки буферизованных записей буфер также очищается. Переопределите этот метод, если требуется другое поведение.

setTarget(target)

Задаёт целевой обработчик для этого обработчика.

shouldFlush(record)

Проверяет, заполнен ли буфер или достигла ли запись уровня flushLevel либо превысила его.

HTTPHandler

Класс HTTPHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журнала на веб-сервер с использованием семантики GET или POST.

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

Возвращает новый экземпляр класса HTTPHandler. host может иметь вид host:port, если необходимо использовать определённый номер порта. Если method не указан, используется GET. Если secure имеет значение true, будет использоваться соединение HTTPS. Параметру context можно присвоить экземпляр ssl.SSLContext для настройки параметров SSL, используемых для соединения HTTPS. Если указан параметр credentials, он должен быть кортежем из двух элементов, содержащим идентификатор пользователя и пароль, которые будут помещены в заголовок HTTP «Authorization» с использованием базовой аутентификации. Если вы указываете учётные данные, следует также указать secure=True, чтобы идентификатор пользователя и пароль не передавались по сети в открытом виде.

Изменено в версии 3.5: Добавлен параметр context.

mapLogRecord(record)

Возвращает словарь на основе record, который будет закодирован в формате URL и отправлен на веб-сервер. Реализация по умолчанию просто возвращает record.__dict__. Этот метод можно переопределить, если, например, на веб-сервер нужно отправить только часть LogRecord или требуется более точная настройка отправляемых на сервер данных.

emit(record)

Отправляет запись на веб-сервер в виде словаря, закодированного в формате URL. Для преобразования записи в отправляемый словарь используется метод mapLogRecord().

Примечание

Поскольку подготовка записи к отправке на веб-сервер отличается от обычного форматирования, использование setFormatter() для задания Formatter для HTTPHandler не имеет эффекта. Вместо вызова format() этот обработчик вызывает mapLogRecord(), а затем urllib.parse.urlencode(), чтобы закодировать словарь в формате, подходящем для отправки на веб-сервер.

QueueHandler

Класс QueueHandler, расположенный в модуле logging.handlers, поддерживает отправку сообщений журнала в очередь, например в очереди, реализованные в модулях queue или multiprocessing.

Вместе с классом QueueListener класс QueueHandler позволяет выполнять обработчикам свою работу в отдельном потоке, отличном от потока, в котором ведётся журналирование. Это важно для веб-приложений, а также других служебных приложений, где потоки, обслуживающие клиентов, должны отвечать как можно быстрее, а потенциально медленные операции (например, отправка электронной почты через SMTPHandler) выполняются в отдельном потоке.

class logging.handlers.QueueHandler(queue)

Возвращает новый экземпляр класса QueueHandler. Экземпляр инициализируется очередью, в которую отправляются сообщения. queue может быть любым объектом, подобным очереди; он используется без изменений методом enqueue(), который должен знать, как отправлять в него сообщения. Наличие API для отслеживания задач в очереди не является обязательным, поэтому в качестве queue можно использовать экземпляры SimpleQueue.

Примечание

При использовании multiprocessing следует избегать SimpleQueue и вместо него использовать multiprocessing.Queue.

emit(record)

Помещает в очередь результат подготовки LogRecord. Если возникает исключение (например, из-за заполнения очереди с ограниченным размером), для обработки ошибки вызывается метод handleError(). В результате запись может быть незаметно отброшена (если logging.raiseExceptions имеет значение False) или сообщение будет выведено в sys.stderr (если logging.raiseExceptions имеет значение True).

prepare(record)

Подготавливает запись для помещения в очередь. Возвращаемый этим методом объект помещается в очередь.

Базовая реализация форматирует запись, объединяя сообщение, аргументы, сведения об исключении и стеке, если они присутствуют. Кроме того, она удаляет из записи на месте элементы, которые нельзя сериализовать с помощью pickle. В частности, она перезаписывает атрибуты записи msg и message объединённым сообщением (полученным вызовом метода обработчика format()) и задаёт атрибутам args, exc_info и exc_text значение None.

Этот метод можно переопределить, если нужно преобразовать запись в словарь или строку JSON либо отправлять изменённую копию записи, оставляя исходную без изменений.

Примечание

Базовая реализация форматирует сообщение вместе с аргументами, задаёт атрибутам message и msg отформатированное сообщение, а атрибутам args и exc_text — значение None, чтобы разрешить сериализацию с помощью pickle и предотвратить дальнейшие попытки форматирования. Это означает, что обработчик на стороне QueueListener не будет располагать данными для пользовательского форматирования, например форматирования исключений. Возможно, вы захотите создать подкласс QueueHandler и переопределить этот метод, чтобы, например, не задавать exc_text значение None. Обратите внимание, что изменения message / msg / args необходимы для обеспечения возможности сериализации записи с помощью pickle. Возможно, от них удастся отказаться или нет — это зависит от того, можно ли сериализовать с помощью pickle ваши args. (Обратите внимание, что нужно учитывать не только собственный код, но и код используемых библиотек.)

enqueue(record)

Помещает запись в очередь с помощью put_nowait(); этот метод можно переопределить, если требуется использовать блокирующее поведение, тайм-аут или пользовательскую реализацию очереди.

listener

При создании с помощью конфигурации через dictConfig() этот атрибут будет содержать экземпляр QueueListener, используемый с этим обработчиком. В противном случае его значение будет None.

Добавлено в версии 3.12.

QueueListener

Класс QueueListener, расположенный в модуле logging.handlers, поддерживает получение сообщений журнала из очереди, например из очередей, реализованных в модулях queue или multiprocessing. Сообщения извлекаются из очереди во внутреннем потоке и передаются в этом же потоке одному или нескольким обработчикам для обработки. Хотя QueueListener сам по себе не является обработчиком, он описан здесь, поскольку работает совместно с QueueHandler.

Вместе с классом QueueHandler класс QueueListener позволяет выполнять обработчикам свою работу в отдельном потоке, отличном от потока, в котором ведётся журналирование. Это важно для веб-приложений, а также других служебных приложений, где потоки, обслуживающие клиентов, должны отвечать как можно быстрее, а потенциально медленные операции (например, отправка электронной почты через SMTPHandler) выполняются в отдельном потоке.

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

Возвращает новый экземпляр класса QueueListener. Экземпляр инициализируется очередью для отправки сообщений и списком обработчиков, которые будут обрабатывать помещённые в очередь записи. Очередью может быть любой объект, подобный очереди; он передаётся без изменений методу dequeue(), который должен знать, как извлекать из него сообщения. Наличие API для отслеживания задач в очереди не является обязательным (хотя он используется, если доступен), поэтому в качестве queue можно использовать экземпляры SimpleQueue.

Примечание

При использовании multiprocessing следует избегать SimpleQueue и вместо него использовать multiprocessing.Queue.

Если respect_handler_level имеет значение True, при принятии решения о передаче сообщений обработчику учитывается его уровень (сравниваемый с уровнем сообщения); в противном случае поведение соответствует предыдущим версиям Python — каждое сообщение всегда передаётся каждому обработчику.

Изменено в версии 3.5: Добавлен аргумент respect_handler_level.

dequeue(block)

Извлекает запись из очереди и возвращает её, при необходимости блокируя выполнение.

В базовой реализации используется get(). Этот метод можно переопределить, если требуется использовать тайм-ауты или работать с пользовательскими реализациями очередей.

prepare(record)

Подготавливает запись к обработке.

Эта реализация просто возвращает переданную запись. Этот метод можно переопределить, если перед передачей записи обработчикам требуется выполнить пользовательскую сериализацию или преобразование.

handle(record)

Обрабатывает запись.

Метод перебирает обработчики, предлагая каждому обработать запись. Обработчикам передаётся объект, возвращённый методом prepare().

start()

Запускает прослушиватель.

Запускает фоновый поток, который отслеживает очередь и обрабатывает LogRecord.

stop()

Останавливает прослушиватель.

Потоку отправляется команда завершиться, после чего метод ожидает его завершения. Обратите внимание: если не вызвать этот метод до завершения приложения, в очереди могут остаться необработанные записи.

enqueue_sentinel()

Помещает в очередь специальное значение, сообщающее прослушивателю о необходимости завершить работу. В этой реализации используется put_nowait(). Этот метод можно переопределить, если требуется использовать тайм-ауты или работать с пользовательскими реализациями очередей.

Добавлено в версии 3.3.