Shulem Deen APIshulemdeen.com ↗

"""
Shulem Deen Events API Client

This module provides a Python client for the Shulem Deen Events API,
which scrapes past events from shulemdeen.com.

Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Any, Dict, List
from datetime import datetime


class ParseClient:
    """Client for interacting with the Parse API."""

    def __init__(self, api_key: str = None):
        """
        Initialize the Parse API client.

        Args:
            api_key: API key for authentication. If not provided,
                    will attempt to load from PARSE_API_KEY environment variable.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "ffc942cb-1d5a-45fd-8fb0-a34f1501678f"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not provided. Set PARSE_API_KEY environment variable "
                "or pass api_key parameter."
            )

    def _call(
        self, endpoint: str, method: str = "POST", **params
    ) -> Dict[str, Any]:
        """
        Make an API call to the Parse API.

        Args:
            endpoint: The API endpoint name.
            method: HTTP method ("GET" or "POST").
            **params: Additional parameters to pass to the API.

        Returns:
            Dictionary containing the API response.

        Raises:
            requests.exceptions.RequestException: If the API call fails.
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}

        if method == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method == "POST":
            payload = params if params else {}
            response = requests.post(url, headers=headers, json=payload)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def get_past_events(self) -> Dict[str, Any]:
        """
        Retrieve all past events from Shulem Deen's website.

        Returns:
            Dictionary containing:
                - events: List of event objects with location, date, and details
                - total: Total count of events returned
        """
        return self._call("get_past_events", method="GET")


def parse_event_date(date_str: str) -> datetime:
    """
    Parse event date string into a datetime object.

    Args:
        date_str: Date string in format like "Tue 3/24/2015 7pm"

    Returns:
        Parsed datetime object (time component approximated to hour only).
    """
    # Simple parser for common date formats
    formats = ["%a %m/%d/%Y %I%p", "%a %m/%d/%y %I%p"]
    for fmt in formats:
        try:
            return datetime.strptime(date_str, fmt)
        except ValueError:
            continue
    # Return None if parsing fails
    return None


def format_event_display(event: Dict[str, str]) -> str:
    """
    Format an event dictionary for display.

    Args:
        event: Event dictionary with location, date, and details.

    Returns:
        Formatted string representation of the event.
    """
    location = event.get("location", "Unknown Location")
    date = event.get("date", "Unknown Date")
    details = event.get("details", [])

    output = f"\n📍 {location}"
    output += f"\n📅 {date}"

    if details:
        output += "\n📝 Details:"
        for detail in details:
            output += f"\n   • {detail}"

    return output


def main():
    """Main execution demonstrating practical API usage."""
    # Initialize the client
    client = ParseClient()

    print("=" * 70)
    print("Shulem Deen Events API - Event Retrieval Example")
    print("=" * 70)

    # Fetch all past events
    print("\n🔄 Fetching past events from shulemdeen.com...")
    response = client.get_past_events()

    events = response.get("events", [])
    total_count = response.get("total", 0)

    print(f"\n✅ Retrieved {total_count} events total\n")

    # Analyze and display events
    print(f"Showing first 10 events:\n")

    parsed_events = []

    for idx, event in enumerate(events[:10], 1):
        print(f"{idx}. {format_event_display(event)}\n")

        # Attempt to parse date for sorting
        parsed_date = parse_event_date(event.get("date", ""))
        if parsed_date:
            parsed_events.append({"event": event, "parsed_date": parsed_date})

    # Group events by location (practical use case)
    print("\n" + "=" * 70)
    print("Events Grouped by Location (all events)")
    print("=" * 70)

    location_groups: Dict[str, List[Dict]] = {}

    for event in events:
        location = event.get("location", "Unknown")
        if location not in location_groups:
            location_groups[location] = []
        location_groups[location].append(event)

    # Sort locations by event count
    sorted_locations = sorted(
        location_groups.items(), key=lambda x: len(x[1]), reverse=True
    )

    print(f"\nFound {len(location_groups)} unique locations:\n")

    for idx, (location, location_events) in enumerate(sorted_locations[:15], 1):
        print(f"{idx}. {location}: {len(location_events)} event(s)")

    # Summary statistics
    print("\n" + "=" * 70)
    print("Summary Statistics")
    print("=" * 70)
    print(f"Total Events: {total_count}")
    print(f"Unique Locations: {len(location_groups)}")
    print(f"Top Location: {sorted_locations[0][0]} ({len(sorted_locations[0][1])} events)")

    if parsed_events:
        # Sort by date
        parsed_events.sort(key=lambda x: x["parsed_date"])
        earliest = parsed_events[0]["parsed_date"]
        latest = parsed_events[-1]["parsed_date"]
        print(f"Date Range: {earliest.strftime('%B %Y')} to {latest.strftime('%B %Y')}")


if __name__ == "__main__":
    main()