اگر تا امروز با کتابخانه requests کار کرده‌اید و حالا با پروژه‌هایی مواجه شده‌اید که نیاز به سرعت بیشتر، پشتیبانی از HTTP/2 یا درخواست‌های هم‌زمان (Async) دارند، HTTPX دقیقاً همان ابزاری است که جای خالی‌اش حس می‌شد. این کتابخانه مدرن پایتون، همان API ساده و محبوب requests را حفظ کرده اما با پشتیبانی کامل از async/await، تایپ‌هینت و پروتکل‌های جدید، شما را برای وب امروز و فردا آماده می‌کند.

کتابخانه HTTPX در پایتون چیست و چرا جایگزین requests شده؟

HTTPX یک کلاینت HTTP فول‌فیچر برای پایتون است که هم به صورت همگام (Sync) و هم ناهمگام (Async) کار می‌کند، از HTTP/1.1 و HTTP/2 پشتیبانی می‌کند و API آن عمداً شبیه requests طراحی شده تا مهاجرت بدون دردسر باشد. اگر به دنبال سرعت بیشتر و کدنویسی مدرن با async هستید، HTTPX بهترین انتخاب فعلی است. در ادامه نصب، مثال‌های عملی و مقایسه کامل را می‌بینید.

فهرست مطالب

HTTPX چیست و چرا باید از آن استفاده کنیم؟
پیش‌نیازها و نصب HTTPX
اولین درخواست همگام با HTTPX
درخواست‌های ناهمگام با AsyncClient
قابلیت‌های پیشرفته که در requests نیست
مقایسه HTTPX، requests و aiohttp
اشتباهات رایج هنگام کار با HTTPX
سوالات متداول
جمع‌بندی

HTTPX چیست و چرا باید از آن استفاده کنیم؟

HTTPX توسط Tom Christie (خالق Django REST Framework و Starlette) ساخته شده و هدفش پر کردن شکاف بین سادگی requests و نیازهای مدرن پایتون است. در حالی که requests از سال ۲۰۱۱ فقط حالت همگام دارد و دیگر توسعه فعال سنگینی ندارد، HTTPX از ابتدا برای پایتون ۳.۸ به بالا، تایپ‌هینت کامل و asyncio طراحی شده است.

سه دلیل اصلی برای مهاجرت:

یک API برای دو دنیا: با یک کتابخانه هم کد همگام بنویسید و هم ناهمگام. دیگر لازم نیست برای async سراغ aiohttp بروید و دو سینتکس متفاوت یاد بگیرید.
پشتیبانی از HTTP/2 و HTTP/1.1: برای APIهایی که HTTP/2 ارائه می‌دهند، به صورت خودکار سریع‌تر عمل می‌کند؛ requests فقط HTTP/1.1 دارد.
تجربه توسعه‌دهنده بهتر: تایم‌اوت‌های دقیق، مدیریت کلاینت، پشتیبانی از پروکسی، احراز هویت، کوکی و حتی درخواست‌های streaming به شکل تمیز.

تفاوت کلیدی HTTPX با requests

از نظر استفاده روزمره، httpx.get(url) دقیقاً مثل requests.get(url) کار می‌کند. تفاوت اصلی زیر کاپوت است: HTTPX بر پایه httpx و httpcore ساخته شده و از anyio برای سازگاری با asyncio و trio استفاده می‌کند. همچنین Client در HTTPX قابل استفاده به عنوان context manager است تا اتصال‌ها reuse شوند و پرفورمنس بالا برود. در پروژه‌های تحلیل داده، وقتی صدها درخواست به API می‌زنید، این reuse تفاوت ثانیه‌ای ایجاد می‌کند. اگر قبلاً با آموزش Pandas در پایتون کار کرده‌اید و داده‌ها را از وب می‌گیرید، ترکیب Pandas + HTTPX Async سرعت pipeline شما را چند برابر می‌کند.

پیش‌نیازها و نصب HTTPX

برای شروع فقط به پایتون ۳.۸ یا بالاتر نیاز دارید. اگر از محیط مجازی استفاده نمی‌کنید، همین حالا بسازید؛ HTTPX وابستگی سنگینی ندارد.

نصب با pip و uv

pip install httpx
# یا با http2
pip install "httpx[http2]"

# اگر از uv استفاده می‌کنید (سریع‌تر)
uv pip install "httpx[http2]"

نکته: برای فعال‌سازی HTTP/2 حتماً اکسترا http2 را نصب کنید. در غیر این صورت HTTPX به صورت خودکار روی HTTP/1.1 می‌ماند ولی خطا نمی‌دهد.

برای بررسی نصب:

python -c "import httpx; print(httpx.__version__)"

اگر نسخه ۰.۲۷ به بالا دیدید، آماده‌اید. نسخه‌های اخیر API پایداری دارند و مستندات رسمی www.python-httpx.org را مبنا قرار دهید.

اولین درخواست همگام با HTTPX

ساده‌ترین حالت دقیقاً مثل requests است. این مثال یک GET به httpbin می‌زند و JSON را چاپ می‌کند:

import httpx

response = httpx.get("https://httpbin.org/json", timeout=10.0)
print(response.status_code)  # 200
print(response.headers["content-type"])
data = response.json()
print(data["slideshow"]["title"])

اما برای چند درخواست بهتر است از httpx.Client استفاده کنید تا کانکشن reuse شود:

import httpx

with httpx.Client(timeout=10.0, headers={"User-Agent": "tooai-httpx/1.0"}) as client:
    r1 = client.get("https://httpbin.org/get")
    r2 = client.get("https://httpbin.org/ip")
    print(r1.json()["url"])
    print(r2.json()["origin"])

مزیت Client این است که هدرها، کوکی‌ها و تایم‌اوت را یک بار تنظیم می‌کنید. همچنین برای ارسال POST با JSON:

with httpx.Client() as client:
    resp = client.post("https://httpbin.org/post", json={"name": "Ali", "lang": "python"})
    print(resp.json()["json"])

تفاوت با requests در جزئیات است: در HTTPX تایم‌اوت به صورت پیش‌فرض ۵ ثانیه نیست و اگر تعیین نکنید، ممکن است درخواست‌ها بی‌نهایت منتظر بمانند؛ حتماً timeout بدهید.

درخواست‌های ناهمگام با HTTPX Async

قدرت اصلی HTTPX اینجاست. فرض کنید باید ۵۰ صفحه API را بخوانید. با requests به صورت ترتیبی ۵۰ ثانیه طول می‌کشد، با Async شاید ۵ ثانیه:

import asyncio
import httpx

async def fetch_one(client, url):
    resp = await client.get(url)
    return resp.json()

async def main():
    urls = [f"https://httpbin.org/get?page={i}" for i in range(5)]
    async with httpx.AsyncClient(timeout=10.0) as client:
        results = await asyncio.gather(*(fetch_one(client, u) for u in urls))
        for r in results:
            print(r["url"])

asyncio.run(main())

نکات مهم این کد:

AsyncClient را حتماً با async with ببندید تا کانکشن‌ها درست آزاد شوند.
هر await client.get یک کوروتین است؛ asyncio.gather آن‌ها را هم‌زمان اجرا می‌کند.
برای لاگ گرفتن از خطاها در حالت async، حتماً try/except برای httpx.RequestError و httpx.HTTPStatusError اضافه کنید. ترکیب این الگو با آموزش Loguru در پایتون باعث می‌شود خطاهای شبکه را تمیز و ساختاریافته ثبت کنید.

چه زمانی Async به درد می‌خورد؟

وقتی کار شما I/O-bound است: صدها درخواست HTTP، کراولر، جمع‌آوری داده از چند API، یا بک‌اند FastAPI که باید هم‌زمان به سرویس‌های دیگر بزند. اگر فقط یک درخواست ساده در اسکریپت دارید، حالت همگام کافی و خواناتر است. Async زمانی ارزش دارد که تعداد درخواست‌ها زیاد باشد یا داخل فریم‌ورک async مثل FastAPI/Starlette باشید.

قابلیت‌های پیشرفته HTTPX که در requests نیست

HTTPX فقط یک کپی async از requests نیست؛ چند قابلیت کاربردی اضافه دارد:

۱. پشتیبانی از HTTP/2

client = httpx.Client(http2=True)
resp = client.get("https://nghttp2.org/httpbin/get")
print(resp.http_version)  # "HTTP/2" اگر سرور پشتیبانی کند

برای APIهایی مثل گوگل یا کلادفلر که HTTP/2 ارائه می‌دهند، multiplexing باعث کاهش latency می‌شود.

۲. کلاینت‌های قابل تنظیم، تایم‌اوت و Retry

timeout = httpx.Timeout(10.0, connect=5.0)
limits = httpx.Limits(max_keepalive_connections=5, max_connections=10)
with httpx.Client(timeout=timeout, limits=limits, follow_redirects=True) as client:
    resp = client.get("https://httpbin.org/redirect/1")
    print(resp.url, resp.status_code)

در requests تایم‌اوت یک عدد ساده است؛ در HTTPX می‌توانید connect/read/write/pool را جدا تنظیم کنید.

۳. کار با هدرها، کوکی، احراز هویت و Streaming

# احراز هویت Basic
with httpx.Client(auth=("user", "pass")) as client:
    r = client.get("https://httpbin.org/basic-auth/user/pass")

# استریم دانلود فایل بزرگ بدون پر کردن RAM
with httpx.stream("GET", "https://speed.hetzner.de/100MB.bin") as r:
    for chunk in r.iter_bytes():
        pass  # پردازش chunk

همچنین Event Hooks برای لاگ یا امضای درخواست‌ها دارید:

def log_response(response):
    request = response.request
    print(f"{request.method} {request.url} -> {response.status_code}")

with httpx.Client(event_hooks={"response": [log_response]}) as client:
    client.get("https://httpbin.org/get")

مقایسه HTTPX، requests و aiohttp

برای انتخاب درست، این جدول را ببینید:

معیار	HTTPX	requests	aiohttp
حالت اجرا	همگام + ناهمگام	فقط همگام	فقط ناهمگام
پشتیبانی HTTP/2	بله (با http2)	خیر	خیر (تجربی)
API ساده	بسیار شبیه requests	استاندارد طلایی	متفاوت، نیاز به یادگیری
تایپ‌هینت	کامل	ناقص	کامل
کاربرد پیشنهادی	پروژه‌های جدید مدرن	اسکریپت‌های ساده قدیمی	سرور/کلاینت async سنگین

جمع‌بندی: اگر پروژه جدید شروع می‌کنید، HTTPX بهترین تعادل سادگی و قدرت است. اگر کد قدیمی requests دارید و async نمی‌خواهید، نیازی به مهاجرت فوری نیست. aiohttp هنوز برای سرورهای async پیچیده قوی است اما برای کلاینت ساده، HTTPX خواناتر است.

اشتباهات رایج هنگام کار با HTTPX

این خطاها را بارها در کد دانشجوها دیده‌ایم:

۱. نبستن Client/AsyncClient: بدون with یا async with کانکشن‌ها باز می‌مانند و هشدار ResourceWarning می‌گیرید. همیشه context manager استفاده کنید.
۲. فراموش کردن timeout: پیش‌فرض HTTPX عدم تایم‌اوت است. در production حتماً timeout=10.0 یا شی Timeout بدهید تا درخواست‌ها قفل نشوند.
۳. ترکیب sync و async اشتباه: داخل تابع async هرگز httpx.get همگام صدا نزنید؛ باید await client.get با AsyncClient باشد. ترکیب آن‌ها event loop را قفل می‌کند.
۴. عدم مدیریت خطا: فقط status_code==200 چک نکنید. از response.raise_for_status() و گرفتن httpx.HTTPStatusError و httpx.RequestError استفاده کنید.
۵. نصب نکردن http2 ولی انتظار HTTP/2: بدون pip install "httpx[http2]" پارامتر http2=True خطا می‌دهد یا نادیده گرفته می‌شود.

سوالات متداول

آیا HTTPX جایگزین کامل requests است؟

بله برای ۹۵٪ موارد. API آن عمداً سازگار طراحی شده؛ get/post/put/delete، پارامترهای params, headers, json, data, cookies یکسان هستند. فقط در جزئیاتی مثل تایم‌اوت پیش‌فرض و نحوه ساختن Session/Client تفاوت دارد. مهاجرت معمولاً با جایگزینی requests با httpx و اضافه کردن timeout انجام می‌شود.

برای یک اسکریپت ساده هم باید HTTPX بزنم یا requests کافی است؟

اگر اسکریپت تک‌درخواستی و بدون نیاز به async یا HTTP/2 است، requests همچنان ساده و سبک است. اما اگر حتی احتمال می‌دهید بعداً async شود یا می‌خواهید کدنویسی مدرن با تایپ‌هینت داشته باشید، از ابتدا HTTPX بزنید تا دوباره‌کاری نشود.

تفاوت httpx.Client و httpx.AsyncClient چیست؟

Client برای کد همگام معمولی و AsyncClient برای کد async با await است. هر دو هدر، کوکی و کانکشن را reuse می‌کنند اما AsyncClient باید داخل async with و event loop اجرا شود. هرگز آن‌ها را جابه‌جا استفاده نکنید.

چطور در HTTPX فایل آپلود یا فرم ارسال کنیم؟

مثل requests: پارامتر data برای فرم و files برای آپلود. مثال: client.post(url, data={"user":"ali"}, files={"avatar": open("pic.jpg","rb")}). برای JSON از json={...} استفاده کنید که خودکار هدر application/json می‌گذارد.

آیا HTTPX با FastAPI و Starlette سازگار است؟

کاملاً. HTTPX توسط همان تیم ساخته شده و در تست‌های FastAPI به عنوان کلاینت پیشنهادی معرفی می‌شود. در تست‌های async فست‌ای‌پی‌آی معمولاً از httpx.AsyncClient(app=app, base_url="http://test") برای تست بدون اجرای سرور واقعی استفاده می‌کنند.

عملکرد HTTPX نسبت به aiohttp چطور است؟

در بنچمارک‌های I/O-heavy هر دو نزدیک هستند. aiohttp کمی سریع‌تر در سناریوهای بسیار سنگین است اما HTTPX خوانایی و سادگی بیشتری دارد و نیاز به یادگیری API جدید ندارد. برای اکثر پروژه‌های وب و دیتا، تفاوت پرفورمنس قابل چشم‌پوشی است.

جمع‌بندی

HTTPX پلی است بین سادگی محبوب requests و دنیای async و HTTP/2. اگر می‌خواهید کدی بنویسید که هم امروز تمیز باشد و هم فردا مقیاس‌پذیر، این چک‌لیست را دنبال کنید:

پایتون ۳.۸+ و pip install "httpx[http2]" را آماده کنید.
برای درخواست‌های تکی از httpx.get با timeout و برای چند درخواست از Client یا AsyncClient با context manager استفاده کنید.
کد async را فقط با AsyncClient و await بنویسید و هرگز sync و async را قاطی نکنید.
همیشه raise_for_status() و مدیریت خطای RequestError اضافه کنید.
وقتی تعداد درخواست‌ها زیاد شد، به asyncio.gather مهاجرت کنید و سرعت را لمس کنید.
برای پروژه بعدی که با API کار می‌کند، از ابتدا HTTPX را انتخاب کنید تا بعداً مجبور به بازنویسی نشوید.

قدم بعدی شما: یک اسکریپت کوچک بنویسید که ۱۰ URL را هم با حالت همگام و هم ناهمگام بگیرد و زمان هر دو را با time.perf_counter مقایسه کنید؛ نتیجه شما را قانع می‌کند که چرا HTTPX امروز انتخاب اول توسعه‌دهندگان مدرن پایتون است.

آموزش HTTPX در پایتون؛ جایگزین مدرن requests با Async