Abstract module to cli and lib to allow module usage and bump version v0.3.0

README.md

@@ -4,38 +4,39 @@
 
 This tool automates the process of downloading photos from Google Photos albums by simulating user interaction with the web interface. It uses Selenium to open shared album links, click the "Download all" button, and extract the images to your local system.
 
-## ✨ Features
+## Features
 
-* 🔗 Accepts public/shared Google Photos album URLs
+* Accepts link-shared Google Photos album URLs
-* 🖱️ Simulates browser behavior to download photos via the "Download all" option
+* Accepts your own Google Photos album URLs if you supply the profile directory.
-* 🗃️ Automatically extracts downloaded `.zip` files into organized folders
+* Automatically extracts downloaded `.zip` files into organized folders
-* 🛠️ Works without needing any API keys or OAuth setup
+* Works without needing any API keys or OAuth setup
-* 📂 Supports batch downloading of multiple album links
+* Supports batch downloading of multiple album links
 
-## 🛑 Why not use the Google Photos API?
+## Why not use the Google Photos API?
 
-As of recent updates, **the original Google Photos API is deprecated**. While the **Google Picker API** is still available, it comes with several major limitations:
+**The original Google Photos API is deprecated**. While the **Google Picker API** is still available, it comes with several major limitations:
 
-* 🚫 You must select each photo manually — no "select all" option
+* You must select each photo manually, no "select all" option, meaning it can not be automated.
-* 📉 Limited to a maximum number of items (up to 100 photos per interaction)
+* Limited to a maximum number of items
-* 🔐 Requires setting up a Google Cloud project and API credentials
+* It requires setting up a Google Cloud project and API credentials, which is pretty hard.
 
-Due to these restrictions, this Selenium-based solution is one of the few remaining ways to fully automate bulk downloads from Google Photos albums.
+## Disclaimer
 
-## ⚠️ Disclaimer
-
-* The project was not made by AI, just the README.
-* It automates actions that a human user would normally perform in a browser.
 * Be aware of Google’s Terms of Service before using this tool.
+* It simulates human actions, but Google might not be happy about someone using this.
+* Selenium auto-downloads the Chrome driver if not found, which can take up space.
 
-## 🧰 Requirements
+## Installation
 
-* Python 3.11+
+`pip install gp-dl`
-* Selenium
-* Chrome or Chromium + WebDriver
 
-## 💡 Usage
+## Usage
 
-```bash
+### CLI
-python main.py --album-urls YOUR_ALBUM_LINK_HERE --output-dir test_images
+`gp-dl --album-urls ALBUM_URL ALBUM_URL2 --output-dir test --log-level info`
+
+### As a module
+```py
+from gp_dl import download_albums
+successful_albums, failed_albums, album_times = download_albums(["ALBUM_URL", "ALBUM_URL2"], output_dir="test")
 ```

gp_dl/__init__.py

@@ -1 +1,3 @@
-__version__ = "0.1.0"
+from .lib import download_albums
+
+__version__ = "0.3.0"

gp_dl/cli.py

@@ -0,0 +1,66 @@
+import argparse, logging, sys, time
+from statistics import median
+from .lib import download_albums
+
+BANNER = """
+██████   ██████         ██████  ██
+██       ██   ██        ██   ██ ██
+██   ███ ██████   █████ ██   ██ ██
+██    ██ ██             ██   ██ ██
+██████   ██             ██████  ███████
+
+gp-dl — Google Photos Downloader
+Download full-resolution albums from Google Photos using Selenium
+
+Author: csd4ni3l  |  GitHub: https://github.com/csd4ni3l
+"""
+
+LOG_LEVELS = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "ERROR": logging.ERROR,
+    "FATAL": logging.FATAL,
+    "QUIET": 999999999
+}
+
+def parse_cli_args():
+    parser = argparse.ArgumentParser(description="Download full-res images from a Google Photos album using Selenium.")
+    parser.add_argument("--album-urls", nargs="+", required=True, help="Google Photos album URL(s)")
+    parser.add_argument("--output-dir", required=True, help="The directory to save downloaded albums")
+    parser.add_argument("--driver-path", default=None, help="Custom Chrome driver path")
+    parser.add_argument("--profile-dir", default=None, help="A Chrome user data directory for sessions, set this if you want to open non-shared links.")
+    parser.add_argument("--headless", action="store_true", help="Run Chrome headlessly")
+    parser.add_argument("--log-level", default="INFO", help="Specifies what to include in log output. Available levels: debug, info, error, fatal")
+    return parser.parse_args()
+
+def configure_logging(log_level: str):
+    if not log_level.upper() in LOG_LEVELS:
+        print(f"Invalid logging level: {log_level}")
+        sys.exit(1)
+
+    logging.basicConfig(format='%(asctime)s %(levelname)s: %(message)s', level=LOG_LEVELS[log_level.upper()])
+    for logger_to_disable in ["selenium", "urllib3"]:
+        logging.getLogger(logger_to_disable).propagate = False
+        logging.getLogger(logger_to_disable).disabled = True
+
+def run_cli():
+    args = parse_cli_args()
+    
+    if not args.log_level.upper() == "QUIET":
+        print(BANNER)
+
+    configure_logging(args.log_level)
+
+    all_start = time.perf_counter()
+
+    successful_albums, failed_albums, album_times = download_albums(args.album_urls, args.output_dir, args.driver_path, args.profile_dir, args.headless)
+
+    logging.info("")
+    logging.info("===== DOWNLOAD STATISTICS =====")
+    logging.info(f"Total albums given: {len(args.album_urls)}")
+    logging.info(f"Successful albums ({len(successful_albums)}): {', '.join(successful_albums) or None}")
+    logging.info(f"Failed albums ({len(failed_albums)}): {', '.join(failed_albums) or 'None'}")
+    logging.info(f"Median time taken per album: {median(album_times or [0]):.2f} seconds")
+    logging.info(f"Average time taken per album: {sum(album_times or [0]) / len(album_times or [0]):.2f} seconds")
+    logging.info(f"Total time taken: {time.perf_counter() - all_start:.2f} seconds")
+    logging.info("================================")

gp_dl/lib.py

@@ -1,4 +1,3 @@
-import os, time, argparse, re, sys, logging
 from selenium.webdriver import Chrome, ChromeService
 from selenium.webdriver.common.by import By
 from selenium.webdriver.chrome.options import Options
@@ -6,28 +5,7 @@ from selenium.common.exceptions import TimeoutException
 from selenium.webdriver.support.ui import WebDriverWait
 from selenium.webdriver.support import expected_conditions as EC
 from zipfile import ZipFile
-
+import os, time, logging
-BANNER = """
-██████   ██████         ██████  ██
-██       ██   ██        ██   ██ ██
-██   ███ ██████   █████ ██   ██ ██
-██    ██ ██             ██   ██ ██
-██████   ██             ██████  ███████
-
-gp-dl — Google Photos Downloader
-Download full-res albums using Selenium
-
-Author: csd4ni3l  |  GitHub: https://github.com/csd4ni3l
-"""
-
-def parse_args():
-    parser = argparse.ArgumentParser(description="Download full-res images from a Google Photos album using Selenium.")
-    parser.add_argument("--album-urls", nargs="+", required=True, help="Google Photos album URL(s)")
-    parser.add_argument("--output-dir", required=True, help="Directory to save downloaded albums")
-    parser.add_argument("--driver-path", default=None, help="Custom Chrome driver path")
-    parser.add_argument("--profile-dir", default=None, help="Chrome user data directory for session reuse")
-    parser.add_argument("--headless", action="store_true", help="Run Chrome headlessly")
-    return parser.parse_args()
 
 def setup_driver(driver_path=None, profile_dir=None, headless=True):
     chrome_options = Options()
@@ -62,50 +40,67 @@ def find_crdownload_file():
         if file.endswith(".crdownload"):
             return file
         
-def configure_logging():
+def download_albums(
-    logging.basicConfig(format='%(asctime)s %(levelname)s: %(message)s', level=logging.DEBUG)
+    album_urls: list[str],
-    for logger_to_disable in ["selenium", "urllib3"]:
+    output_dir: str,
-        logging.getLogger(logger_to_disable).propagate = False
+    driver_path: str | None = None,
-        logging.getLogger(logger_to_disable).disabled = True
+    profile_dir: str | None = None,
+    headless: bool = False,
+) -> tuple[list[str], list[str], list[float]]:
+    """
+    1) Download full-resolution images from one or more Google Photos albums using Selenium.
 
-def main():
+    2) Return lists of successful and failed album names, as well as download durations.
-    args = parse_args()
+
-    driver = setup_driver(profile_dir=args.profile_dir, headless=args.headless)
+    :type album_urls: list[str]
+    :param album_urls: One or more Google Photos album URLs to download images from.
+
+    :type output_dir: str
+    :param output_dir: Directory path where the downloaded albums will be saved.
+
+    :type driver_path: str | None
+    :param driver_path: Path to a custom Chrome WebDriver binary. If None, Selenium will download it or choose the default system ChromeDriver.
+
+    :type profile_dir: str | None
+    :param profile_dir: Path to a Chrome user data directory. Use this to access private albums (non-shared links).
+
+    :type headless: bool
+    :param headless: Whether to run Chrome in headless mode. Defaults to False.
+
+    :returns: A tuple containing the names of the successful albums, names of the albums that failed to download, and the durations it took to download each album.
+    :rtype: tuple[list[str], list[str], list[float]]
+    """
+
+    driver = setup_driver(driver_path=driver_path, profile_dir=profile_dir, headless=headless)
 
     if not os.path.exists("gp_temp") or not os.path.isdir("gp_temp"):
         logging.info("Creating gp_temp directory to temporarily store the downloaded zip files.")
         os.makedirs("gp_temp", exist_ok=True)
 
-    if not os.path.exists(args.output_dir) or not os.path.isdir(args.output_dir):
+    if not os.path.exists(output_dir) or not os.path.isdir(output_dir):
         logging.fatal("Invalid output directory. Please supply a valid and existing directory.")
         return
 
-    failed_album_count = 0
+    failed_albums = []
-    successful_album_count = 0
+    successful_albums = []
-    total_albums = len(args.album_urls)
-    all_start = time.perf_counter()
     album_times = []
 
-    for album_url in args.album_urls:
+    for album_url in album_urls:
         album_start = time.perf_counter()
 
-        if re.match(r'^https?://photos\.app\.goo\.gl/[A-Za-z0-9]+$', album_url) is None:
-            logging.error(f"Invalid album URL: {album_url}")
-            logging.info("Continuing with next album URL.")
-            failed_album_count += 1
-            continue
-
-        logging.info(f"Now downloading {album_url}")
-
         driver.get(album_url)
 
+        album_title = driver.title.split(" -")[0]
+
+        logging.info(f"Now downloading {album_title} ({album_url})")
+
         logging.debug("Waiting for menu button...")
         try:
             menu_button = WebDriverWait(driver, 10).until(EC.presence_of_element_located((By.XPATH, '//*[@aria-label="More options"]')))
         except TimeoutException:
-            logging.error("Could not find more options button in time.")
+            logging.error("Could not find the 'more options' button in time.")
             logging.info("Continuing with next album URL.")
-            failed_album_count += 1
+            failed_albums.append(album_title)
             continue
 
         logging.debug("Clicking menu button...")
@@ -115,9 +110,9 @@ def main():
         try:
             download_all_button = WebDriverWait(driver, 10).until(EC.presence_of_element_located((By.XPATH, '//*[@aria-label="Download all"]')))
         except TimeoutException:
-            logging.error("Could not find download all button in time.")
+            logging.error("Could not find the 'download all' button in time.")
             logging.info("Continuing with next album.")
-            failed_album_count += 1
+            failed_albums.append(album_title)
             continue
 
         logging.debug("Clicking the download all button...")
@@ -135,33 +130,22 @@ def main():
             zip_file = find_zip_file()
             time.sleep(0.1)
 
-        logging.debug(f"Zip file downloaded, extracting to {args.output_dir}")
+        logging.debug(f"Zip file downloaded, extracting to {output_dir}")
 
         with ZipFile(f"gp_temp/{zip_file}") as opened_file:
-            opened_file.extractall(args.output_dir)
+            opened_file.extractall(output_dir)
 
         logging.debug("Deleting zip file...")
         os.remove(f"gp_temp/{zip_file}")
 
-        logging.info(f"Succesfully extracted zip file to {args.output_dir}")
+        logging.info(f"Succesfully extracted zip file to {output_dir}")
 
-        successful_album_count += 1
+        successful_albums.append(album_title)
         album_times.append(time.perf_counter() - album_start)
     
         logging.debug("Removing temporary gp_temp directory.")
         os.removedirs("gp_temp")
 
-    print("\n===== DOWNLOAD STATISTICS =====")
-    print(f"Total albums given: {total_albums}")
-    print(f"Successfully downloaded: {successful_album_count}")
-    print(f"Failed downloads: {failed_album_count}")
-    print(f"Average time taken per album: {sum(album_times) / len(album_times):.2f} seconds")
-    print(f"Total time taken: {time.perf_counter() - all_start:.2f} seconds")
-    print("================================")
-
     driver.quit()
 
-def run_cli():
+    return successful_albums, failed_albums, album_times
-    print(BANNER)
-    configure_logging()
-    main()

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gp-dl"
-version = "0.1.0"
+version = "0.3.0"
 description = "A Python-based Google Photos downloader built with Selenium."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -18,7 +18,7 @@ classifiers = [
 ]
 
 [project.scripts]
-gp-dl = "gp_dl.main:run_cli"
+gp-dl = "gp_dl.cli:run_cli"
 
 [build-system]
 requires = ["setuptools>=61.0"]

uv.lock

@@ -39,7 +39,7 @@ wheels = [
 
 [[package]]
 name = "gp-dl"
-version = "0.1.0"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "selenium" },