Documentation for the script

Avatars/Current Gravatar/fetch.py

@@ -1,30 +1,94 @@
-# Script to grab the current Gravatar image for a given email address
+"""
+Script to grab the current Gravatar image for a given email address and save it in multiple sizes and formats.
+
+Functions:
+    hash_email(email: str) -> str:
+        Hashes the email address using SHA-256 and returns the hexadecimal digest.
+
+    fetch_gravatar(email: str, size: int = 1000, rating: str = "g") -> bytes:
+        Fetches the Gravatar image for the given email address, size, and rating.
+        Returns the image content as bytes.
+
+    save_gravatar(email: str, size: int = 1000, rating: str = "g") -> None:
+        Saves the Gravatar image for the given email address, size, and rating to a PNG file.
+
+    convert_to_webp(size: int = 1000) -> None:
+        Converts the saved PNG Gravatar image to WebP format.
+
+    variety_of_sizes(email: str, sizes: list = [1000, 1500, 800, 300, 200, 150, 100]) -> None:
+        Fetches and saves Gravatar images in multiple sizes and converts them to WebP format.
+
+Usage:
+    Run the script with an email address as a command-line argument to fetch and save Gravatar images in multiple sizes and formats.
+"""
+
 import hashlib
 import requests
 import sys
 from PIL import Image
 
-# allow script to receive an argument
+# Allow script to receive an argument
 email_input = sys.argv[1]
 
 def hash_email(email):
+    """
+    Hashes the email address using SHA-256 and returns the hexadecimal digest.
+
+    Args:
+        email (str): The email address to hash.
+
+    Returns:
+        str: The SHA-256 hash of the email address.
+    """
     return hashlib.sha256(email.encode('utf-8')).hexdigest()
 
 def fetch_gravatar(email, size=1000, rating="g"):
+    """
+    Fetches the Gravatar image for the given email address, size, and rating.
+
+    Args:
+        email (str): The email address to fetch the Gravatar for.
+        size (int, optional): The size of the Gravatar image. Defaults to 1000.
+        rating (str, optional): The rating of the Gravatar image. Defaults to "g".
+
+    Returns:
+        bytes: The content of the Gravatar image.
+    """
     url = f"https://www.gravatar.com/avatar/{hash_email(email)}?s={size}&r={rating}"
     print(url)
     response = requests.get(url)
     return response.content
 
 def save_gravatar(email, size=1000, rating="g"):
+    """
+    Saves the Gravatar image for the given email address, size, and rating to a PNG file.
+
+    Args:
+        email (str): The email address to fetch the Gravatar for.
+        size (int, optional): The size of the Gravatar image. Defaults to 1000.
+        rating (str, optional): The rating of the Gravatar image. Defaults to "g".
+    """
     with open(f"gravatar-{size}.png", "wb") as f:  # Use "wb" mode for binary write
         f.write(fetch_gravatar(email, size))
 
 def convert_to_webp(size=1000):
+    """
+    Converts the saved PNG Gravatar image to WebP format.
+
+    Args:
+        size (int, optional): The size of the Gravatar image. Defaults to 1000.
+    """
     im = Image.open(f"gravatar-{size}.png")
     im.save(f"gravatar-{size}.webp")
 
 def variety_of_sizes(email, sizes=[1000, 1500, 800, 300, 200, 150, 100]):
+    """
+    Fetches and saves Gravatar images in multiple sizes and converts them to WebP format.
+
+    Args:
+        email (str): The email address to fetch the Gravatar for.
+        sizes (list, optional): A list of sizes for the Gravatar images. Defaults to [1000, 1500, 800, 300, 200, 150, 100].
+    """
     for x in sizes:
         save_gravatar(email, size=x)
         convert_to_webp(size=x)