http.server --- سرورهای HTTP¶

کد منبع: Lib/http/server.py

این ماژول کلاس‌هایی برای پیاده‌سازی سرورهای HTTP تعریف می‌کند.

یک کلاس، HTTPServer، زیرکلاسی از socketserver.TCPServer است. این کلاس یک سوکت HTTP ایجاد می‌کند و به آن گوش می‌دهد و درخواست‌ها را به یک هندلر ارجاع می‌دهد. کد برای ایجاد و اجرای سرور به این صورت است:

def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler):
    server_address = ('', 8000)
    httpd = server_class(server_address, handler_class)
    httpd.serve_forever()

class http.server.HTTPServer(server_address, RequestHandlerClass)¶

این کلاس بر پایه‌ی کلاس TCPServer ساخته شده است و نشانی سرور را به‌عنوان متغیرهای نمونه‌ای به نام‌های server_name و server_port ذخیره می‌کند. سرور برای هندلر قابل‌دسترسی است، معمولاً از طریق متغیر نمونه‌ی server در هندلر .

server_name¶

نام دامنه‌ی کامل سرور HTTP.

server_port¶

شماره پورت سرور HTTP که از server_address به‌دست می‌آید.

class http.server.ThreadingHTTPServer(server_address, RequestHandlerClass)¶

این کلاس دقیقاً مشابه HTTPServer است، اما برای رسیدگی به درخواست‌ها با استفاده از ThreadingMixIn از نخ‌ها استفاده می‌کند. این برای رسیدگی به مرورگرهای وبی که سوکت‌ها را از قبل باز می‌کنند مفید است، سوکت‌هایی که HTTPServer به‌طور نامحدود روی آن‌ها منتظر می‌ماند.

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

class http.server.HTTPSServer(server_address, RequestHandlerClass, bind_and_activate=True, *, certfile, keyfile=None, password=None, alpn_protocols=None)¶

زیرکلاسی از HTTPServer با سوکتی که با استفاده از ماژول ssl پوشیده شده است. اگر ماژول ssl در دسترس نباشد، نمونه‌سازی از یک شیء HTTPSServer با یک RuntimeError شکست می‌خورد.

آرگومان certfile مسیر پرونده زنجیره‌ی گواهی SSL است، و keyfile مسیر پرونده حاوی کلید خصوصی است.

می‌توانید یک گذرواژه برای پرونده‌های محافظت‌شده و پوشش‌داده‌شده با PKCS#8 مشخص کنید، اما توجه داشته باشید که این کار ممکن است گذرواژه‌های سخت‌کدشده را به‌صورت متن آشکار افشا کند.

همچنین ببینید

برای اطلاعات بیشتر درباره مقادیر پذیرفته‌شده برای certfile، keyfile و password، ssl.SSLContext.load_cert_chain() را ببینید.

در صورت مشخص شدن، آرگومان alpn_protocols باید دنباله‌ای از رشته‌ها باشد که پروتکل‌های «مذاکره پروتکل لایه کاربردی» (ALPN) مورد پشتیبانی سرور را مشخص می‌کنند. ALPN به سرور و کلاینت اجازه می‌دهد تا در طول دست‌دهی TLS درباره پروتکل لایه کاربردی مذاکره کنند.

به‌طور پیش‌فرض، روی ["http/1.1"] تنظیم شده است، به این معنا که سرور از HTTP/1.1 پشتیبانی می‌کند.

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

class http.server.ThreadingHTTPSServer(server_address, RequestHandlerClass, bind_and_activate=True, *, certfile, keyfile=None, password=None, alpn_protocols=None)¶

این کلاس با HTTPSServer یکسان است، اما با ارث‌بری از ThreadingMixIn برای مدیریت درخواست‌ها از نخ‌ها استفاده می‌کند. این مشابه ThreadingHTTPServer است، با این تفاوت که از HTTPSServer استفاده می‌کند.

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

HTTPServer، ThreadingHTTPServer، HTTPSServer و ThreadingHTTPSServer باید هنگام نمونه‌سازی یک RequestHandlerClass دریافت کنند، که این ماژول سه گونه متفاوت از آن را فراهم می‌کند:

class http.server.BaseHTTPRequestHandler(request, client_address, server)¶

این کلاس برای رسیدگی به درخواست‌های HTTP که به سرور می‌رسند استفاده می‌شود. این کلاس به‌تنهایی نمی‌تواند به هیچ درخواست HTTP واقعی پاسخ دهد؛ برای رسیدگی به هر متد درخواست (برای مثال، 'GET' یا 'POST') باید از آن زیرکلاس ساخته شود. BaseHTTPRequestHandler تعدادی متغیر کلاس و نمونه و متدهایی را برای استفاده در زیرکلاس‌ها فراهم می‌کند.

هندلر درخواست و سرآیند‌ها را تجزیه می‌کند، سپس متدی مخصوص نوع درخواست را فراخوانی می‌کند. نام متد از روی درخواست ساخته می‌شود. برای مثال، برای متد درخواست SPAM، متد do_SPAM() بدون آرگومان فراخوانی می‌شود. تمام اطلاعات مرتبط در متغیرهای نمونه‌ی هندلر ذخیره می‌شود. زیرکلاس‌ها نباید نیازی به بازنویسی یا گسترش متد __init__() داشته باشند.

BaseHTTPRequestHandler دارای متغیرهای نمونه زیر است:

client_address¶

شامل یک تاپل به‌صورت (host, port) است که به نشانی کلاینت اشاره می‌کند.

server¶

شامل نمونه‌ی سرور است.

close_connection¶

بولی که باید پیش از بازگشت handle_one_request() تنظیم شود و نشان می‌دهد که آیا ممکن است درخواست دیگری انتظار رود، یا اینکه اتصال باید بسته شود.

requestline¶

شامل نمایش رشته‌ای خط درخواست HTTP است. CRLF پایانی حذف می‌شود. این ویژگی باید توسط handle_one_request() تنظیم شود. اگر هیچ خط درخواست معتبری پردازش نشد، باید به رشته خالی تنظیم شود.

command¶

شامل دستور (نوع درخواست) است. برای مثال، 'GET'.

path¶

شامل مسیر درخواست است. اگر کامپوننت پرس‌وجوی URL وجود داشته باشد، آنگاه path شامل پرس‌وجو می‌شود. با استفاده از اصطلاحات RFC 3986، path در اینجا شامل hier-part و query می‌شود.

request_version¶

شامل رشته‌ی نسخه از درخواست است. برای مثال، 'HTTP/1.0'.

headers¶

یک نمونه از کلاس مشخص‌شده توسط متغیر کلاس MessageClass را نگه می‌دارد. این نمونه سرآیند‌های موجود در درخواست HTTP را تجزیه و مدیریت می‌کند. برای تجزیه سرآیند‌ها از تابع parse_headers() در http.client استفاده می‌شود و این تابع نیاز دارد که درخواست HTTP سرآیند‌ای معتبر به سبک RFC 5322 ارائه دهد.

rfile¶

یک جریان ورودی io.BufferedIOBase، آماده برای خواندن از ابتدای داده‌های ورودی اختیاری.

wfile¶

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

تغییر یافته در نسخه‌ی 3.6: این یک جریان io.BufferedIOBase است.

BaseHTTPRequestHandler دارای ویژگی‌های زیر است:

server_version¶

نسخه‌ی نرم‌افزار سرور را مشخص می‌کند. ممکن است بخواهید آن را بازنویسی کنید. قالب آن چند رشته‌ی جداشده با فضای خالی است، که هر رشته به شکل name[/version] است. برای مثال، 'BaseHTTP/0.2'.

sys_version¶

شامل نسخه سیستم پایتون است، در قالبی قابل‌استفاده توسط متد version_string و متغیر کلاس server_version. برای مثال، 'Python/1.4'.

error_message_format¶

رشته قالبی را مشخص می‌کند که باید توسط متد send_error() برای ساخت پاسخ خطا به کلاینت استفاده شود. این رشته به‌طور پیش‌فرض با متغیرهایی از responses بر اساس کد وضعیت ارسال‌شده به send_error() پر می‌شود.

error_content_type¶

سرآیند Content-Type در HTTP را برای پاسخ‌های خطای ارسال‌شده به کلاینت مشخص می‌کند. مقدار پیش‌فرض 'text/html' است.

protocol_version¶

نسخه‌ای از HTTP را که سرور با آن منطبق است مشخص می‌کند. این مقدار در پاسخ‌ها ارسال می‌شود تا کلاینت از قابلیت‌های ارتباطی سرور برای درخواست‌های آینده آگاه شود. اگر روی 'HTTP/1.1' تنظیم شود، سرور اتصالات پایا HTTP را مجاز می‌شمارد؛ با این حال، سرور شما باید در این صورت یک سرآیند Content-Length دقیق را (با استفاده از send_header()) در تمام پاسخ‌های خود به کلاینت‌ها بگنجاند. برای سازگاری با نسخه‌های قدیمی، مقدار پیش‌فرض این تنظیم 'HTTP/1.0' است.

MessageClass¶

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

responses¶

این ویژگی شامل نگاشتی از اعداد صحیح کد خطا به تاپل‌های دو عنصری است که حاوی یک پیام کوتاه و یک پیام بلند هستند. برای مثال، {code: (shortmessage, longmessage)}. معمولاً از shortmessage به‌عنوان کلید message در یک پاسخ خطا و از longmessage به‌عنوان کلید explain استفاده می‌شود. این ویژگی توسط متدهای send_response_only() و send_error() استفاده می‌شود.

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

handle()¶

handle_one_request() را یک بار فراخوانی می‌کند (یا، اگر اتصال‌های پایا فعال باشند، چندین بار) تا درخواست‌های HTTP ورودی را مدیریت کند. شما هرگز نباید نیازی به بازنویسی آن داشته باشید؛ در عوض، متدهای مناسب do_*() را پیاده‌سازی کنید.

handle_one_request()¶

این متد درخواست را تجزیه کرده و به متد do_*() مناسب ارسال می‌کند. شما هرگز نباید نیازی به بازنویسی آن داشته باشید.

handle_expect_100()¶

هنگامی که یک سرور مطابق با HTTP/1.1 یک سرآیند درخواست Expect: 100-continue دریافت می‌کند، با سرآیند 100 Continue و به‌دنبال آن سرآیند 200 OK پاسخ می‌دهد. این متد را می‌توان بازنویسی کرد تا در صورتی که سرور نمی‌خواهد کلاینت ادامه دهد، خطایی را پرتاب کند. برای مثال، سرور می‌تواند انتخاب کند که 417 Expectation Failed را به‌عنوان سرآیند پاسخ ارسال کند و return False را برگرداند.

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

send_error(code, message=None, explain=None)¶

یک پاسخ خطای کامل را به کلاینت ارسال و در گزارش ثبت می‌کند. مقدار عددی code کد خطای HTTP را مشخص می‌کند و message توضیحی اختیاری، کوتاه و قابل‌فهم برای انسان در مورد خطا است. می‌توان از آرگومان explain برای ارائه اطلاعات با جزئیات بیشتر در مورد خطا استفاده کرد؛ این مقدار با استفاده از ویژگی error_message_format قالب‌بندی می‌شود و پس از یک مجموعه کامل از سرآیندها، به‌عنوان بدنه پاسخ ارسال می‌شود. ویژگی responses حاوی مقادیر پیش‌فرض برای message و explain است که اگر مقداری ارائه نشود، استفاده می‌شوند؛ برای کدهای ناشناخته، مقدار پیش‌فرض هر دو، رشته ??? است. اگر متد HEAD باشد یا کد پاسخ یکی از موارد زیر باشد، بدنه خالی خواهد بود: 1xx، 204 No Content، 205 Reset Content، 304 Not Modified.

تغییر یافته در نسخه‌ی 3.4: پاسخ خطا شامل سرآیند Content-Length است. آرگومان explain افزوده شد.

send_response(code, message=None)¶

یک سرآیند پاسخ به بافر سرآیندها اضافه می‌کند و درخواست پذیرفته‌شده را ثبت می‌کند. خط پاسخ HTTP در بافر داخلی نوشته می‌شود و پس از آن سرآیندهای Server و Date می‌آیند. مقادیر این دو سرآیند به‌ترتیب از متدهای version_string() و date_time_string() گرفته می‌شوند. اگر سرور قصد ارسال سرآیندهای دیگری را با استفاده از متد send_header() نداشته باشد، پس از send_response() باید یک فراخوانی end_headers() انجام شود.

تغییر یافته در نسخه‌ی 3.3: سرآیندها در یک بافر داخلی ذخیره می‌شوند و end_headers() باید به‌صراحت فراخوانی شود.

send_header(keyword, value)¶

سرآیند HTTP را به یک بافر داخلی اضافه می‌کند که هنگام فراخوانی end_headers() یا flush_headers() به جریان خروجی نوشته می‌شود. keyword باید کلیدواژه سرآیند را مشخص کند و value مقدار آن را مشخص کند. توجه داشته باشید که پس از انجام فراخوانی‌های send_header، برای تکمیل عملیات باید حتماً end_headers() فراخوانی شود.

این متد ورودی حاوی دنباله‌های CRLF را رد نمی‌کند.

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

send_response_only(code, message=None)¶

فقط سرآیند پاسخ را ارسال می‌کند و برای مواردی استفاده می‌شود که پاسخ 100 Continue از سوی سرور به کلاینت فرستاده می‌شود. سرآیندها بافر نمی‌شوند و مستقیماً به جریان خروجی فرستاده می‌شوند. اگر message مشخص نشده باشد، پیام HTTP متناظر با code پاسخ ارسال می‌شود.

این متد message حاوی دنباله‌های CRLF را رد نمی‌کند.

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

end_headers()¶

یک خط خالی (که نشان‌دهنده‌ی پایان سرآیندهای HTTP در پاسخ است) را به بافر سرآیندها اضافه می‌کند و flush_headers() را فراخوانی می‌کند.

تغییر یافته در نسخه‌ی 3.2: سرآیندهای بافرشده در جریان خروجی نوشته می‌شوند.

flush_headers()¶

در نهایت، سرآیندها را به جریان خروجی بفرستید و بافر داخلی سرآیندها را تخلیه کنید.

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

log_request(code='-', size='-')¶

یک درخواست پذیرفته‌شده (موفق) را ثبت می‌کند. code باید کد عددی HTTP مرتبط با پاسخ را مشخص کند. اگر اندازه‌ای برای پاسخ در دسترس باشد، باید به‌عنوان پارامتر size ارسال شود.

log_error(...)¶

هنگامی که نتوان درخواستی را برآورده کرد، خطایی را ثبت می‌کند. به‌طور پیش‌فرض، پیام را به log_message() می‌فرستد، بنابراین آرگومان‌های یکسانی را می‌پذیرد (format و مقادیر اضافی).

log_message(format, ...)¶

یک پیام دلخواه را در sys.stderr ثبت می‌کند. این متد معمولاً برای ایجاد سازوکارهای سفارشی ثبت خطا بازنویسی می‌شود. آرگومان format یک رشته قالب استاندارد به سبک printf است، که در آن آرگومان‌های اضافیِ log_message() به‌عنوان ورودی‌های قالب‌بندی اعمال می‌شوند. نشانی IP کلاینت و تاریخ و زمان فعلی به ابتدای هر پیام ثبت‌شده اضافه می‌شوند.

version_string()¶

رشته‌ی نسخه‌ی نرم‌افزار سرور را برمی‌گرداند. این ترکیبی از ویژگی‌های server_version و sys_version است.

date_time_string(timestamp=None)¶

تاریخ و زمان داده‌شده توسط timestamp (که باید None یا در قالب برگردانده‌شده توسط time.time() باشد) را به‌صورت قالب‌بندی‌شده برای سرآیند پیام برمی‌گرداند. اگر timestamp داده نشود، از تاریخ و زمان کنونی استفاده می‌کند.

نتیجه شبیه 'Sun, 06 Nov 1994 08:49:37 GMT' است.

log_date_time_string()¶

تاریخ و زمان جاری را به‌صورت قالب‌بندی‌شده برای گزارش‌گیری برمی‌گرداند.

address_string()¶

نشانی کلاینت را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.3: پیش‌تر، یک جست‌وجوی نام انجام می‌شد. برای پرهیز از تأخیرهای حل نام، اکنون همیشه نشانی IP را برمی‌گرداند.

class http.server.SimpleHTTPRequestHandler(request, client_address, server, *, directory=None, extra_response_headers=None)¶

این کلاس پرونده‌ها را از پوشه‌ی directory و زیرمجموعه‌های آن، یا اگر directory ارائه نشده باشد از پوشه‌ی جاری، سرو می‌کند و ساختار پوشه را به‌طور مستقیم به درخواست‌های HTTP نگاشت می‌کند.

تغییر یافته در نسخه‌ی 3.7: پارامتر directory افزوده شد.

تغییر یافته در نسخه‌ی 3.9: پارامتر directory یک path-like object را می‌پذیرد.

تغییر یافته در نسخه‌ی 3.15: پارامتر extra_response_headers اضافه شد.

بخش زیادی از کار، مانند تجزیه درخواست، توسط کلاس پایه BaseHTTPRequestHandler انجام می‌شود. این کلاس توابع do_GET() و do_HEAD() را پیاده‌سازی می‌کند.

موارد زیر به‌عنوان ویژگی‌های سطح کلاس برای SimpleHTTPRequestHandler تعریف شده‌اند:

server_version¶

این مقدار "SimpleHTTP/" + __version__ خواهد بود، که __version__ در سطح ماژول تعریف شده است.

default_content_type¶

مقدار سرآیند Content-Type را که هنگام عدم امکان حدس نوع MIME از روی پسوند پرونده‌ی URL درخواست‌شده ارسال می‌شود، مشخص می‌کند. به طور پیش‌فرض، روی 'application/octet-stream' تنظیم شده است.

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

index_pages¶

نام پرونده‌هایی را مشخص می‌کند که به‌عنوان صفحات اندیس پوشه در نظر گرفته می‌شوند.

به‌طور پیش‌فرض ("index.html", "index.htm") است.

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

extensions_map¶

یک دیکشنری که پسوندها را به انواع MIME نگاشت می‌کند و شامل بازنویسی‌های سفارشی برای نگاشت‌های پیش‌فرض سیستم است. این نگاشت بدون حساسیت به بزرگی و کوچکی حروف استفاده می‌شود، بنابراین باید فقط شامل کلیدهای با حروف کوچک باشد.

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

extra_response_headers¶

دنباله‌ای از جفت‌های (name, value) شامل سرآیند‌های اضافی پاسخ HTTP تعریف‌شده توسط کاربر که به هر پاسخ موفقیت‌آمیز HTTP با وضعیت ۲۰۰ اضافه می‌شود. این سرآیندها در پاسخ‌های با کدهای وضعیت دیگر گنجانده نمی‌شوند.

سرآیندهایی که سرور به طور خودکار ارسال می‌کند، مانند Content-Type، توسط extra_response_headers بازنویسی نخواهند شد.

کلاس SimpleHTTPRequestHandler متدهای زیر را تعریف می‌کند:

do_HEAD()¶

این متد به نوع درخواست 'HEAD' پاسخ می‌دهد: سرآیند‌هایی را که برای درخواست GET معادل ارسال می‌کرد، می‌فرستد. برای توضیح کامل‌تر درباره سرآیند‌های ممکن، متد do_GET() را ببینید.

do_GET()¶

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

اگر درخواست به یک پوشه نگاشته شده باشد، پوشه برای یافتن یک صفحه اندیس مشخص‌شده توسط index_pages بررسی می‌شود. در صورت پیدا شدن، محتوای پرونده برگردانده می‌شود؛ در غیر این صورت، یک فهرست پوشه با فراخوانی متد list_directory() تولید می‌شود. این متد از os.listdir() برای پویش پوشه استفاده می‌کند و در صورت شکست listdir()، یک پاسخ خطای 404 برمی‌گرداند.

اگر درخواست به یک پرونده نگاشت شده باشد، آن پرونده باز می‌شود. هر استثنای OSError هنگام باز کردن پرونده درخواست‌شده، به خطای 404، 'File not found' نگاشت می‌شود. اگر سرآیند 'If-Modified-Since' در درخواست وجود داشته باشد و پرونده پس از این زمان تغییر نکرده باشد، پاسخ 304، 'Not Modified' ارسال می‌شود. در غیر این صورت، نوع محتوا با فراخوانی متد guess_type() حدس زده می‌شود، که خود از متغیر extensions_map استفاده می‌کند، و محتوای پرونده برگردانده می‌شود.

یک سرآیند 'Content-type:' با نوع محتوای حدس‌زده‌شده خروجی داده می‌شود و پس از آن، یک سرآیند 'Content-Length:' با اندازه‌ی پرونده و یک سرآیند 'Last-Modified:' با زمان تغییر پرونده خروجی داده می‌شوند.

ویژگی نمونه‌ی extra_response_headers دنباله‌ای از جفت‌های (name, value) شامل سرآیند‌های اضافی پاسخ تعریف‌شده توسط کاربر است.

سپس یک خط خالی می‌آید که پایان سرآیندها را نشان می‌دهد، و سپس محتوای پرونده خروجی داده می‌شود.

برای نمونه‌ی کاربرد، پیاده‌سازی تابع test را در Lib/http/server.py ببینید.

تغییر یافته در نسخه‌ی 3.7: پشتیبانی از سرآیند 'If-Modified-Since'.

list_directory(path)¶

راهنما برای فهرست‌کردن محتویات path در صورت نبود صفحه‌ی index.

این یا یک file-like object (که باید توسط فراخواننده بسته شود) را برمی‌گرداند یا None را برای نشان دادن خطا؛ در این صورت، فراخواننده کار دیگری برای انجام ندارد. در هر صورت، سرآیند‌ها ارسال می‌شوند.

guess_type(path)¶

نوع پرونده در path داده‌شده را حدس می‌زند.

این یک رشته به‌شکل type/subtype برمی‌گرداند که برای سرآیند MIME Content-type قابل استفاده است.

پیاده‌سازی پیش‌فرض، پسوند پرونده را در extensions_map جستجو می‌کند، و در صورت عدم یافتن، به mimetypes.guess_file_type() و سپس به default_content_type بازمی‌گردد.

تغییر یافته در نسخه‌ی 3.13: mimetypes.guess_file_type() را به‌عنوان جایگزین اضافه کنید.

می‌توان از کلاس SimpleHTTPRequestHandler برای ایجاد یک وب‌سرور بسیار ساده که پرونده‌ها را نسبت به پوشه جاری ارائه می‌دهد، به‌صورت زیر استفاده کرد:

import http.server
import socketserver

PORT = 8000

Handler = http.server.SimpleHTTPRequestHandler

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print("serving at port", PORT)
    httpd.serve_forever()

همچنین می‌توان از SimpleHTTPRequestHandler زیرکلاس ساخت تا رفتار آن بهبود یابد، مانند استفاده از نام‌های متفاوت برای پرونده‌های اندیس با بازنویسی صفت کلاس index_pages.

python -m http.server [OPTIONS] [port]