记录便利例程。

最新版本 20220531：PfxFormatter.patch_formatter：请注意 record.args 是否不是元组并且不要尝试为其添加前缀（暂时）。

日志包非常有用，但使用起来有点痛苦。这个包提供了低影响的日志记录设置和一些非常有用的非常有用的日志记录上下文挂钩。

根据输出日志文件是否为 tty、是否设置了环境变量$DEBUG以及设置的内容，默认的日志记录详细程度输出格式具有不同的默认值。

在终端上，警告和错误会得到 ANSI 着色。

有一种模式可cs.upd用于某些日志级别。

通过该模块和朋友发送的日志消息warning会自动以当前cs.pfx前缀字符串作为前缀，从而提供自动消息上下文。

一些例子：

程序初始化：

from cs.logutils import setup_logging

def main(argv):
    cmd = os.path.basename(argv.pop(0))
    setup_logging(cmd)

来自任何地方的基本日志记录：

from cs.logutils import info, warning, error
[...]
def some_function(...):
    [...]
    error("nastiness found! bad value=%r", bad_value)

功能add_logfile(filename, logger=None, mode='a', encoding=None, delay=False, format=None, no_prefix=False)

将FileHandler日志记录添加到指定的filename; 返回选择的记录器和新的处理程序。

参数：

• logger: 如果提供而不提供None，则添加FileHandler到 that Logger，否则添加到根 Logger。如果logger是字符串，则调用 logging.getLogger(logger)以获取记录器。
• mode,encoding和delay: 传递给FileHandler 初始化程序。
• format：用于覆盖处理程序的默认格式。
• no_prefix：如果为真，则不要将Pfx上下文放在消息的前面。

功能critical(*a, **kw)

logging.CRITICAL在具有当前Pfx前缀的级别发出日志。

功能D(msg, *args)

sys.stderr如果 为真，则直接打印格式化的调试字符串D_mode，完全绕过日志记录模块。一个快速的调试工具。

功能debug(*a, **kw)

logging.DEBUG在具有当前Pfx前缀的级别发出日志。

功能error(*a, **kw)

logging.ERROR在具有当前Pfx前缀的级别发出日志。

功能exception(msg, *args, **kwargs)

发出带有当前Pfx前缀的异常日志。

功能ftrace(func)

__module__.DEBUG如果为真，则装饰器跟踪函数。

功能ifdebug()

测试loginfo.level反对logging.DEBUG。

功能ifverbose(*a, **kw)

有条件地记录一条消息。

如果is_verbose是None，则在VERBOSE级别记录并依赖日志记录设置。否则，如果is_verbose为真，则在INFO级别登录。

功能infer_logging_level(env_debug=None, environ=None, verbose=None)

从 推断日志级别env_debug，默认情况下来自环境变量$DEBUG。

通常默认为logging.WARNING，但如果sys.stderr是终端，则默认为logging.INFO.

将环境变量解析$DEBUG为逗号分隔的标志列表。

检查顺序标志以影响日志记录级别：

• 数字 < 1：logging.WARNING
• 数字 >= 1 且 < 2：logging.INFO
• 数字 >= 2：logging.DEBUG
• "DEBUG"：logging.DEBUG
• "STATUS"：STATUS
• "INFO"：logging.INFO
• "TRACK"：TRACK
• "WARNING"：logging.WARNING
• "ERROR"：logging.ERROR

返回具有以下属性的对象：

• .level: 日志级别。
• .flags: 所有的单词都$DEBUG用逗号隔开，大写。
• .module_names：要调试的模块名称。
• .function_names：要以module_name .func_name形式跟踪的函数。

功能info(*a, **kw)

logging.INFO在具有当前Pfx前缀的级别发出日志。

功能log(*a, **kw)

Pfx使用当前前缀在指定级别发出日志。

功能logException(exc_type, exc_value, exc_tb)

通过日志记录包装器替换sys.excepthook该报告。cs.logutils

班级LogTime

LogTime 是一个上下文管理器，用于记录所附代码的经过时间。运行后，字段 .elapsed 包含经过的时间（以秒为单位）。

方法LogTime.__init__(self, tag, *args, **kwargs)：设置一个 LogTime。

参数：

• tag: 包含在日志条目开头的标签
• args: 可选数组；如果不为空args，则应用于 tagwith%
• level: 关键字参数指定默认日志条目的日志级别，默认logging.INFO
• threshold: 关键字参数指定产生日志的最短时间，默认无（无最小值）
• warning_level: 关键字参数，指定警告日志条目的日志级别，默认logging.WARNING
• warning_threshold: 关键字参数指定将日志级别提升到的时间warning_level

功能logTo(filename, logger=None, mode='a', encoding=None, delay=False, format=None, no_prefix=False)

将FileHandler日志记录添加到指定的filename; 返回选择的记录器和新的处理程序。

参数：

• logger: 如果提供而不提供None，则添加FileHandler到 that Logger，否则添加到根 Logger。如果logger是字符串，则调用 logging.getLogger(logger)以获取记录器。
• mode,encoding和delay: 传递给FileHandler 初始化程序。
• format：用于覆盖处理程序的默认格式。
• no_prefix：如果为真，则不要将Pfx上下文放在消息的前面。

班级NullHandler(logging.Handler, logging.Filterer)

AHandler丢弃其请求。

班级PfxFormatter(logging.Formatter)

可以访问程序cmd和Pfx状态的 Formatter 子类。

方法PfxFormatter.__init__(self, fmt=None, datefmt=None, cmd=None)：初始化PfxFormatter.

参数：

• fmt: 格式模板，默认来自DEFAULT_PFX_FORMAT '%(asctime)s %(levelname)s %(pfx)s: %(message)s'. 传递到Formatter.__init__。
• datefmt: 传递到Formatter.__init__.
• cmd：可用于格式化字符串的“命令前缀”。如果未设置，cs.pfx.cmd则显示。

功能quiet(*a, **kw)

QUIET在具有当前Pfx前缀的级别发出日志。

功能setup_logging(cmd_name=None, main_log=None, format=None, level=None, flags=None, upd_mode=None, ansi_mode=None, trace_mode=None, module_names=None, function_names=None, verbose=None, supplant_root_logger=False)

为传统的 UNIX 命令行错误消息安排基本的日志记录设置；返回具有信息属性的对象。该对象也可用作 global cs.logutils.loginfo。

除其他外，默认记录器现在cs.pfx在消息中包含前缀。

此函数以两种模式运行：

• 如果尚未设置日志记录，则设置一个根记录器
• 如果根记录器已经有处理程序，猴子修补第一个处理程序的格式化程序以作为cs.pfx状态的前缀

参数：

• cmd_name: 程序名称，默认来自basename(sys.argv[0]). 副作用：设置cs.pfx.cmd为此值。
• main_log: 默认日志系统。如果None，主日志将转到sys.stderr；ifmain_log是一个字符串，它是否用作以附加模式打开的文件名；否则 main_log 应该是适合与logging.StreamHandler(). 生成的日志处理程序将添加到logging根记录器。
• format: 的消息格式main_log。如果None，则使用DEFAULT_PFX_FORMAT_TTY whenmain_log是 tty 或 FIFO，否则DEFAULT_PFX_FORMAT。
• level：main_log日志记录级别。如果None，则使用 推断环境级别infer_logging_level()。
• flags: 一个包含调试标志的字符串，用逗号分隔。如果None，则使用 . 从环境中推断标志 infer_logging_level()。以下标志具有含义： D：将 cs.logutils.D_mode 设置为 True； TDUMP：将信号处理程序附加到 SIGHUP 以进行线程堆栈转储； TRACE：启用各种嘈杂的追踪设施； UPD, NOUPD: 将默认值upd_mode分别设置为 True 或 False。
• upd_mode: 用于激活 cs.upd 作为main_log方法的布尔值；如果None，则将其设置为Trueif flagscontains 'UPD'，否则设置为Falseif flagscontains 'NOUPD'，否则将其设置为main_log.isatty()。true 值会导致根记录器cs.upd用于记录。
• ansi_mode: 如果None，则从 设置它main_log.isatty() and not cs.colourise.env_no_color()，从而尊重$NO_COLOR环境变量（有关约定，请参见https://no-color.org/）。真值会导致根记录器使用 ANSI 终端序列（当前仅在cs.upd使用时）为某些记录级别着色。
• trace_mode：如果是None，根据标志中是否存在“TRACE”进行设置。否则，如果trace_mode为真，则将全局设置loginfo.trace_level为loginfo.level; 否则默认为logging.DEBUG.
• verbose: if None, then if stderr is a tty 然后 log level 为INFOelse WARNING。否则，如果verbose为 true，则日志级别为INFOelse WARNING。

功能status(*a, **kw)

STATUS在具有当前Pfx前缀的级别发出日志。

功能trace(*a, **kw)

loginfo.trace_level使用当前Pfx前缀发出日志消息。

功能track(*a, **kw)

TRACK在具有当前Pfx前缀的级别发出日志。

功能upd(*a, **kw)

如果我们使用的是UpdHandler，请更新状态行，否则写一条信息消息。

请注意，这Upd.out直接调用msg%args ，因此不包括当前Pfx前缀。您可能希望改用该status()功能。

班级UpdHandler(logging.StreamHandler, logging.Handler, logging.Filterer)

一个StreamHandler子类，其.emit方法使用 acs.upd.Upd进行转录。

方法UpdHandler.__init__(self, strm=None, upd_level=None, ansi_mode=None, over_handler=None)：初始化UpdHandler.

参数：

• strm: 输出流，默认sys.stderr。
• upd_level：通过 . 更新状态行的神奇日志记录级别Upd。默认值：STATUS。
• ansi_mode: 如果None，从 设置strm.isatty()。真值使处理程序使用 ANSI 终端序列为某些日志记录级别着色。

功能verbose(*a, **kw)

VERBOSE在具有当前Pfx前缀的级别发出日志。

功能warning(*a, **kw)

logging.WARNING在具有当前Pfx前缀的级别发出日志。

功能with_log(filename, **kw)

上下文管理器Logger临时添加到输出日志。

发布日志

发布 20220531：PfxFormatter.patch_formatter：注意 record.args 是否不是元组并且不要尝试为其添加前缀（暂时）。

发布 20220530：

• TRACK 和 STATUS 之间的新 QUIET 日志级别，添加新的 quiet() 日志调用。
• PfxFormatter.patch_formatter：修复处理record.msg，record.args。

发布 20220315：防止双重修补格式化程序的一些技巧，例如当 BaseCommand 调用 BaseCommand 和其他情况下 setup_logging() 被多次调用。

发布 20220227：

• PfxFormatter：用于修改现有 Formatter 的新 patch_formatter() 静态方法。
• setup_logging：如果已经设置了日志记录，只需在第一个处理程序的格式化程序上使用 PfxFormatter.patch_formatter。

发布 20211208：文档字符串更新。

发布 20210721：UpdHandler.emit：对于新行发射消息，如果 Upd 被禁用，则回退到新的 .over_handler。

发布 20210718：setup_logging：新的 supplant_root_logger=False 参数来弹出现有的处理程序，典型使用 supplant_root_logger=sys.stderr.isatty()。

发布 20210306：

• ttys 的默认日志记录级别现在是 INFO，而不是 STATUS。
• 新的 VERBOSE 级别低于 INFO 但高于 DEBUG。
• infer_logging_level：如果未指定详细，则在 tty 上记录 = WARNING，否则为 TRACK，否则如果详细，则级别 = VERBOSE，否则为 WARNING。
• 在日志信息中包含 .verbose。
• 新的详细（）和 ifverbose（）。

发布 20201021：

• setup_logging：始终提供 loginfo.upd，如果 upd_mode 则为 main_handler.upd，否则为 Upd()。
• 异常（）：铅垂关键字参数。

发布 20200729：setup_logging：如果未指定 ansi_mode，则按照https://no-color.org/尊重 $NO_COLOR

发布 20200613：

• LogTime：在退出时设置 .end。
• UpdHandle.emit：修复消息着色逻辑。

发布 20200521：setup_logging：在 loginfo 中包含记录器（目前始终是根记录器）。

发布 20200519：错误修复 setup_logging：显然 LoggingProxy 没有编码

发布 20200518：

• 彻底删除 cs.obj.O，普遍被 types.SimpleNamespace 取代。
• 如果 stderr 是 tty 而不是 logging.INFO，则默认为记录级别 TRACK。
• 带有前导参数的新 ifverbose 函数verbose：如果为 None，则在 INFO 处记录，否则如果为 true，则在 TRACK 处记录，否则不记录。
• BREAKING：删除全局 logging_level 和 trace_level 变量，将其全部放在全局 loginfo 中。
• 将 STATUS 设置在 TRACK 下方，使其位于 INFO 上方而不是下方。
• cs.upd 消息的新 status() 函数。
• UpdHandler：将status_level视为特殊，直接进入Upd.out。
• 改进了现代 Python 上的源代码行背诵。
• 默认级别，如果 sys.stderr.isatty() 现在是 STATUS，而不是 TRACK。
• loginfo 初始化和设置 cs.pfx.cmd 的一些修复。

发布 20200229：

• 更新新的 Upd.without 上下文管理器。
• setup_logging：默认upd_mode为main_log.isatty()，以前为 False。
• Drop UpdHandler.upd 方法，被实例属性遮蔽，从未使用过。

发布 20190923：

• 新TRACK常数等于logging.INFO+5提供一个高于INFO
• （这似乎是不合理的嘈杂）和低于WARNING
• 跟踪显着事件的警告。
• track()匹配的新功能。

版本 20190220：对 upd_mode 的改进。

版本 20190103：文档更新。

发布 20190101：@contextmanager 使用的错误修复。

发布 20171030：最近模块重组的各种修复。其他小功能和清理。删除几个未使用的功能。

发布 20160828：在 DISTINFO 中使用“install_requires”而不是“requires”。

发布 20160827：

• Pfx：导入退出处理程序
• $DEBUG envvar 中接受的每个模块和每个函数的初步语法。
• 对 X() 的改进，添加 DP() 和 XP() 前缀风味。
• status() 函数更新终端状态行。
• 新的 X_via_tty 全局标志：将 X() 指向 tty 而不是 sys.stderr。
• 各种其他小的改进。

发布 20150118：元数据更新

版本 20150110：初始 PyPI 版本。