Merge pull request #596 from realpython/python-selenium

Add slimmed-down Selenium project code

Author: brendaweles

python-selenium/README.md

@@ -0,0 +1,64 @@
+# Modern Web Automation With Python and Selenium
+
+This repository contains the module `bandcamp`, which is the sample app built in the Real Python tutorial [Modern Web Automation With Python and Selenium](https://realpython.com/modern-web-automation-with-python-and-selenium/).
+
+## Installation and Setup
+
+Create and activate a [Python virtual environment](https://realpython.com/python-virtual-environments-a-primer/).
+
+Then, install the requirements:
+
+```sh
+(venv) $ python -m pip install -r requirements.txt
+```
+
+The only direct dependency for this project is [Selenium](https://selenium-python.readthedocs.io/). You should use a Python version of at least 3.10, which is necessary to support [structural pattern matching](https://realpython.com/structural-pattern-matching/).
+
+You'll need a [Firefox Selenium driver](https://selenium-python.readthedocs.io/installation.html#drivers) called `geckodriver` to run the project as-is. Make sure to [download and install](https://github.com/mozilla/geckodriver/releases) it before running the project.
+
+## Run the Bandcamp Discover Player
+
+To run the music player, install the package, then use the entry-point command from your command line:
+
+```sh
+(venv) $ python -m pip install .
+(venv) $ bandcamp-player
+```
+
+You'll see a text-based user interface that allows you to interact with the music player:
+
+```
+Type: play [<track_number>] | pause | tracks | more | exit
+>
+```
+
+Type one of the available commands to interact with Bandcamp's Discover section through your headless browser. Listen to songs with `play`, pause the current song with `pause`, and restart it with `play`. List available tracks with `tracks`, and load more songs using `more`. You can exit the music player by typing `exit`.
+
+## Troubleshooting
+
+If the music player seems to hang when you run the script, confirm whether you've correctly set up your WebDriver based on the following points.
+
+### Version Compatibility
+
+Confirm that your browser and corresponding WebDriver are in sync. If you followed the previous suggestion, then you should be using Firefox and geckodriver. If that doesn't work for some reason, then you may need to switch your browser _and_ WebDriver.
+
+For example, if you're using Chrome, then you need to install ChromeDriver and it must match your Chrome version. Otherwise, you may run into errors like `SessionNotCreatedException`.
+For more details, refer to the official [ChromeDriver documentation](https://sites.google.com/chromium.org/driver/) or [geckodriver releases](https://github.com/mozilla/geckodriver/releases).
+
+### Driver Installation and Path Issues
+
+Once you've confirmed that your browser and driver match, make sure that the WebDriver executable is properly installed:
+
+- **Path Configuration:** The driver must be in your system's PATH, or you need to specify its full path in your code.
+- **Permissions:** Ensure the driver file has the necessary execution permissions.
+
+If you're still running into issues executing the script, then consult the [Selenium Documentation](https://www.selenium.dev/documentation/) for additional troubleshooting tips or leave a comment in the tutorial.
+
+## About the Authors
+
+Martin Breuss - Email: martin@realpython.com
+Bartosz Zaczyński - Email: bartosz@realpython.com
+
+## License
+
+Distributed under the MIT license.

python-selenium/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pycamp"
+version = "0.1.1"
+requires-python = ">=3.10"
+description = "A CLI music player for Bandcamp's Discover page using Python and Selenium"
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent"
+]
+authors = [
+    { name = "Martin Breuss", email = "martin@realpython.com" },
+    { name = "Bartosz Zaczyński", email = "bartosz@realpython.com" },
+]
+dependencies = [
+    "selenium",
+]
+[project.scripts]
+discover = "bandcamp.__main__:main"
+pycamp = "bandcamp.__main__:main"

python-selenium/requirements.txt

@@ -0,0 +1,15 @@
+attrs==25.2.0
+certifi==2025.1.31
+h11==0.14.0
+idna==3.10
+outcome==1.3.0.post0
+pysocks==1.7.1
+selenium==4.29.0
+sniffio==1.3.1
+sortedcontainers==2.4.0
+trio==0.29.0
+trio-websocket==0.12.2
+typing-extensions==4.12.2
+urllib3==2.3.0
+websocket-client==1.8.0
+wsproto==1.2.0

python-selenium/src/bandcamp/__init__.py

@@ -0,0 +1,6 @@
+from bandcamp.app.tui import interact
+
+
+def main():
+    """Provide the main entry point for the app."""
+    interact()

python-selenium/src/bandcamp/__main__.py

@@ -0,0 +1,43 @@
+from selenium.webdriver import Firefox
+from selenium.webdriver.firefox.options import Options
+
+from bandcamp.web.pages import DiscoverPage
+
+BANDCAMP_DISCOVER_URL = "https://bandcamp.com/discover/"
+
+
+class Player:
+    """Play tracks from Bandcamp's Discover page."""
+
+    def __init__(self) -> None:
+        self._driver = self._set_up_driver()
+        self.page = DiscoverPage(self._driver)
+        self.tracklist = self.page.discover_tracklist
+        self._current_track = self.tracklist.available_tracks[0]
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_tb):
+        """Close the headless browser."""
+        self._driver.quit()
+
+    def play(self, track_number=None):
+        """Play the first track, or one of the available numbered tracks."""
+        if track_number:
+            self._current_track = self.tracklist.available_tracks[
+                track_number - 1
+            ]
+        self._current_track.play()
+
+    def pause(self):
+        """Pause the current track."""
+        self._current_track.pause()
+
+    def _set_up_driver(self):
+        """Create a headless browser pointing to Bandcamp."""
+        options = Options()
+        options.add_argument("--headless")
+        browser = Firefox(options=options)
+        browser.get(BANDCAMP_DISCOVER_URL)
+        return browser

python-selenium/src/bandcamp/app/__init__.py

@@ -0,0 +1,77 @@
+from bandcamp.app.player import Player
+
+COLUMN_WIDTH = CW = 30
+MAX_TRACKS = 100  # Allows to load more tracks once.
+
+
+def interact():
+    """Control the player through user interactions."""
+    with Player() as player:
+        while True:
+            print(
+                "\nType: play [<track number>] | pause | tracks | more | exit"
+            )
+            match input("> ").strip().lower().split():
+                case ["play"]:
+                    play(player)
+                case ["play", track]:
+                    try:
+                        track_number = int(track)
+                        play(player, track_number)
+                    except ValueError:
+                        print("Please provide a valid track number.")
+                case ["pause"]:
+                    pause(player)
+                case ["tracks"]:
+                    display_tracks(player)
+                case ["more"] if (
+                    len(player.tracklist.available_tracks) >= MAX_TRACKS
+                ):
+                    print(
+                        "Can't load more tracks. Pick one from the track list."
+                    )
+                case ["more"]:
+                    player.tracklist.load_more()
+                    display_tracks(player)
+                case ["exit"]:
+                    print("Exiting the player...")
+                    break
+                case _:
+                    print("Unknown command. Try again.")
+
+
+def play(player, track_number=None):
+    """Play a track and show info about the track."""
+    try:
+        player.play(track_number)
+        print(player._current_track._get_track_info())
+    except IndexError:
+        print(
+            "Please provide a valid track number. "
+            "You can list available tracks with `tracks`."
+        )
+
+
+def pause(player):
+    """Pause the current track."""
+    player.pause()
+
+
+def display_tracks(player):
+    """Display information about the currently playable tracks."""
+    header = f"{'#':<5} {'Album':<{CW}} {'Artist':<{CW}} {'Genre':<{CW}}"
+    print(header)
+    print("-" * 80)
+    for track_number, track_element in enumerate(
+        player.tracklist.available_tracks, start=1
+    ):
+        track = track_element._get_track_info()
+        album = _truncate(track.album, CW)
+        artist = _truncate(track.artist, CW)
+        genre = _truncate(track.genre, CW)
+        print(f"{track_number:<5} {album:<{CW}} {artist:<{CW}} {genre:<{CW}}")
+
+
+def _truncate(text, width):
+    """Truncate track information."""
+    return text[: width - 3] + "..." if len(text) > width else text

python-selenium/src/bandcamp/app/player.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from pprint import pformat
+
+from selenium.webdriver.remote.webdriver import WebDriver
+from selenium.webdriver.remote.webelement import WebElement
+from selenium.webdriver.support.wait import WebDriverWait
+
+MAX_WAIT_SECONDS = 10.0
+DEFAULT_WINDOW_SIZE = (1920, 3000)
+
+
+@dataclass
+class Track:
+    album: str
+    artist: str
+    genre: str
+    url: str
+
+    def __str__(self):
+        return pformat(self)
+
+
+class WebPage:
+    def __init__(self, driver: WebDriver) -> None:
+        self._driver = driver
+        self._driver.set_window_size(*DEFAULT_WINDOW_SIZE)
+        self._driver.implicitly_wait(5)
+        self._wait = WebDriverWait(driver, MAX_WAIT_SECONDS)
+
+
+class WebComponent(WebPage):
+    def __init__(self, parent: WebElement, driver: WebDriver) -> None:
+        super().__init__(driver)
+        self._parent = parent