Metadata-Version: 2.4
Name: descraper
Version: 0.2.0
Summary: A robust web scraping pipeline with smart static/dynamic fallback and semantic text classification.
Home-page: https://github.com/unan/descraper
Author: Ugurhan Colak
Author-email: ugurhancolak5544@gmail.com
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: beautifulsoup4
Requires-Dist: selenium
Requires-Dist: webdriver-manager
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# DeScraper 🕷️

**The Intelligent, AI-Ready Web Scraping Pipeline**

[![PyPI version](https://badge.fury.io/py/descraper.svg)](https://badge.fury.io/py/descraper)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

**DeScraper** is a resilient and intelligent Python library designed for the modern web. Unlike traditional scrapers, it semantically analyzes content, automatically handles dynamic (JavaScript-heavy) sites, and produces clean, structured data perfect for LLM / RAG applications.

---

<details>
<summary><strong>🇬🇧 English Documentation</strong> (Click to expand)</summary>

### Why DeScraper?

If you've ever built a scraper, you've faced these problems:
1.  **Dynamic Sites:** You get empty HTML because the content is rendered with React/Vue.
2.  **Noisy Data:** Navigation menus, footers, and ad text get mixed with the main article.
3.  **Bot Blocks:** Simple HTTP requests are blocked with a 403 error.

**DeScraper solves these for you:**
*   🚀 **Smart Strategy:** It first tries a fast static request (`requests`). If the site requires JavaScript or the content looks sparse, it automatically switches to a full browser engine (`selenium`).
*   🧠 **AI-Ready Output:** It doesn't just strip HTML tags. It intelligently detects headings, paragraphs, lists, and **tables**, generating a clean, markdown-like text in the `content` field—perfect for feeding into a RAG pipeline or fine-tuning an LLM.
*   🛡️ **Production-Ready:** Built-in features like automatic retries, configurable timeouts, and User-Agent management make it robust for real-world use.

### Installation

```bash
pip install descraper
```
*Note: The dynamic mode requires Firefox. The necessary driver is downloaded automatically.*

### Usage

#### 1. As a Python Library (Recommended)

The simplest way to use DeScraper:

```python
from descraper import run_scrape

url = "https://en.wikipedia.org/wiki/List_of_Byzantine_emperors"

# 'smart' mode is default: tries static, falls back to dynamic if needed.
data = run_scrape(url)

if data:
    # 1. AI-Ready Clean Content
    print("--- Clean Content for AI/RAG ---")
    print(data['content']) 
    # Example Output:
    # # List of Byzantine emperors
    # This is a list of the Byzantine emperors from the foundation of Constantinople...
    #
    # ## Palaiologan dynasty (1261–1453)
    # | Emperor | Reign | Notes |
    # | --- | --- | --- |
    # | Michael VIII Palaiologos | 1261–1282 | Reconquered Constantinople... |
    
    # 2. Metadata
    print(f"\nTitle: {data['title']}")
    print(f"Image Count: {len(data['images'])}")
```

#### 2. CLI Usage

For quick tests or getting a JSON output directly:

```bash
# Print to screen
web-scraper https://www.python.org

# Save to file
web-scraper https://www.python.org -o result.json

# Run in dynamic mode with a 10-second scroll/wait time
web-scraper "https://medium.com/tag/python" -s dynamic -w 10
```

### Output Structure (JSON)

DeScraper returns a rich dictionary:

```json
{
  "url": "https://...",
  "title": "Page Title",
  "meta_description": "SEO description...",
  "content": "# Title\n\nThe main article text, cleaned and formatted in markdown, including tables...",
  "structured_text": [
    {"type": "heading_h1", "text": "Page Title", "tag": "h1"},
    {"type": "article_paragraph", "text": "First paragraph...", "tag": "p"}
  ],
  "links": {
    "internal": ["https://..."],
    "external": ["https://google.com..."]
  },
  "images": [{"src": "...", "alt": "..."}]
}
```

</details>

<br>

<details>
<summary><strong>🇹🇷 Türkçe Dokümantasyon</strong> (Genişletmek için tıklayın)</summary>

### Neden DeScraper?

Eğer daha önce bir scraper yazdıysanız, şu sorunlarla kesinlikle karşılaştınız:
1.  **Dinamik Siteler:** İçerik React/Vue ile oluşturulduğu için elinize boş HTML gelir.
2.  **Kirli Veri:** Menüler, altbilgiler (footer) ve reklam metinleri, asıl makaleye karışır.
3.  **Bot Korumaları:** Basit HTTP istekleri 403 hatasıyla engellenir.

**DeScraper bunları sizin yerinize çözer:**
*   🚀 **Akıllı Strateji:** Önce hızlı statik yöntemle (`requests`) dener. Eğer site JavaScript gerektiriyorsa veya içerik zayıfsa, otomatik olarak tam bir tarayıcı motoruna (`selenium`) geçer.
*   🧠 **Yapay Zekaya Hazır Çıktı:** Sadece HTML etiketlerini temizlemez. Başlıkları, paragrafları, listeleri ve **tabloları** akıllıca tespit ederek `content` alanında yapay zekaya vermeye uygun, **markdown benzeri** temiz bir metin üretir. Bu çıktı, RAG (Retrieval-Augmented Generation) sistemleri veya LLM (Büyük Dil Modeli) eğitimi için idealdir.
*   🛡️ **Production Seviyesinde:** Otomatik tekrar deneme (retry), ayarlanabilir zaman aşımı (timeout) ve User-Agent yönetimi gibi yerleşik özelliklerle gerçek dünya kullanımı için dayanıklıdır.

### Kurulum

```bash
pip install descraper
```
*Not: Dinamik mod için Firefox tarayıcısı gereklidir. Gerekli sürücü otomatik olarak indirilir.*

### Kullanım

#### 1. Python Kütüphanesi Olarak (Önerilen)

En basit haliyle kullanımı:

```python
from descraper import run_scrape

url = "https://tr.wikipedia.org/wiki/Bizans_imparatorları_listesi"

# 'smart' modu varsayılandır: Önce static dener, gerekirse dynamic'e geçer.
data = run_scrape(url)

if data:
    # 1. AI/RAG için Temiz İçerik
    print("--- AI İçin Temiz Metin ---")
    print(data['content']) 
    # Örnek Çıktı:
    # # Bizans imparatorları listesi
    # Bu madde, Konstantinopolis'in imparatorluk başkenti olarak kurulmasından...
    #
    # ## Palaiologos Hanedanı (1261-1453)
    # | Resim | İsim | Hüküm süresi | Notlar |
    # | --- | --- | --- | --- |
    # | | VIII. Mihail | 1261-1282 | Konstantinopolis'i Latinlerden geri aldı... |
    
    # 2. Metadata
    print(f"\nBaşlık: {data['title']}")
    print(f"Görsel Sayısı: {len(data['images'])}")
```

#### 2. Komut Satırı (CLI)

Hızlıca bir URL'i test etmek veya JSON çıktısı almak için:

```bash
# Ekrana basar
web-scraper https://www.python.org

# Dosyaya kaydeder
web-scraper https://www.python.org -o sonuc.json

# Dinamik modda, 10 saniye scroll yaparak çalıştırır
web-scraper "https://medium.com/tag/python" -s dynamic -w 10
```

### Çıktı Yapısı (JSON)

DeScraper aşağıdaki formatta zengin bir sözlük (dictionary) döndürür:

```json
{
  "url": "https://...",
  "title": "Sayfa Başlığı",
  "meta_description": "SEO açıklaması...",
  "content": "# Başlık\n\nTablolar dahil, temizlenmiş ve markdown formatında ana metin...",
  "structured_text": [
    {"type": "heading_h1", "text": "Sayfa Başlığı", "tag": "h1"},
    {"type": "article_paragraph", "text": "İlk paragraf...", "tag": "p"}
  ],
  "links": {
    "internal": ["https://..."],
    "external": ["https://google.com..."]
  },
  "images": [{"src": "...", "alt": "..."}]
}
```

</details>

---

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
