---- 带有动态缩进格式的自定义 logging 机制的输出效果：
* 设计目标:
---- 使用 Python 自带的 logging 模块可以很方便地让程序输出 logging 信息，而当程序比较复杂，尤其是使用了多线程以后，如果 logging 信息本身的格式也能反映出这些程序结构，分析起来就会比较方便：
---- 比如:
我的程序中有个下载模块 Downloader, 在运行时负责为程序的其它部分提供指定内容的下载服务，算是顶级模块。这个模块的直属成员函数所输出的 logging 信息应该使用 0 级缩进格式。
Downloader 下面有若干个 DownloadServer（服务器）对象，每个服务器对象负责处理特定的一批下载任务，这些 DownloadServer 对象输出的信息应该使用 1 级缩进格式。
在执行下载任务的时候，每个 DownloadServer 对象下面又有一批下载任务对象，这些具体的任务对象输出的信息应该使用 2 级缩进格式。
---- 又比如:
程序的总体运行过程是一个个任务对象的执行过程，这些对象根据用户实时的输入而建立并执行，在执行完毕后销毁，留下执行结果。这些顶级的 Task 对象在运行时拥有自己的主控线程，并且有自己专属的 log 文件。Task 对象大部分时间在自己的线程里运行，但是当中间需要下载一些数据的时候，它会通知 Downloader 模块建立相应的下载任务对象，并且在下载过程中，切换到属于 Downloader 模块的线程里运行。而下载的过程中所产生的 logging 信息，就需要同时写入到 Downloader 模块的 log 文件和 Task 对象专属的 log 文件里，并且可能要在相同内容的基础上采用不同的缩进格式，因为下载任务对于 Downloader 模块和对于 Task 对象来说，可能具有不一样的逻辑等级。
---- 要实现这些功能，就需要通过自定义类型，对标准的 logging 模块的特性做一些扩展
* Python 标准的 logging 机制
---- Python 标准的 logging 机制基本上由三种不同等级的对象构成:
[1] Logger 对象，主要向用户提供 logging 的界面函数: Logger.debug(), Logger.error(), Logger.warning() ... 这些函数的参数就是要记录的字串，用户通过调用这些函数来输出 logging 信息。
[2] Handler 对象，是 Logger 对象的成员，主要用来指定 logging 的目标（一般是个 log 文件），一个 Handler 指定一个目标。用 Logger.addHandler() 可以向 Logger 对象中添加 Handler。如果一个 logging 信息需要写入多个不同的目标，那么就要向相关的 Logger 对象中添加多个 Handler。
[3] Formatter 对象，是 Handler 对象的成员，内部包含字符串模板，用来控制写入相关 Handler 指定目标的消息的格式。一个 Handler 只包含一个 Formatter。
---- logging 机制的使用可以很灵活。对较小的程序来说，可以整个程序使用一个 Logger 和一个 Handler。对于较复杂的程序来说，可以每个模块拥有自己的 Logger 和 Handler，一个动态建立的任务也可以拥有自己的 Logger 和 Handler。当任务执行到某阶段需要切换到 A 模块的线程里运行时，可以把自身的 Handler 加入 A 模块的 Logger，这样执行过程中产生的信息会同时写入 A 模块的 log 文件和任务自身专属的 log 文件。在 A 模块中执行结束后，可以把 Handler 从 A 模块的 Logger 中移走。下一阶段在 B 模块的线程中运行时，也可以做同样处理。
---- 另外需要专门提到的是，所有的 logging 界面函数（debug(), warning(), error() ...）都可以接受一个 extra 参数，类型是 dict。这个参数可以在相同 log 内容的基础上，向不同的 Handler 提供不同的附加信息。比如，现在已经建立了下面这样的 logging 结构:
Logger_A:
|
├───── Handler_A:
| |
| └───── Formatter_A: "%(aaa)s %(message)s"
|
└───── Handler_B:
|
└───── Formatter_B: "%(bbb)s %(message)s"
注意，两个 Handler 下面的 Formatter 使用了不同的格式模板，Formatter_A 里面包含域 "aaa"，而 Formatter_B 里面包含域 "bbb"。
如果用户这样调用 Logger_A 的界面函数：
Logger_A.debug('blah blah blah ...', extra={'aaa':'xxxxxxx', 'bbb':'yyyyyyy'})
那么，写入 Handler_A 所指定目标的消息会是这样：
'xxxxxxx blah blah blah ...'
而写入 Handler_B 指定目标的消息会是这样：
'yyyyyyy blah blah blah ...'
---- 使用上面所说的这种机制，就可以在相同的 logging 内容基础上使用不同的缩进格式。
* 增强的 logging 机制的设计
---- 下面是在 Python 标准的 Logger 和 Handler 对象的基础上所定义的增强的 IndentLogger 和 IndentHandler。
1 # -*- coding: utf-8 -*-
2
3 import logging
4 import logging.handlers
5
6
7 class IndentHandler:
8
9 def __init__(self, file, idtname): # 如果本类的多个实例要加入一个 IndentLogger 里，那么这些实例的 idtname 不能冲突。
10
11 self._handler= logging.handlers.RotatingFileHandler(filename=file, mode='a', encoding='utf-8')
12
13 self._idtname= idtname # indent name, 作为 format string 内的 field，同时也是 extra 参数里的 key。
14 self._idtstr= "" # indent string，由 '\t' 组成，反映了写入此 Handler 相关目标的消息的缩进等级
15
16 self._format= "%(asctime)s %(name)-12s %(levelname)-8s>> %(" + self._idtname + ")s%(message)s"
17 # self._format= "%(asctime)s %(levelname)-8s>> %(" + self._idtname + ")s%(message)s"
18 self._formatter= logging.Formatter(self._format)
19
20 self._handler.setFormatter(self._formatter)
21
22 def set_indent_level(self, ilevel):
23 '''
24 将本对象的缩进等级重设一下。
25 '''
26 self._idtstr= '\t' * ilevel
27
28 class IndentLogger:
29 '''
30 接受 IndentHandler 实例作为成员，IndentHandler 实例包含了写入相关目标的消息的缩进信息。
31 '''
32
33 def __init__(self, name, level):
34
35 self._logger= logging.getLogger(name)
36 self._logger.setLevel(level)
37
38 self._ihandlers= [] # 所有在本实例注册过的 IndentHandler 实例组成的 list
39
40 def addIndentHandler(self, ihandler):
41
42 self._ihandlers.append(ihandler)
43 self._logger.addHandler(ihandler._handler)
44
45 def removeIndentHandler(self, ihandler):
46
47 self._ihandlers.remove(ihandler)
48 self._logger.removeHandler(ihandler._handler)
49
50
51
52 def critical(self, message, *pargs):
53 extra= {h._idtname: h._idtstr for h in self._ihandlers}
54 for arg in pargs: # arg[0] 是 IndentHandler 对象，arg[1] 是针对此对象在这个消息中使用的缩进等级
55 extra[arg[0]._idtname]= '\t' * arg[1] # 注意，不改变 self._ihandlers[n]._idtstr 的值
56
57 self._logger.critical(message, extra=extra)
58
59 # 注意，其余的界面函数与 critical() 形式完全一样，只是名字不同。
---- 这里主要有下面几个考虑：
[1] IndentHandler._idtstr 只是一个默认的缩进等级，在调用界面函数未指定 *pargs 的情况下会使用，一般是供顶级模块的直属成员用的。而 IndentHandler.set_indent_level() 是供初始化时用的，平时不需要动态设定缩进等级。
[2] 界面函数的 *pargs 参数形式是这样：
((ihandler_A, ilevel_A), (ihandler_B, ilevel_B), ...)
其中 ihandler 是 IndentHandler 对象，ilevel 是 int 类型的缩进等级，顶级模块是 0 级。含义是：针对这个 IndentLogger 下面的 IndentHandler 对象 ihandler_A 使用缩进等级 ilevel_A，针对 ihandler_B 使用缩进等级 ilevel_B ...
pargs 里需要指定 IndentHandler 对象是因为 IndentLogger 里面可能包含多个 IndentHandler，而设计 pargs 参数本身主要是为了使用起来方便。因为一个顶级模块下面所有不同等级的成员都要使用同一个 IndentLogger，而在执行过程中动态调整缩进等级（通过 IndentHandler.set_indent_level() 函数）不如让这些成员自带缩进等级信息，然后在输出 logging 信息时通过 pargs 参数传递给 IndentLogger。
