`logging.handlers.md`

537 строк · 61.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.3/library/logging.handlers.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 16.9. [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers) – Обработчики логирования89Важно1011На этой странице представлена только справочная информация. Учебные руководства см. в1213- [*Базовое руководство*](https://python-all.ru/3.3/howto/logging.html#logging-basic-tutorial)14- [*Продвинутое руководство*](https://python-all.ru/3.3/howto/logging.html#logging-advanced-tutorial)15- [*Поваренная книга по логированию*](https://python-all.ru/3.3/howto/logging-cookbook.html#logging-cookbook)1617**Исходный код:** [Lib/logging/handlers.py](https://python-all.ru/src/3.3/Lib/logging/handlers.py)1819---2021В пакете предоставлены следующие полезные обработчики. Обратите внимание, что три из них ([`StreamHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.StreamHandler), [`FileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.FileHandler) и [`NullHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.NullHandler)) на самом деле определены в самом модуле [`logging`](https://python-all.ru/3.3/library/logging.html#module-logging), но описаны здесь вместе с остальными обработчиками.2223## 16.9.1. StreamHandler2425Класс [`StreamHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.StreamHandler), расположенный в основном пакете [`logging`](https://python-all.ru/3.3/library/logging.html#module-logging), отправляет вывод логирования в такие потоки, как *sys.stdout*, *sys.stderr* или любой файлоподобный объект (или, точнее, любой объект, поддерживающий методы `write()` и `flush()`).2627#### `class logging.StreamHandler(stream=None)`2829Возвращает новый экземпляр класса [`StreamHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.StreamHandler). Если указан параметр *поток данных*, экземпляр использует его для вывода логирования; в противном случае используется *sys.stderr*.3031#### `emit(record)`3233Если указан форматтер, он форматирует запись. Затем запись записывается в поток с завершающим символом. Если присутствует информация об исключении, она форматируется с помощью [`traceback.print_exception()`](https://python-all.ru/3.3/library/traceback.html#traceback.print_exception) и добавляется в поток.3435#### `flush()`3637Сбрасывает поток, вызывая его метод [`flush()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.StreamHandler.flush). Обратите внимание, что метод `close()` наследуется от `Handler` и поэтому не выполняет вывод, так что иногда может потребоваться явный вызов [`flush()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.StreamHandler.flush).3839Изменено в версии 3.2: Теперь у класса `StreamHandler` есть атрибут `terminator`, значение по умолчанию `'\n'`, который используется как завершитель при записи форматированной записи в поток. Если вы не хотите завершать переводом строки, вы можете установить атрибут `terminator` экземпляра обработчика в пустую строку. В предыдущих версиях завершитель был жёстко задан как `'\n'`.4041## 16.9.2. FileHandler4243Класс [`FileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.FileHandler), расположенный в основном пакете [`logging`](https://python-all.ru/3.3/library/logging.html#module-logging), отправляет вывод логирования в файл на диске. Он наследует функциональность вывода от [`StreamHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.StreamHandler).4445#### `class logging.FileHandler(filename, mode='a', encoding=None, delay=False)`4647Возвращает новый экземпляр класса [`FileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.FileHandler). Указанный файл открывается и используется как поток для логирования. Если *mode* не указан, используется `'a'`. Если *encoding* не равен *None*, файл открывается с указанной кодировкой. Если *delay* равен true, открытие файла откладывается до первого вызова [`emit()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.FileHandler.emit). По умолчанию файл растёт бесконечно.4849#### `close()`5051Закрывает файл.5253#### `emit(record)`5455Выводит запись в файл.5657## 16.9.3. NullHandler5859Новое в версии 3.1.6061Класс [`NullHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.NullHandler), расположенный в основном пакете [`logging`](https://python-all.ru/3.3/library/logging.html#module-logging), не выполняет никакого форматирования или вывода. По сути это обработчик-пустышка, предназначенный для разработчиков библиотек.6263#### `class logging.NullHandler`6465Возвращает новый экземпляр класса [`NullHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.NullHandler).6667#### `emit(record)`6869Этот метод ничего не делает.7071#### `handle(record)`7273Этот метод ничего не делает.7475#### `createLock()`7677Этот метод возвращает `None` для блокировки, поскольку нет базового ввода-вывода, доступ к которому необходимо синхронизировать.7879Смотрите [*Настройка логирования для библиотеки*](https://python-all.ru/3.3/howto/logging.html#library-config) для получения дополнительной информации об использовании [`NullHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.NullHandler).8081## 16.9.4. WatchedFileHandler8283The [`WatchedFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.WatchedFileHandler) class, located in the [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers) module, is a `FileHandler` which watches the file it is logging to. If the file changes, it is closed and reopened using the file name.8485Файл может измениться из-за использования таких программ, как *newsyslog* и *logrotate*, которые выполняют ротацию файлов журнала. Этот обработчик, предназначенный для использования в Unix/Linux, следит, не изменился ли файл с момента последнего вызова emit. (Считается, что файл изменился, если изменились его устройство или inode.) Если файл изменился, старый поток файла закрывается, а файл открывается для получения нового потока.8687Этот обработчик не подходит для использования в Windows, потому что в Windows открытые файлы журналов нельзя перемещать или переименовывать – логирование открывает файлы с эксклюзивными блокировками – поэтому нет необходимости в таком обработчике. Кроме того, *ST\_INO* не поддерживается в Windows; [`stat()`](https://python-all.ru/3.3/library/os.html#os.stat) всегда возвращает ноль для этого значения.8889#### `class logging.handlers.WatchedFileHandler(filename[, mode[, encoding[, delay]]])`9091Возвращает новый экземпляр класса [`WatchedFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.WatchedFileHandler). Указанный файл открывается и используется как поток для логирования. Если *mode* не указан, используется `'a'`. Если *encoding* не равен *None*, файл открывается с указанной кодировкой. Если *delay* равен true, открытие файла откладывается до первого вызова [`emit()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.WatchedFileHandler.emit). По умолчанию файл растёт бесконечно.9293#### `emit(record)`9495Выводит запись в файл, но сначала проверяет, изменился ли файл. Если изменился, существующий поток сбрасывается и закрывается, а файл открывается заново, после чего запись выводится в файл.9697## 16.9.5. BaseRotatingHandler9899Класс [`BaseRotatingHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.BaseRotatingHandler), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), является базовым классом для ротационных файловых обработчиков, [`RotatingFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.RotatingFileHandler) и [`TimedRotatingFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler). Обычно не требуется создавать экземпляры этого класса, однако он содержит атрибуты и методы, которые может понадобиться переопределить.100101#### `class logging.handlers.BaseRotatingHandler(filename, mode, encoding=None, delay=False)`102103Параметры такие же, как у `FileHandler`. Атрибуты:104105#### `namer`106107Если этому атрибуту присвоен вызываемый объект, метод [`rotation_filename()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.BaseRotatingHandler.rotation_filename) делегирует вызов этому объекту. Параметры, передаваемые вызываемому объекту, – это те же параметры, что передаются методу [`rotation_filename()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.BaseRotatingHandler.rotation_filename).108109> **Примечание**110>111> Функция namer вызывается довольно много раз во время ротации, поэтому она должна быть максимально простой и быстрой. Она также должна возвращать одинаковый результат для одного и того же входного значения, иначе поведение ротации может не соответствовать ожидаемому.112113Новое в версии 3.3.114115#### `rotator`116117Если этому атрибуту присвоен вызываемый объект, метод [`rotate()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.BaseRotatingHandler.rotate) делегирует вызов этому объекту. Параметры, передаваемые вызываемому объекту, – это те же параметры, что передаются методу [`rotate()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.BaseRotatingHandler.rotate).118119Новое в версии 3.3.120121#### `rotation_filename(default_name)`122123Изменяет имя файла журнала при ротации.124125Это предусмотрено, чтобы можно было задать пользовательское имя файла.126127Реализация по умолчанию вызывает атрибут 'namer' обработчика, если он является вызываемым, передавая ему имя по умолчанию. Если атрибут не является вызываемым (по умолчанию `None`), имя возвращается без изменений.128129| Параметры: | **default\_name** – имя файла журнала по умолчанию. |130| --- | --- |131132Новое в версии 3.3.133134#### `rotate(source, dest)`135136При ротации выполняет ротацию текущего журнала.137138Реализация по умолчанию вызывает атрибут 'rotator' обработчика, если он является вызываемым, передавая ему аргументы source и dest. Если атрибут не является вызываемым (по умолчанию `None`), файл source просто переименовывается в destination.139140| Параметры: | **source** – Имя исходного файла. Обычно это базовое имя файла, например, ‘test.log’ **dest** – имя файла назначения. Обычно это то, во что ротируется source, например ‘test.log.1’. |141| --- | --- |142143Новое в версии 3.3.144145Атрибуты существуют для того, чтобы избавить от необходимости создавать подклассы: можно использовать одни и те же вызываемые объекты для экземпляров [`RotatingFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.RotatingFileHandler) и [`TimedRotatingFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler). Если какой-либо из вызываемых объектов namer или rotator возбуждает исключение, оно обрабатывается так же, как любое другое исключение при вызове `emit()`, то есть через метод `handleError()` обработчика.146147Если требуется внести более существенные изменения в обработку ротации, можно переопределить методы.148149Пример см. в [*Использование rotator и namer для настройки обработки ротации журналов*](https://python-all.ru/3.3/howto/logging-cookbook.html#cookbook-rotator-namer).150151## 16.9.6. RotatingFileHandler152153Класс [`RotatingFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.RotatingFileHandler), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), поддерживает ротацию файлов журнала на диске.154155#### `class logging.handlers.RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=0)`156157Возвращает новый экземпляр класса [`RotatingFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.RotatingFileHandler). Указанный файл открывается и используется как поток для журналирования. Если *mode* не указан, используется `'a'`. Если *encoding* не равен *None*, файл открывается с указанной кодировкой. Если *delay* равен истине, открытие файла откладывается до первого вызова [`emit()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.RotatingFileHandler.emit). По умолчанию файл растёт бесконечно.158159Значения *maxBytes* и *backupCount* позволяют задать размер, при котором файл *переключается*. Когда размер почти превышен, файл закрывается и новый файл открывается для записи. Переключение происходит, когда текущий файл журнала приближается к длине *maxBytes*; если *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` и т.д. соответственно.160161#### `doRollover()`162163Выполняет ротацию, как описано выше.164165#### `emit(record)`166167Записывает запись (record) в файл, выполняя при необходимости ротацию, как описано ранее.168169## 16.9.7. TimedRotatingFileHandler170171Класс [`TimedRotatingFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), поддерживает ротацию файлов журнала на диске через заданные интервалы времени.172173#### `class logging.handlers.TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False)`174175Возвращает новый экземпляр класса [`TimedRotatingFileHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler). Указанный файл открывается и используется как поток для журналирования. При ротации также устанавливается суффикс имени файла. Ротация происходит на основе произведения *when* и *interval*.176177Параметр *when* указывает тип *interval*. Список возможных значений приведён ниже. Обратите внимание, что регистр не учитывается.178179| Значение | Тип интервала |180| --- | --- |181| `'S'` | Секунды |182| `'M'` | Минуты |183| `'H'` | Часы |184| `'D'` | Дни |185| `'W0'-'W6'` | День недели (0=понедельник) |186| `'midnight'` | Переключение в полночь |187188При использовании ротации по дням недели укажите 'W0' для понедельника, 'W1' для вторника и так далее до 'W6' для воскресенья. В этом случае значение, переданное для *interval*, не используется.189190Система будет сохранять старые файлы журнала, добавляя расширения к имени файла. Расширения основаны на дате и времени, с использованием формата strftime `%Y-%m-%d_%H-%M-%S` или его начальной части, в зависимости от интервала ротации.191192При первом вычислении времени следующей ротации (при создании обработчика) используется время последнего изменения существующего файла журнала или, в противном случае, текущее время, чтобы определить, когда произойдёт следующая ротация.193194Если аргумент *utc* равен true, используется время в UTC; в противном случае используется местное время.195196Если *backupCount* не равен нулю, сохраняется не более *backupCount* файлов; если при ротации должно быть создано больше файлов, самый старый удаляется. Логика удаления использует интервал для определения того, какие файлы нужно удалить, поэтому изменение интервала может привести к тому, что старые файлы останутся.197198Если *delay* равен true, открытие файла откладывается до первого вызова [`emit()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler.emit).199200#### `doRollover()`201202Выполняет ротацию, как описано выше.203204#### `emit(record)`205206Выводит запись в файл, обеспечивая ротацию, как описано выше.207208## 16.9.8. SocketHandler209210Класс [`SocketHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SocketHandler), находящийся в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), отправляет вывод журнала в сетевой сокет. Базовый класс использует TCP-сокет.211212#### `class logging.handlers.SocketHandler(host, port)`213214Возвращает новый экземпляр класса [`SocketHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SocketHandler), предназначенного для взаимодействия с удаленной машиной, адрес которой задается *host* и *port*.215216#### `close()`217218Закрывает сокет.219220#### `emit()`221222Сериализует словарь атрибутов записи и записывает его в сокет в dвоичном формате. Если возникла ошибка с сокетом, пакет молча отбрасывается. Если соединение было ранее потеряно, восстанавливает его. Чтобы десериализовать запись на принимающей стороне в объект [`LogRecord`](https://python-all.ru/3.3/library/logging.html#logging.LogRecord), используйте функцию [`makeLogRecord()`](https://python-all.ru/3.3/library/logging.html#logging.makeLogRecord).223224#### `handleError()`225226Обрабатывает ошибку, возникшую во время [`emit()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SocketHandler.emit). Наиболее вероятная причина – потеря соединения. Закрывает сокет, чтобы можно было повторить попытку при следующем событии.227228#### `makeSocket()`229230Это фабричный метод, позволяющий подклассам определять точный тип сокета, который они хотят. Реализация по умолчанию создает TCP-сокет ([`socket.SOCK_STREAM`](https://python-all.ru/3.3/library/socket.html#socket.SOCK_STREAM)).231232#### `makePickle(record)`233234Сериализует словарь атрибутов записи в двоичном формате с префиксом длины и возвращает его готовым к передаче через сокет.235236Обратите внимание, что модуль pickle не является полностью безопасным. Если вас беспокоит безопасность, вы можете переопределить этот метод, чтобы реализовать более надёжный механизм. Например, можно подписывать данные с помощью HMAC и проверять подпись на принимающей стороне, либо отключить десериализацию глобальных объектов на принимающей стороне.237238#### `send(packet)`239240Отправляет сериализованную с помощью pickle строку *packet* в сокет. Эта функция допускает частичную отправку, которая может произойти, когда сеть занята.241242#### `createSocket()`243244Пытается создать сокет; в случае неудачи использует алгоритм экспоненциальной задержки. При первоначальном сбое обработчик отбрасывает сообщение, которое пытался отправить. Когда последующие сообщения обрабатываются тем же экземпляром, он не будет пытаться подключиться, пока не пройдет некоторое время. Параметры по умолчанию таковы, что начальная задержка составляет одну секунду, и если после этой задержки соединение всё ещё не может быть установлено, обработчик будет каждый раз удваивать задержку вплоть до максимума в 30 секунд.245246Это поведение управляется следующими атрибутами обработчика:247248- `retryStart` (начальная задержка, по умолчанию 1.0 секунды).249- `retryFactor` (множитель, по умолчанию 2.0).250- `retryMax` (максимальная задержка, по умолчанию 30.0 секунд).251252Это означает, что если удалённый слушатель запускается *после* того, как обработчик уже использовался, возможна потеря сообщений (поскольку обработчик даже не будет пытаться установить соединение, пока не истечёт задержка, а будет просто молча отбрасывать сообщения в течение этого периода).253254## 16.9.9. DatagramHandler255256Класс [`DatagramHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.DatagramHandler), находящийся в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), наследует от [`SocketHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SocketHandler) для поддержки отправки сообщений журнала через UDP-сокеты.257258#### `class logging.handlers.DatagramHandler(host, port)`259260Возвращает новый экземпляр класса [`DatagramHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.DatagramHandler), предназначенного для взаимодействия с удаленной машиной, адрес которой задается *host* и *port*.261262#### `emit()`263264Сериализует словарь атрибутов записи и записывает его в сокет в dвоичном формате. Если возникла ошибка с сокетом, пакет молча отбрасывается. Чтобы десериализовать запись на принимающей стороне в объект [`LogRecord`](https://python-all.ru/3.3/library/logging.html#logging.LogRecord), используйте функцию [`makeLogRecord()`](https://python-all.ru/3.3/library/logging.html#logging.makeLogRecord).265266#### `makeSocket()`267268Фабричный метод [`SocketHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SocketHandler) здесь переопределен для создания UDP-сокета ([`socket.SOCK_DGRAM`](https://python-all.ru/3.3/library/socket.html#socket.SOCK_DGRAM)).269270#### `send(s)`271272Отправляет сериализованную с помощью pickle строку в сокет.273274## 16.9.10. SysLogHandler275276Класс [`SysLogHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SysLogHandler), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), поддерживает отправку сообщений журнала на удалённый или локальный syslog Unix.277278#### `class logging.handlers.SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)`279280Возвращает новый экземпляр класса [`SysLogHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SysLogHandler), предназначенного для взаимодействия с удалённой Unix-машиной, чей адрес задаётся *address* в виде кортежа `(host, port)`. Если *address* не указан, используется `('localhost', 514)`. Адрес используется для открытия сокета. Альтернативой предоставлению кортежа `(host, port)` является передача адреса в виде строки, например ‘/dev/log’. В этом случае для отправки сообщения syslog используется сокет домена Unix. Если *facility* не указан, используется `LOG_USER`. Тип открываемого сокета зависит от аргумента *socktype*, который по умолчанию равен [`socket.SOCK_DGRAM`](https://python-all.ru/3.3/library/socket.html#socket.SOCK_DGRAM) и, таким образом, открывает UDP-сокет. Чтобы открыть TCP-сокет (для использования с более новыми демонами syslog, такими как rsyslog), укажите значение [`socket.SOCK_STREAM`](https://python-all.ru/3.3/library/socket.html#socket.SOCK_STREAM).281282Обратите внимание: если ваш сервер не слушает UDP-порт 514, [`SysLogHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SysLogHandler) может не работать. В этом случае проверьте, какой адрес следует использовать для сокета домена – это зависит от системы. Например, в Linux это обычно ‘/dev/log’, а в OS/X – ‘/var/run/syslog’. Вам нужно проверить свою платформу и использовать соответствующий адрес (возможно, придётся делать эту проверку во время выполнения, если приложение должно работать на нескольких платформах). В Windows практически приходится использовать опцию UDP.283284Изменено в версии 3.2: добавлен параметр *socktype*.285286#### `close()`287288Закрывает сокет, подключённый к удалённому узлу.289290#### `emit(record)`291292Запись форматируется и отправляется на сервер syslog. Если присутствует информация об исключении, она *не* отправляется на сервер.293294Изменено в версии 3.2.1: (См.: [issue 12168](https://python-all.ru/3.3/library/logging.handlers.html).) В более ранних версиях сообщение, отправляемое демонам syslog, всегда завершалось NUL-байтом, поскольку ранние версии этих демонов ожидали сообщение с завершающим NUL – хотя это не предусмотрено соответствующей спецификацией (RFC 5424). Более новые версии этих демонов не ожидают NUL-байт, но удаляют его, если он присутствует, а ещё более новые демоны (которые точнее следуют RFC 5424) передают NUL-байт как часть сообщения.295296Чтобы упростить обработку сообщений syslog в условиях столь разного поведения демонов, добавление NUL-байта было сделано настраиваемым с помощью атрибута уровня класса `append_nul`. По умолчанию он равен `True` (сохраняя существующее поведение), но может быть установлен в `False` на экземпляре `SysLogHandler`, чтобы этот экземпляр *не* добавлял завершающий NUL.297298Изменено в версии 3.3: (См.: [issue 12419](https://python-all.ru/3.3/library/logging.handlers.html).) В более ранних версиях не было возможности указать префикс “ident” или “tag” для идентификации источника сообщения. Теперь его можно задать с помощью атрибута уровня класса, по умолчанию `""` для сохранения существующего поведения, но который может быть переопределён на экземпляре `SysLogHandler`, чтобы этот экземпляр добавлял идентификатор к каждому обработанному сообщению. Обратите внимание, что указанный идентификатор должен быть текстом, не байтами, и добавляется к сообщению как есть.299300#### `encodePriority(facility, priority)`301302Кодирует средство и приоритет в целое число. Можно передавать строки или целые числа – если передаются строки, внутренние словари сопоставлений используются для преобразования их в целые числа.303304Символические значения `LOG_` определены в [`SysLogHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SysLogHandler) и соответствуют значениям, определённым в заголовочном файле `sys/syslog.h`.305306**Приоритеты**307308| Имя (строка) | Символическое значение |309| --- | --- |310| `alert` | LOG\_ALERT |311| `crit` или `critical` | LOG\_CRIT |312| `отладка` | LOG\_DEBUG |313| `аварийная` или `паника` | LOG\_EMERG |314| `ошибка` или `ошибка` | LOG\_ERR |315| `информация` | LOG\_INFO |316| `уведомление` | LOG\_NOTICE |317| `предупреждение` или `предупреждение` | LOG\_WARNING |318319**Средства**320321| Имя (строка) | Символическое значение |322| --- | --- |323| `аутентификация` | LOG\_AUTH |324| `authpriv` | LOG\_AUTHPRIV |325| `cron` | LOG\_CRON |326| `демон` | LOG\_DAEMON |327| `ftp` | LOG\_FTP |328| `ядро` | LOG\_KERN |329| `lpr` | LOG\_LPR |330| `почта` | LOG\_MAIL |331| `новости` | LOG\_NEWS |332| `syslog` | LOG\_SYSLOG |333| `user` | LOG\_USER |334| `uucp` | LOG\_UUCP |335| `local0` | LOG\_LOCAL0 |336| `local1` | LOG\_LOCAL1 |337| `local2` | LOG\_LOCAL2 |338| `local3` | LOG\_LOCAL3 |339| `local4` | LOG\_LOCAL4 |340| `local5` | LOG\_LOCAL5 |341| `local6` | LOG\_LOCAL6 |342| `local7` | LOG\_LOCAL7 |343344#### `mapPriority(levelname)`345346Сопоставляет имя уровня логирования с именем приоритета syslog. Возможно, потребуется переопределить это, если используются пользовательские уровни, или если алгоритм по умолчанию не подходит. Алгоритм по умолчанию сопоставляет `DEBUG`, `INFO`, `WARNING`, `ERROR` и `CRITICAL` с соответствующими именами syslog, а все остальные уровни сопоставляет с 'warning'.347348## 16.9.11. NTEventLogHandler349350Класс [`NTEventLogHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.NTEventLogHandler), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers) модуле, поддерживает отправку сообщений логирования в журнал событий локальной системы Windows NT, Windows 2000 или Windows XP. Перед использованием необходимо установить расширения Win32 для Python от Mark Hammond.351352#### `class logging.handlers.NTEventLogHandler(appname, dllname=None, logtype='Application')`353354Возвращает новый экземпляр класса [`NTEventLogHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.NTEventLogHandler). Параметр *appname* используется для определения имени приложения, отображаемого в журнале событий. С использованием этого имени создается соответствующая запись реестра. Параметр *dllname* должен содержать полный путь к .dll или .exe-файлу с определениями сообщений для хранения в журнале (если не указан, используется `'win32service.pyd'` – он устанавливается вместе с расширениями Win32 и содержит несколько базовых определений сообщений-заполнителей. Обратите внимание, что использование этих заполнителей приведет к увеличению размера журнала, так как весь источник сообщений хранится в журнале. Если нужны более компактные журналы, следует передать имя собственного .dll или .exe, содержащего нужные определения сообщений). Параметр *logtype* может быть одним из `'Application'`, `'System'` или `'Security'`, по умолчанию `'Application'`.355356#### `close()`357358На этом этапе можно удалить имя приложения из реестра как источник записей журнала событий. Однако после этого события не будут отображаться в средстве просмотра журнала событий так, как предполагалось – для получения имени .dll требуется доступ к реестру. Текущая версия этого не делает.359360#### `emit(record)`361362Определяет идентификатор сообщения, категорию и тип события, а затем записывает сообщение в журнал событий NT.363364#### `getEventCategory(record)`365366Возвращает категорию события для записи. Переопределите этот метод, чтобы указать собственные категории. Данная версия возвращает 0.367368#### `getEventType(record)`369370Возвращает тип события для записи. Переопределите этот метод, если нужно задать собственные типы. В данной версии используется сопоставление через атрибут typemap обработчика, который устанавливается в [`__init__()`](https://python-all.ru/3.3/reference/datamodel.html#object.__init__) в виде словаря, содержащего сопоставления для `DEBUG`, `INFO`, `WARNING`, `ERROR` и `CRITICAL`. При использовании собственных уровней потребуется либо переопределить этот метод, либо поместить подходящий словарь в атрибут *typemap* обработчика.371372#### `getMessageID(record)`373374Возвращает идентификатор сообщения для записи. При использовании собственных сообщений можно передать в логгер идентификатор *msg* вместо строки форматирования. Затем здесь можно выполнить поиск по словарю для получения идентификатора сообщения. Данная версия возвращает 1 – базовый идентификатор сообщения в `win32service.pyd`.375376## 16.9.12. SMTPHandler377378Класс [`SMTPHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SMTPHandler), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), поддерживает отправку сообщений логирования на адрес электронной почты через SMTP.379380#### `class logging.handlers.SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)`381382Возвращает новый экземпляр класса [`SMTPHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SMTPHandler). Экземпляр инициализируется адресами отправителя, получателя и темой письма. Параметр *toaddrs* должен быть списком строк. Для указания нестандартного порта SMTP используется кортеж (host, port) в аргументе *mailhost*. Если передана строка, используется стандартный порт SMTP. Если SMTP-сервер требует аутентификации, можно указать кортеж (username, password) в аргументе *credentials*.383384Для использования защищенного протокола (TLS) передайте кортеж в аргумент *secure*. Это будет работать только при наличии учетных данных для аутентификации. Кортеж должен быть либо пустым, либо содержать один элемент – имя файла ключа, либо два элемента – имена файла ключа и сертификата. (Этот кортеж передается методу [`smtplib.SMTP.starttls()`](https://python-all.ru/3.3/library/smtplib.html#smtplib.SMTP.starttls).)385386Для взаимодействия с SMTP-сервером можно задать тайм-аут с помощью аргумента *timeout*.387388Новое в версии 3.3: Аргумент *timeout* был добавлен.389390#### `emit(record)`391392Форматирует запись и отправляет её указанным получателям.393394#### `getSubject(record)`395396Чтобы задать тему письма, зависящую от записи, переопределите этот метод.397398## 16.9.13. MemoryHandler399400Класс [`MemoryHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.MemoryHandler), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), поддерживает буферизацию записей логирования в памяти с периодической отправкой в целевой обработчик *target*. Сброс происходит, когда буфер заполнен или когда встречается событие определенного уровня серьезности или выше.401402[`MemoryHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.MemoryHandler) является подклассом более общего [`BufferingHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.BufferingHandler), который является абстрактным классом. Он буферизует записи логирования в памяти. При добавлении каждой записи в буфер вызывается `shouldFlush()` для проверки необходимости сброса. Если сброс требуется, то ожидается, что `flush()` выполнит сброс.403404#### `class logging.handlers.BufferingHandler(capacity)`405406Инициализирует обработчик буфером указанной ёмкости.407408#### `emit(record)`409410Добавляет запись в буфер. Если [`shouldFlush()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.BufferingHandler.shouldFlush) возвращает true, вызывает [`flush()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.BufferingHandler.flush) для обработки буфера.411412#### `flush()`413414Вы можете переопределить этот метод, чтобы задать собственное поведение при сбросе. Текущая версия просто очищает буфер.415416#### `shouldFlush(record)`417418Возвращает true, если буфер заполнен до ёмкости. Этот метод можно переопределить для реализации собственных стратегий сброса.419420#### `class logging.handlers.MemoryHandler(capacity, flushLevel=ERROR, target=None)`421422Возвращает новый экземпляр класса [`MemoryHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.MemoryHandler). Экземпляр инициализируется с размером буфера *capacity*. Если *flushLevel* не указан, используется `ERROR`. Если *target* не указан, перед тем как обработчик начнёт работать, цель нужно задать с помощью [`setTarget()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.MemoryHandler.setTarget).423424#### `close()`425426Вызывает [`flush()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.MemoryHandler.flush), устанавливает цель в `None` и очищает буфер.427428#### `flush()`429430Для [`MemoryHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.MemoryHandler) сброс означает просто отправку буферизованных записей целевому обработчику, если он есть. Буфер также очищается, когда это происходит. Переопределите, если нужно иное поведение.431432#### `setTarget(target)`433434Устанавливает целевой обработчик для данного обработчика.435436#### `shouldFlush(record)`437438Проверяет, заполнен ли буфер или поступила запись уровня *flushLevel* или выше.439440## 16.9.14. HTTPHandler441442Класс [`HTTPHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.HTTPHandler), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), поддерживает отправку сообщений журнала на веб-сервер с использованием семантики `GET` или `POST`.443444#### `class logging.handlers.HTTPHandler(host, url, method='GET', secure=False, credentials=None)`445446Возвращает новый экземпляр класса [`HTTPHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.HTTPHandler). Параметр *host* может иметь вид `host:port`, если нужно указать конкретный номер порта. Если параметр *method* не указан, используется `GET`. Если *secure* имеет значение true, будет использоваться HTTPS-соединение. Если указан *credentials*, это должен быть кортеж из двух элементов: идентификатор пользователя и пароль. Они будут помещены в HTTP-заголовок «Authorization» с использованием базовой аутентификации. Если указываются учетные данные, также следует установить secure=True, чтобы идентификатор и пароль не передавались в открытом виде по сети.447448#### `emit(record)`449450Отправляет запись на веб-сервер в виде словаря в процентной кодировке.451452## 16.9.15. QueueHandler453454Новое в версии 3.2.455456Класс [`QueueHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueHandler), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers), поддерживает отправку сообщений журнала в очередь, например, реализованную в модулях [`queue`](https://python-all.ru/3.3/library/queue.html#module-queue) или [`multiprocessing`](https://python-all.ru/3.3/library/multiprocessing.html#module-multiprocessing).457458Вместе с классом [`QueueListener`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueListener) [`QueueHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueHandler) можно использовать, чтобы обработчики выполняли свою работу в отдельном потоке, отличном от того, который ведёт журналирование. Это важно в веб-приложениях и других служебных приложениях, где потоки, обслуживающие клиентов, должны отвечать как можно быстрее, в то время как потенциально медленные операции (например, отправка электронной почты через [`SMTPHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SMTPHandler)) выполняются в отдельном потоке.459460#### `class logging.handlers.QueueHandler(queue)`461462Возвращает новый экземпляр класса [`QueueHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueHandler). Экземпляр инициализируется очередью для отправки сообщений. Очередью может быть любой объект, похожий на очередь; он используется как есть методом [`enqueue()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueHandler.enqueue), который должен знать, как отправлять в неё сообщения.463464#### `emit(record)`465466Помещает в очередь результат подготовки LogRecord.467468#### `prepare(record)`469470Подготавливает запись для помещения в очередь. Объект, возвращаемый этим методом, помещается в очередь.471472Базовая реализация форматирует запись, объединяя сообщение и аргументы, и удаляет несериализуемые элементы из записи на месте.473474Этот метод можно переопределить, если требуется преобразовать запись в словарь или JSON-строку, или отправить изменённую копию записи, оставив оригинал нетронутым.475476#### `enqueue(record)`477478Помещает запись в очередь с помощью `put_nowait()`; этот метод можно переопределить, если требуется блокирующее поведение, или тайм-аут, или собственная реализация очереди.479480## 16.9.16. QueueListener481482Новое в версии 3.2.483484Класс [`QueueListener`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueListener), расположенный в модуле [`logging.handlers`](https://python-all.ru/3.3/library/logging.handlers.html#module-logging.handlers) , поддерживает получение сообщений журнала из очереди, например, реализованной в модулях [`queue`](https://python-all.ru/3.3/library/queue.html#module-queue) или [`multiprocessing`](https://python-all.ru/3.3/library/multiprocessing.html#module-multiprocessing). Сообщения получаются из очереди во внутреннем потоке и передаются, в том же потоке, одному или нескольким обработчикам для обработки. Хотя [`QueueListener`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueListener) сам по себе не является обработчиком, он документирован здесь, поскольку работает в тесной связке с [`QueueHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueHandler).485486Вместе с классом [`QueueHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueHandler) [`QueueListener`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueListener) можно использовать, чтобы обработчики выполняли свою работу в отдельном потоке, отличном от того, который ведёт журналирование. Это важно в веб-приложениях и других служебных приложениях, где потоки, обслуживающие клиентов, должны отвечать как можно быстрее, в то время как потенциально медленные операции (например, отправка электронной почты через [`SMTPHandler`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.SMTPHandler)) выполняются в отдельном потоке.487488#### `class logging.handlers.QueueListener(queue, *handlers)`489490Возвращает новый экземпляр класса [`QueueListener`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueListener). Экземпляр инициализируется очередью для отправки сообщений и списком обработчиков, которые будут обрабатывать записи, помещенные в очередь. Очередью может быть любой объект, похожий на очередь; он передается как есть методу [`dequeue()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueListener.dequeue), который должен знать, как получать из неё сообщения.491492#### `dequeue(block)`493494Извлекает запись из очереди и возвращает её, опционально блокируя.495496Базовая реализация использует `get()`. Возможно, потребуется переопределить этот метод, если нужно использовать тайм-ауты или работать с нестандартными реализациями очередей.497498#### `prepare(record)`499500Подготавливает запись к обработке.501502Эта реализация просто возвращает переданную запись. Можно переопределить этот метод, если требуется выполнить какую-либо собственную маршалинг или манипуляцию записью перед передачей обработчикам.503504#### `handle(record)`505506Обрабатывает запись.507508Этот метод просто перебирает обработчики, предлагая им запись для обработки. Объект, фактически передаваемый обработчикам, – это тот, который возвращается из [`prepare()`](https://python-all.ru/3.3/library/logging.handlers.html#logging.handlers.QueueListener.prepare).509510#### `start()`511512Запускает прослушиватель.513514Запускает фоновый поток для отслеживания очереди на предмет LogRecords, которые нужно обработать.515516#### `stop()`517518Останавливает прослушиватель.519520Запрашивает завершение потока и затем ожидает его завершения. Обратите внимание: если не вызвать этот метод до завершения приложения, в очереди могут остаться некоторые записи, которые не будут обработаны.521522#### `enqueue_sentinel()`523524Записывает сторожевой элемент в очередь, чтобы сообщить слушателю о завершении. В данной реализации используется `put_nowait()`. Возможно, потребуется переопределить этот метод, если нужно использовать тайм-ауты или работать с нестандартными реализациями очередей.525526Новое в версии 3.3.527528> **См. также**529>530> **Модуль [`logging`](https://python-all.ru/3.3/library/logging.html#module-logging)**531>532> Справочник API для модуля logging.533>534> **Модуль [`logging.config`](https://python-all.ru/3.3/library/logging.config.html#module-logging.config)**535>536> API конфигурации для модуля logging.537