Metadata-Version: 2.4
Name: NullGaze
Version: 1.0.0
Summary: A highly resilient image downloading library that bypasses DPI/SNI blocks, Cloudflare, TLS fingerprinting, and hotlinking protections.
Home-page: https://github.com/batal/NullGaze
Author: Batal
Author-email: batal@example.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: curl_cffi>=0.5.0
Provides-Extra: browser
Requires-Dist: DrissionPage>=4.0.0; extra == "browser"
Provides-Extra: full
Requires-Dist: curl_cffi>=0.5.0; extra == "full"
Requires-Dist: DrissionPage>=4.0.0; extra == "full"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NullGaze 👁️‍🗨️

**مكتبة بايثون ثورية لتحميل الصور من أي رابط مهما كانت الحمايات.**

تتخطى حجب مزودي الإنترنت (ISP SNI Blocks)، وحمايات Cloudflare، ومنع الربط المباشر (Hotlinking)، وبصمات TLS — بسرعة مجنونة تصل إلى أجزاء من الثانية.

---

## ⚡ التثبيت السريع

```bash
pip install NullGaze
```

أو للتثبيت الكامل مع دعم المتصفح الخفي:
```bash
pip install NullGaze[full]
```

أو التثبيت المحلي من المصدر:
```bash
cd NullGaze
pip install -e .
```

---

## 🚀 طريقة الاستخدام

```python
from nullgaze import download_image

# سطر واحد فقط لتحميل أي صورة محمية
download_image(
    url="https://cdn4.webtoonscan.com/erotic-manga-cafe-girls-raw-15264/chapter-20/17.jpg",
    output_path="my_image.jpg",
    verbose=True
)
print("تم التحميل بنجاح!")
```

### استخدام متقدم مع كلاس ImageDownloader

```python
from nullgaze import ImageDownloader

downloader = ImageDownloader(verbose=True)

# تحميل صورة واحدة
downloader.download(
    url="https://example.com/protected/image.jpg",
    output_path="output/image.jpg"
)

# تحميل عدة صور
urls = [
    "https://cdn.example.com/img1.jpg",
    "https://cdn.example.com/img2.jpg",
    "https://cdn.example.com/img3.jpg",
]

for i, url in enumerate(urls):
    try:
        downloader.download(url, f"output/image_{i+1}.jpg")
        print(f"✅ Image {i+1} downloaded!")
    except Exception as e:
        print(f"❌ Image {i+1} failed: {e}")
```

### إضافة ترويسات مخصصة

```python
from nullgaze import download_image

custom_headers = {
    "Referer": "https://mywebsite.com/",
    "Cookie": "session_id=abc123"
}

download_image(
    url="https://protected-cdn.example.com/image.png",
    output_path="result.png",
    headers=custom_headers
)
```

---

## 🧠 كيف تعمل المكتبة (نظام التخطي المتعدد المستويات)

| المستوى | الاسم | السرعة | الوصف |
|---------|-------|--------|-------|
| 1 | Direct HTTP Request | ⚡⚡⚡ | طلب مباشر بترويسات متصفح ذكية |
| 2 | **DPI-Bypass TLS Impersonation** | ⚡⚡⚡ | **الطريقة الثورية**: تقسيم حزمة ClientHello + انتحال بصمة Chrome |
| 3 | Stealth Browser Rendering | ⚡ | متصفح Chromium خفي مع استخراج بكسلات Canvas |
| 4 | Weserv Image Proxy | ⚡⚡ | توجيه عبر بروكسي تخزين مؤقت |

> **ملاحظة**: المستوى الثاني هو الابتكار الثوري الأساسي. يقوم بتشغيل بروكسي محلي خفيف على جهازك يقسم حزمة مصافحة TLS إلى جزأين، مما يخدع جدار حماية مزود الإنترنت ويمنعه من قراءة اسم النطاق المحجوب (SNI). اقرأ [التوثيق التقني الكامل](nullgaze/DPI_BYPASS_DOC.md) لفهم الآلية.

---

## 📦 دليل نشر المكتبة على PyPI (للمبتدئين خطوة بخطوة)

### الخطوة 1: إنشاء حساب على PyPI
1. افتح الموقع: https://pypi.org/account/register/
2. سجّل بإيميلك وأنشئ كلمة مرور.
3. فعّل الحساب من الإيميل.
4. ادخل على **Account Settings** → **API tokens** → **Add API token**.
5. اختر الاسم مثلاً `nullgaze-token` والنطاق `Entire account`.
6. **انسخ الرمز** الذي يبدأ بـ `pypi-` واحفظه في مكان آمن. هذا هو كلمة مرورك للرفع.

### الخطوة 2: تثبيت أدوات البناء والرفع
```bash
pip install --upgrade build twine
```

### الخطوة 3: بناء الحزمة
تأكد أنك داخل مجلد `NullGaze` (الذي فيه `setup.py`):
```bash
cd C:\Users\batal\Desktop\cwewd21\NullGaze
python -m build
```
سيظهر مجلد جديد اسمه `dist/` فيه ملفات `.whl` و `.tar.gz`.

### الخطوة 4: رفع المكتبة إلى PyPI
```bash
python -m twine upload dist/*
```
- **Username**: اكتب `__token__`
- **Password**: الصق الرمز (API Token) الذي يبدأ بـ `pypi-`

🎉 **مبروك!** مكتبتك الآن متاحة للعالم كله:
```bash
pip install NullGaze
```

---

## 🔄 كيف تحدّث المكتبة (بعد إضافة ميزات جديدة)

### الخطوة 1: غيّر رقم الإصدار
افتح ملف `setup.py` وغيّر الرقم:
```python
version="1.0.1"  # كان 1.0.0، الآن 1.0.1
```
وافتح ملف `nullgaze/__init__.py` وغيّر:
```python
__version__ = "1.0.1"
```

### الخطوة 2: احذف الملفات القديمة
```bash
rmdir /s /q dist build NullGaze.egg-info
```

### الخطوة 3: أعد البناء والرفع
```bash
python -m build
python -m twine upload dist/*
```

---

## 📥 كيف يثبّت المستخدمون مكتبتك

```bash
# التثبيت الأساسي (يكفي لمعظم الحالات)
pip install NullGaze

# التثبيت الكامل مع دعم المتصفح الخفي
pip install NullGaze[full]

# التحديث لآخر إصدار
pip install --upgrade NullGaze
```

---

## 📄 الترخيص

MIT License — مكتبة مفتوحة المصدر، استخدمها كما تشاء.
