MovieFinder

A command-line movie search application written in Python. MovieFinder lets you search for movies using the OMDb API, view detailed information about them, and save your favorites to a local JSON file for later.

Features

• Search for movies by title
• View detailed movie information: title, year, genre, rating, runtime, and plot
• Select a movie from a list of search results
• Save movies to a local favorites list
• View all saved favorite movies
• Search within your saved favorites
• Remove movies from favorites
• Export favorites to a JSON file
• Graceful handling of API errors, timeouts, and invalid input
• Clean, menu-driven CLI interface

Technologies Used

• Python 3
• requests for HTTP requests
• python-dotenv for environment variable management
• JSON for local data storage
• unittest for testing

API Information

MovieFinder uses the OMDb API (The Open Movie Database) to search for and retrieve movie data.

How to Obtain an API Key

1. Go to https://www.omdbapi.com/apikey.aspx
2. Select the FREE tier (1,000 daily requests) and submit the form with your email.
3. Check your email for the activation link and click it to activate your key.
4. Copy the API key you receive - you'll need it in the next step.

Environment Variable Setup

MovieFinder reads your OMDb API key from an environment variable named OMDB_API_KEY. The key is never hard-coded and never committed to the repository.

1. Copy the example environment file:

   cp .env.example .env

2. Open .env in a text editor and replace the placeholder with your real key:

   OMDB_API_KEY=your_actual_key_here
   

3. Save the file. .env is already listed in .gitignore, so it will never be committed to version control.

Installation

# Clone the repository
git clone https://github.com/yourusername/moviefinder.git
cd moviefinder

# (Recommended) Create and activate a virtual environment
python -m venv venv
source venv/bin/activate      # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up your environment file
cp .env.example .env
# then edit .env and add your OMDb API key

How to Run

python main.py

Example Usage

================================
MOVIEFINDER
===========

1. Search Movies
2. View Favorites
3. Search Favorites
4. Remove Favorite
5. Export Favorites
6. Exit

Choose an option: 1

Enter movie name: Interstellar

Search Results:

1. Interstellar (2014)
2. Interstellar: The Mission (2015)

Select a movie (1-2, or 0 to cancel): 1

================================
MOVIE DETAILS
=============

Title: Interstellar
Year: 2014
Genre: Adventure, Drama, Sci-Fi
Rating: 8.7/10
Runtime: 169 min

Plot:
A team of explorers travel through a wormhole in space...

1. Add to Favorites
2. Back
Choose an option: 1

'Interstellar' was added to your favorites.

Project Structure

moviefinder/
│
├── main.py              # CLI entry point and menu loop
├── api_client.py         # OMDb API communication logic
├── movie.py               # Movie data model
├── favorites.py           # Local favorites storage and operations
├── config.py               # Environment variable / configuration loading
├── utils.py                 # CLI display and prompt helpers
│
├── data/
│   └── favorites.json        # Local favorites storage (auto-created)
│
├── tests/
│   ├── test_favorites.py       # Unit tests for favorites logic
│   └── test_movie.py            # Unit tests for the Movie model
│
├── .env.example                  # Example environment variable file
├── .gitignore                     # Files/folders excluded from git
├── requirements.txt                # Python dependencies
├── README.md                        # Project documentation
└── LICENSE                           # MIT License

Testing

Unit tests cover movie creation, favorites saving/removal/searching, and JSON storage handling. Run all tests with:

python -m unittest discover

Security Notes

• The OMDb API key is never hard-coded anywhere in the source code.
• The key is loaded exclusively from the OMDB_API_KEY environment variable (via a local .env file during development).
• .env is included in .gitignore and must never be committed.
• Only .env.example (with a placeholder value) is included in the repository.
• If you believe your API key has been exposed, regenerate it from your OMDb account and update your local .env file.

Future Improvements

• Add support for searching TV series and episodes
• Add pagination for search results with more than 10 matches
• Add a simple text-based rating/review system for favorites
• Add caching to reduce redundant API calls
• Add a packaged CLI entry point (e.g. via pip install -e .)
• Add colorized terminal output

License

This project is licensed under the MIT License - see the LICENSE file for details.