اشیای HTTPConnection¶

نمونه‌های HTTPConnection دارای متدهای زیر هستند:

HTTPConnection.request(method, url, body=None, headers={}, *, encode_chunked=False)¶

با این کار، یک درخواست با استفاده از متد درخواست HTTP method و URI درخواست url به سرور ارسال می‌شود. url ارائه‌شده باید یک مسیر مطلق باشد تا با RFC 2616 §5.1.2 مطابقت داشته باشد (مگر در صورت اتصال به یک سرور پراکسی HTTP یا استفاده از متدهای OPTIONS یا CONNECT).

اگر body مشخص شده باشد، داده‌ی مشخص‌شده پس از پایان سرآیندها ارسال می‌شود. این داده می‌تواند یک str، یک bytes-like object، یک file object باز یا یک پیمایش‌پذیر از bytes باشد. اگر body یک رشته باشد، به‌صورت ISO-8859-1، که پیش‌فرض HTTP است، کدگذاری می‌شود. اگر یک شیء شبه‌بایت باشد، بایت‌ها همان‌طور که هستند ارسال می‌شوند. اگر یک file object باشد، محتوای پرونده ارسال می‌شود؛ این شیء پرونده باید دست‌کم از متد read() پشتیبانی کند. اگر شیء پرونده نمونه‌ای از io.TextIOBase باشد، داده‌ای که متد read() برمی‌گرداند به‌صورت ISO-8859-1 کدگذاری می‌شود؛ در غیر این صورت، داده‌ای که read() برمی‌گرداند همان‌طور که هست ارسال می‌شود. اگر body یک پیمایش‌پذیر باشد، عناصر آن همان‌طور که هستند ارسال می‌شوند تا زمانی که پیمایش‌پذیر exhausted شود.

آرگومان headers باید یک نگاشت از سرآیندهای HTTP اضافی برای ارسال همراه با درخواست باشد. برای مطابقت با RFC 2616 §5.1.2 باید یک سرآیند Host ارائه شود (مگر اینکه به یک سرور پراکسی HTTP متصل شوید یا از متدهای OPTIONS یا CONNECT استفاده کنید).

اگر headers نه شامل Content-Length و نه شامل Transfer-Encoding باشد، اما بدنه‌ای برای درخواست وجود داشته باشد، یکی از آن فیلدهای سرآیند به‌طور خودکار اضافه خواهد شد. اگر body برابر None باشد، سرآیند Content-Length برای متدهایی که انتظار بدنه دارند (PUT، POST و PATCH) روی 0 تنظیم خواهد شد. اگر body یک رشته یا یک شیء شبه‌بایت باشد که در عین حال یک پرونده نیست، سرآیند Content-Length برابر طول آن تنظیم خواهد شد. هر نوع دیگری از body (به‌طور کلی پرونده‌ها و پیمایش‌پذیرها) به‌صورت کدگذاری تکه‌ای (chunk-encoded) درخواهد آمد و سرآیند Transfer-Encoding به‌طور خودکار به‌جای Content-Length تنظیم خواهد شد.

آرگومان encode_chunked تنها زمانی مرتبط است که Transfer-Encoding در headers مشخص شده باشد. اگر encode_chunked برابر False باشد، شیء HTTPConnection فرض می‌کند که تمام کدگذاری‌ها توسط کد فراخوان مدیریت می‌شود. اگر True باشد، بدنه به‌صورت تکه‌ای (chunk-encoded) کدگذاری می‌شود.

برای مثال، جهت انجام یک درخواست GET به https://docs.python.org/3/:

>>> import http.client
>>> host = "docs.python.org"
>>> conn = http.client.HTTPSConnection(host)
>>> conn.request("GET", "/3/", headers={"Host": host})
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200 OK

نکته

کدگذاری انتقال تکه‌ای (chunked transfer encoding) به نسخه 1.1 پروتکل HTTP افزوده شده است. مگر اینکه مشخص باشد سرور HTTP از HTTP 1.1 پشتیبانی می‌کند، فراخواننده باید یا Content-Length را مشخص کند، یا باید یک شیء str یا شیء شبه‌بایت (bytes-like) را که همزمان پرونده هم نباشد، به‌عنوان نمایش بدنه ارسال کند.

نکته

توجه داشته باشید که پیش از آن‌که بتوانید درخواست جدیدی را به سرور ارسال کنید، باید کل پاسخ را خوانده باشید یا اگر getresponse() استثنایی غیر از ConnectionError پرتاب کرده باشد، close() را فراخوانی کرده باشید.

تغییر یافته در نسخه‌ی 3.2: body اکنون می‌تواند پیمایش‌پذیر باشد.

تغییر یافته در نسخه‌ی 3.6: اگر هیچ‌کدام از Content-Length و Transfer-Encoding در headers تنظیم نشده باشند، اشیاء پرونده و پیمایش‌پذیر body اکنون کدگذاری تکه‌ای (chunk-encoded) می‌شوند. آرگومان encode_chunked اضافه شد. هیچ تلاشی برای تعیین Content-Length برای اشیاء پرونده انجام نمی‌شود.

HTTPConnection.getresponse()¶

باید پس از ارسال درخواست، برای دریافت پاسخ از سرور فراخوانی شود. یک نمونه HTTPResponse برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.5: اگر یک ConnectionError یا یکی از زیرکلاس‌های آن پرتاب شود، شیء HTTPConnection هنگامی که درخواست جدیدی ارسال شود، برای اتصال مجدد آماده خواهد بود.

توجه داشته باشید که این موضوع به استثناهای OSError پرتاب‌شده توسط سوکت زیرین اعمال نمی‌شود. در عوض، فراخواننده مسئول فراخوانی close() روی اتصال موجود است.

HTTPConnection.set_debuglevel(level)¶

سطح اشکال‌زدایی را تنظیم کنید. سطح اشکال‌زدایی پیش‌فرض 0 است، به این معنا که هیچ خروجی اشکال‌زدایی چاپ نمی‌شود. هر مقدار بزرگ‌تر از 0 باعث می‌شود تمام خروجی‌های اشکال‌زدایی که در حال حاضر تعریف شده‌اند، در stdout چاپ شوند. debuglevel به هر شیء جدید HTTPResponse که ایجاد شود، منتقل می‌شود.

اضافه شده در نسخه‌ی 3.1.

HTTPConnection.set_tunnel(host, port=None, headers=None)¶

میزبان و پورت را برای تونل‌زنی HTTP Connect تنظیم کنید. این کار امکان برقراری اتصال از طریق یک سرور پراکسی را فراهم می‌کند.

آرگومان‌های host و port پایانه‌ی اتصال تونل‌شده را مشخص می‌کنند (یعنی نشانی گنجانده‌شده در درخواست CONNECT، نه نشانی سرور پراکسی).

آرگومان headers باید نگاشتی از سرآیند‌های اضافی HTTP برای ارسال با درخواست CONNECT باشد. مقادیر سرآیند غیررشته‌ای از طریق str() به رشته تبدیل می‌شوند.

از آن‌جا که برای درخواست تونل‌سازی HTTP CONNECT از HTTP/1.1 استفاده می‌شود، طبق RFC، باید یک سرآیند HTTP Host: ارائه شود که با قالب authority (authority-form) هدف درخواستی که به‌عنوان مقصد درخواست CONNECT ارائه شده است مطابقت داشته باشد. اگر سرآیند HTTP Host: از طریق آرگومان headers ارائه نشود، یک سرآیند به‌طور خودکار تولید و ارسال می‌شود.

برای مثال، برای ایجاد تونل از طریق یک سرور پراکسی HTTPS که به‌صورت محلی روی پورت ۸۰۸۰ اجرا می‌شود، نشانی پراکسی را به سازنده‌ی HTTPSConnection و نشانی میزبانی را که در نهایت می‌خواهیم به آن دسترسی پیدا کنیم، به متد set_tunnel() می‌دهیم:

>>> import http.client
>>> conn = http.client.HTTPSConnection("localhost", 8080)
>>> conn.set_tunnel("www.python.org")
>>> conn.request("HEAD","/index.html")

اضافه شده در نسخه‌ی 3.2.

تغییر یافته در نسخه‌ی 3.12: درخواست‌های تونل‌زنی HTTP CONNECT از پروتکل HTTP/1.1 استفاده می‌کنند، که از پروتکل HTTP/1.0 ارتقا یافته است. سرآیند HTTP Host: برای HTTP/1.1 الزامی است، بنابراین اگر در آرگومان headers ارائه نشده باشد، یک سرآیند به‌طور خودکار تولید و ارسال می‌شود.

HTTPConnection.get_proxy_response_headers()¶

یک دیکشنری شامل سرآیند‌های پاسخ دریافت‌شده از سرور پراکسی به درخواست CONNECT برمی‌گرداند.

اگر درخواست CONNECT ارسال نشده باشد، متد None را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.12.

HTTPConnection.connect()¶

به سرور مشخص‌شده در زمان ایجاد شیء متصل می‌شود. به‌طور پیش‌فرض، اگر کلاینت از قبل اتصالی نداشته باشد، این متد به‌صورت خودکار هنگام ارسال درخواست فراخوانی می‌شود.

یک رویداد حسابرسی http.client.connect را با آرگومان‌های self، host و port پرتاب می‌کند.

HTTPConnection.close()¶

بستن اتصال به سرور.

HTTPConnection.blocksize¶

اندازه‌ی بافر بر حسب بایت برای ارسال بدنه‌ی پیام شبه‌پرونده.

اضافه شده در نسخه‌ی 3.7.

HTTPConnection.max_response_headers¶

حداکثر تعداد سرآیند‌های پاسخ مجاز برای کمک به جلوگیری از حملات محرومیت از سرویس. به طور پیش‌فرض، حداکثر تعداد سرآیند‌های مجاز روی ۱۰۰ تنظیم شده است. همین محدودیت برای بخش پایانی (trailer) یک پاسخ بخش‌بندی‌شده نیز اعمال می‌شود.

اضافه شده در نسخه‌ی 3.15.

به‌عنوان جایگزینی برای استفاده از متد request() که در بالا توضیح داده شد، می‌توانید با استفاده از چهار تابع زیر، درخواست خود را گام‌به‌گام ارسال کنید.

HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)¶

این باید اولین فراخوانی پس از برقراری اتصال به سرور باشد. این فراخوانی سطری را به سرور می‌فرستد که شامل رشته‌ی method، رشته‌ی url و نسخه‌ی HTTP (HTTP/1.1) است. برای غیرفعال‌سازی ارسال خودکار سرآیندهای Host: یا Accept-Encoding: (برای مثال برای پذیرش کدگذاری‌های اضافی محتوا)، skip_host یا skip_accept_encoding را با مقادیری غیر از False تعیین کنید.

HTTPConnection.putheader(header, argument[, ...])¶

این متد یک سرآیند به سبک RFC 822 را به سرور ارسال می‌کند. این متد سطری را به سرور می‌فرستد که شامل سرآیند، یک دونقطه و یک فاصله، و اولین آرگومان است. اگر آرگومان‌های بیشتری داده شوند، سطرهای ادامه ارسال می‌شوند که هر یک شامل یک تب و یک آرگومان است.

HTTPConnection.endheaders(message_body=None, *, encode_chunked=False)¶

یک خط خالی به سرور ارسال کنید تا پایان سرآیندها اعلام شود. می‌توانید از آرگومان اختیاری message_body برای ارسال بدنه پیام مرتبط با درخواست استفاده کنید.

اگر encode_chunked برابر True باشد، نتیجه هر تکرار از message_body به‌صورت تکه‌ای کدگذاری می‌شود (chunk-encoded)، همان‌طور که در RFC 7230، بخش 3.3.1 مشخص شده است. نحوه کدگذاری داده‌ها به نوع message_body وابسته است. اگر message_body رابط بافر را پیاده‌سازی کند، کدگذاری منجر به یک تکه واحد می‌شود. اگر message_body یک collections.abc.Iterable باشد، هر تکرار از message_body منجر به یک تکه می‌شود. اگر message_body یک شیء پرونده باشد، هر فراخوانی .read() منجر به یک تکه می‌شود. این متد به‌طور خودکار پایان داده‌های کدگذاری‌شده به‌صورت تکه‌ای را بلافاصله پس از message_body اعلام می‌کند.

نکته

به دلیل مشخصات کدگذاری تکه‌ای (chunked encoding)، تکه‌های خالی که توسط بدنه‌ی پیمایش‌گر تولید می‌شوند، توسط کدگذار تکه‌ای (chunk-encoder) نادیده گرفته می‌شوند. این برای جلوگیری از خاتمه زودهنگام خواندن درخواست توسط سرور هدف به دلیل کدگذاری نادرست است.

تغییر یافته در نسخه‌ی 3.6: پشتیبانی از کدگذاری تکه‌ای (chunked encoding) و پارامتر encode_chunked افزوده شد.

HTTPConnection.send(data)¶

داده را به سرور ارسال می‌کند. این متد باید فقط پس از فراخوانی متد endheaders() و پیش از فراخوانی getresponse() به‌طور مستقیم استفاده شود.

یک رویداد حسابرسی http.client.send را با آرگومان‌های self و data پرتاب می‌کند.

اشیاء HTTPResponse¶

یک نمونه از HTTPResponse پاسخ HTTP از سرور را دربر می‌گیرد. این نمونه دسترسی به سرآیندهای درخواست و بدنه‌ی موجودیت را فراهم می‌کند. پاسخ یک شیء پیمایش‌پذیر است و می‌توان از آن در یک دستور with استفاده کرد.

HTTPResponse.read([amt])¶

بدنه پاسخ یا حداکثر تا amt بایت بعدی را می‌خواند و برمی‌گرداند.

HTTPResponse.readinto(b)¶

حداکثر len(b) بایت بعدی از بدنه پاسخ را در بافر b می‌خواند. تعداد بایت‌های خوانده‌شده را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.3.

HTTPResponse.getheader(name, default=None)¶

مقدار سرآیند name را برمی‌گرداند، یا اگر سرآیندی مطابق با name وجود نداشته باشد، default را برمی‌گرداند. اگر بیش از یک سرآیند با نام name وجود داشته باشد، تمام مقادیر را که با ', ' به هم پیوسته‌اند برمی‌گرداند. اگر default هر پیمایش‌پذیری به‌جز یک رشته تنها باشد، عناصر آن نیز به همین ترتیب با ویرگول به هم پیوسته و برگردانده می‌شوند.

HTTPResponse.getheaders()¶

فهرستی از تاپل‌های (سرآیند، مقدار) برمی‌گرداند.

HTTPResponse.fileno()¶

fileno سوکت زیرین را برمی‌گرداند.

HTTPResponse.msg¶

یک نمونه http.client.HTTPMessage که شامل سرآیندهای پاسخ است. http.client.HTTPMessage زیرکلاسی از email.message.Message است.

HTTPResponse.version¶

نسخه‌ی پروتکل HTTP که سرور از آن استفاده می‌کند. 10 برای HTTP/1.0 و 11 برای HTTP/1.1.

HTTPResponse.url¶

URL منبع واکشی‌شده، معمولاً برای تشخیص اینکه آیا یک تغییرمسیر دنبال شده است استفاده می‌شود.

HTTPResponse.headers¶

سرآیندهای پاسخ در قالب یک نمونه از email.message.EmailMessage.

HTTPResponse.status¶

کد وضعیت برگردانده‌شده توسط سرور.

HTTPResponse.reason¶

عبارت دلیل برگردانده‌شده از سوی سرور.

HTTPResponse.debuglevel¶

یک قلاب اشکال‌زدایی . اگر debuglevel بزرگ‌تر از صفر باشد، در حین خوانده و تجزیه شدن پاسخ، پیام‌ها در stdout چاپ خواهند شد.

HTTPResponse.closed¶

اگر جریان بسته باشد، True است.

HTTPResponse.geturl()¶

منسوخ شده از نسخه‌ی 3.9: منسوخ‌شده به نفع url.

HTTPResponse.info()¶

منسوخ شده از نسخه‌ی 3.9: منسوخ‌شده به نفع headers.

HTTPResponse.getcode()¶

منسوخ شده از نسخه‌ی 3.9: منسوخ شده به نفع status.

مثال‌ها¶

در اینجا یک نشست نمونه آمده است که از متد GET استفاده می‌کند:

>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print(r1.status, r1.reason)
200 OK
>>> data1 = r1.read()  # This will return entire content.
>>> # The following example demonstrates reading data in chunks.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while chunk := r1.read(200):
...     print(repr(chunk))
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> conn = http.client.HTTPSConnection("docs.python.org")
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print(r2.status, r2.reason)
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

در اینجا یک نشست نمونه آمده است که از متد HEAD استفاده می‌کند. توجه داشته باشید که متد HEAD هرگز هیچ داده‌ای را برنمی‌گرداند.

>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("HEAD", "/")
>>> res = conn.getresponse()
>>> print(res.status, res.reason)
200 OK
>>> data = res.read()
>>> print(len(data))
0
>>> data == b''
True

در اینجا یک نشست نمونه آمده است که از متد POST استفاده می‌کند:

>>> import http.client, urllib.parse
>>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
...            "Accept": "text/plain"}
>>> conn = http.client.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
302 Found
>>> data = response.read()
>>> data
b'Redirecting to <a href="https://bugs.python.org/issue12524">https://bugs.python.org/issue12524</a>'
>>> conn.close()

درخواست‌های HTTP PUT در سمت کلاینت بسیار شبیه به درخواست‌های POST هستند. تفاوت تنها در سمت سرور است، جایی که سرورهای HTTP اجازه می‌دهند منابع از طریق درخواست‌های PUT ایجاد شوند. لازم به ذکر است که متدهای HTTP سفارشی نیز در urllib.request.Request و با تنظیم ویژگی method مناسب مدیریت می‌شوند. در ادامه یک نشست نمونه آمده است که از متد PUT استفاده می‌کند:

>>> # This creates an HTTP request
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost:8080/file
...
>>> import http.client
>>> BODY = "***filecontents***"
>>> conn = http.client.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200, OK

اشیای HTTPMessage¶

class http.client.HTTPMessage(email.message.Message)¶

یک نمونه از http.client.HTTPMessage سرآیندهای یک پاسخ HTTP را نگه می‌دارد. این نمونه با استفاده از کلاس email.message.Message پیاده‌سازی شده است.