From 333da12f51a09733c6fe172edea697e60984246d Mon Sep 17 00:00:00 2001
From: Bruno Alla <browniebroke@users.noreply.github.com>
Date: Mon, 10 Aug 2020 18:30:36 +0100
Subject: [PATCH] Add docstrings to the update_contributors.py file

---
 scripts/update_contributors.py | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/scripts/update_contributors.py b/scripts/update_contributors.py
index cc22f33c..0f157595 100644
--- a/scripts/update_contributors.py
+++ b/scripts/update_contributors.py
@@ -8,6 +8,7 @@ CURRENT_FILE = Path(__file__)
 ROOT = CURRENT_FILE.parents[1]
 BOT_LOGINS = ["pyup-bot"]
 
+# Jinja template for CONTRIBUTORS.md
 CONTRIBUTORS_TEMPLATE = """
 # Contributors
 
@@ -69,9 +70,19 @@ guidance and advice.
 
 
 def main() -> None:
+    """
+    Script entry point.
+
+    1. Fetch recent contribtors from the Github API
+    2. Add missing ones to the JSON file
+    3. Generate Markdown from JSON file
+    """
+    # Use Github API to fetch recent authors rather than
+    # git CLI because we need to know their GH username
     gh = GitHub()
     recent_authors = set(gh.iter_recent_authors())
 
+    # Add missing users to the JSON file
     contrib_file = ContributorsJSONFile()
     for username in recent_authors:
         print(f"Checking if {username} should be added")
@@ -81,10 +92,13 @@ def main() -> None:
             print(f"Added {username} to contributors")
     contrib_file.save()
 
+    # Generate MD file from JSON file
     write_md_file(contrib_file.content)
 
 
 class GitHub:
+    """Small wrapper around Github REST API."""
+
     base_url = "https://api.github.com"
 
     def __init__(self) -> None:
@@ -107,29 +121,36 @@ class GitHub:
 
 
 class ContributorsJSONFile:
+    """Helper to interact with the JSON file."""
+
     file_path = ROOT / ".github" / "contributors.json"
     content = None
 
     def __init__(self) -> None:
+        """Read initial content."""
         self.content = json.loads(self.file_path.read_text())
 
     def __contains__(self, github_login: str):
+        """Provide a nice API to do: `username in file`."""
         return any(github_login == contrib["github_login"] for contrib in self.content)
 
     def add_contributor(self, user_data):
+        """Append the contributor data we care about at the end."""
         contributor_data = {
             "name": user_data["name"],
             "github_login": user_data["login"],
             "twitter_username": user_data["twitter_username"],
         }
-        self.content.extend(contributor_data)
+        self.content.append(contributor_data)
 
     def save(self):
+        """Write the file to disk with indentation."""
         text_content = json.dumps(self.content, indent=2, ensure_ascii=False)
         self.file_path.write_text(text_content)
 
 
 def write_md_file(contributors):
+    """Generate markdown file from Jinja template."""
     template = Template(CONTRIBUTORS_TEMPLATE, autoescape=True)
     core_contributors = [c for c in contributors if c.get("is_core", False)]
     other_contributors = (c for c in contributors if not c.get("is_core", False))