🎬 IMDb Data Downloader & Manager

A production-grade Python desktop application for downloading, organizing, storing, versioning, and exporting IMDb-related data. Built with a clean architecture, robust error handling, and a polished dark-themed Tkinter interface.

---

✨ Features

Core Functionality

• Search & Download — Enter an IMDb ID (tt0111161), title name, or person/actor name
• Automatic Input Detection — Auto-classifies input as title ID, person ID, or search query
• Rich Data Display — View downloaded metadata in a sortable treeview with double-click details

Data Management

• SQLite Database — All records persisted via SQLAlchemy ORM (ready for MariaDB/MySQL swap)
• Record Versioning — Every update archives the previous version to title_history — no data is ever lost
• Duplicate Detection — SHA-256 content hashing prevents redundant snapshots
• Folder-Based Storage — Organized as data/{type}/{imdb_id}/{timestamp}/data.json

Export & Backup

• JSON Export — Full record export with parsed data
• CSV Export — Flat tabular export for spreadsheet analysis
• Offline Archive — Complete folder structure for reliable offline backup and restoration

Developer Experience

• Embedded Log Viewer — Live log panel inside the GUI with color-coded levels
• File Logging — Rotating log files with timestamps and stack traces
• Startup Health Checks — Bootstrap verifies PyMovieDb, directories, and database on launch
• Dark Theme — Professional Catppuccin Mocha color scheme

---

📋 Prerequisites

Requirement	Version	Notes
Python	3.12+	Tested on 3.12, 3.13, 3.14
pip	Latest	Package installer
Tkinter	Built-in	Included with standard Python install

Note: No external database server needed for the MVP. SQLite is included with Python.

---

🚀 Setup

1. Clone the Repository

git clone https://github.com/filipetorresdecarvalho/get-imdb-json.git
cd get-imdb-json

2. Create a Virtual Environment (Recommended)

python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

This installs:

• PyMovieDb — IMDb data acquisition library (scrapes IMDb.com)
• SQLAlchemy — ORM for database operations

4. Run the Application

python app.py

The app will:

1. Load configuration from config/default.ini
2. Run bootstrap health checks
3. Create data/ and logs/ directories
4. Initialize the SQLite database
5. Open the GUI window

---

💻 Usage

Searching by IMDb ID

Enter a title ID (e.g. tt0111161) or person ID (e.g. nm0000151) and click Download.

Searching by Name

Enter a movie title (e.g. The Shawshank Redemption) or person name (e.g. Morgan Freeman). Select the appropriate type from the dropdown if auto-detection isn't working.

Viewing Details

Double-click any row in the results table to view the full JSON data.

Exporting Data

Click Export to choose format (JSON/CSV), scope (Titles/Persons/Everything), and destination.

---

🏗️ Architecture

┌──────────────────────────────────────────────────────┐
│                    Tkinter GUI                       │
│  ┌─────────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Search Input │  │ Results  │  │  Log Panel    │  │
│  │ + Type Combo │  │ Treeview │  │  (live logs)  │  │
│  └──────┬──────┘  └────┬─────┘  └───────────────┘  │
└─────────┼──────────────┼────────────────────────────┘
          │              │
   ┌──────▼──────────────▼──────────┐
   │       Services Layer           │
   │  ┌─────────────────────────┐   │
   │  │   Download Service      │   │
   │  │  (orchestration core)   │   │
   │  └──────┬──────────────────┘   │
   │  ┌──────▼──────┐  ┌────────┐  │
   │  │ Validation  │  │History │  │
   │  │  Service    │  │Service │  │
   │  └─────────────┘  └────────┘  │
   │  ┌──────────────┐  ┌───────┐  │
   │  │Export Service │  │ Boot  │  │
   │  └──────────────┘  │strap │  │
   └─────────────────────┴───────┘──┘
          │              │
   ┌──────▼──────┐  ┌───▼────────────┐
   │ Integration │  │    Storage      │
   │  (Adapter)  │  │  ┌───────────┐ │
   │  PyMovieDb  │  │  │ Folder    │ │
   │             │  │  │ Manager   │ │
   └──────┬──────┘  │  ├───────────┤ │
          │         │  │JSON Writer│ │
   ┌──────▼──────┐  │  ├───────────┤ │
   │  IMDb.com   │  │  │ Snapshot  │ │
   │  (external) │  │  │ Manager   │ │
   └─────────────┘  │  └───────────┘ │
                    └────────────────┘
          │
   ┌──────▼──────────────────────┐
   │      Database (SQLite)      │
   │  ┌───────┐  ┌────────────┐  │
   │  │Actors │  │  Titles    │  │
   │  └───────┘  ├────────────┤  │
   │             │TitleDetail │  │
   │             ├────────────┤  │
   │             │TitleHistory│  │
   │             └────────────┘  │
   └─────────────────────────────┘

---

📁 Folder Structure

get-imdb-json/
├── app.py                          # Entry point
├── README.md                       # This file
├── requirements.txt                # Python dependencies
│
├── config/
│   ├── settings.py                 # Config loader (INI + env vars)
│   └── default.ini                 # Default configuration
│
├── gui/
│   ├── main_window.py              # Main Tkinter window (dark theme)
│   ├── dialogs.py                  # Bootstrap, export, detail dialogs
│   └── status_panel.py             # Status bar + log viewer widget
│
├── services/
│   ├── bootstrap_service.py        # Startup health checks
│   ├── download_service.py         # Download orchestration pipeline
│   ├── export_service.py           # JSON/CSV export
│   ├── validation_service.py       # Input validation & classification
│   └── history_service.py          # Record versioning / snapshots
│
├── db/
│   ├── engine.py                   # SQLAlchemy engine + session
│   └── models.py                   # ORM models (Actor, Title, etc.)
│
├── storage/
│   ├── folder_manager.py           # Directory hierarchy management
│   ├── json_writer.py              # Atomic JSON read/write
│   └── snapshot_manager.py         # Content-hash deduplication
│
├── integrations/
│   └── pymoviedb_adapter.py        # PyMovieDb wrapper (safe API)
│
├── utils/
│   ├── logger.py                   # Logging setup + Tkinter handler
│   ├── hashing.py                  # SHA-256 utilities
│   ├── paths.py                    # Path constants & helpers
│   └── errors.py                   # Custom exception hierarchy
│
├── logs/                           # Runtime logs (gitignored)
├── data/                           # Downloaded data (gitignored)
└── tests/                          # Future test suite

---

⚙️ Configuration

config/default.ini

[database]
url = sqlite:///data/imdb_data.db

[storage]
data_dir = data
log_dir = logs

[app]
log_level = INFO
window_title = IMDb Data Downloader & Manager
request_timeout = 30

Environment Variable Overrides

Variable	Config Key	Example
IMDB_APP_DB_URL	database.url	mysql+pymysql://user:pass@localhost/imdb
IMDB_APP_DATA_DIR	storage.data_dir	D:\imdb_data
IMDB_APP_LOG_DIR	storage.log_dir	D:\imdb_logs
IMDB_APP_LOG_LEVEL	app.log_level	DEBUG

---

🔀 Switching to MariaDB/MySQL

The SQLAlchemy models work with any supported backend. To switch:

1. Install the MySQL driver:

   pip install pymysql

2. Update config/default.ini:

   [database]
   url = mysql+pymysql://user:password@localhost:3306/imdb_db

3. Create the database:

   CREATE DATABASE imdb_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

4. Restart the app — tables are created automatically.

---

📦 Dependency Strategy

This project uses PyMovieDb as the primary IMDb data acquisition layer. PyMovieDb provides:

• get_by_id() / get_by_name() — Movie/TV-series lookup
• person_by_id() / person_by_name() — Person/celebrity lookup
• search() — Search with filters (year, TV, person)
• popular_movies() / popular_tv() — Browse popular content

The imdb-scraper project was used as an architectural reference for database storage patterns and scraping workflows, but is not a runtime dependency (no license detected).

What This Project Adds (Beyond the Dependencies)

Feature	PyMovieDb	imdb-scraper	This Project
IMDb data scraping	✅	✅	Via PyMovieDb
Desktop GUI	❌	❌	✅ Tkinter
Record versioning	❌	❌	✅ Full history
Content deduplication	❌	❌	✅ SHA-256
Folder-based archive	❌	❌	✅ Timestamped
JSON/CSV export	❌	❌	✅ Multiple formats
Startup health checks	❌	❌	✅ Bootstrap
Embedded log viewer	❌	❌	✅ Live GUI panel
Error handling	Basic	Basic	✅ Full hierarchy
Database versioning	❌	❌	✅ History table

---

🔧 Troubleshooting

PyMovieDb not found

pip install PyMovieDb

SQLite "database is locked"

Ensure only one instance of the app is running. The app uses WAL mode for better concurrency.

No data returned for a valid ID

• IMDb may be blocking scraping requests. Try again after a few minutes.
• Check the log panel for specific error details.
• Verify your internet connection.

GUI looks wrong / fonts not rendering

Ensure your Python installation includes Tkinter (usually bundled on Windows and macOS).

Permission errors on data/ or logs/

Run the app from a directory where you have write permissions, or set custom paths:

set IMDB_APP_DATA_DIR=D:\my_imdb_data
set IMDB_APP_LOG_DIR=D:\my_imdb_logs
python app.py

---

📄 License

This project is licensed under the MIT License.

Dependency Licenses

• PyMovieDb: MIT License
• SQLAlchemy: MIT License
• imdb-scraper: No license detected (used as reference only, not bundled)

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

🗺️ Roadmap (v2)

• MariaDB/MySQL as configurable backend
• Auto-clone dependency repos from GitHub on first launch
• Retry queue for failed downloads with exponential back-off
• Actor/title history browser panel in GUI
• Batch download from a list of IDs
• SQL dump export
• Alembic database migrations
• Settings/preferences dialog
• Response caching (in-memory LRU)
• Packaging as standalone executable (PyInstaller)