Add guide to generate events using Meetup APIs

Author: hankngo

tools/events-automation/README.md

@@ -9,6 +9,11 @@
 from event import Event
 
 def authenticate():
+    """
+    Handles the OAuth 2.0 authentication process.
+    Returns obtaining access and refresh tokens from the Meetup API
+    """
+    # API Configuration:
     URL = "https://secure.meetup.com/oauth2/access"
     headers = {
         "Content-Type": "application/x-www-form-urlencoded"
@@ -17,6 +22,8 @@ def authenticate():
         "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
         "assertion": generate_signed_jwt()
     }
+
+    # Make a request for access and refresh tokens
     response = requests.post(url=URL, headers=headers, data=body)
     if response.status_code == 200:
         access_token = response.json().get("access_token")
@@ -34,18 +41,29 @@ def authenticate():
 GEOLOCATOR = Nominatim(user_agent="TWiR")
 
 def fetch_groups(endCursor=""):
+    """
+    Returns the response from the API call, which includes data on groups matching the criteria specified in the GraphQL query.
+    :type endCursor: An optional string parameter used for pagination, indicating the starting point of the query for fetching subsequent pages of results
+    :rtype: requests.Response
+    """
+
+    # API Configuration: 
+    # Sets the API endpoint and constructs headers using an access token for authentication.
     URL = "https://api.meetup.com/gql"
     access_token, refresh_token = ACCESS_TOKEN, REFRESH_TOKEN
 
     if not access_token:
         print("Authentication failed, cannot proceed to fetch events.")
         return
 
+    # Sets the content type to application/json for the request body.
     headers = {
         "Authorization": f"Bearer {access_token}",
         "Content-Type": "application/json",
     }
 
+    # GraphQL Query:
+    # Below is a GraphQL query that requests information about groups such as ID, name, link, URL name, latitude, and longitude. 
     data = {
         "query": """
         query (
@@ -79,6 +97,7 @@ def fetch_groups(endCursor=""):
             }
         }
         """,
+        # The query filters results based on the keyword "Rust" and sorts them by relevance
         "variables": {
             "searchGroupFilter": {
                 "query": "Rust",
@@ -98,9 +117,10 @@ def fetch_groups(endCursor=""):
     }
     return requests.post(url=URL, headers=headers, json=data)
 
-def get_rush_groups():
+def get_rush_groups() -> dict:
     """
-    Return a dictionary of groups
+    Returns a dictionary where each key represents the unique ID of a group, and the corresponding value is another dictionary containing details about the group such as name, link, URL name, latitude, and longitude
+    :rtype: dict
     """
     endCursor = None
     groups = dict()
@@ -119,15 +139,19 @@ def get_rush_groups():
             break
     return groups
 
-def get_known_rush_groups(fileName):
+def get_known_rush_groups(fileName="rust_meetup_groups.csv") -> dict:
     """
-    Read url and location of groups. Extract the urlname from the url
-    Return a dictionary of groups
+    Returns a dictionary represents all groups from a specified CSV file 
+    :type fileName: Name or Path of the CSV file that contains the URLs and locations of the groups.
     """
-    groups = dict()
+
+    # Reads the CSV file, specifically extracting data from the 'url' and 'location' columns
+    groups = dict() # main dictionary that stores all information of different groups
     df = pd.read_csv(fileName, header=0, usecols=['url', 'location'])
 
-    # Format: [source](https://stackoverflow.com/questions/35616434/how-can-i-get-the-base-of-a-url-in-python)
+    # Extracting the url name of known Rust groups
+    # Format of extracting the URL:
+    # [source](https://stackoverflow.com/questions/35616434/how-can-i-get-the-base-of-a-url-in-python)
     # https://www.meetup.com/seattle-rust-user-group/
     # split_url.scheme   "http"
     # split_url.netloc   "www.meetup.com" 
@@ -142,7 +166,14 @@ def get_known_rush_groups(fileName):
     return groups
 
 def get_20_events(groups) -> list[Event]:
-    events = []
+    """
+    Returns a list where each element is an instance of the Event class, representing event data from the Meetup API 
+    :type groups: A dictionary of groups where each entry contains the group's URL name to make an API request
+    :rtype: dict
+    """
+    events = [] # main list to store data about each fetched event.
+
+    # API Configuration:
     URL = "https://api.meetup.com/gql"
     access_token, refresh_token = ACCESS_TOKEN, REFRESH_TOKEN
 
@@ -154,8 +185,9 @@ def get_20_events(groups) -> list[Event]:
         "Authorization": f"Bearer {access_token}",
         "Content-Type": "application/json",
     }
+
+    # Constructs and sends a GraphQL query for each group to fetch up to 20 upcoming events from the Meetup API using the group's URL name
     data = {}
-    count = 1
     for group in groups.values():
         urlName = group["urlname"]
         data = {
@@ -194,6 +226,7 @@ def get_20_events(groups) -> list[Event]:
         response = requests.post(url=URL, headers=headers, json=data)
         data = response.json()["data"]
 
+        # Constructs Event with attributes such as title, location, date, URL, and organizer details
         if data:
             searchGroupByUrlname = data["groupByUrlname"]
             if searchGroupByUrlname:
@@ -212,8 +245,11 @@ def get_20_events(groups) -> list[Event]:
                                 virtual = True
                                 if venue["venueType"] != "online":
                                     virtual = False
+
+                                # Convert obtained latitude and longitude of an event to formatted location 
                                 address = (GEOLOCATOR.reverse(str(venue["lat"]) +","+ str(venue["lng"]))).raw["address"]
                                 location = format_location(address)
+
                                 date = node["dateTime"]
                                 url = node["eventUrl"]
                                 organizerName = group.get("name", urlName)
@@ -222,21 +258,29 @@ def get_20_events(groups) -> list[Event]:
                                 events.append(Event(name, location, date, url, virtual, organizerName, organizerUrl))
     return events
 
-def format_location(address):
+def format_location(address) -> str:
+    """
+    Helper method to format address of events with required components for a location
+    :rtype: string
+    """
     if not address:
         return "No location"
 
     # Components in the order for location
-    components = ['road', 'city', 'state', 'postcode', 'country']
+    components = ['city', 'state', 'country']
 
-    # Get available components
+    # Get available components, otherwise replace missing component with empty string
     location = [address.get(component, "") for component in components]
 
-    return ', '.join(location) if location else "No location"
+    return ','.join(location) if location else "No location"
 
 def get_events() -> list[Event]:
-    events_meetup_groups = get_20_events(get_rush_groups())
-    events_known_groups = get_20_events(get_known_rush_groups("rust_meetup_groups.csv"))
-    return events_meetup_groups + events_known_groups
+    """
+    Returns a list of Event objects querying from known, and Meetup API Rust groups
+    :rtype: list[Event]
+    """
+    # events_meetup_groups = get_20_events(get_rush_groups())
+    events_known_groups = get_20_events(get_known_rush_groups())
+    return events_known_groups
 
 # get_events()

tools/events-automation/generate_events_meetup.py

@@ -10,31 +10,47 @@
 load_dotenv()
 
 def get_PEM_private_key():
-    # Load the PRIVATE_KEY in PEM-formatted string from .env to bytes
+    """
+    Loads the PRIVATE_KEY in string from .env file.
+    Returns it in PEM-formatted bytes
+    """
     pem_bytes = (os.getenv('PRIVATE_KEY', "")).encode() 
     return pem_bytes
 
 def get_RSA_private_key():
-    # Deserializes/Loads the private key from PEM-formatted bytes to an RSA private key object, so we could perform cryptographic operations, such as signing data
+    """
+    Deserializes and sign the private key in PEM-formatted in bytes to an RSA private key object using cryptographic operations.
+    Returns the RSA private key object
+    """
     private_key = serialization.load_pem_private_key(
         get_PEM_private_key(), password=None, backend=default_backend()
     )
     return private_key
 
 def get_RSA_public_key():
-    # Get the corresponding RSA public key object from private_key
+    """
+    Returns the corresponding RSA public key object from RSA private_key
+    """
     public_key = get_RSA_private_key().public_key()
     return public_key
 
 def get_PEM_public_key():
-    #git, to verify digital signatures
+    """
+    Returns the public key in in PEM-formatted in bytes using RSA public key, to verify digital signatures
+    """
     pem_bytes = (get_RSA_public_key().public_bytes(
         encoding=serialization.Encoding.PEM,
         format=serialization.PublicFormat.SubjectPublicKeyInfo
     )).decode()
     return pem_bytes
 
+# This function is essential for authorize step when calling Meetup API
 def generate_signed_jwt():
+    """
+    Generates a JWT: 
+    Encodes and signs the payload using RS256 and the private RSA key, forming a base64-url encoded header, payload, and signature. 
+    Then returns it.
+    """
     AUTHORIZED_MEMBER_ID = os.getenv('AUTHORIZED_MEMBER_ID', "") # the member id that owns the OAuth Client
     CLIENT_KEY = os.getenv('CLIENT_KEY', "")
     private_key = get_RSA_private_key()
@@ -44,14 +60,17 @@ def generate_signed_jwt():
         "aud": "api.meetup.com",
         "exp": (datetime.datetime.utcnow() + datetime.timedelta(hours=24)).timestamp()
     }
-    # Generates a JWT: Encodes and signs the payload using RS256 and the private RSA key, forming a base64-url encoded header, payload, and signature. Then return it.
     return jwt.encode(
         payload=payload, 
         key=private_key, 
         algorithm="RS256"
     )
 
-def decode_and_validate_jwt(): #get_token_payload/claims
+def decode_and_validate_jwt():
+    """
+    Checks/Validates the signed jwt.
+    Returns a decoded jwt payload/claim
+    """
     token = generate_signed_jwt()
     pem_public_key = get_PEM_public_key()
     try:

tools/events-automation/jwt_auth.py

@@ -2,6 +2,7 @@
 # collect all the events from the event sources
 # call event sink with our collected events
 # print to console / output to file formatted markdown
+from generate_events_meetup import get_events as get_meetup_events
 
 """
 Example Markdown format:
@@ -20,10 +21,11 @@
 from test_events import get_test_events
 
 def main():
-    event_list = get_test_events()
+    event_list = get_meetup_events()
     sort_and_filter_events(event_list)
     for event in event_list:
         print(event.to_markdown_string())
+        print()
 
 
 def sort_and_filter_events(event_list):

tools/events-automation/main.py

@@ -0,0 +1,75 @@
+## Guide to Generating Events Using Meetup APIs
+
+### Introduction
+This guide provides step-by-step instructions on how to use Meetup APIs to fetch event data related to Rust programming groups. It outlines the installation of necessary packages, setting up environment variables, and executing the script to obtain event data.
+
+### Prerequisites
+Before you start, ensure you have the following:
+- Python installed on your system (Python 3.8 or later recommended).
+- `pip` for managing Python packages.
+- Access to terminal or command line.
+
+### Tips for Managing Python Packages
+
+- **Virtual Environment**: Create a virtual environment using `venv` (built into Python 3) or `virtualenv`. Here's how to activate a virtual environment:
+  ```bash
+  # Creating a virtual environment (for Linux/macOS)
+  python3 -m venv myenv
+  # Activating the virtual environment (for Linux/macOS)
+  source myenv/bin/activate
+
+  or
+
+  # Creating a virtual environment (for Windows)
+  python -m venv myenv
+  # Activating the virtual environment (for Windows)
+  myenv\Scripts\activate
+  ```
+- **Upgrade `pip`**: Ensure your `pip` is up-to-date to avoid installation issues with newer packages:
+  ```bash
+  pip install --upgrade pip
+  ```
+
+### Installation
+1. **Open Terminal or Command Prompt**: 
+   Navigate to the directory `.../tools/events-automation` where `requirements.txt` file is located.
+
+2. **Run the Installation Command**: 
+   Execute the following command to install all the packages listed in `requirements.txt`:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set Up Environment Variables**:
+   - Create a `.env` file for project directory.
+   - Add the following environment variables with your actual values:
+     ```
+     AUTHORIZED_MEMBER_ID=<Your_Meetup_Member_ID>
+     CLIENT_KEY=<Your_Meetup_Client_Key>
+     PRIVATE_KEY=<Your_RSA_Private_Key>
+     ```
+   These values are used for authentication with the Meetup API and to generate JWT tokens securely.
+
+### Running the Script
+To fetch events, run the following command from the project directory `.../tools/events-automation`:
+```bash
+python main.py
+```
+This script performs the following operations:
+- Authenticates with the Meetup API using JWT.
+- Fetches data for known Rust groups from a CSV file and Meetup API.
+- Filters and formats the event data into a standardized structure.
+- Outputs the details of upcoming events.
+
+### Example Output Format
+The script outputs event details in the following format:
+```
+* 2025-05-08T19:00+02:00 | Virtual (,,Tuvalu) | [rust-noris](TODO: ORGANISER URL HERE)
+    *[**Rust Nürnberg online**](https://www.meetup.com/rust-noris/events/gmkpctyhchblb)
+```
+This format includes the date and time of the event, the location (virtual in this case), and links to both the organizer's profile and the event itself.
+
+### Challenges and Considerations
+- **Data Accuracy**: The script uses "Rust" as a keyword for searching groups and events. This can sometimes pull in events that merely mention Rust but aren't directly related to Rust programming in the event descriptions.
+- **Event Data Completeness**: Not all events have complete venue information, especially for virtual events. The script currently ignores handling missing data, but the ideal is flagging such events for manual review or excluding them from the final output.
+- **API Limitations**: The Meetup API has rate limits and other constraints that may affect how frequently you can fetch data.