Feat/search and csv

[paixaop]

Pull Request: Search and CSV Batch Download Features

Overview

This PR adds iTunes search functionality and CSV batch download capabilities to the CLI, enabling users to discover and download music without direct URLs.

Features

1. iTunes Search Mode (--search)

• Search iTunes API for songs, albums, and artists
• Interactive selection with rich terminal output
• JSON output option (--json) for programmatic use
• Automatic download of selected items (--download)
• Results include Apple Music URLs for direct downloads

Usage:

gamdl --search "artist name song title" --limit 10 --download
gamdl --search "query" --json  # Output as JSON

Features:

• Rich terminal formatting (colors, formatting)
• Interactive checkbox selection
• Configurable result limit
• Automatic URL construction for songs

2. CSV Batch Processing (--input-csv)

• Batch download from CSV files with title and artist columns
• Automatic song matching via iTunes search
• Flexible title/artist matching (handles variations, feat/collab)
• Batch processing with rate limiting
• Automatic retry on rate limits

CSV Format:

title,artist
Never Gonna Give You Up,Rick Astley
Bohemian Rhapsody,Queen

Usage:

gamdl --input-csv songs.csv

Features:

• Batch processing (configurable batch size, default: 10)
• Rate limit handling with automatic retries
• Flexible matching:
  • Title variations (handles parentheses, brackets)
  • Artist matching (handles "feat.", "ft.", collaborations)
• Progress tracking with batch and item counters
• Error handling: continues on failures, reports summary
• Batch delays to respect API limits

Technical Implementation

Architecture

• ItunesSearch class: Wraps iTunes API with URL construction and retry logic
• CSVProcessor class: Handles CSV reading, searching, matching, and batch downloads
• Separation of concerns: Search logic separate from download logic

Key Components

ItunesSearch (gamdl/cli/song_search.py):

• Wraps ItunesApi with enhanced functionality
• Automatic URL construction for song entities
• Rate limit retry logic with exponential backoff
• Entity-agnostic (supports song, album, artist, etc.)
• Only enriches results with URLs when entity="song"

CSVProcessor (gamdl/cli/csv_processor.py):

• CSV file parsing and validation
• Batch orchestration with configurable size
• Title/artist matching algorithms
• Integration with downloader for batch processing
• Error tracking and reporting

Configuration Constants

• CSV_BATCH_SIZE: Number of songs to process per batch (default: 10)
• CSV_BATCH_DELAY_SECONDS: Delay between batches (default: 2)
• CSV_RATE_LIMIT_RETRY_SECONDS: Wait time on rate limit (default: 30)
• CSV_MAX_RETRIES: Maximum retry attempts (default: 3)

Code Quality Improvements

• ✅ Extracted reusable functions to reduce duplication
• ✅ Class-based design following project patterns
• ✅ Dependency injection for testability
• ✅ Comprehensive error handling with detailed logging
• ✅ Type hints throughout

Benefits

1. Discovery: Find songs without direct URLs
2. Bulk operations: Process large CSV lists efficiently
3. Reliability: Rate limit handling and retries
4. User experience: Progress tracking and clear error messages
5. Maintainability: Modular, testable design

Example Workflows

Search and download:

gamdl --search "The Beatles" --limit 20 --download

Batch download from CSV:

gamdl --input-csv my-playlist.csv

Search with JSON output:

gamdl --search "query" --json > results.json

Testing Considerations

• CSV parsing with various formats
• Matching algorithm with edge cases
• Rate limit retry behavior
• Error handling for missing/invalid data
• Batch processing with different sizes

---

This PR significantly enhances the CLI's capabilities by adding search and batch download features while maintaining code quality and following existing project patterns.

[paixaop]

was getting an error when the URL pointed directly to a song, ie, the playlist metadata was None