Skip to content
/ PyGHee Public

PyGHee (pronounced as "piggy") is the GitHub Event Executor, a Python library to facilitate creating a GitHub App implemented in Python to process events from GitHub.

License

Notifications You must be signed in to change notification settings

boegel/PyGHee

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

38 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PyGHee

PyGHee (pronounced as "piggy") is the GitHub Event Executor, a Python library to facilitate creating a GitHub App implemented in Python to process events from GitHub (like the creation of a pull request, a comment being posted in an issue, etc.).

It takes care of:

  • detailed logging of all event activity;
  • logging all incoming events in JSON format;
  • verifying incoming events to check whether they're indeed coming from GitHub (see also Validating payloads from GitHub);
  • collecting event information in an easy to digest format to make processing of events easier;
  • handling events by calling the appropriate handle_*_event method (if it is implemented);

Requirements

PyGHee depends on a couple of Python libraries:

For more specific information, like required versions, see requirements.txt.

In addition:

Installation

PyGHee is available on PyPI, so you can install it with pip (or another standard Python package installation tool):

pip3 install PyGHee

Using PyGHee

To use PyGHee, you should implement a Python class that derives from the PyGHee class that is provided by the pyghee.lib module, and implement one or more handle_*_event methods that correspond to the types of events you want to act on.

A list of event types is available in the GitHub documentation.

Each handle_*_event is passed a Python dictionary as first argument that contains event information. The location of the PyGHee log file is specified as a second named argument log_file.

So if there would be an event type named example, the corresponding method should be implemented as:

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

If no handle_*_event method is implemented for a particular event type, a message is logged to signal this. For example:

[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!

Your main program should use the create_app function and serve it using waitress:

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

Location of log file

The PyGHee log file is named pyghee.log is located in the directory where the GitHub App is started, and is only appended (not overwritten if it already existed).

Location and structure of event logs

Event data is logged in JSON format in a directory named events_log that is located in the directory where the GitHub App is started.

The logs are organised hierarchically, by event type, event action, date (in that order).

For each incoming event, two JSON files are created, one for:

  • the request headers including high-level information like the timestamp on which the event occured, etc.
  • the request body including the actual event information (which depends on the event type).

Here's an example of a single event that got logged: an issue commented that was created on 20 Feb 2022 at 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

Example

Here's an example of how to use PyGHee.

Copy-paste this into a file named 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')

To run your GitHub App:

You should see a log file named pyghee.log that is created in the directory where your GitHub App was started from, which includes a message like:

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

Test suite

To run the test suite, use pytest:

pytest -v -s

About

PyGHee (pronounced as "piggy") is the GitHub Event Executor, a Python library to facilitate creating a GitHub App implemented in Python to process events from GitHub.

Resources

License

Stars

Watchers

Forks