feat: port github sample to python (#79)

samples/github/README.md

@@ -3,14 +3,17 @@
 This [AutoKitteh](https://github.com/autokitteh/autokitteh) project
 demonstrates 2-way integration with [GitHub](https://github.com).
 
-The file [`program.star`](./program.star) implements multiple entry-point
+The file [`program.py`](./program.py) implements multiple entry-point
 functions that are triggered by various GitHub webhook events, which are
 defined in the [`autokitteh.yaml`](./autokitteh.yaml) manifest file. It also
 executes various GitHub API calls.
 
-The file [`workflow.star`](./workflow.star) demonstrates triggering GitHub
+The file [`workflow.py`](./workflow.py) demonstrates triggering GitHub
 Action workflows, and receiving workflow events.
 
+> [!NOTE]  
+> The `start_github_action` trigger is commented out in the [`autokitteh.yaml`](./autokitteh.yaml) manifest because it depends on a named workflow YAML file being available in the corresponding GitHub repository. For more information, refer to the function's docstring.
+
 GitHub API details:
 
 - [REST API reference](https://docs.github.com/en/rest)

samples/github/autokitteh.yaml

@@ -16,16 +16,21 @@ project:
       # Handle only new issue comments in this sample code
       # (FYI, the other options are "edited" and "deleted").
       filter: data.action == "created"
-      call: program.star:on_github_issue_comment
+      call: program.py:on_github_issue_comment
     - name: github_workflow_dispatch
       connection: github_conn
       event_type: workflow_dispatch
-      call: workflow.star:on_github_workflow_dispatch
+      call: workflow.py:on_github_workflow_dispatch
     - name: github_workflow_job
       connection: github_conn
       event_type: workflow_job
-      call: workflow.star:on_github_workflow_job
+      call: workflow.py:on_github_workflow_job
     - name: github_workflow_run
       connection: github_conn
       event_type: workflow_run
-      call: workflow.star:on_github_workflow_run
+      call: workflow.py:on_github_workflow_run
+    # Uncomment the following trigger:
+    # - name: github_push
+    #   connection: github_conn
+    #   event_type: push
+    #   call: workflow.py:start_github_action

samples/github/program.star → samples/github/program.py

@@ -6,39 +6,33 @@
 
 API details:
 - REST API referene: https://docs.github.com/en/rest
-- Go client API: https://pkg.go.dev/github.com/google/go-github/v57/github
-
-It also demonstrates using a custom builtin function (rand.intn) to generate
-random integer numbers (based on https://pkg.go.dev/math/rand#Rand.Intn).
+- PyGitHub library: https://pygithub.readthedocs.io/en/latest/index.html
 
 This program isn't meant to cover all available functions and events.
 It merely showcases a few illustrative, annotated, reusable examples.
-
-Starlark is a dialect of Python (see https://bazel.build/rules/language).
 """
 
-load("@github", "github_conn")
+import random
+
+from autokitteh.github import github_client
 
 # https://docs.github.com/en/rest/reactions/reactions#about-reactions
 REACTIONS = ["+1", "-1", "laugh", "confused", "heart", "hooray", "rocket", "eyes"]
 
-def on_github_issue_comment(data):
+
+def on_github_issue_comment(event):
     """https://docs.github.com/en/rest/overview/github-event-types#issuecommentevent
 
     Based on the filter in the "autokitteh.yaml" manifest file,
     handle only *new* issue comments in this sample code
     (FYI, the other options are "edited" and "deleted").
 
     Args:
-        data: GitHub event data.
+        event: GitHub event data.
     """
 
-    # Add to each new issue comment a random reaction emoji.
-    # rand.intn: https://pkg.go.dev/math/rand#Rand.Intn.
-    reaction = REACTIONS[rand.intn(len(REACTIONS))]
-    github_conn.create_reaction_for_issue_comment(
-        owner = data.repo.owner.login,
-        repo = data.repo.name,
-        id = data.comment.id,
-        content = reaction,
-    )
+    g = github_client("github_conn")
+    repo = g.get_repo(event.data.repo.full_name)
+    issue = repo.get_issue(event.data.issue.number)
+    comment = issue.get_comment(event.data.comment.id)
+    comment.create_reaction(random.choice(REACTIONS))

samples/github/workflow.py

@@ -0,0 +1,75 @@
+"""Trigger GitHub Action workflows, and receive workflow events."""
+
+from autokitteh.github import github_client
+
+
+def start_github_action(event):
+    """Start a GitHub action workflow.
+
+    See the following link for more information:
+    https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch
+
+    This function is preconfigured as the entry-point for an AutoKitteh trigger,
+    but it's currently commented out in the "autokitteh.yaml" file. To activate it,
+    uncomment the following lines:
+
+        # - name: github_push
+        #   connection: github_conn
+        #   event_type: push
+        #   call: workflow.py:start_github_action
+
+    Additionally, it requires a named workflow YAML file to be present in a relevant GitHub repository.
+
+    Example workflow YAML file (in the repo's ".github/workflows" directory):
+
+        on: workflow_dispatch
+        jobs:
+          job-name:
+            runs-on: ubuntu-latest
+            steps:
+              - run: echo "Do stuff"
+
+    Args:
+        event: GitHub event data (e.g. new pull request or push event).
+    """
+    repo = event.data.repo.full_name
+    # TODO: ENG-1631
+    ref = event.data.repo.default_branch  # Branch name or tag
+    workflow_file = "dispatch.yml"  # .github/workflows/dispatch.yml
+
+    g = github_client("github_conn")
+    workflow = g.get_repo(repo).get_workflow(workflow_file)
+
+    print("Triggering workflow:", workflow_file)
+    # https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event
+    workflow.create_dispatch(ref=ref)
+
+
+def on_github_workflow_dispatch(event):
+    """https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_dispatch
+
+    Args:
+        data: GitHub event data.
+    """
+    print("Workflow dispatch:", event.data.workflow)
+    print(event.data.inputs)
+
+
+def on_github_workflow_job(event):
+    """https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_job
+
+    Args:
+        data: GitHub event data.
+    """
+    print(f"Workflow job {event.data.action}: {event.data.workflow_job.name}")
+    print(event.data.workflow_job.htmlurl)
+
+
+def on_github_workflow_run(event):
+    """https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_run
+
+    Args:
+        data: GitHub event data.
+    """
+    print(f"Workflow run {event.data.action}: {event.data.workflow_run.name}")
+    print(event.data.workflow_run.htmlurl)