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 | 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 — מילון הממפה שם שדה ל-tuple מסוג (filename, fileobj). נשלח כ-multipart/form-data.

• headers — מילון של כותרות בקשה נוספות.

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

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

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.

גוף בקשה באמצעות 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.

העבר לכל היותר אחד מבין 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.