Metadata-Version: 2.4
Name: linkify-media
Version: 0.1.0
Summary: Async movie/TV metadata fetcher — TMDB, IMDb, RT, Letterboxd
Author-email: Shadow Dev <your@email.com>
License: MIT License
        
        Copyright (c) 2026 Code2Encoder aka Shadow Dev
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Abdullahkhan000/Linkify-Media
Project-URL: Repository, https://github.com/Abdullahkhan000/Linkify-Media
Keywords: tmdb,movies,tv,metadata,async,cli
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9
Requires-Dist: python-decouple>=3.8
Dynamic: license-file

# 🎬 Linkify-Media

[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?style=flat&logo=python&logoColor=white)](https://www.python.org)
[![Async](https://img.shields.io/badge/Async-aiohttp-blue.svg?style=flat)](https://docs.aiohttp.org/)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg?style=flat&logo=docker&logoColor=white)](https://hub.docker.com)
[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-2ea44f?style=flat)](https://github.com/Abdullahkhan000/Linkify-Media/issues)
[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](LICENSE)

<div align="center">
  <img src="assets/banner.png" alt="Linkify Media Banner" width="100%" />
  <p>
    <b>Async TMDB · IMDb · Rotten Tomatoes · Metacritic · Letterboxd</b><br>
    Fast CLI · Clean JSON · Docker Ready · API Ready · Zero 404 RT Links
  </p>
</div>

---

## 📌 About

**Linkify Media** is a high-performance **Async CLI utility** that fetches complete metadata and verified platform links for **Movies & TV Series** using the **TMDB API**.

Built for:
- Backend APIs
- Media platforms
- Automation scripts
- Portfolio projects
- Data enrichment pipelines

Powered by:
- ⚡ `aiohttp` (async requests)
- 🎯 Smart slug generation
- 🛡️ Rotten Tomatoes link validation
- 💾 In-memory caching
- 🖥️ Proper CLI with `argparse`
- 🐳 Docker support

---

## ✨ Key Features

| Feature | Status | Description |
| :--- | :---: | :--- |
| **Async Engine** | ⚡ | Concurrent API calls using `asyncio` |
| **Full Metadata** | 🎬 | Title, Year, Genres, Runtime, Rating |
| **Top Cast Fetching** | 👥 | First 5 credited actors |
| **Poster Support** | 🖼️ | TMDB poster image URL |
| **Multi-Platform Links** | 🔗 | TMDB, IMDb, RT, Metacritic, Letterboxd |
| **RT Validation** | 🛡️ | Prevents broken Rotten Tomatoes URLs |
| **CLI Arguments** | 🖥️ | `--media`, `--json` support |
| **Caching** | 💾 | In-memory caching for performance |
| **Docker Support** | 🐳 | Run anywhere without local setup |
| **Package Structure** | 📦 | Clean, importable Python package |
| **API Ready** | 🚀 | Easy to plug into Django / FastAPI |

---

## 📦 Platforms Generated

- ✅ TMDB
- ✅ IMDb
- ✅ Rotten Tomatoes (validated)
- ✅ Metacritic
- ✅ Letterboxd (movies only)
- ✅ JustWatch (PK region)

---

## 🗂️ Project Structure

```
linkify-media/
├── linkify_media/
│   ├── __init__.py       # Package entry point
│   ├── utils.py          # slugify, fetch helpers
│   ├── core.py           # TMDB logic + link generation
│   └── cli.py            # argparse CLI
├── assets/
├── .dockerignore
├── .env                  # TMDB_API_KEY (never commit this)
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── LICENSE
├── README.md
├── requirements.txt
└── pyproject.toml
```

---

## 🚀 Installation & Setup

### Option A — Local (Python)

**1. Clone Repository**

```bash
git clone https://github.com/Abdullahkhan000/Linkify-Media
cd Linkify-Media
```

**2. Create Virtual Environment**

```bash
# Windows
python -m venv .venv
.venv\Scripts\activate

# Mac / Linux
python3 -m venv .venv
source .venv/bin/activate
```

**3. Install Dependencies**

```bash
pip install -r requirements.txt
pip install .
```

**4. Configure API Key**

Create `.env` in project root:

```
TMDB_API_KEY=your_actual_api_key_here
```

> ⚠️ Never commit `.env` — it's already in `.gitignore`

Get your free API key at [themoviedb.org/settings/api](https://www.themoviedb.org/settings/api)

---

### Option B — Docker 🐳

No Python setup needed. Just Docker + your API key.

**1. Clone & create `.env`**

```bash
git clone https://github.com/Abdullahkhan000/Linkify-Media
cd Linkify-Media
echo TMDB_API_KEY=your_key_here > .env
```

**2. Build image**

```bash
docker build -t linkify-media .
```

**3. Run**

```bash
# Movie
docker run --env-file .env linkify-media "Inception" --media movie

# TV Show
docker run --env-file .env linkify-media "The Bear" --media tv

# Save JSON output
docker run --env-file .env -v ${PWD}/output:/app/output linkify-media "Dune" --json
```

> 💡 **Windows PowerShell** users: use `${PWD}` not `$(pwd)` for volume mounts

---

## 🖥️ Usage (CLI)

```bash
# Movie (default)
linkify-media "Inception"

# TV Series
linkify-media "Breaking Bad" --media tv

# Save output as JSON file
linkify-media "Dune" --media movie --json
```

---

## 📤 Sample Output

```json
{
    "Official Title": "Inception",
    "Release Year": "2010",
    "Genres": ["Action", "Science Fiction", "Adventure"],
    "Runtime (mins)": 148,
    "TMDB Rating": "8.369 (38000 votes)",
    "Poster URL": "https://image.tmdb.org/t/p/w500/oYuLEt3zVCKq57qu2F8dT7NIa6f.jpg",
    "Top Cast": ["Leonardo DiCaprio", "Joseph Gordon-Levitt", "Elliot Page", "Tom Hardy", "Ken Watanabe"],
    "TMDB Link": "https://www.themoviedb.org/movie/27205",
    "IMDb Link": "https://www.imdb.com/title/tt1375666/",
    "Rotten Tomatoes": "https://www.rottentomatoes.com/m/inception",
    "Metacritic": "https://www.metacritic.com/search/movie/inception/results",
    "Letterboxd": "https://letterboxd.com/film/inception/",
    "JustWatch (PK)": "https://www.justwatch.com/pk/search?q=Inception"
}
```

---

## 🧠 Architecture

```
linkify_media/
│
├── utils.py
│   ├── slugify()          # Clean URL-safe slugs
│   ├── fetch_json()       # Async GET requests
│   └── head_exists()      # URL validation (RT check)
│
├── core.py
│   ├── fetch_tmdb_data()  # Async TMDB search + details + credits
│   ├── generate_links()   # Platform links + RT validation + caching
│   └── CACHE              # In-memory cache dict
│
└── cli.py
    └── main()             # argparse CLI entrypoint
```

---

## 🧩 Use Cases

- Backend Movie APIs
- Django REST integration
- FastAPI async endpoints
- Media dashboards
- Streaming aggregation tools
- Data scraping & enrichment pipelines

---

## 🔜 Roadmap

- [x] Async engine
- [x] Docker support
- [x] Python package structure
- [ ] PyPI release
- [ ] Redis caching
- [ ] Batch processing mode
- [ ] FastAPI version
- [ ] Trailer support (YouTube API)

---

## 🤝 Contributing

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

---

## ❤️ Support the Project

If this project saves you time or helps your workflow, consider supporting its development.

[![Patreon](https://img.shields.io/badge/Support-Patreon-orange?style=flat&logo=patreon)](https://www.patreon.com/c/code2encoder)

Your support helps add new features, improve performance, and maintain long-term updates.

---

## 📄 License

Licensed under the **MIT License** — free to use, modify, and distribute.

---

⭐ Star the repo if you find it useful!

<div align="center">
  <p>🚀 Proudly made by <b>code2encoder aka Shadow Dev</b> 🚀</p>
</div>
