Metadata-Version: 2.4
Name: urldrop
Version: 1.0.2
Summary: A visual URL batch downloader tool
License: MIT
Requires-Python: >=3.8
Requires-Dist: requests
Requires-Dist: tqdm
Description-Content-Type: text/markdown

<div align="center">

<img src="https://img.shields.io/badge/python-3.8+-5b6ef5?style=for-the-badge&logo=python&logoColor=white" />
<img src="https://img.shields.io/badge/license-MIT-8b5cf6?style=for-the-badge" />
<img src="https://img.shields.io/badge/version-1.0.0-22c55e?style=for-the-badge" />

# ⬇ URLDrop

**Batch download files from a URL list — fast, simple, zero config.**

[Getting Started](#-getting-started) · [Usage](#-usage) · [Options](#%EF%B8%8F-options) · [UI Tool](#-ui-tool) · [PyPI](#-install-via-pypi)

</div>

---

## What it does

URLDrop reads a plain text file of URLs and downloads everything in it — PDFs, images, ZIPs, anything. It skips files you already have, retries failed downloads, and saves a full report when it's done.

```
https://example.com/report.pdf      ✓ downloaded
https://example.com/photo.jpg       ✓ downloaded
https://example.com/broken-link     ✗ failed (saved to report.txt)
```

---

## 📂 Project Structure

When you set up URLDrop, your folder will look like this:

```
url-downloader/
├── downloader.py        ← main script
├── index.html           ← visual UI (open in browser)
├── style.css            ← UI styles
├── urls.txt             ← your URL list (you create this)
├── downloads/           ← saved files  (auto-created)
└── report.txt           ← run summary  (auto-created)
```

---

## 🚀 Getting Started

**Requirements:** Python 3.8+

**Step 1: Install dependencies**

```bash
pip install requests tqdm
```

Or install the package directly from PyPI:

```bash
pip install urldrop
```

No database, no server, no config file needed.

---

## 📋 Usage

**Step 1: Create your `urls.txt` file with one URL per line:**

```
https://example.com/file.pdf
https://example.com/image.png
https://example.com/archive.zip

# Lines starting with # are comments — ignored at runtime
```

**Step 2: Run the downloader:**

```bash
python downloader.py
```

**Step 3: Done!** Files land in `downloads/` and a full summary is written to `report.txt`.

---

## ⚙️ Options

| Argument    | Default     | Description                               |
| ----------- | ----------- | ----------------------------------------- |
| `--urls`    | `urls.txt`  | Path to your URL list                     |
| `--output`  | `downloads` | Folder to save downloaded files into      |
| `--retries` | `3`         | How many times to retry a failed download |
| `--timeout` | `30`        | Seconds before a request times out        |
| `--skip`    | `true`      | Skip files that already exist locally     |

**Example with custom options:**

```bash
python downloader.py --urls my_links.txt --output my_files --retries 5 --timeout 60
```

---

## 🖥 UI Tool

Don't want to edit `urls.txt` by hand? URLDrop comes with a browser-based UI. Just open `index.html` and you get:

- Paste or upload URLs visually
- Instant image thumbnail preview
- List and grid view toggle
- One-click `urls.txt` export with your options baked in

```bash

urldrop


open index.html
```

---

## 📦 Install via PyPI

```bash
pip install urldrop
urldrop
```

---

## 📁 Output Files

After a run, these files are created automatically:

| File         | Contents                                                      |
| ------------ | ------------------------------------------------------------- |
| `report.txt` | Full summary — total attempted, succeeded, failed, time taken |
| `downloads/` | All successfully downloaded files, named from their URLs      |

Failed URLs are not lost — they're printed at the end of the run. Simply keep them in `urls.txt` and run again to retry.

---

## 🚨 Error Handling

Things go wrong — here's how URLDrop handles them:

| Error                   | What Happens                                                                             | Where to Look   |
| ----------------------- | ---------------------------------------------------------------------------------------- | --------------- |
| Broken or dead URL      | Waits (exponential back-off) and retries up to `--retries` times, then logs the failure. | `report.txt`    |
| No internet connection  | Retries with back-off. If all retries fail, the URL is skipped and logged.               | `report.txt`    |
| File already downloaded | Skipped automatically if `--skip` is `true`. Re-download by setting `--skip false`.      | Terminal output |
| Timeout exceeded        | Request is cancelled and the URL is retried. Increase `--timeout` for slow servers.      | Terminal output |
| Malformed URL in list   | Skipped with a warning. Check your `urls.txt` for typos or missing `https://`.           | Terminal output |

---

## ❓ FAQ

**1. What file types can URLDrop download?**
Anything accessible via a direct URL — PDFs, images (JPG, PNG, GIF, WebP), ZIPs, MP4s, CSVs, and more. If a browser can download it, so can URLDrop.

**2. Will it overwrite files I already downloaded?**
No. By default (`--skip true`), URLDrop checks if a file with the same name already exists in the output folder and skips it. Set `--skip false` to force re-downloading.

**3. Can I download from password-protected or login-required pages?**
Not currently. URLDrop sends simple unauthenticated HTTP requests. URLs that require cookies or a login session will fail.

**4. What happens if my script crashes halfway through?**
Check `report.txt` to see what already succeeded. Remove those URLs from your `urls.txt` and run again — or just run again with `--skip true` (the default) so already-downloaded files are safely skipped.

**5. I'm getting `ModuleNotFoundError: No module named 'requests'`. What do I do?**
Run `pip install requests tqdm` to install the required dependencies, then try again.

**6. Can I comment out URLs without deleting them?**
Yes! Any line starting with `#` is treated as a comment and ignored. Useful for temporarily disabling a URL without losing it.

---

## 📜 License

This project is licensed under the MIT License. Feel free to use it, modify it, and share it!

---

## 👤 Author

Developed by Aiswarya Pokharel

<div align="center">
  <sub>Built with Python · No nonsense · Just downloads</sub>
</div>
