requests — לקוח HTTP#

המודול requests מספק API מינימלי של לקוח 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 | str | None = None, json: Any | None = None, files: dict | None = None, headers: dict | None = None, auth: tuple | None = None, stream: Any | None = None, timeout: float | None = 5.0) → Response#

שליחת בקשת HTTP אל url והחזרת requests.Response.

  • method — שיטת HTTP כ-str (למשל "GET", "POST").

  • url — כתובת URL היעד. חייבת להתחיל ב-http:// או https://.

  • data — גוף הבקשה הגולמי. str מקודד ב-UTF-8 לפני השליחה. אם הוגדר, Content-Length מתווסף אוטומטית.

  • json — אובייקט המסוריאליז ל-JSON ונשלח כגוף. מגדיר Content-Type: application/json.

  • files — מילון הממפה שם שדה ל-tuple מסוג (filename, fileobj). נשלח כ-multipart/form-data.

  • headers — מילון של כותרות בקשה נוספות. המילון מועתק, כך שהמילון של הקורא לעולם אינו משתנה (וכותרת Authorization שנוספה עבור auth אינה דולפת לבקשות מאוחרות יותר שעושות בו שימוש חוזר).

  • auth — tuple מסוג (username, password) עבור אימות HTTP Basic.

  • stream — מתקבל לצורך תאימות API; אינו בשימוש.

  • timeout — פסק זמן של השקע בשניות, המוחל לאחר שהחיבור נוצר. ברירת המחדל היא 5.0; העבירו None כדי לחסום ללא הגבלה. עם פקיעתו מתעוררת OSError.

תגובות הנשלחות עם Transfer-Encoding: chunked מפוענחות באופן שקוף, כך ש-requests.Response.content תמיד מכיל את הגוף לאחר פירוק המקטעים. כותרות התגובה מותאמות ללא תלות ברישיות. הפניות מחדש אינן נעקבות: תגובת 3xx עם כותרת Location מעוררת NotImplementedError.

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

שליחת בקשת HEAD של HTTP והחזרת Response.

HEAD זהה ל-GET למעט זאת שהשרת משיב בשורת המצב ובכותרות בלבד; הגוף ריק. השתמש בה כדי לבדוק אם משאב קיים, לבחון Content-Length / Content-Type ללא הורדת ה-payload, או לבחון URL לפני הנפקת GET כבד יותר.

ארגומנטים:

  • url – כתובת URL היעד; חייבת להתחיל ב-http:// או https://.

  • headers (kwarg) – מילון של כותרות בקשה נוספות.

  • auth (kwarg) – tuple מסוג (username, password) עבור אימות HTTP Basic.

data / json / files / stream מ-request() מתקבלים לשם שלמות אך לעיתים נדירות הגיוניים עבור HEAD.

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

שליחת בקשת GET של HTTP והחזרת Response.

GET הוא הפועל הסטנדרטי לאחזור ייצוג של המשאב המזוהה על ידי url. הוא בטוח (אינו גורם לשינוי מצב בצד השרת) ואידמפוטנטי.

ארגומנטים:

  • url – כתובת URL היעד; חייבת להתחיל ב-http:// או https://.

  • headers (kwarg) – מילון של כותרות בקשה נוספות (לדוגמה Authorization או Accept).

  • auth (kwarg) – tuple מסוג (username, password) עבור אימות HTTP Basic.

  • timeout (kwarg) – פסק זמן של השקע בשניות (ברירת מחדל 5.0).

גוף בקשה באמצעות data / json מותר על ידי request() הבסיסי אך מתעלמים ממנו רוב השרתים.

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

שליחת בקשת POST של HTTP והחזרת Response.

POST מגיש נתונים אל url, בדרך כלל יוצר משאב כפוף חדש, מפעיל הגשת טופס או מפעיל פעולה. הוא אינו בטוח ואינו אידמפוטנטי: קריאות חוזרות עשויות ליצור משאבים כפולים.

ארגומנטים:

  • url – כתובת URL היעד; חייבת להתחיל ב-http:// או https://.

  • data (kwarg) – גוף בקשה גולמי (דמוי bytes). שולח כותרת Content-Length אוטומטית.

  • json (kwarg) – אובייקט המסוריאליז ל-JSON ונשלח כגוף. מגדיר Content-Type: application/json.

  • files (kwarg) – מילון הממפה שם שדה ל-(filename, fileobj). נשלח כ-multipart/form-data.

  • headers (kwarg) – מילון של כותרות בקשה נוספות.

  • auth (kwarg) – tuple מסוג (username, password) עבור אימות HTTP Basic.

  • timeout (kwarg) – פסק זמן של השקע בשניות (ברירת מחדל 5.0). הגדילו אותו עבור נקודות קצה איטיות כגון ממשקי API של LLM.

העבר לכל היותר אחד מבין data / json / files.

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

שליחת בקשת PUT של HTTP והחזרת Response.

PUT מחליף את המשאב ב-url בייצוג שסופק, ויוצר אותו אם אינו קיים. הוא אידמפוטנטי: חזרה על PUT זהה מניבה את אותו מצב סופי.

ארגומנטים:

  • url – כתובת URL היעד; חייבת להתחיל ב-http:// או https://.

  • data (kwarg) – גוף החלפה גולמי (דמוי bytes).

  • json (kwarg) – אובייקט המסוריאליז ל-JSON ונשלח כגוף ההחלפה. מגדיר Content-Type: application/json.

  • headers (kwarg) – מילון של כותרות בקשה נוספות.

  • auth (kwarg) – tuple מסוג (username, password) עבור אימות HTTP Basic.

העבר data או json כדי לשאת את הייצוג החדש.

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

שליחת בקשת PATCH של HTTP והחזרת Response.

PATCH מחיל שינוי חלקי על המשאב ב-url – רק השדות הכלולים בגוף הבקשה משתנים. בניגוד ל-PUT, אין דרישה שיהיה אידמפוטנטי (אם כי ממשקי API רבים עושים אותו ככזה).

ארגומנטים:

  • url – כתובת URL היעד; חייבת להתחיל ב-http:// או https://.

  • data (kwarg) – גוף דלתא גולמי (דמוי bytes). הפורמט תלוי בשרת (למשל JSON Patch, JSON Merge Patch).

  • json (kwarg) – אובייקט דלתא המסוריאליז ל-JSON. מגדיר Content-Type: application/json.

  • headers (kwarg) – מילון של כותרות בקשה נוספות.

  • auth (kwarg) – tuple מסוג (username, password) עבור אימות HTTP Basic.

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

שליחת בקשת DELETE של HTTP והחזרת Response.

DELETE מבקש הסרה של המשאב ב-url. הוא אידמפוטנטי: מחיקת משאב שכבר נמחק אינה שגיאה (השרת בדרך כלל מחזיר 404, אך המצב הסופי זהה).

ארגומנטים:

  • url – כתובת URL היעד; חייבת להתחיל ב-http:// או https://.

  • headers (kwarg) – מילון של כותרות בקשה נוספות.

  • auth (kwarg) – tuple מסוג (username, password) עבור אימות HTTP Basic.

גוף באמצעות data / json מותר על ידי request() הבסיסי אך לעיתים נדירות בשימוש עם DELETE.