dark-req

🇪🇬 بالعربي

dark-req مكتبة بايثون للتعامل مع HTTP، شغالة بنفس طريقة مكتبة requests المشهورة — بس بتصلّح كل عيوبها، ومن غير أي تعقيد زيادة.

ليه dark-req؟

• ⏱️ مهلة افتراضية ذكية: الاتصال 5 ثواني والقراءة 30 ثانية — عمرها ما هتعلّق للأبد زي requests
• 🔁 إعادة محاولة تلقائية: لو السيرفر رد 429 أو 5xx أو الاتصال وقع، بتحاول لوحدها مع انتظار متزايد وبتحترم Retry-After
• 🚦 تحديد معدل الطلبات: rate_limit=5 يعني 5 طلبات في الثانية لكل سيرفر
• 🔗 رابط أساسي للجلسة: base_url="https://api.example.com" وبعدها نادي /users بس
• 🪝 خطافات (Hooks): نفّذ كود قبل الطلب وبعده وعند الخطأ
• ⬇️ تحميل ب progress: سطر واحد بدل ما تكتب loop بنفسك
• ⚡ دعم Async: نفس الواجهة بالظبط مع AsyncSession
• 🔐 توثيق جاهز: BearerAuth("token") أو (user, pass)

مثال سريع

import dark_req

# شغالة زي requests بالظبط...
r = dark_req.get("https://api.example.com/users", timeout=10)
print(r.status_code, r.json())

# ...بس بقدرات زيادة
s = dark_req.Session(
    base_url="https://api.example.com",
    max_retries=3,          # إعادة محاولة تلقائية
    rate_limit=5,           # 5 طلبات/ثانية لكل سيرفر
    hooks={"on_error": [lambda e: print("failed:", e)]},
)
r = s.get("/users", params={"page": 2})
r.raise_for_status()

# تحميل ملف مع progress في سطر واحد
s.download("https://example.com/big.zip", "big.zip",
           progress=lambda done, total: print(f"{done}/{total}"))

# Async بنفس الواجهة
import asyncio
async def main():
    async with dark_req.AsyncSession(base_url="https://api.example.com") as s:
        users, repos = await asyncio.gather(s.get("/users"), s.get("/repos"))
asyncio.run(main())

التثبيت

pip install dark-req

بتحتاج Python 3.9 أو أحدث.

🇬🇧 In English

dark-req is a requests-compatible Python HTTP client that fixes everything requests gets wrong — in the same lightweight footprint (only urllib3 + certifi).

Why dark-req?

• ⏱️ Sane default timeouts: 5s connect / 30s read — never hangs forever like requests
• 🔁 Auto-retry: on 429/5xx and network errors, with exponential backoff + jitter, honors Retry-After
• 🚦 Per-host rate limiting: rate_limit=5 = 5 req/sec per host (token bucket)
• 🔗 base_url sessions: set it once, then just call /users
• 🪝 Hooks: on_request / on_response / on_error
• ⬇️ Downloads with progress: one line instead of a manual streaming loop
• ⚡ Async support: AsyncSession with the exact same API
• 🔐 Auth helpers: BearerAuth("token") or (user, pass) tuples

Quick example

import dark_req

# Works exactly like requests...
r = dark_req.get("https://api.example.com/users", timeout=10)
print(r.status_code, r.json())

# ...but with superpowers baked in
s = dark_req.Session(
    base_url="https://api.example.com",
    max_retries=3,          # auto-retry on 429/5xx + connection errors
    rate_limit=5,           # max 5 req/sec per host (token bucket)
    hooks={"on_error": [lambda e: print("failed:", e)]},
)
r = s.get("/users", params={"page": 2})   # -> https://api.example.com/users?page=2
r.raise_for_status()

# Downloads with progress, one line
s.download("https://example.com/big.zip", "big.zip",
           progress=lambda done, total: print(f"{done}/{total}"))

# Async, same API
import asyncio
async def main():
    async with dark_req.AsyncSession(base_url="https://api.example.com") as s:
        users, repos = await asyncio.gather(s.get("/users"), s.get("/repos"))
asyncio.run(main())

Install

pip install dark-req

Requires Python 3.9+.

⚔️ dark-req vs requests

Everything else stays familiar: get/post/put/patch/delete/head/options, Session, Request/PreparedRequest/Response, HTTPBasicAuth, and an exception hierarchy mirroring requests (so existing except blocks keep working).

Sane defaults / إعدادات ذكية

dark_req.get("https://slow.example.com")   # gives up after 5s connect / 30s read
dark_req.get("https://flaky.example.com")  # 3 automatic retries with backoff

Override per call with timeout=... (seconds, (connect, read) tuple, or timeout=None to wait indefinitely), max_retries=0 to disable retries, verify=False to skip TLS verification.

Roadmap / خطة التطوير

• files= multipart uploads
• Proxy support from environment variables
• HTTP/2 transport option
• Connection-level metrics / tracing hooks

License / الرخصة

MIT