PinPy

platform Python application designed to automatically fetch public images ("pins") from a specified Pinterest board and set them as your desktop wallpaper, creating a dynamic wallpaper engine experience. The project leverages browser automation, web scraping, and image processing to seamlessly rotate wallpapers based on user-selected Pinterest content. ::update

Table of Contents

• Introduction
• Features
• Prerequisites
• Usage
• Additional-Information

Introduction

Order of Operations

1. Startup & Configuration

   • The user initiates the application by running main.py
   • main.py first loads configuration variables from config.py and sets up logging via utils/logger.py

2. System Checks

   • main.py calls helper functions from utils/helpers.py to validate source/destination paths and ensure the temporary image folder exists

3. User Input (GUI)

   • main.py launches the GUI window from gui/tkinterWindow.py
   • The GUI prompts the user for a Pinterest board URL, validates its format, and checks accessibility

4. Fetching Pinterest Board Data

   • Once a valid URL is provided, main.py calls the board data fetcher in core/fetcher.py
   • core/fetcher.py uses Selenium and BeautifulSoup to load the Pinterest board, extract pin data, and filter out unwanted content
   • Pin and board objects are structured using models from core/pinModel.py

5. Selecting and Downloading an Image

   • main.py uses utils/helpers.py to randomly select an image from the board’s pins
   • The selected image is downloaded to the temporary folder via core/downloader.py

6. Image Validation and Processing

   • The downloaded image is validated and processed for screen compatibility using core/validation.py

7. Setting the Wallpaper

   • The processed image is set as the desktop wallpaper using platform-specific logic in core/wallpaper.py

8. Cleanup

   • Upon completion or shutdown, main.py triggers cleanup routines from core/cleanup.py to remove temporary files

Brief Synopsis

::update

Features

• x ::update

Prerequisites

Asahi Linux (Fedora)

1. download git ::update
2. download python ::update
3. using git --version & python --version to validate downloads
4. x ::update

Windows

1. download git ::update
2. download python ::update
3. using git --version & python --version to validate downloads
4. x ::update

MacOS

1. download homebrew by opening terminal and entering /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. download git by opening terminal and entering brew install git
3. using brew --version & git --version to validate downloads
4. download dos2unix by opening terminal and entering brew install dos2unix
5. download python3 [https://www.python.org/ftp/python/3.13.2/python-3.13.2-macos11.pkg]
6. x ::update

Usage

Asahi Linux (Fedora)

1. clone the repo & cd in
2. x ::update

Windows

1. Clone the repo & cd into the project directory
2. Give the setup script permission via chmod +x setup.sh (if using Git Bash or WSL)
3. Run the setup script via ./setup.sh
4. Activate the virtual environment: .\venv\Scripts\activate
5. Run the program: python main.py

MacOS

1. clone the repo & cd in
2. give the setup script permission via chmod +x setup.sh
3. run the setup script via ./setup.sh
4. activate virtual environment source venv/bin/activate
5. run the program python3 main.py

Additional-Info

Current Project Structure

PinPy\

• core\
  • cleanup.py
  • downloader.py
  • fetcher.py
  • pinModel.py
  • validation.py
  • wallpaper.py
• gui\
  • assets\
    • colors.py
    • logo.png
  • tkinterWindow.py
• utils\
  • helpers.py
  • logger.py
• .gitignore
• config.py
• main.py
• ReadMe.md
• requirements.txt
• setup.sh

::update

ToDo

1. Updated CLI
   Goal : Enhance the command-line interface for better user experience and debugging

   Actions : Integrate a CLI framework (e.g., argparse or click) for structured commands and options, Add colorized output using colorama or rich for status, warnings, and errors , Refactor logging to support verbosity levels and colored logs , Add CLI options for headless mode, board URL input, and cleanup

   Files Impacted : main.py & logger.py

2. Tkinter GUI Redesign Goal : Modernize the GUI to match Pinterest’s color scheme and improve usability

   Actions : Redesign UI elements (buttons, backgrounds, fonts) to use Pinterest’s red, white, and gray palette, Add a logo or favicon for branding Improve input validation feedback (e.g., colored borders, tooltips) , Add progress indicators for fetching and downloading , Modularize GUI logic for easier maintenance

   Files Impacted : tkinterWindow.py

   New: assets/ (for icons, color constants)

3. PinModel Structure Update Goal: Make pin and board data models more extensible and robust

   Actions : Add more attributes to Pin (e.g., title, description, repin count, link) , Add metadata to Board (e.g., owner, category, total pins) , Implement serialization/deserialization for saving/loading boards , Add type hints and validation in constructors

   Files Impacted : pinModel.py

4. Optimized Pin Fetching & Collection Goal: Make pin retrieval more reliable and efficient

   Actions: Dynamically adjust Selenium scroll depth based on actual pin count and retrieval validation , Add retry logic for failed fetches , Filter out duplicates and ads more robustly , Log pin fetching progress and errors , Modularize fetching logic for easier testing

   Files Impacted : fetcher.py (scroll logic, validation, modularization) & pinModel.py (for new attributes)

5. Selenium Optimization (All OS)

   Goal : Ensure Selenium runs smoothly on Windows, macOS, and Linux

   Actions : Detect OS and configure drivers accordingly (Chrome, Edge, Firefox) , Add headless mode and resource management, Handle browser installation and updates automatically , Document setup steps for each OS in the ReadMe , Add error handling for common Selenium issues (timeouts, missing drivers).

   Files Impacted : fetcher.py (driver setup, OS detection) & setup.sh (driver installation) & ReadMe.md (setup documentation)