stacklog

堆栈日志消息

• 文档: https://micahjsmith.github.io/stacklog
• 主页: https://github.com/micahjsmith/stacklog

概述

Stacklog是一个小巧的Python库，用于堆叠日志消息。

堆栈结构的日志是一种日志方法，其中日志消息（概念上）被推入堆栈，并且仅在相应的块返回时才发出。Stacklog提供了一个名为stacklog的单个方法，它可以作为装饰器或上下文管理器。这在小型项目或一次性脚本中非常有用。

以下是一个示例来最好地说明这一点

with stacklog(print, 'Running some code'):
    with stacklog(print, 'Running some other code'):
        pass

这将产生以下日志输出

Running some code...
Running some other code...
Running some other code...DONE
Running some code...DONE

当堆栈日志上下文中的代码完成时，提供的消息将与返回状态一起回显，返回状态为DONE或FAILURE。就是这样。通过回调提供自定义和高级功能。

安装

stacklog已在Python 2.7和3.5+上进行开发和测试。

pip install stacklog

快速入门

您有多经常在Python中使用以下日志反模式？

import logging

def a():
    logging.info('Running a')
    do_something()
    logging.info('Done with a')

def b():
    logging.info('Running b')
    a()
    logging.info('Done with b')

try:
    b()
except:
    logging.info('There was an error running b')

这里的意图是记录过程调用的开始和结束，用于调试或用户监控。我将其称为反模式，因为

• 它需要在入口/出口点手动编写/更新日志调用，需要过多的关注
• 它导致了冗余的异常处理逻辑
• 如果发生错误，生成的日志消息可能会产生误导

相反，stacklog采用的方法是仅使用装饰器和上下文管理器来完成这项任务。

作为装饰器的使用

以下是将stacklog作为装饰器使用的示例

@stacklog(logging.info, 'Running a')
def a():
    raise Exception

@stacklog(logging.info, 'Running b')
def b():
    a()

b()

这将生成日志输出

INFO:root:Running b...
INFO:root:Running a...
INFO:root:Running a...FAILURE
INFO:root:Running b...FAILURE

作为上下文管理器的使用

以下是将stacklog作为上下文管理器使用的另一个示例

>>> with stacklog(logging.info, 'Running some code'):
...     do_something()
...
INFO:root:Running some code...
INFO:root:Running some code...DONE

高级使用

提供自定义条件

条件 是一个元组 异常, 状态。如果在提供的代码执行期间抛出了提供的异常，则记录提供的状态而不是默认的 失败。

>>> with stacklog(logging.info, 'Running some code', conditions=[(NotImplementedError,
'SKIPPED')]):
...     raise NotImplementedError
...
INFO:root:Running some code...
INFO:root:Running some code...SKIPPED

使用回调进行自定义

通过回调，stacklog 的行为可以完全自定义。

回调主要会做的是调用传递给 stacklog 实例的 log 方法，并附加一些自定义后缀。

首先，有三个回调用于自定义块开始、块成功完成和块失败时的日志行为。每次只能为这些事件注册一个函数。

• on_begin(func: stacklog -> None)
• on_success(func: stacklog -> None)
• on_failure(func: stacklog -> None)

其次，可以通过传递一对函数来自定义给定不同可能抛出的异常时的失败行为，第一个函数匹配在块执行期间抛出的异常，第二个函数响应异常。可以注册多个函数对，但在多个函数匹配的情况下，只会执行最后注册的函数。

• on_condition(match: *exc_info -> bool, func: stacklog, *exc_info -> None)

第三，可以在块执行前后初始化和销毁资源。这对于启动/停止计时器等操作很有用。可以注册多个函数，并且它们都将被执行。

• on_enter(func: stacklog -> None)
• on_exit(func: stacklog -> None)

查看 stacktime 的实现以获取示例。

添加计时信息

可以通过回调自定义 stacklog，例如，添加关于块执行持续时间的详细信息。这作为库本身的一部分提供，作为 stacktime 装饰器/上下文管理器。它的使用方式与 stacklog 相同，只是在块成功完成时还会记录计时信息。

>>> with stacktime(print, 'Running some code', unit='ms'):
...     time.sleep(1e-2)
...
Running some code...
Running some code...DONE in 11.11 ms

历史记录

2.0.2 (2024-07-29)

• 使用 poetry 和 pyproject.toml 进行所有配置

2.0.1 (2024-07-29)

• 将一些 py3 兼容性代码移入导入保护中

2.0 (2024-07-26)

• 停止对 python 2 的支持
• 停止对 python 3.5、3.6 和 3.7 的支持
• 添加类型注解
• 将 stacktime 重新实现为子类

1.1 (2020-03-19)

• 重构以使用回调
• 实现了 stacktime

1.0 (2019-12-10)

初始发布。