PyGHee

PyGHee（发音为"piggy"）是GitHub事件执行器，一个Python库，用于简化在Python中创建GitHub App以及处理GitHub事件（如拉取请求的创建、在问题中发布评论等）。

它负责：

• 详细记录所有事件活动；
• 以JSON格式记录所有传入事件；
• 验证传入事件以检查它们是否确实来自GitHub（请参阅验证来自GitHub的有效载荷）；
• 以易于消化的格式收集事件信息，使事件处理更加容易；
• 通过调用适当的 handle_*_event 方法处理事件（如果已实现）；

要求

PyGHee 依赖于一些Python库

• Flask，一个用于构建复杂Web应用的简单框架；
• PyGithub，一个用于访问GitHub REST API的Python库；
• waitress，一个生产级别的纯Python WSGI 服务器；

有关更具体的信息，如所需版本，请参阅requirements.txt。

此外

• 必须通过$GITHUB_TOKEN环境变量提供GitHub个人访问令牌(PAT)；
• GitHub应用密钥令牌必须通过$GITHUB_APP_SECRET_TOKEN环境变量可用，具体信息请参阅GitHub应用密钥令牌；

安装

PyGHee可在PyPI上找到，因此您可以使用pip（或任何其他标准Python包安装工具）进行安装。

pip3 install PyGHee

使用PyGHee

要使用PyGHee，您应该实现一个继承自pyghee.lib模块提供的PyGHee类的Python类，并实现一个或多个对应于您想要处理的的事件类型的handle_*_event方法。

事件类型的列表可在GitHub文档中找到。

每个handle_*_event方法都将一个包含事件信息的Python字典作为第一个参数传递。将PyGHee日志文件的路径指定为第二个命名参数log_file。

因此，如果存在一个名为example的事件类型，相应的实现方法应该为

from pyghee.lib import PyGHee

class ExamplePyGHee(PyGHee):

    def handle_example_event(self, event_info, log_file=None):
        # implementation of handling example event goes here

如果没有为特定事件类型实现handle_*_event方法，将记录一条消息以指示这一点。例如

[20220227-T17:06:35] WARNING: [event id e81030bc-238d-440f-b438-54ba902a2224] No handler found for event type 'issue_comment' (action: created) - event was received but left unhandled!

您的主要程序应使用create_app函数，并使用waitress提供服务

app = create_app(klass=ExamplePyGHee)
waitress.serve(app, listen='*:3000')

日志文件位置

PyGHee日志文件名为pyghee.log，位于GitHub应用启动的目录中，并且仅追加（如果已存在则不覆盖）。

事件日志的位置和结构

事件数据以JSON格式记录在名为events_log的目录中，该目录位于GitHub应用启动的目录中。

日志按事件类型、事件操作、日期（按此顺序）进行组织。

对于每个传入的事件，将创建两个JSON文件，一个用于

• 请求头，包括诸如事件发生的时间戳等高级信息。
• 请求体，包括实际的事件信息（这取决于事件类型）。

以下是一个已记录的单个事件的示例：2022年2月20日14:23:27创建的评论问题。

$ ls events_log/issue_comment/created/2022-02-20/
2022-02-20T14-23-27_d3ed7694-8a6c-4008-a93f-b92aa86a95a8_body.json
2022-02-20T14-23-27_d3ed7694-8a6c-4008-a93f-b92aa86a95a8_headers.json

示例

以下是使用PyGHee的示例。

将以下内容复制粘贴到名为pyghee_example.py的文件中

import waitress

from pyghee.lib import PyGHee, create_app
from pyghee.utils import log

class ExamplePyGHee(PyGHee):

    def handle_issue_comment_event(self, event_info, log_file=None):
        """
        Handle adding/removing of comment in issue or PR.
        """
        request_body = event_info['raw_request_body']
        issue_url = request_body['issue']['url']
        comment_author = request_body['comment']['user']['login']
        comment_txt = request_body['comment']['body']
        log("Comment posted in %s by @%s: %s" % (issue_url, comment_author, comment_txt))
        log("issue_comment event handled!", log_file=log_file)


if __name__ == '__main__':
    app = create_app(klass=ExamplePyGHee)
    log("App started!")
    waitress.serve(app, listen='*:3000')

运行您的GitHub应用

• 为GitHub个人访问令牌（PAT）和GitHub应用密钥令牌定义环境变量

  export GITHUB_TOKEN=...
  export GITHUB_APP_SECRET_TOKEN=...
  

• 启动您的GitHub应用

  python3 -m pyghee_example
  

您应该会看到一个名为pyghee.log的日志文件，该文件位于您的GitHub应用启动的目录中，其中包含类似的消息

[20220227-T18:54:49] App started!

测试套件

要运行测试套件，请使用pytest

pytest -v -s