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, следит за тем, изменился ли файл с момента последнего вывода записи. (Файл считается изменившимся, если изменились его устройство или индексный дескриптор.) Если файл изменился, старый поток файла закрывается, а файл открывается для получения нового потока.

Этот обработчик не подходит для использования в 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)

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

shouldRollover(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()

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

shouldRollover(record)

Проверяет, прошло ли достаточно времени для ротации, и, если прошло, вычисляет время следующей ротации.

SocketHandler

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

class logging.handlers.SocketHandler(host, port)

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

Изменено в версии 3.4: Если port задано как None, с использованием значения в host создаётся доменный сокет Unix; в противном случае создаётся сокет 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, с использованием значения в host создаётся доменный сокет Unix; в противном случае создаётся сокет UDP.

emit()

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

makeSocket()

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

send(s)

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

SysLogHandler

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

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

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

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

Примечание

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

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

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

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

close()

Закрывает сокет, соединённый с удалённым узлом.

createSocket()

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

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

emit(record)

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

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

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

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

encodePriority(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)

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

NTEventLogHandler

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

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, используйте для аргумента mailhost кортеж в формате (host, port). Если передана строка, используется стандартный порт 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.

Предупреждение

Модуль multiprocessing использует внутренний регистратор, создаваемый и доступный через get_logger(). multiprocessing.Queue записывает сообщения уровня DEBUG при помещении элементов в очередь. Если эти сообщения журнала обрабатываются объектом QueueHandler, использующим тот же экземпляр 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. Возможно, вам удастся избежать этих изменений, если ваши 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.

Изменено в версии 3.14: Теперь QueueListener можно использовать как менеджер контекста с помощью with. При входе в контекст прослушиватель запускается. При выходе из контекста прослушиватель останавливается. __enter__() возвращает объект QueueListener.

dequeue(block)

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

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

prepare(record)

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

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

handle(record)

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

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

start()

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

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

Изменено в версии 3.14: Вызывает RuntimeError, если метод вызван, когда прослушиватель уже работает.

stop()

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

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

enqueue_sentinel()

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

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