侧轨

Sidetrack提供了一个简单的接口，用于在 Python 程序中编写日志消息。对日志函数的调用可以留在你的代码中，让用户在现场生成调试日志；如果性能很重要，使用某些编码习惯并打开 Python 优化将导致日志语句被编译出来。

目录

• 介绍
• 安装
• 用法
• 获得帮助
• 贡献
• 执照
• 作者和历史
• 致谢

介绍

IDE 非常适合调试和跟踪代码的执行，但它们不能在所有情况下都使用。例如，如果您的代码在多台远程计算机上执行，或者您已经向普通用户发布了一个程序，并且您希望他们向您发送调试日志/执行跟踪，那么在运行时使用 IDE 可能是不切实际或不可能的。logging为这些情况制作的日志包；您可以在代码中插入日志语句，并使用输出来了解正在发生的事情以及用于软件遥测和其他目的。logging但是，如果您不需要它的所有功能，那么设置 Python或大多数类似的包是（恕我直言）复杂而冗长的。

Sidetrack（简单的调试错误跟踪包）提供了一个简单的API，可让您打开日志记录、设置输出目标（可以是标准输出），并log(f'my message and my {variable} value')在整个代码中使用。此外，它经过精心编写，因此如果您使用该选项运行 Python 并在调用log前加上. 这导致了以下使用 Sidetrack 的风格：-Ologif __debug__

...
for item in item_list:
    if __debug__: log(f'getting data for {item}')
    ...

当运行 with 时-O，循环中的log语句将不仅仅是一个无操作函数调用：Python 将完全丢弃条件块，就好像代码不存在一样。这是尽可能优化的，这意味着您不必担心使用log或评估其参数的性能成本。

安装

以下说明假设您的计算机上安装了 Python 解释器；如果不是这种情况，请先安装 Python 版本 3并熟悉在您的系统上运行 Python 程序。

在Linux、macOS和Windows操作系统上，您应该能够sidetrack使用pip. 要从Python 包存储库 (PyPI)sidetrack安装，请运行以下命令：

python3 -m pip install sidetrack

作为从PyPI获取它的替代方法，您可以使用直接从 GitHubpip安装，如下所示：sidetrack

python3 -m pip install git+https://github.com/caltechlibrary/sidetrack.git

用法

包中只有四个函数sidetrack：

• set_debug：打开/关闭登录，设置输出目的地，并配置选项
• log: 按原样记录消息。
• loglist：获取消息列表并单独记录它们，就好像log依次应用到每条消息一样。
• logf：记录带有可选参数的消息；消息字符串可以包含嵌入式format指令。

如何导入 Sidetrack

要利用 Python 的优化行为，请确保在 Python 内置符号上对 Sidetrack 函数的所有引用进行条件化__debug__。这包括 Sidetrack 的导入语句：

if __debug__:
    from sidetrack import set_debug, log, logf, loglist

log上面的片段说明了另一个技巧：在代码中尽可能短地调用函数， import set_debug, log, logf, 并loglist直接使用该from sidetrack ...方法而不是做一个 plain import sidetrack，这样你就可以编写log(...)而不是sidetrack.log(...). 相信我，你的手指和眼睛会感谢你的！

如何打开调试日志记录

要打开日志记录，请set_debug(...)在代码中至少调用一次。通常，如果与程序的命令行参数结合使用，这将最方便，以便可以在运行时启用或禁用调试跟踪。以下示例显示了基本用法。

if __debug__:
    if ...some condition of your choosing...:
        set_debug(True)
else:
    print('Python -O is in effect, so debug logging is not available.')

以上将打开调试日志并将输出发送到默认目标，即标准错误流 ( sys.stderr)。要将输出发送到不同的目的地，请使用可选的第二个参数debug_output，它可以是文件名、流或短划线符号 ( -)；后者表示目的地应该是默认值（即sys.stderr）。这是一个例子：

if __debug__:
    set_debug(True, dest = '/tmp/debug.txt')

该函数set_debug还接受另一个可选参数 ，show_package它使每个log、loglist和logfmessage 都以 Python 包的名称为前缀，该包包含使用对 log 函数的调用的源文件。当 Sidetrack 在多个包中使用时，这非常有用。

if __debug__:
    set_debug(True, show_package = True)

最后，该函数set_debug(...)还接受另一个可选参数 ，extra它允许您在每个输出行前面加上您选择的额外文本。extra文本字符串可以包含Python 日志记录系统 % 格式化字符串。例如，可以通过传递来插入进程 ID '%(process)d'，如下例所示：

if __debug__:
    set_debug(True, debug_output, extra = '%(process)d')

如果您的程序使用线程，您可能会发现使用extra = "%(threadName)s"很有帮助。

如何调用log, loglist, 和logf

该函数log是 Sidetrack 中最基本的函数。使用单个参数调用它，即要打印的消息：

if __debug__: log("I'm right here!")

如果要打印多个字符串，当然可以log连续调用多次，但在某些情况下，调用可能更方便loglist——尤其是如果字符串是动态生成的，如下例所示：

if __debug__: loglist(f'{var} = {value}' for var, value in settings())

最后，由于在运行时的评估方式或某些固有限制，有些情况下无法使用 f 字符串。对于这些情况，Sidetrack 提供了该logf功能。它接受一个参数、一个字符串和任意数量的可选参数。这是一个例子：

if __debug__: logf('exception (failure #{}): {}', failures, str(ex))

在内部，logf应用于format字符串并将任何剩余的参数作为参数传递给format. 换句话说，它本质上是以下伪代码：

def logf(msg, *other_args):
    final_text = msg.format(*other_args)
    write_log(final_text)

使用 时logf，请注意包含对可能在运行时扩展以包含对 Pythonformat命令具有特殊含义的字符的变量的引用，例如{字符。

了解输出

在所有情况下，输出的每一行都具有以下形式：

< package >额外  文件名：lineno   function() --消息

其中package和extra是可选的，分别由 toshow_package和参数控制，并且总是打印剩余的值：文件名、行号和调用 、 或的函数，以及消息。示例在下一节中显示。extraset_debug(...)logloglistlogf

使用 Sidetrack 的提示

在您的其余代码中，在有用的地方添加对日志函数的调用。这是一个简单的人为示例，取自Sidetrack 提供的演示程序：

if __debug__: log('=== demo program starting ===')

print('Looping my loopy loop:')
for i in range(0, 3):
    if __debug__: log(f'loop value {i}')
    print('Another go-around the loop')
print('Done looping.')

if __debug__: log('=== demo program stopping ===')

使用上面的代码，如果没有打开调试，或者程序在Python 优化打开的情况下运行，输出将是：

Looping my loopy loop:
Another go-around the loop
Another go-around the loop
Another go-around the loop
Done looping.

打开调试并将目标设置为-，输出变为：

demo_debug.py:32 main() -- === demo program starting ===
Looping my loopy loop:
demo_debug.py:36 main() -- loop value 0
Another go-around the loop
demo_debug.py:36 main() -- loop value 1
Another go-around the loop
demo_debug.py:36 main() -- loop value 2
Another go-around the loop
Done looping.
demo_debug.py:40 main() -- === demo program stopping ===

在处理更长和更复杂的程序时，能够将调试输出发送到文件变得很有用——它可以存储详细的跟踪，而不会像上面的示例中那样弄乱输出。文件输出对于已部署的代码也很有用：您可以将调试功能保留在代码中，并指示您的用户打开调试，并将输出定向到文件，然后将文件发送给您，以便您更轻松地调试问题。

如何运行演示程序

在tests子目录中，有一个简单的演示程序说明 Sidetrack 的使用。要运行它，在 Linux 和 macOS 系统上，您可以启动终端 shell 并运行以下命令：

python3 tests/demo_debug.py -h

要在启用调试日志记录的情况下运行它，请使用-d命令行选项（此示例中的输出为-，表示将输出发送到终端）：

python3 tests/demo_debug.py -d -

要查看 Python 优化处于活动状态时的差异，请将-O选项添加到 Python 解释器：

python3 -O tests/demo_debug.py -d -

获得帮助

如果您发现问题，请在此存储库的 GitHub 问题跟踪器中提交。

贡献

我们将很高兴收到您的帮助和参与以增强sidetrack！请访问指南以获取有关入门的一些提示。

执照

加州理工学院图书馆制作的软件版权所有 (C) 2020, Caltech。该软件在 BSD/MIT 类型许可下免费分发。请参阅许可证文件以获取更多信息。

作者和历史

我在实现Spiral时开发了此代码的第一个版本。从那时起，我基本上开始在我编写的每个 Python 软件包中使用该代码，首先是通过复制粘贴代码（最初非常短）并最终创建一个单文件模块（命名为debug.py）。这显然是一种次优方法。最后，在 2020 年，我决定是时候将其拆分为一个适当的自包含 Python 包了。

致谢

这项工作由加州理工学院图书馆资助。

带有换行符的文档的矢量图，用作此存储库的图标，是由名词项目的iconixar创建的。它根据知识共享CC-BY 3.0许可证获得许可。