spotifyscraper 2.0.0__py3-none-any.whl

spotify_scraper/__init__.py

@@ -0,0 +1,88 @@
+"""SpotifyScraper - Modern Spotify Web Scraper.
+
+A fast, modern Python library for extracting data from Spotify's web player.
+Supports tracks, albums, artists, playlists, and lyrics with both requests and 
+Selenium backends.
+
+This package provides a high-level interface for extracting metadata from Spotify's
+web player without requiring API authentication. It parses Spotify's React-based
+web interface to extract structured data.
+
+Key Features:
+    - Extract metadata for tracks, albums, artists, and playlists
+    - Download preview audio clips and cover images
+    - Support for both lightweight (requests) and full (Selenium) browsers
+    - No API key required - works with public Spotify web pages
+    - Type-safe data structures using TypedDict
+    - Comprehensive error handling with specific exception types
+
+Typical usage example:
+    from spotify_scraper import SpotifyClient
+    
+    # Create a client
+    client = SpotifyClient()
+    
+    # Extract track information
+    track_data = client.get_track_info("https://open.spotify.com/track/...")
+    print(f"Track: {track_data['name']} by {track_data['artists'][0]['name']}")
+    
+    # Download preview and cover
+    client.download_preview_mp3(track_url, path="downloads/")
+    client.download_cover(track_url, path="covers/")
+
+For authenticated features (e.g., lyrics), provide cookies:
+    client = SpotifyClient(cookie_file="cookies.txt")
+    track_with_lyrics = client.get_track_info_with_lyrics(track_url)
+
+Note:
+    This library is designed for educational and personal use. Always respect
+    Spotify's Terms of Service and robots.txt when using this library.
+"""
+
+__version__ = "2.0.0"
+__author__ = "Ali Akhtari"
+__email__ = "aliakhtari78@hotmail.com"
+__license__ = "MIT"
+__url__ = "https://github.com/AliAkhtari78/SpotifyScraper"
+
+# Core imports for easy access
+from spotify_scraper.client import SpotifyClient
+from spotify_scraper.core.exceptions import (
+    SpotifyScraperError,
+    URLError,
+    ParsingError,
+    ExtractionError,
+    NetworkError,
+    AuthenticationError,
+    BrowserError,
+    MediaError,
+)
+
+# Utility functions
+from spotify_scraper.utils.url import (
+    is_spotify_url,
+    extract_id,
+    convert_to_embed_url,
+)
+
+# No backward compatibility needed
+
+__all__ = [
+    "SpotifyClient",
+    "is_spotify_url",
+    "extract_id", 
+    "convert_to_embed_url",
+    "SpotifyScraperError",
+    "URLError",
+    "ParsingError",
+    "ExtractionError",
+    "NetworkError",
+    "AuthenticationError",
+    "BrowserError",
+    "MediaError",
+]
+
+# Package metadata
+__title__ = "spotifyscraper"
+__description__ = "A modern Python library for extracting data from Spotify's web interface"
+__version_info__ = tuple(int(part) for part in __version__.split('.'))

spotify_scraper/__main__.py

@@ -0,0 +1,10 @@
+"""
+Main entry point for running SpotifyScraper as a module.
+
+This allows the package to be run with `python -m spotify_scraper`.
+"""
+
+from spotify_scraper.cli import main
+
+if __name__ == "__main__":
+    main()

spotify_scraper/auth/__init__.py

@@ -0,0 +1,100 @@
+"""
+Authentication module for SpotifyScraper.
+
+This module handles session management and authentication.
+"""
+
+from typing import Dict, Optional, Any
+import re
+import requests
+import logging
+
+from spotify_scraper.exceptions import AuthenticationError
+from spotify_scraper.constants import DEFAULT_HEADERS
+
+logger = logging.getLogger(__name__)
+
+
+class Session:
+    """
+    Session management class for authentication with Spotify web player.
+    
+    This class provides functionality to create authenticated sessions
+    using cookies, headers, and proxies. It is designed to be backward
+    compatible with the original Request class from SpotifyScraper v1.
+    """
+    
+    def __init__(
+        self,
+        cookie_file: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        proxy: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Initialize the Session.
+        
+        Args:
+            cookie_file: Path to a cookies.txt file (optional)
+            headers: Custom headers for requests (optional)
+            proxy: Proxy configuration (optional)
+        """
+        # Store provided parameters
+        self.cookie_file = cookie_file
+        self.headers = headers
+        self.proxy = proxy
+        
+        # Initialize cookie dictionary
+        if cookie_file is None:
+            self.cookie = None
+        else:
+            try:
+                self.cookie = self._parse_cookie_file()
+                logger.debug(f"Loaded cookies from {cookie_file}")
+            except Exception as e:
+                logger.error(f"Failed to load cookies from {cookie_file}: {e}")
+                raise AuthenticationError(f"Failed to load cookies: {e}") from e
+    
+    def _parse_cookie_file(self) -> Dict[str, str]:
+        """
+        Parse a cookies.txt file and return a dictionary of key-value pairs.
+        
+        Returns:
+            Dictionary of cookies
+        """
+        cookies = {}
+        with open(self.cookie_file, "r") as fp:
+            for line in fp:
+                if not re.match(r"^\#", line):
+                    line_fields = line.strip().split("\t")
+                    if len(line_fields) >= 7:
+                        cookies[line_fields[5]] = line_fields[6]
+        
+        return cookies
+    
+    def request(self) -> requests.Session:
+        """
+        Create session using requests library and set cookie and headers.
+        
+        Returns:
+            Configured requests.Session object
+        """
+        # Create a new session
+        request_session = requests.Session()
+        
+        # Set headers with defaults if not provided
+        if self.headers is None:
+            request_session.headers.update(DEFAULT_HEADERS)
+        else:
+            request_session.headers.update(self.headers)
+        
+        # Set cookies if provided
+        if self.cookie is not None:
+            request_session.cookies.update(self.cookie)
+        
+        # Set proxy if provided
+        if self.proxy is not None:
+            request_session.proxies.update(self.proxy)
+        
+        logger.debug("Created requests session")
+        
+        return request_session

spotify_scraper/auth/session.py

@@ -0,0 +1,263 @@
+"""
+Session management for SpotifyScraper authentication.
+
+This module handles authentication and session management for Spotify access.
+Think of this as the key management system - it handles getting and maintaining
+the credentials needed to access Spotify's data.
+"""
+
+from typing import Optional, Dict, Any, Union
+import logging
+import json
+import os
+from datetime import datetime, timedelta
+
+from spotify_scraper.core.exceptions import AuthenticationError
+from spotify_scraper.core.constants import (
+    CREDENTIALS_FILE_NAME,
+    SESSION_CACHE_FILE,
+    DEFAULT_SESSION_TIMEOUT,
+    MAX_SESSION_RETRIES,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Session:
+    """
+    Manages authentication sessions for Spotify access.
+    
+    This class handles the complex task of maintaining valid authentication
+    with Spotify. It can work with different authentication methods like
+    cookies from a browser session or API tokens.
+    
+    The session acts like a smart credential manager - it knows when credentials
+    are expired and can attempt to refresh them automatically.
+    """
+    
+    def __init__(
+        self,
+        access_token: Optional[str] = None,
+        cookies: Optional[Dict[str, str]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Initialize a session for Spotify authentication.
+        
+        Args:
+            access_token: Spotify access token if available
+            cookies: HTTP cookies for authentication
+            headers: Additional HTTP headers to include in requests
+        """
+        self.access_token = access_token
+        self.cookies = cookies or {}
+        self.headers = headers or {}
+        self.expires_at: Optional[datetime] = None
+        self.is_anonymous = access_token is None
+        
+        logger.debug(f"Initialized Session (anonymous: {self.is_anonymous})")
+    
+    def is_valid(self) -> bool:
+        """
+        Check if the session is currently valid.
+        
+        A session is considered valid if it has authentication credentials
+        and those credentials haven't expired.
+        
+        Returns:
+            True if session is valid and can be used for requests
+        """
+        # If we have no authentication method, session is not valid
+        if not self.access_token and not self.cookies:
+            return False
+        
+        # If we have an expiration time, check if we're still within it
+        if self.expires_at and datetime.now() >= self.expires_at:
+            logger.debug("Session has expired")
+            return False
+        
+        return True
+    
+    def refresh(self) -> bool:
+        """
+        Attempt to refresh the session credentials.
+        
+        This method tries to get new credentials when the current ones
+        have expired. The actual refresh mechanism depends on the type
+        of authentication being used.
+        
+        Returns:
+            True if refresh was successful, False otherwise
+        """
+        # For now, this is a placeholder. A real implementation would:
+        # 1. Use refresh tokens to get new access tokens
+        # 2. Re-authenticate with stored credentials
+        # 3. Prompt user for new authentication if needed
+        
+        logger.warning("Session refresh not yet implemented")
+        return False
+    
+    def set_access_token(self, token: str, expires_in: Optional[int] = None) -> None:
+        """
+        Set a new access token for the session.
+        
+        Args:
+            token: The access token to use
+            expires_in: Token lifetime in seconds (optional)
+        """
+        self.access_token = token
+        self.is_anonymous = False
+        
+        if expires_in:
+            self.expires_at = datetime.now() + timedelta(seconds=expires_in)
+        
+        logger.debug("Updated session with new access token")
+    
+    def add_cookies(self, cookies: Dict[str, str]) -> None:
+        """
+        Add cookies to the session.
+        
+        Args:
+            cookies: Dictionary of cookie name-value pairs
+        """
+        self.cookies.update(cookies)
+        logger.debug(f"Added {len(cookies)} cookies to session")
+    
+    def get_auth_headers(self) -> Dict[str, str]:
+        """
+        Get HTTP headers needed for authenticated requests.
+        
+        Returns:
+            Dictionary of headers to include in HTTP requests
+        """
+        auth_headers = self.headers.copy()
+        
+        if self.access_token:
+            auth_headers["Authorization"] = f"Bearer {self.access_token}"
+        
+        return auth_headers
+    
+    def save_to_file(self, filepath: Optional[str] = None) -> bool:
+        """
+        Save session data to a file for persistence.
+        
+        This allows sessions to be restored after the program restarts,
+        which is convenient for users so they don't have to re-authenticate
+        every time.
+        
+        Args:
+            filepath: Path to save session data. If None, uses default location.
+            
+        Returns:
+            True if save was successful, False otherwise
+        """
+        if filepath is None:
+            filepath = SESSION_CACHE_FILE
+        
+        try:
+            session_data = {
+                "access_token": self.access_token,
+                "cookies": self.cookies,
+                "headers": self.headers,
+                "expires_at": self.expires_at.isoformat() if self.expires_at else None,
+                "is_anonymous": self.is_anonymous,
+            }
+            
+            with open(filepath, "w") as f:
+                json.dump(session_data, f, indent=2)
+            
+            logger.debug(f"Saved session to {filepath}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to save session: {e}")
+            return False
+    
+    @classmethod
+    def load_from_file(cls, filepath: Optional[str] = None) -> Optional["Session"]:
+        """
+        Load session data from a file.
+        
+        Args:
+            filepath: Path to load session data from. If None, uses default location.
+            
+        Returns:
+            Session instance if loading was successful, None otherwise
+        """
+        if filepath is None:
+            filepath = SESSION_CACHE_FILE
+        
+        if not os.path.exists(filepath):
+            logger.debug(f"Session file {filepath} does not exist")
+            return None
+        
+        try:
+            with open(filepath, "r") as f:
+                session_data = json.load(f)
+            
+            session = cls(
+                access_token=session_data.get("access_token"),
+                cookies=session_data.get("cookies", {}),
+                headers=session_data.get("headers", {}),
+            )
+            
+            # Restore expiration time if available
+            expires_at_str = session_data.get("expires_at")
+            if expires_at_str:
+                session.expires_at = datetime.fromisoformat(expires_at_str)
+            
+            session.is_anonymous = session_data.get("is_anonymous", True)
+            
+            logger.debug(f"Loaded session from {filepath}")
+            return session
+            
+        except Exception as e:
+            logger.error(f"Failed to load session: {e}")
+            return None
+    
+    def clear(self) -> None:
+        """
+        Clear all authentication data from the session.
+        
+        This essentially logs the user out by removing all stored credentials.
+        """
+        self.access_token = None
+        self.cookies.clear()
+        self.headers.clear()
+        self.expires_at = None
+        self.is_anonymous = True
+        
+        logger.debug("Cleared session authentication data")
+
+
+# Backward compatibility class for the old Request interface
+class Request:
+    """
+    Backward compatibility wrapper for the old Request class.
+    
+    This class provides the same interface as the original SpotifyScraper
+    Request class, but internally uses the new Session system. This allows
+    existing code to work without changes while benefiting from the improved
+    architecture underneath.
+    """
+    
+    def __init__(self, cookie_file: Optional[str] = None, headers: Optional[Dict[str, str]] = None, proxy: Optional[str] = None):
+        """
+        Initialize with the same interface as the original Request class.
+        
+        Args:
+            cookie_file: Path to cookie file (legacy parameter)
+            headers: HTTP headers to use
+            proxy: Proxy URL to use (legacy parameter)
+        """
+        self.session = Session(headers=headers)
+        logger.debug("Initialized Request (compatibility mode)")
+    
+    def request(self) -> Session:
+        """
+        Return a session object that can be used with the old Scraper interface.
+        
+        Returns:
+            Session object compatible with old code
+        """
+        return self.session

spotify_scraper/browsers/__init__.py

@@ -0,0 +1,72 @@
+"""
+Browser factory module for SpotifyScraper.
+
+This module provides factory functions for creating browser instances.
+"""
+
+from typing import Optional, Union, Dict, Any
+import logging
+
+from spotify_scraper.exceptions import BrowserError
+from spotify_scraper.browsers.base import Browser
+
+logger = logging.getLogger(__name__)
+
+def create_browser(browser_type: str = "auto", **kwargs) -> Browser:
+    """
+    Create appropriate browser instance.
+    
+    Args:
+        browser_type: Type of browser ('requests', 'selenium', or 'auto')
+        **kwargs: Additional arguments to pass to browser constructor
+        
+    Returns:
+        Configured browser instance
+        
+    Raises:
+        BrowserError: If browser creation fails
+        ValueError: If browser_type is invalid
+    """
+    # Import implementation classes here to avoid circular imports
+    from spotify_scraper.browsers.requests_browser import RequestsBrowser
+    
+    try:
+        from spotify_scraper.browsers.selenium_browser import SeleniumBrowser
+        selenium_available = True
+    except ImportError:
+        selenium_available = False
+        logger.warning("Selenium is not available, falling back to requests")
+    
+    # Create browser based on type
+    if browser_type == "requests":
+        logger.debug("Creating RequestsBrowser")
+        return RequestsBrowser(**kwargs)
+    
+    elif browser_type == "selenium":
+        if selenium_available:
+            logger.debug("Creating SeleniumBrowser")
+            return SeleniumBrowser(**kwargs)
+        else:
+            logger.warning("Selenium requested but not available, falling back to requests")
+            return RequestsBrowser(**kwargs)
+    
+    elif browser_type == "auto":
+        # Try requests first, fallback to selenium if needed
+        try:
+            logger.debug("Trying RequestsBrowser")
+            browser = RequestsBrowser(**kwargs)
+            # Test browser with a simple request
+            browser.get("https://open.spotify.com")
+            return browser
+        except Exception as e:
+            logger.warning(f"RequestsBrowser failed: {e}")
+            
+            if selenium_available:
+                logger.debug("Falling back to SeleniumBrowser")
+                return SeleniumBrowser(**kwargs)
+            else:
+                logger.error("Neither RequestsBrowser nor SeleniumBrowser are working")
+                raise BrowserError("Failed to create any browser instance") from e
+    
+    else:
+        raise ValueError(f"Unknown browser type: {browser_type}")