requests --- عميل HTTP

توفر الوحدة requests واجهة برمجية لعميل HTTP/HTTPS بسيطة شبيهة بمكتبة Python requests. تُرجع كل دالة طلب كائن requests.Response.

مثال:

import requests

# GET a JSON resource.
r = requests.get("https://httpbin.org/get")
print(r.status_code, r.reason)
print(r.json())

# POST JSON.
r = requests.post(
    "https://httpbin.org/post",
    json={"id": 1, "value": 42},
    headers={"X-Source": "openmv"},
)
print(r.json())

صنف Response

class requests.Response(code: int, reason: str, headers: bytes = None, content: bytes = None)

يمثّل استجابة HTTP. تُرجع النسخ بواسطة requests.request والدوال المساعدة الخاصة بكل طريقة.

status_code: int

رمز حالة HTTP الصحيح الذي يُرجعه الخادم.

reason: str

عبارة السبب التي يُرجعها الخادم (مفكوكة الترميز str).

encoding: str

ترميز السلسلة المستخدم لفك ترميز requests.Response.headers وrequests.Response.content. القيمة الافتراضية "utf-8".

headers: str

ترويسات الاستجابة مفكوكة الترميز بواسطة requests.Response.encoding ومُرجَعة على هيئة str.

content: str

متن الاستجابة مفكوك الترميز بواسطة requests.Response.encoding ومُرجَع على هيئة str.

json() → dict

تحليل requests.Response.content على أنه JSON وإرجاع الكائن الناتج.

الدوال

requests.request(method: str, url: str, data: bytes | None = None, json: Any | None = None, files: dict | None = None, headers: dict = {}, auth: tuple | None = None, stream: Any | None = None) → Response

إرسال طلب HTTP إلى url وإرجاع requests.Response.

  • method --- طريقة HTTP على هيئة str (مثل "GET" و"POST").

  • url --- عنوان URL الهدف. يجب أن يبدأ بـ http:// أو https://.

  • data --- متن الطلب الخام. إذا ضُبط، تُضاف Content-Length تلقائيًا.

  • json --- كائن مُسلسل إلى JSON ومُرسَل كمتن. يضبط Content-Type: application/json.

  • files --- قاموس يربط اسم الحقل بصف (filename, fileobj). يُرسَل على هيئة multipart/form-data.

  • headers --- قاموس بترويسات طلب إضافية.

  • auth --- صف (username, password) لمصادقة HTTP الأساسية.

  • stream --- مقبول من أجل التوافق مع الواجهة البرمجية؛ غير مستخدم.

requests.head(url: str, **kw: Any) → Response

إرسال طلب HTTP من نوع HEAD وإرجاع Response.

HEAD مطابق لـ GET إلا أن الخادم يرد بسطر الحالة والترويسات فقط؛ ويكون المتن فارغًا. استخدمه للتحقق من وجود مورد، أو لفحص Content-Length / Content-Type دون تنزيل الحمولة، أو لاستكشاف عنوان URL قبل إصدار طلب GET أثقل.

المعطيات:

  • url -- عنوان URL الهدف؛ يجب أن يبدأ بـ http:// أو https://.

  • headers (وسيط مفتاحي) -- قاموس بترويسات طلب إضافية.

  • auth (وسيط مفتاحي) -- صف (username, password) لمصادقة HTTP الأساسية.

يُقبل data / json / files / stream من request() من أجل الاكتمال، لكنها نادرًا ما تكون منطقية مع HEAD.

requests.get(url: str, **kw: Any) → Response

إرسال طلب HTTP من نوع GET وإرجاع Response.

GET هو الفعل القياسي لاسترجاع تمثيل المورد المحدد بـ url. وهو آمن (لا يسبب أي تغيير في حالة الخادم) وعديم التأثر بالتكرار (idempotent).

المعطيات:

  • url -- عنوان URL الهدف؛ يجب أن يبدأ بـ http:// أو https://.

  • headers (وسيط مفتاحي) -- قاموس بترويسات طلب إضافية (مثل Authorization أو Accept).

  • auth (وسيط مفتاحي) -- صف (username, password) لمصادقة HTTP الأساسية.

يسمح request() الأساسي بمتن طلب عبر data / json، لكن معظم الخوادم تتجاهله.

requests.post(url: str, **kw: Any) → Response

إرسال طلب HTTP من نوع POST وإرجاع Response.

POST يقدّم بيانات إلى url، وعادةً ينشئ موردًا تابعًا جديدًا، أو يطلق إرسال نموذج، أو يستدعي إجراءً. وهو ليس آمنًا ولا عديم التأثر بالتكرار: قد تنشئ الاستدعاءات المتكررة موارد مكررة.

المعطيات:

  • url -- عنوان URL الهدف؛ يجب أن يبدأ بـ http:// أو https://.

  • data (وسيط مفتاحي) -- متن الطلب الخام (شبيه بـ bytes). يرسل ترويسة Content-Length تلقائيًا.

  • json (وسيط مفتاحي) -- كائن مُسلسل إلى JSON ومُرسَل كمتن. يضبط Content-Type: application/json.

  • files (وسيط مفتاحي) -- قاموس يربط اسم حقل بـ (filename, fileobj). يُرسَل على هيئة multipart/form-data.

  • headers (وسيط مفتاحي) -- قاموس بترويسات طلب إضافية.

  • auth (وسيط مفتاحي) -- صف (username, password) لمصادقة HTTP الأساسية.

مرّر واحدًا على الأكثر من data / json / files.

requests.put(url: str, **kw: Any) → Response

إرسال طلب HTTP من نوع PUT وإرجاع Response.

PUT يستبدل المورد عند url بالتمثيل المقدَّم، وينشئه إن لم يكن موجودًا. وهو عديم التأثر بالتكرار: تكرار PUT متطابق ينتج عنه نفس الحالة النهائية.

المعطيات:

  • url -- عنوان URL الهدف؛ يجب أن يبدأ بـ http:// أو https://.

  • data (وسيط مفتاحي) -- متن الاستبدال الخام (شبيه بـ bytes).

  • json (وسيط مفتاحي) -- كائن مُسلسل إلى JSON ومُرسَل كمتن استبدال. يضبط Content-Type: application/json.

  • headers (وسيط مفتاحي) -- قاموس بترويسات طلب إضافية.

  • auth (وسيط مفتاحي) -- صف (username, password) لمصادقة HTTP الأساسية.

مرّر إما data أو json لحمل التمثيل الجديد.

requests.patch(url: str, **kw: Any) → Response

إرسال طلب HTTP من نوع PATCH وإرجاع Response.

PATCH يطبّق تعديلًا جزئيًا على المورد عند url -- فقط الحقول الموجودة في متن الطلب تتغير. وعلى خلاف PUT، ليس مطلوبًا أن يكون عديم التأثر بالتكرار (وإن جعلته كثير من الواجهات البرمجية كذلك).

المعطيات:

  • url -- عنوان URL الهدف؛ يجب أن يبدأ بـ http:// أو https://.

  • data (وسيط مفتاحي) -- متن الفرق الخام (شبيه بـ bytes). يعتمد التنسيق على الخادم (مثل JSON Patch وJSON Merge Patch).

  • json (وسيط مفتاحي) -- كائن الفرق مُسلسل إلى JSON. يضبط Content-Type: application/json.

  • headers (وسيط مفتاحي) -- قاموس بترويسات طلب إضافية.

  • auth (وسيط مفتاحي) -- صف (username, password) لمصادقة HTTP الأساسية.

requests.delete(url: str, **kw: Any) → Response

إرسال طلب HTTP من نوع DELETE وإرجاع Response.

DELETE يطلب إزالة المورد عند url. وهو عديم التأثر بالتكرار: حذف مورد محذوف بالفعل ليس خطأ (يُرجع الخادم عادةً 404، لكن الحالة النهائية متطابقة).

المعطيات:

  • url -- عنوان URL الهدف؛ يجب أن يبدأ بـ http:// أو https://.

  • headers (وسيط مفتاحي) -- قاموس بترويسات طلب إضافية.

  • auth (وسيط مفتاحي) -- صف (username, password) لمصادقة HTTP الأساسية.

يسمح request() الأساسي بمتن عبر data / json، لكنه نادرًا ما يُستخدم مع DELETE.