feat: create a py scrip to automate project creations fix: #2026

  This script is expected to run either by dispatch or when a
  new open-release occur which it's name ends with '.1' It
  expects a TX_TOKEN to be exist when the script is triggered.
  This script is wont recreate a project if runs twice for same
  name release.
  The API calls is based on transifex API V3, doc can found at:
  https://developers.transifex.com/reference/api-introduction

Author: ghassanmas

.github/workflows/create-transifex-project.yml

@@ -0,0 +1,35 @@
+# GitHub Action for creating a transifex project when a release occurs
+
+name: "Create Transifex Project for the new release"
+
+on:
+  push:
+    tags:
+      - "open-release/*.1"
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  create_project:
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Check out the repo"
+        uses: "actions/checkout@v2"
+
+      - name: "Set up Python"
+        uses: "actions/setup-python@v2"
+        with:
+          python-version: "3.8"
+
+      - name: "Install requests"
+        run: pip install requests
+
+      - name : "Create Transifex project"
+        env:
+            TX_TOKEN: ${{ secrets.TX_TOKEN }}
+        run: |
+          python3 create_transifex_project.py ${{github.ref_name}} "$TX_TOKEN"
+          

create_transifex_project.py

@@ -0,0 +1,131 @@
+import sys
+import json
+import requests
+
+OPENEDX_ORG_ID = "open-edx"
+TRANSIFEX_API = "https://rest.api.transifex.com"
+
+
+def check_arguments_health():
+    """
+    Check the correctness of the expected arguments such as:
+    sys.argv[0]: Is not checked for and is suppose to be this file/script name.
+    sys.argv[1]: Is the open-release name, and is expected to start with 'open-release' and end with .1 
+    sys.argv[2]: Is the transifex token, and only checked that is not an empty string. If it's wrong, invalid, or expired...etc. It would be indicated by other function handle_request_error().
+    len(sys.argv): If the there was less or more than 3 arguments, it will fail.
+    And accordingly it would return:
+    returns True: If all good it will return True.
+    sys.exit('error message'): Whenever any of the checks above fails.
+    """
+    if len(sys.argv) < 3:
+        sys.exit("Too few arguments, we need release name followed by TX token")
+    elif len(sys.argv) > 3:
+        sys.exit("Too many arguments!")
+    else:
+        TX_TOKEN = sys.argv[2]
+        release_name = sys.argv[1]
+        if TX_TOKEN == "":  # Check that Transifex token is not null
+            sys.exit("Transifex token is empty. Job aborted")
+        if not (release_name.startswith("open-release") and release_name.endswith(".1")):
+            sys.exit(
+                "Aborted because: it's either not an open-release or not the first version of an open-release"
+            )
+        return True
+
+
+def convert_release_to_project_slug():
+    """
+    This is a simple function that takes release name in this format 'open-release/tictactoe.1' and return as 'openedx-documentation-tictactoe'. This is important to do because transifex doesn't support '/' for projects slug which has to be unique as well.
+    Return project slug: a project slug for the release.
+    """
+    release_name = sys.argv[1].split("/")[1].split(".")[0]
+    return f"openedx-documentation-{release_name}"
+
+
+def handle_request_error(response, context):
+    """
+    A helper function for handeling failed requests while trying to request something form transifex API. It handels the cases according to the API documentation:
+    401: It occurs when the token is invalid
+    403: It occur when the token is valid, but not with sufficient permission 
+    *: It would just print the status code and response body
+    """
+    code = response.status_code
+    if code == 401:
+        sys.exit(f"Unauthorized or invalid token! while trying to {context}.\n"
+                 f"More details: {response.text}")
+    elif code == 403:
+        sys.exit(f"TX token doesn't have the right permission for {context}.\n"
+                 f"More details: {response.text}")
+    else:
+        sys.exit(
+            f"Request for {context} returned with {code}.\n"
+            f"Detailed response: {response.text}"
+        )
+
+
+def is_project_exist():
+    """
+    This function given a release name, it will (or try) to get info about the project as if it was already created. And if transifex returns 404, then this means the project doesn't exist.
+    Return False: if a project for release doesn't exist in Transifex.
+    Exit 1: If status code is 200, i.e. (the project already exists). 
+    Otherwise it will forward the request to the helper function handle_request_error().
+    """
+    headers = {
+        "Accept": "application/vnd.api+json",
+        "Authorization": f"Bearer {sys.argv[2]}",
+    }
+    url = f"{TRANSIFEX_API}/projects/o:{OPENEDX_ORG_ID}:p:{convert_release_to_project_slug()}"
+    response = requests.get(url, headers=headers)
+    if response.status_code == 404:
+        return False
+    elif response.status_code == 200:
+        sys.exit(
+            f"Project with slug {convert_release_to_project_slug()}, already exist. Job aborted!."
+        )
+    else:
+        handle_request_error(response, context="getting a project detail")
+
+
+def create_transifex_project():
+    """
+    It tries to create a new transifex project, with configuration which can be altered, e.g. passing a new arg that indicate weather the project should machine translation, machine memory...etc. 
+    If the function succeed, (i.e. request to create project returned 200), it will exit the script with 0 code, and printing the url of the project. Otherwise it will forward the request to the helper function handle_request_error(). 
+    """
+    payload = {
+        "data": {
+            "attributes": {
+                "machine_translation_fillup": False,
+                "translation_memory_fillup": True,
+                "name": f"{convert_release_to_project_slug().replace('-',' ').title()}",
+                "private": False,
+                "slug": convert_release_to_project_slug(),
+                "repository_url": "https://github.com/openedx/edx-documentation"
+            },
+            "relationships": {
+                "organization": {
+                    "data": {"id": f"o:{OPENEDX_ORG_ID}", "type": "organizations"}
+                },
+                "source_language": {"data": {"id": "l:en_US", "type": "languages"}},
+            },
+            "type": "projects",
+        }
+    }
+    headers = {
+        "Accept": "application/vnd.api+json",
+        "Content-Type": "application/vnd.api+json",
+        "Authorization": f"Bearer {sys.argv[2]}",
+    }
+    url = f"{TRANSIFEX_API}/projects"
+    response = requests.post(url,headers=headers,json=payload)
+    if response.status_code == 200:
+        print(f"A transifex project for {sys.argv[1]}, has been successfully created! \n"
+        f"You can access the project at: https://www.transifex.com/{OPENEDX_ORG_ID}/{convert_release_to_project_slug()} \n"
+        f"Happy Translations!")
+        sys.exit(0)
+    else:
+        handle_request_error(response,f"Creating a project for {sys.argv[1]}")
+
+
+if __name__ == "__main__":
+    if check_arguments_health() and not is_project_exist():
+        create_transifex_project()