*******************
日志
*******************

:官方手册: https://docs.python.org/zh-cn/3/library/logging.html
:日志打印规范: https://blog.csdn.net/liubenlong007/article/details/110262961

快速入门::

    import logging
    logging.basicConfig(level=logging.INFO)
    logging.info('Hello World')

.. seealso::

    * 应用案例1: ``imapclient(v2.2.0)`` 库。 imapclient.py line:44。
    * 应用案例2 ``core`` 库

**初始化basicConfig配置**

logging.basicConfig只在第一次调用的时候生效。
basicConfig函数是通过logging.root.handles的元素数量来判断是否第一次调用::

    logging.basicConfig(level=logging.INFO)

    # 重置配置
    # 日志级别改为默认值
    logging.root.setLevel(logging.WARNING)
    logging.root.handlers.clear()

    # 重新设置
    logging.basicConfig(level=logging.ERROR)

**getLogger**

.. code-block:: python
    :linenos:
    :emphasize-lines: 4-7

    import logging

    logger = logging.getLogger(__name__)
    h = logging.StreamHandler()
    h.setFormatter(logging.Formatter("%(asctime)s - %(levelname)s - %(module)s:%(funcName)s - %(message)s"))
    logger.addHandler(h)
    logger.setLevel(logging.INFO)
    logger.info("message")

如果这个代码文件有可能是作为启动入口的位置，那就应该加上4-7行代码，作为第一次设置日志配置

logger.setLevel应该跟logger.addHandler搭配使用，只调用setLevel是没有效果的。

基础
=======================

* [便利函数](#便利函数)
* [记录日志到文件](#记录日志到文件)
* [日志级别](#日志级别)
* 其他

进阶
=======================

* [记录器](#Logger)(暴露了应用程序代码直接使用的接口)
* [处理程序Handler](#处理程序)(将日志记录发送到适当的目标)
   - SMTPHandler日志发送邮件
* 格式化程序Formatter(指定最终输出中日志记录的样式)
* 过滤器(提供更精细的附加功能，用于确定要输出的日志记录)
* 配置日志记录
* LogRecord属性

--------------------------------

记录日志到文件
=======================

.. code-block:: python

    import logging
    logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG,
                        format=' %(asctime)s - %(levelname)s- %(message)s',
                        datefmt='%m%d%Y%I:%M%S%p')
    logging.debug('This message should go to the log file')
    logging.info('So should this')
    logging.warning('And this, too')
    logging.error('And non-ASCII stuff, too, like Øresund and Malmö')


对 basicConfig() 的调用应该在 debug() ， info() 等的前面。因为它被设计为一次性的配置，只有第一次调用会进行操作，随后的调用不会产生有效操作。

如果多次运行上述脚本，则连续运行的消息将追加到文件 example.log 。 如果你希望每次运行重新开始，而不是记住先前运行的消息，则可以通过将上例中的调用更改为来指定 filemode 参数::

    import logging
    logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)

禁用日志
====================

logging.disble()函数禁用了这些消息，这样就不必进入到程序中，手工删除所有日的日志调用。
只要向logging.disble()传入一个日志级别，它就会禁止该级别和更低级别的所有日志消息。所以，如果想
要禁用所有日志，只要在程序中添加logging.disable(logging.CRITICAL)。

记录器
==========================

创建
--------------------------

.. code-block:: python

    import logging
    logger = logging.getLogger('name')

.. warning::

    直接实例化: ``logger = logging.Logger('name')`` 是错误的做法

配置
---------------

* Logger.setLevel()指定记录器将处理的最低严重性日志消息。
* Logger.addHandler()和Logger.removeHandler()从记录器对象中添加和删除处理程序对象。
* Logger.addFilter()和Logger.removeFilter()可以添加或移除记录器对象中的过滤器。

处理程序Handler
------------------------

SMTPHandler
------------------------

该实例使用电子邮件的发件人、收件人地址和主题行进行初始化。 toaddrs 应当为字符串列表。 要指定一个非标准 SMTP 端口，请使用 (host, port) 元组格式作为 mailhost 参数。 如果你使用一个字符串，则会使用标准 SMTP 端口。 如果你的 SMTP 服务器要求验证，你可以指定一个 (username, password) 元组作为 credentials 参数。

要指定使用安全协议 (TLS)，请传入一个元组作为 secure 参数。 这将仅在提供了验证凭据时才能被使用。 元组应当或是一个空元组，或是一个包含密钥文件名的单值元组，或是一个包含密钥文件和证书文件的 2 值元组。 （此元组会被传给 smtplib.SMTP.starttls() 方法。）::

    import logging
    import logging.handlers

    logger = logging.Logger('email')

    logger.setLevel(logging.WARNING)

    eh = logging.handlers.SMTPHandler(mailhost=('smtp.exmail.qq.com',587),
                                      fromaddr='username',toaddrs=['username'],
                                      subject = 'logging测试',credentials= ('username','pwd'),
                                      secure =tuple(),timeout=300)

    # 处理程序处理级别
    eh.setLevel(logging.ERROR)
    logger.addHandler(eh)

    logger.warning('警告消息1')

    # 发送邮件
    logger.error('错误消息1')
    # 发送第二封邮件
    logger.error('错误消息2')

Django配置日志
================================

.. code-block:: python

    LOGGING = {
        'version': 1,
        'disable_existing_loggers': False,
        'handlers': {
            'console': {
                'class': 'logging.StreamHandler',
            },
        },
        # 根日志器的配置。
        'root': {
            'handlers': ['console'],
            'level': 'WARNING',
        },
        'loggers': {
            'django': {
                'handlers': ['console'],
                'level': os.getenv('DJANGO_LOG_LEVEL', 'INFO'),
                # 是否广播给父日志器, 默认为广播到logger.root, root的配置的效果被触发。
                'propagate': False,
            },
        },
    }