@loggo：Python 3 自动化记录

版本 8.1.0

您觉得 Python 内置的 logging 模块重复、繁琐且难看，而且您用它写的日志与您的其他风格不一致。 loggo 就是为了帮助您：它自动处理无聊的事情，简化复杂的事情，可以轻松连接到 graylog，并在需要时保护隐私和安全。

安装

pip install loggo
# or
python setup.py install

要使用 Graylog 支持，请执行以下操作

pip install loggo[graylog]

设置

要开始，导入并实例化主类，最好是在您项目的核心部分。如果您有一个包含多个文件的模块，请在主 __init__.py 或名为 log.py 的文件中进行初始配置，这样您可以轻松导入已设置的日志记录器。

例如，如果您的应用程序名为 tester，您可以在 tester/__init__.py 中添加以下内容

from loggo import Loggo

# all setup values are optional
loggo = Loggo(
    facility="tester",  # name of program logging the message
    graylog_address=("0.0.0.0", 9999),  # address for graylog (ip, port)
    do_print=True,  # print each log to console
    do_write=True,  # write each log to file
    logfile="mylog.txt",  # custom path to logfile
    truncation=1000,  # longest possible value in extra data
    private_data={"password"},  # set of sensitive args/kwargs
)

用法

在其他项目部分，您可以使用以下方式访问配置的日志记录器实例

from tester import loggo

Loggo 作为装饰器

您可以在任何可调用对象上使用 @loggo 作为装饰器：类、其方法或函数。在类上，它将记录每个方法；在方法和函数上，它将记录调用签名、返回值和错误。loggo 的核心思想是您可以简单地装饰您项目中的每个类以及任何重要的独立函数，而无需任何额外的工作，即可获得关于项目内部的综合、标准化的信息。

如果装饰类中的方法调用过于频繁，或者您不需要关注它，您可以使用 @loggo.ignore 来忽略它。还有 @loggo.errors，它将只记录异常，而不是调用和返回。

让我们通过一个简单的示例来演示其用法：创建一个简单的类，该类仅当提供密码时才将两个数字相乘。我们将忽略无聊的认证系统的记录。

@loggo
class Multiplier:
    def __init__(self, base):
        self.base = base

    def multiply(self, n, password):
        """
        Multiply by the number given during initialisation--requires password
        """
        self.authenticated = self._do_authentication(password)
        if not self.authenticated:
            raise ValueError("Not authenticated!")
        return self.base * n

    @loggo.ignore
    def _do_authentication(self, password):
        """Not exactly Fort Knox"""
        return password == "tOpSeCrEt"

首先，让我们正确使用它，并传入我们的秘密密码

mult = Multiplier(50)
result = mult.multiply(50, "tOpSeCrEt")
assert result == 2500  # True

我们将在控制台中获得一些漂亮的文本

11.05 2018 17:14:54 *Called Multiplier.multiply(n=50, password='******')
11.05 2018 17:14:54 *Returned from Multiplier.multiply(n=50, password='******') with int (2500)

请注意，我们的私有参数 password 已成功隐藏，即使我们在调用方法时没有命名该参数。如果您使用了 do_write=True，此日志也将出现在您指定的日志文件中，并且密码也将被隐藏。

result = mult.multiply(7, "password123")

这里将引发错误，将生成日志，我们将在控制台中获取额外的信息，包括跟踪信息

11.05 2018 17:19:43 *Called Multiplier.multiply(n=7, password='******')
11.05 2018 17:19:43 *Errored during Multiplier.multiply(n=7, password='******') with ValueError "Not authenticated!"    20 -- see below:
Traceback (most recent call last):
  File "/Users/danny/work/loggo/loggo/loggo.py", line 137, in full_decoration
    response = function(*args, **kwargs)
  File "tester.py", line 13, in multiply
    raise ValueError('Not authenticated!')
ValueError: Not authenticated!

如果您使用 graypy，您将获得许多额外的功能，例如调用签名的键值对、时间戳、参数、返回值、异常信息等。

自定义消息

在配置 loggo 时，您可以使用自己的消息格式来自动生成的日志。有四个键，每个自动记录类型一个

loggo = Loggo(
    called="Log before callable is run",
    returned="Log for return from {call_signature} at {timestamp}",
    returned_none="Log when the return value of the callable is None",
    errored="Log string on exception: {exception_type}",
)


@loggo
def test():
    pass

如果您为这些关键字段中的任何一个传递 None，则将完全抑制该时间段的日志。如果您没有为 returned_none 提供值，则 loggo 将使用您为 returned 提供的值，或者回退到其默认值。

请注意，在上面的示例中，您可以在日志消息中包含特定的格式字符串。目前支持以下格式

• call_signature：可调用名称及其参数和关键字参数
• callable：装饰对象的__qualname__
• params：传递参数的逗号分隔键值对
• log_level：与该日志关联的日志级别
• timestamp：记录日志的时间
• couplet：调用和返回/错误对的uuid.uuid1()
• number_of_params：总参数数args + kwargs作为整型
• private_keys：已识别的私有参数名称列表
• decorated：始终为True

errored日志还支持

• exception_type：ValueError、AttributeError等
• exception_msg：抛出异常的详细信息
• traceback：异常堆栈跟踪

returned和returned_none日志支持

• return_value：可调用返回的对象
• return_type：返回对象的类型

添加更多此类字符串很简单；如果有其他需要，请提交问题。

无装饰器日志记录

对于手动日志记录，loggo提供了类似于logging标准库中日志记录函数的方法：loggo.log、loggo.debug、loggo.info、loggo.warning、loggo.error和loggo.critical。这些方法使用已定义的配置。主要方法loggo.log接受三个参数

level = 50
msg = "Message to log"
extra = dict(some="data", that="will", be="logged")
loggo.log(level, msg, extra)
# console: 11.05 2018 17:36:24 Message to log  50
# extra_data in log file if `do_print` setting is True

loggo.debug、loggo.info、loggo.warning、loggo.error和loggo.critical是设置日志级别的便利方法。例如，

loggo.warning("A message", dict(some="data"))

等同于

loggo.log(logging.WARNING, "A message", dict(some="data"))

其中logging.WARNING是从标准库导入的整数常量。

使用loggo进行此类日志记录的优势在于loggo将使额外数据更易于阅读，并截断非常长的字符串。更重要的是，您仍然会获得您已配置的任何额外内容，例如私有数据的混淆或写入控制台/文件。

方法

您还可以在代码的任何位置使用loggo.start()和loggo.stop()开始和停止日志记录，尽管默认情况下，错误日志仍然会通过。如果您还想抑制错误，可以传递allow_errors=False。

上下文管理器

您可以使用上下文管理器来抑制日志。默认情况下也允许错误

with loggo.pause(allow_errors=False):
    do_something()

贡献

风格

风格是Black，有以下例外和额外严格性

• 最大行长度为110
• 除非使用# type: ignore忽略，否则不应使用类型注释的注释语法。也就是说，这样写

  def hello() -> str:
      return_value: str = 'hello'
      return return_value
  

  而不是这样写

  def hello(): # type: () -> str
      return_value = 'hello'  # type: str
      return return_value
  

制作拉取请求

问题、功能请求和代码贡献都受到欢迎。按照以下步骤制作拉取请求

1. 分叉/克隆存储库。

2. 安装依赖关系（您可能首先需要创建一个虚拟环境，使用您首选的方法）。

   pip install -e .[dev]
   

3. 安装pre-commit钩子

   pre-commit install
   

4. 在修改并编写测试后，确保测试通过

   python -m unittest
   

5. 提交、推送并创建PR。

版本升级

loggo遵循语义版本控制，理想情况下通过bump2version实用程序。使用pip安装它

pip install bump2version

每次需要升级版本时，在项目根目录中执行

bump2version (major | minor | patch)
git push <remote> <branch> --follow-tags 

限制

loggo使用Python标准库（logging）生成日志。在使用它时有一些需要注意的地方：例如，在可以传递的额外数据方面，这些额外数据的键名不能与logging模块内部使用的某些内部名称冲突（message、args等）。为了解决这个问题，您将收到一个警告，指出您的数据包含一个不良的键名，并且它将被更改（即从message更改为protected_message）。