How sharmaaarush/spotify-billboard-playlist works
Project Type and Purpose
• This is a standalone Python desktop application with a simple GUI that scrapes Billboard’s Hot 100 for a user-entered date and then uses the Spotify Web API to build a private playlist in the user’s account.
• Key functions:
– Collect a date via GUI (tkinter)
– Scrape Billboard chart (BeautifulSoup)
– Authenticate with Spotify and manage tokens (requests + python-dotenv)
– Search tracks, create playlist, add tracks (Spotify Web API)
File Structure and Roles
• .env – environment variables for Spotify credentials (CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, ACCESS_TOKEN, REFRESH_TOKEN, USER_ID)
• api_setup.py – handles OAuth flow, token refresh, and wraps Spotify API calls:
· get_access_token()
· create_playlist()
· search_track()
· add_tracks_to_playlist()
• main.py – GUI orchestration, ties together:
· Date input & button event (tkinter)
· Billboard scraping (BeautifulSoup)
· Spotify workflow (calls api_setup functions)
· Outputs playlist link to user
• README.md, LICENSE – documentation and licensing
Main Architectural Components
A. User Interface Layer
– tkinter window, date input field, “Create Playlist” button
B. Application Logic Layer
– Scraper sub-component (BeautifulSoup)
– Spotify Client sub-component (api_setup.py)
C. Configuration
– .env loader (python-dotenv) providing credentials to Spotify Client
D. External Systems
– Billboard website (HTML pages to scrape)
– Spotify Web API (OAuth 2.0 endpoints and data endpoints)
Component Interactions and Data Flow
1) User enters date → clicks button in UI
2) UI triggers Scraper → GET request to Billboard → parse top 100 song titles
3) UI invokes Spotify Client
a) Load .env → retrieve CLIENT_ID/SECRET, tokens
b) If needed, refresh access token via OAuth endpoint
c) For each song title → call search track endpoint → collect track URIs
d) Call create playlist endpoint → receive new playlist ID
e) Call add tracks endpoint with URIs → playlist populated
4) Spotify Client returns playlist URL → UI displays in console
Architectural Patterns and Principles
• Separation of concerns: GUI code (main.py) vs. API code (api_setup.py) vs. scrapers vs. config
• One‐process, event‐driven flow: user event triggers sequential tasks
Technologies and Frameworks to Annotate
• Python 3.x
• tkinter (UI)
• BeautifulSoup4 + requests (scraping)
• python-dotenv (config)
• Spotify Web API (OAuth 2.0 + REST endpoints)