'\" t .\" Man page generated from reStructuredText .\" by the Docutils 0.22.3 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "PYTHON-SOCKETIO" "1" "Feb 07, 2026" "" "python-socketio" .SH "نام (NAME)" python-socketio \- مستندات کتابخانه python-socketio .sp این پروژه کلاینت‌ها و سرورهای Socket.IO را پیاده‌سازی می‌کند که می‌توانند به‌صورت مستقل یا یکپارچه‌شده با انواع فریم‌ورک‌های وب Python اجرا شوند. .SH "شروع به کار (GETTING STARTED)" .SS "‏Socket.IO چیست؟" .sp پروتکل Socket.IO یک پروتکل انتقال است که امکان برقراری ارتباط دوسویه، بلادرنگ و مبتنی بر رویداد را میان کلاینت‌ها (معمولاً، اما نه لزوماً، مرورگرهای وب) و یک سرور فراهم می‌کند. پیاده‌سازی‌های رسمی مؤلفه‌های کلاینت و سرور به زبان JavaScript نوشته شده‌اند. این بسته، پیاده‌سازی‌های Python هر دو مؤلفه را در قالب نسخه‌های استاندارد و asyncio ارائه می‌دهد. .SS "سازگاری نسخه‌ها" .sp پروتکل Socket.IO چندین بازنگری را پشت سر گذاشته است و برخی از آن‌ها تغییرات ناسازگار با نسخه‌های پیشین (backward incompatible) داشته‌اند؛ بدین معنا که کلاینت و سرور برای کارکرد صحیح باید از نسخه‌های سازگار استفاده کنند. .sp اگر از کلاینت و سرور Python استفاده می‌کنید، ساده‌ترین راه برای اطمینان از سازگاری، به‌کارگیری نسخه‌ای یکسان از این بسته برای هر دو بخش کلاینت و سرور است. چنانچه از این بسته همراه با کلاینت یا سرور دیگری استفاده می‌کنید، باید از سازگاری نسخه‌ها با یکدیگر اطمینان حاصل کنید. .sp جدول سازگاری نسخه در زیر، نگاشت میان نسخه‌های این بسته با نسخه‌های پیاده‌سازی مرجع JavaScript و همچنین نسخه‌های پروتکل‌های Socket.IO و Engine.IO را نمایش می‌دهد. .TS box center; l|l|l|l|l. T{ نسخه JavaScript Socket.IO T} T{ بازنگری پروتکل Socket.IO T} T{ بازنگری پروتکل Engine.IO T} T{ نسخه python\-socketio T} T{ نسخه python\-engineio T} _ T{ 0.9.x T} T{ 1, 2 T} T{ 1, 2 T} T{ پشتیبانی نمی‌شود T} T{ پشتیبانی نمی‌شود T} _ T{ 1.x و 2.x T} T{ 3, 4 T} T{ 3 T} T{ 4.x T} T{ 3.x T} _ T{ 3.x و 4.x T} T{ 5 T} T{ 4 T} T{ 5.x T} T{ 4.x T} .TE.SS "مثال‌های کلاینت (Client Examples)" .sp مثال زیر یک کلاینت سادهٔ Python را نشان می‌دهد: .INDENT 0.0 .INDENT 3.5 .sp .EX import socketio sio = socketio.Client() @sio.event def connect(): print(\(aqconnection established\(aq) @sio.event def my_message(data): print(\(aqmessage received with \(aq, data) sio.emit(\(aqmy response\(aq, {\(aqresponse\(aq: \(aqmy response\(aq}) @sio.event def disconnect(): print(\(aqdisconnected from server\(aq) sio.connect(\(aqhttp://localhost:5000\(aq) sio.wait() .EE .UNINDENT .UNINDENT .sp در زیر کلاینت مشابهی آمده است که برای \fBasyncio\fP کدنویسی شده است (تنها ویژهٔ Python 3.5 یا بالاتر): .INDENT 0.0 .INDENT 3.5 .sp .EX import asyncio import socketio sio = socketio.AsyncClient() @sio.event async def connect(): print(\(aqconnection established\(aq) @sio.event async def my_message(data): print(\(aqmessage received with \(aq, data) await sio.emit(\(aqmy response\(aq, {\(aqresponse\(aq: \(aqmy response\(aq}) @sio.event async def disconnect(): print(\(aqdisconnected from server\(aq) async def main(): await sio.connect(\(aqhttp://localhost:5000\(aq) await sio.wait() if __name__ == \(aq__main__\(aq: asyncio.run(main()) .EE .UNINDENT .UNINDENT .SS "ویژگی‌های کلاینت (Client Features)" .INDENT 0.0 .IP \(bu 2 می‌تواند به سایر سرورهای Socket.IO که با سرور مرجع JavaScript Socket.IO سازگار هستند، متصل شود. .IP \(bu 2 سازگار با Python 3.8 یا بالاتر. .IP \(bu 2 دو نسخه از کلاینت، یکی برای Python استاندارد و دیگری برای asyncio. .IP \(bu 2 از یک معماری مبتنی بر رویداد پیاده‌سازی‌شده با دکوراتورها استفاده می‌کند که جزئیات پروتکل را پنهان می‌سازد. .IP \(bu 2 روش‌های انتقال HTTP long\-polling و WebSocket را پیاده‌سازی می‌کند. .IP \(bu 2 در صورت قطع اتصال، به‌طور خودکار مجدداً به سرور متصل می‌شود. .UNINDENT.SS "مثال‌های سرور (Server Examples)" .sp برنامه زیر یک نمونه سرور مقدماتی است که از سرور ناهمگام Eventlet استفاده می‌کند: .INDENT 0.0 .INDENT 3.5 .sp .EX import eventlet import socketio sio = socketio.Server() app = socketio.WSGIApp(sio, static_files={ \(aq/\(aq: {\(aqcontent_type\(aq: \(aqtext/html\(aq, \(aqfilename\(aq: \(aqindex.html\(aq} }) @sio.event def connect(sid, environ): print(\(aqconnect \(aq, sid) @sio.event def my_message(sid, data): print(\(aqmessage \(aq, data) @sio.event def disconnect(sid): print(\(aqdisconnect \(aq, sid) if __name__ == \(aq__main__\(aq: eventlet.wsgi.server(eventlet.listen((\(aq\(aq, 5000)), app) .EE .UNINDENT .UNINDENT .sp در زیر برنامه مشابهی آمده است که برای \fBasyncio\fP (تنها Python 3.5+) و وب‌سرور Uvicorn نوشته شده است: .INDENT 0.0 .INDENT 3.5 .sp .EX from aiohttp import web import socketio sio = socketio.AsyncServer() app = web.Application() sio.attach(app) async def index(request): \(dq\(dq\(dqServe the client\-side application.\(dq\(dq\(dq with open(\(aqindex.html\(aq) as f: return web.Response(text=f.read(), content_type=\(aqtext/html\(aq) @sio.event def connect(sid, environ): print(\(dqconnect \(dq, sid) @sio.event async def chat_message(sid, data): print(\(dqmessage \(dq, data) @sio.event def disconnect(sid): print(\(aqdisconnect \(aq, sid) app.router.add_static(\(aq/static\(aq, \(aqstatic\(aq) app.router.add_get(\(aq/\(aq, index) if __name__ == \(aq__main__\(aq: web.run_app(app) .EE .UNINDENT .UNINDENT .SS "ویژگی‌های سرور (Server Features)" .INDENT 0.0 .IP \(bu 2 امکان اتصال به سرورهایی که سایر کلاینت‌های Socket.IO سازگار با کلاینت مرجع JavaScript را اجرا می‌کنند. .IP \(bu 2 سازگار با Python 3.8+. .IP \(bu 2 دو نسخه از سرور، یکی برای Python استاندارد و دیگری برای asyncio. .IP \(bu 2 پشتیبانی از تعداد زیادی کلاینت حتی روی سخت‌افزارهای معمولی به دلیل ناهمگام بودن. .IP \(bu 2 امکان میزبانی روی هر وب‌سرور WSGI \% یا ASGI \% از جمله Gunicorn \%، Uvicorn \%، eventlet \% و gevent \%\&. .IP \(bu 2 امکان ادغام با برنامه‌های WSGI نوشته‌شده در فریم‌ورک‌هایی مانند Flask، Django و غیره. .IP \(bu 2 امکان ادغام با برنامه‌های \fBasyncio\fP مانند aiohttp \%، FastAPI \%، sanic \% و tornado \%\&. .IP \(bu 2 ارسال همگانی پیام‌ها به تمام کلاینت‌های متصل، یا به زیرمجموعه‌هایی از آن‌ها که به \(dqاتاق‌ها\(dq (rooms) تخصیص یافته‌اند. .IP \(bu 2 پشتیبانی اختیاری از چندین سرور متصل از طریق صف پیام (messaging queue) مانند Redis یا RabbitMQ. .IP \(bu 2 ارسال پیام به کلاینت‌ها از فرایندهای خارجی، مانند workerهای Celery یا اسکریپت‌های کمکی. .IP \(bu 2 معماری رویدادمحور (Event\-based) پیاده‌سازی‌شده با دکوراتورها که جزئیات پروتکل را پنهان می‌کند. .IP \(bu 2 پشتیبانی از روش‌های انتقال (transports) HTTP long\-polling و WebSocket. .IP \(bu 2 پشتیبانی از مرورگرهای XHR2 و XHR. .IP \(bu 2 پشتیبانی از پیام‌های متنی و باینری (binary). .IP \(bu 2 پشتیبانی از فشرده‌سازی HTTP به روش‌های gzip و deflate. .IP \(bu 2 پاسخ‌های CORS با قابلیت پیکربندی، جهت جلوگیری از مشکلات cross\-origin در مرورگرها. .UNINDENT.SH "کلاینت‌های SOCKET.IO (THE SOCKET.IO CLIENTS)" .sp این بسته شامل دو کلاینت Socket.IO است: .INDENT 0.0 .IP \(bu 2 یک کلاینت \(dqساده\(dq، که یک API سرراست ارائه می‌دهد و برای اکثر برنامه‌ها کافی است .IP \(bu 2 یک کلاینت \(dqرویداد\-محور\(dq، که دسترسی به تمام ویژگی‌های پروتکل Socket.IO را فراهم می‌سازد .UNINDENT .sp هر یک از این کلاینت‌ها در دو گونه عرضه می‌شوند: یکی برای کتابخانه استاندارد Python، و دیگری برای برنامه‌های ناهمگام ساخته‌شده با بسته \fBasyncio\fP. .SS نصب .sp برای نصب کلاینت استاندارد Python به همراه وابستگی‌های آن، از دستور زیر استفاده کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX pip install \(dqpython\-socketio[client]\(dq .EE .UNINDENT .UNINDENT .sp اگر در عوض قصد دارید از کلاینت \fBasyncio\fP استفاده کنید، از این دستور استفاده کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX pip install \(dqpython\-socketio[asyncio_client]\(dq .EE .UNINDENT .UNINDENT .SS استفاده از کلاینت ساده .sp مزیت کلاینت ساده این است که منطق مورد نیاز برای برقراری و نگه‌داری اتصال Socket.IO را انتزاع می‌کند. این کلاینت قطع اتصال و اتصال مجدد را به‌شکلی کاملاً شفاف، بدون افزودن هیچ‌گونه پیچیدگی به برنامه مدیریت می‌نماید. .SS ایجاد یک نمونه از کلاینت .sp ساده‌ترین روش برای ایجاد یک کلاینت Socket.IO، استفاده از رابط context manager است: .INDENT 0.0 .INDENT 3.5 .sp .EX import socketio # standard Python with socketio.SimpleClient() as sio: # ... connect to a server and use the client # ... no need to manually disconnect! # asyncio async with socketio.AsyncSimpleClient() as sio: # ... connect to a server and use the client # ... no need to manually disconnect! .EE .UNINDENT .UNINDENT .sp با این روش، context manager تضمین می‌کند که کلاینت پیش از خروج از بلوک \fBwith\fP یا \fBasync with\fP به‌درستی قطع اتصال شود. .sp در صورت تمایل، کلاینت می‌تواند به‌صورت دستی نمونه‌سازی شود: .INDENT 0.0 .INDENT 3.5 .sp .EX import socketio # standard Python sio = socketio.SimpleClient() # asyncio sio = socketio.AsyncSimpleClient() .EE .UNINDENT .UNINDENT.SS اتصال به سرور (Connecting to a Server) .sp اتصال به یک سرور با فراخوانی متد \fBconnect()\fP برقرار می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.connect(\(aqhttp://localhost:5000\(aq) .EE .UNINDENT .UNINDENT .sp در مورد کلاینت \fBasyncio\fP، این متد یک کوروتین (coroutine) است: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.connect(\(aqhttp://localhost:5000\(aq) .EE .UNINDENT .UNINDENT .sp به‌طور پیش‌فرض کلاینت ابتدا با استفاده از روش انتقال long\-polling به سرور متصل می‌شود، و سپس تلاش می‌کند تا اتصال را برای استفاده از WebSocket ارتقا دهد. برای اتصال مستقیم با استفاده از WebSocket، از آرگومان \fBtransports\fP استفاده کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.connect(\(aqhttp://localhost:5000\(aq, transports=[\(aqwebsocket\(aq]) .EE .UNINDENT .UNINDENT .sp پس از برقراری اتصال، سرور یک شناسه نشست یکتا به کلاینت اختصاص می‌دهد. برنامه می‌تواند این شناسه را در ویژگی \fBsid\fP بیابد: .INDENT 0.0 .INDENT 3.5 .sp .EX print(\(aqmy sid is\(aq, sio.sid) .EE .UNINDENT .UNINDENT .sp روش انتقال Socket.IO که در این اتصال استفاده می‌شود را می‌توان از ویژگی \fBtransport\fP به دست آورد: .INDENT 0.0 .INDENT 3.5 .sp .EX print(\(aqmy transport is\(aq, sio.transport) .EE .UNINDENT .UNINDENT .sp روش انتقال به صورت یک رشته بازگردانده می‌شود و می‌تواند \fB\(aqwebsocket\(aq\fP یا \fB\(aqpolling\(aq\fP\& باشد. .SS پشتیبانی از TLS/SSL (TLS/SSL Support) .sp کلاینت از اتصالات TLS/SSL پشتیبانی می‌کند. برای فعال کردن آن، از یک نشانی اینترنتی (URL) اتصال با \fBhttps://\fP استفاده کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT .sp یا هنگام استفاده از \fBasyncio\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT .sp کلاینت به‌طور پیش‌فرض گواهی‌های سرور را بررسی و تأیید می‌کند. برای کسب اطلاعات درباره نحوه سفارشی‌سازی این رفتار، به مستندات کلاینت رویدادمحور مراجعه کنید..SS "ارسال رویدادها (Emitting Events)" .sp کلاینت می‌تواند با استفاده از متد \fBemit()\fP یک رویداد را به سرور ارسال کند: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.emit(\(aqmy message\(aq, {\(aqfoo\(aq: \(aqbar\(aq}) .EE .UNINDENT .UNINDENT .sp یا در صورت استفاده از \fBasyncio\fP، به‌صورت یک کوروتین: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.emit(\(aqmy message\(aq, {\(aqfoo\(aq: \(aqbar\(aq}) .EE .UNINDENT .UNINDENT .sp آرگومان‌های ارائه‌شده به این متد، نام رویدادی است که باید ارسال شود و داده‌های اختیاری که به سرور ارسال می‌شوند. داده‌ها می‌توانند از نوع \fBstr\fP، \fBbytes\fP، \fBdict\fP، \fBlist\fP یا \fBtuple\fP باشند\&. هنگام ارسال یک \fBlist\fP یا یک \fBtuple\fP، عناصر موجود در آن باید از هر یک از انواع مجاز به جز \fBtuple\fP باشند\&. هنگامی که از یک تاپل استفاده می‌شود، عناصر آن تاپل به‌صورت آرگومان‌های مجزا به تابع مدیریت رویداد در سمت سرور منتقل خواهند شد. .SS "دریافت رویدادها (Receiving Events)" .sp کلاینت می‌تواند با استفاده از متد \fBreceive()\fP منتظر بماند تا سرور یک رویداد را ارسال کند: .INDENT 0.0 .INDENT 3.5 .sp .EX event = sio.receive() print(f\(aqreceived event: \(dq{event[0]}\(dq with arguments {event[1:]}\(aq) .EE .UNINDENT .UNINDENT .sp هنگام استفاده از \fBasyncio\fP، این متد باید با \fBawait\fP فراخوانی شود: .INDENT 0.0 .INDENT 3.5 .sp .EX event = await sio.receive() print(f\(aqreceived event: \(dq{event[0]}\(dq with arguments {event[1:]}\(aq) .EE .UNINDENT .UNINDENT .sp مقدار بازگشتی \fBreceive()\fP یک لیست است. نخستین عنصر این لیست نام رویداد است، در حالی که سایر عناصر، آرگومان‌های ارسال‌شده از سوی سرور هستند. .sp با روش استفاده‌ای که در بالا نشان داده شد، متد \fBreceive()\fP تنها زمانی برمی‌گردد که رویدادی از سرور دریافت شود. می‌توان یک مهلت زمانی اختیاری (timeout) بر حسب ثانیه ارسال کرد تا از انتظار همیشگی کلاینت جلوگیری شود: .INDENT 0.0 .INDENT 3.5 .sp .EX from socketio.exceptions import TimeoutError try: event = sio.receive(timeout=5) except TimeoutError: print(\(aqtimed out waiting for event\(aq) else: print(\(aqreceived event:\(aq, event) .EE .UNINDENT .UNINDENT .sp یا با \fBasyncio\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX from socketio.exceptions import TimeoutError try: event = await sio.receive(timeout=5) except TimeoutError: print(\(aqtimed out waiting for event\(aq) else: print(\(aqreceived event:\(aq, event) .EE .UNINDENT .UNINDENT.SS "قطع اتصال از سرور (Disconnecting from the Server)" .sp در هر زمان کلاینت می‌تواند با فراخوانی متد \fBdisconnect()\fP، درخواست قطع اتصال از سرور را بدهد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.disconnect() .EE .UNINDENT .UNINDENT .sp برای کلاینت \fBasyncio\fP این یک هم‌روال (coroutine) است: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.disconnect() .EE .UNINDENT .UNINDENT .SS "اشکال‌زدایی و عیب‌یابی (Debugging and Troubleshooting)" .sp برای کمک به اشکال‌زدایی مشکلات، می‌توان کلاینت را برای ارسال لاگ‌ها به ترمینال پیکربندی کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX import socketio # standard Python sio = socketio.Client(logger=True, engineio_logger=True) # asyncio sio = socketio.AsyncClient(logger=True, engineio_logger=True) .EE .UNINDENT .UNINDENT .sp آرگومان \fBlogger\fP ثبت لاگ‌های مربوط به پروتکل Socket.IO را کنترل می‌کند، در حالی که \fBengineio_logger\fP لاگ‌های نشئت‌گرفته از لایهٔ انتقال سطح پایین Engine.IO را کنترل می‌نماید. مقداری که به این آرگومان‌ها اختصاص می‌یابد رفتار ثبت لاگ را تعیین می‌کند: .INDENT 0.0 .IP \(bu 2 \fBTrue\fP: خروجی لاگ را در \fBstderr\fP در سطح \fBINFO\fP فعال می‌کند. .IP \(bu 2 \fBFalse\fP: خروجی لاگ را در \fBstderr\fP در سطح \fBERROR\fP فعال می‌کند. این مقدار پیش‌فرض است. .IP \(bu 2 یک نمونه از \fBlogging.Logger\fP: از لاگر ارائه‌شده بدون نیاز به پیکربندی اضافی استفاده می‌کند. .UNINDENT .sp ثبت لاگ می‌تواند به شناسایی علت مشکلات اتصال، قطع ارتباط‌های غیرمنتظره و سایر مسائل کمک کند. .SS "استفاده از کلاینت رویدادمحور (Using the Event\-Driven Client)" .SS "ایجاد یک نمونه از کلاینت (Creating a Client Instance)" .sp برای نمونه‌سازی از یک کلاینت Socket.IO، کافی است یک نمونه از کلاس کلاینت مناسب ایجاد کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX import socketio # standard Python sio = socketio.Client() # asyncio sio = socketio.AsyncClient() .EE .UNINDENT .UNINDENT .SS "تعریف گرداننده‌های رویداد (Defining Event Handlers)" .sp پروتکل Socket.IO مبتنی بر رویداد است. هنگامی که سرور می‌خواهد با کلاینت ارتباط برقرار کند، یک رویداد را \fIمنتشر (emit)\fP می‌کند. هر رویداد دارای یک نام و فهرستی از آرگومان‌ها است. کلاینت توابع گردانندهٔ رویداد را با دکوراتورهای \fBsocketio.Client.event()\fP \%<#\:socketio\:.Client\:.event> یا \fBsocketio.Client.on()\fP \%<#\:socketio\:.Client\:.on> ثبت می‌کند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def message(data): print(\(aqI received a message!\(aq) @sio.on(\(aqmy message\(aq) def on_message(data): print(\(aqI received a message!\(aq) .EE .UNINDENT .UNINDENT .sp در مثال اول، نام رویداد از نام تابع گرداننده گرفته می‌شود. مثال دوم کمی مفصل‌تر است، اما این امکان را فراهم می‌سازد که نام رویداد با نام تابع متفاوت باشد یا شامل نویسه‌هایی شود که در نام توابع غیرمجاز هستند، مانند فاصله‌ها. .sp برای کلاینت \fBasyncio\fP، گرداننده‌های رویداد می‌توانند همانند بالا توابعی معمولی باشند، یا این که به صورت هم‌روال (coroutine) تعریف شوند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event async def message(data): print(\(aqI received a message!\(aq) .EE .UNINDENT .UNINDENT .sp اگر سرور به همراه رویداد آرگومان‌هایی ارسال کند، آن آرگومان‌ها به تابع گرداننده تحویل داده می‌شوند..SS گرداننده‌های همه‌گیر رویداد و فضای‌نام (Catch\-All Event and Namespace Handlers) .sp یک گردانندهٔ رویداد «همه‌گیر» (catch\-all) برای تمام رویدادهایی که گردانندهٔ مشخصی ندارند فراخوانی می‌شود. می‌توانید با استفاده از \fB\(aq*\(aq\fP به عنوان نام رویداد، یک گردانندهٔ همه‌گیر تعریف کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.on(\(aq*\(aq) def any_event(event, sid, data): pass .EE .UNINDENT .UNINDENT .sp سرورهای Asyncio همچنین می‌توانند از یک هم‌روال (coroutine) استفاده کنند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.on(\(aq*\(aq) async def any_event(event, sid, data): pass .EE .UNINDENT .UNINDENT .sp یک گردانندهٔ رویداد همه‌گیر، نام رویداد را به عنوان نخستین آرگومان دریافت می‌کند. باقی آرگومان‌ها همانند یک گردانندهٔ رویداد معمولی هستند. .sp رویدادهای \fBconnect\fP و \fBdisconnect\fP باید به‌طور صریح تعریف شوند و توسط گردانندهٔ رویداد همه‌گیر فراخوانی نمی‌شوند. .sp به‌طور مشابه، یک گردانندهٔ فضای‌نام «همه‌گیر» برای تمام فضاهای نام متصلی که گردانندهٔ رویداد صریحاً تعریف‌شده‌ای ندارند فراخوانی می‌شود. همانند رویدادهای همه‌گیر، از \fB\(aq*\(aq\fP به جای نام فضای‌نام استفاده می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.on(\(aqmy_event\(aq, namespace=\(aq*\(aq) def my_event_any_namespace(namespace, sid, data): pass .EE .UNINDENT .UNINDENT .sp برای این رویدادها، فضای‌نام به عنوان نخستین آرگومان ارسال شده و به دنبال آن آرگومان‌های معمول رویداد قرار می‌گیرند. .sp در نهایت، تعریف یک گردانندهٔ «همه‌گیر» برای تمام رویدادها در تمامی فضاهای نام نیز امکان‌پذیر است: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.on(\(aq*\(aq, namespace=\(aq*\(aq) def any_event_any_namespace(event, namespace, sid, data): pass .EE .UNINDENT .UNINDENT .sp گرداننده‌های رویداد با رویدادها و فضاهای نام همه‌گیر، نام رویداد و نام فضای‌نام را به عنوان آرگومان‌های اول و دوم دریافت می‌کنند. .SS گرداننده‌های رویداد اتصال، خطای اتصال و قطع اتصال (Connect, Connect Error and Disconnect Event Handlers) .sp رویدادهای \fBconnect\fP، \fBconnect_error\fP و \fBdisconnect\fP خاص هستند؛ آن‌ها هنگام اتصال کلاینت به سرور یا قطع اتصال از آن، به‌طور خودکار فراخوانی می‌شوند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def connect(): print(\(dqI\(aqm connected!\(dq) @sio.event def connect_error(data): print(\(dqThe connection failed!\(dq) @sio.event def disconnect(reason): print(\(dqI\(aqm disconnected! reason:\(dq, reason) .EE .UNINDENT .UNINDENT .sp گردانندهٔ \fBconnect_error\fP هنگامی که تلاشی برای اتصال با شکست مواجه شود فراخوانی می‌گردد. اگر سرور آرگومان‌هایی ارائه دهد، این مقادیر به گرداننده منتقل می‌شوند. سرور می‌تواند از یک آرگومان برای ارائهٔ اطلاعات مربوط به شکست اتصال به کلاینت استفاده کند. .sp گردانندهٔ \fBdisconnect\fP برای قطع اتصال‌های آغاز شده توسط برنامه، آغاز شده توسط سرور، یا قطع اتصال‌های تصادفی مانند خرابی‌های شبکه فراخوانی می‌شود. در صورت وقوع یک قطع اتصال تصادفی، کلاینت بلافاصله پس از فراخوانی گردانندهٔ قطع اتصال، برای اتصال مجدد تلاش خواهد کرد. به محض برقراری مجدد اتصال، گردانندهٔ connect بار دیگر فراخوانی خواهد شد. این گرداننده یک آرگومان \fBreason\fP دریافت می‌کند که علت قطع اتصال را مشخص می‌کند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def disconnect(reason): if reason == sio.reason.CLIENT_DISCONNECT: print(\(aqthe client disconnected\(aq) elif reason == sio.reason.SERVER_DISCONNECT: print(\(aqthe server disconnected the client\(aq) else: print(\(aqdisconnect reason:\(aq, reason) .EE .UNINDENT .UNINDENT .sp برای فهرستی از دلایل ممکن قطع اتصال، صفت \fBsocketio.Client.reason\fP \%<#\:socketio\:.Client\:.reason> را ببینید. .sp رویدادهای \fBconnect\fP، \fBconnect_error\fP و \fBdisconnect\fP باید صریحاً تعریف شوند و توسط یک گردانندهٔ رویداد همه‌گیر فراخوانی نمی‌شوند..SS اتصال به سرور .sp اتصال به یک سرور با فراخوانی متد \fBconnect()\fP برقرار می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.connect(\(aqhttp://localhost:5000\(aq) .EE .UNINDENT .UNINDENT .sp در مورد کلاینت \fBasyncio\fP، این متد یک کوروتین (coroutine) است: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.connect(\(aqhttp://localhost:5000\(aq) .EE .UNINDENT .UNINDENT .sp به محض اتصال، سرور یک شناسه نشست یکتا به کلاینت اختصاص می‌دهد. برنامه می‌تواند این شناسه را در صفت \fBsid\fP بیابد: .INDENT 0.0 .INDENT 3.5 .sp .EX print(\(aqmy sid is\(aq, sio.sid) .EE .UNINDENT .UNINDENT .sp روش انتقال Socket.IO که در اتصال استفاده می‌شود را می‌توان از صفت \fBtransport\fP به دست آورد: .INDENT 0.0 .INDENT 3.5 .sp .EX print(\(aqmy transport is\(aq, sio.transport) .EE .UNINDENT .UNINDENT .sp نوع انتقال به‌صورت یک رشته مشخص می‌شود و می‌تواند \fB\(aqwebsocket\(aq\fP یا \fB\(aqpolling\(aq\fP باشد\&. .SS پشتیبانی از TLS/SSL .sp کلاینت از اتصالات TLS/SSL پشتیبانی می‌کند. برای فعال‌سازی آن، از یک URL اتصال با \fBhttps://\fP استفاده کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT .sp یا هنگام استفاده از \fBasyncio\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT .sp کلاینت به‌طور پیش‌فرض گواهی سرور را اعتبارسنجی می‌کند. برای غیرفعال کردن اعتبارسنجی گواهی یا استفاده از گزینه‌های کمتر رایج مانند گواهی‌های کلاینت، کلاینت باید با یک شیء نشست HTTP سفارشی که با گزینه‌های مورد نظر TLS/SSL پیکربندی شده است، مقداردهی اولیه شود. .sp مثال زیر اعتبارسنجی گواهی سرور را غیرفعال می‌کند که هنگام اتصال به سروری که از یک گواهی خودامضا (self\-signed) استفاده می‌کند، می‌تواند مفید باشد: .INDENT 0.0 .INDENT 3.5 .sp .EX http_session = requests.Session() http_session.verify = False sio = socketio.Client(http_session=http_session) sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT .sp و هنگام استفاده از \fBasyncio\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX connector = aiohttp.TCPConnector(ssl=False) http_session = aiohttp.ClientSession(connector=connector) sio = socketio.AsyncClient(http_session=http_session) await sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT .sp به جای غیرفعال کردن اعتبارسنجی گواهی، می‌توانید یک بسته مرجع صدور گواهی (CA bundle) سفارشی برای اعتبارسنجی گواهی در برابر آن ارائه دهید: .INDENT 0.0 .INDENT 3.5 .sp .EX http_session = requests.Session() http_session.verify = \(aq/path/to/ca.pem\(aq sio = socketio.Client(http_session=http_session) sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT .sp و برای \fBasyncio\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX ssl_context = ssl.create_default_context() ssl_context.load_verify_locations(\(aq/path/to/ca.pem\(aq) connector = aiohttp.TCPConnector(ssl=ssl_context) http_session = aiohttp.ClientSession(connector=connector) sio = socketio.AsyncClient(http_session=http_session) await sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT .sp در ادامه نحوه استفاده از یک گواهی کلاینت برای احراز هویت در برابر سرور نشان داده شده است: .INDENT 0.0 .INDENT 3.5 .sp .EX http_session = requests.Session() http_session.cert = (\(aq/path/to/client/cert.pem\(aq, \(aq/path/to/client/key.pem\(aq) sio = socketio.Client(http_session=http_session) sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT .sp و برای \fBasyncio\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX ssl_context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) ssl_context.load_cert_chain(\(aq/path/to/client/cert.pem\(aq, \(aq/path/to/client/key.pem\(aq) connector = aiohttp.TCPConnector(ssl=ssl_context) http_session = aiohttp.ClientSession(connector=connector) sio = socketio.AsyncClient(http_session=http_session) await sio.connect(\(aqhttps://example.com\(aq) .EE .UNINDENT .UNINDENT.SS "ارسال رویدادها (Emitting Events)" .sp کلاینت می‌تواند با استفاده از متد \fBemit()\fP یک رویداد را به سرور ارسال کند: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.emit(\(aqmy message\(aq, {\(aqfoo\(aq: \(aqbar\(aq}) .EE .UNINDENT .UNINDENT .sp یا در صورت استفاده از \fBasyncio\fP، به عنوان یک کوروتین: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.emit(\(aqmy message\(aq, {\(aqfoo\(aq: \(aqbar\(aq}) .EE .UNINDENT .UNINDENT .sp آرگومان‌های ارائه‌شده به این متد، نام رویداد ارسالی و داده‌های اختیاری هستند که به سرور منتقل می‌شوند. داده‌ها می‌توانند از نوع \fBstr\fP، \fBbytes\fP، \fBdict\fP، \fBlist\fP یا \fBtuple\fP باشند\&. هنگام ارسال یک \fBlist\fP یا یک \fBtuple\fP، عناصر موجود در آن باید از هر یک از انواع مجاز به جز \fBtuple\fP باشند\&. هنگامی که از یک تاپل استفاده می‌شود، عناصر تاپل به عنوان آرگومان‌های مجزا به تابع مدیریت رویداد در سمت سرور ارسال خواهند شد. .sp متد \fBemit()\fP را می‌توان درون یک مدیریت‌کننده رویداد به عنوان پاسخی به یک رویداد سرور، یا در هر بخش دیگری از برنامه، از جمله در وظایف پس‌زمینه فراخوانی کرد. .SS "کال‌بک‌های رویداد (Event Callbacks)" .sp هنگامی که یک سرور رویدادی را به کلاینت ارسال می‌کند، می‌تواند به صورت اختیاری یک تابع کال‌بک (callback) ارائه دهد تا پس از پردازش رویداد توسط سرور، به عنوان راهی برای تأیید دریافت فراخوانی شود. اگرچه این موضوع به طور کامل توسط سرور مدیریت می‌شود، اما کلاینت می‌تواند فهرستی از مقادیر بازگشتی را برای ارسال به تابع کال‌بک تعیین‌شده توسط سرور فراهم کند. این کار به سادگی با بازگرداندن مقادیر مورد نظر از تابع مدیریت‌کننده انجام می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def my_event(sid, data): # handle the message return \(dqOK\(dq, 123 .EE .UNINDENT .UNINDENT .sp به همین ترتیب، کلاینت می‌تواند درخواست کند که پس از پردازش یک رویداد توسط سرور، یک تابع کال‌بک فراخوانی شود. متد \fBsocketio.Server.emit()\fP \%<#\:socketio\:.Server\:.emit> یک آرگومان اختیاری \fBcallback\fP دارد که می‌توان آن را روی یک شیء قابل فراخوانی (callable) تنظیم کرد. اگر این آرگومان مشخص شود، پس از پردازش رویداد توسط سرور، شیء قابل فراخوانی اجرا خواهد شد و هر مقداری که توسط مدیریت‌کننده سرور بازگردانده شود، به عنوان آرگومان به این تابع ارسال می‌گردد. .SS "فضاهای نام (Namespaces)" .sp پروتکل Socket.IO از چندین اتصال منطقی پشتیبانی می‌کند که همگی روی همان اتصال فیزیکی تسهیم (multiplex) می‌شوند. کلاینت‌ها می‌توانند با تعیین یک \fInamespace\fP متفاوت روی هر کدام، چندین اتصال برقرار کنند. فضاهای نام از قواعد ساختاری مسیر که با یک اسلش رو به جلو آغاز می‌شود استفاده می‌کنند. فهرستی از فضاهای نام را می‌توان توسط کلاینت در فراخوانی \fBconnect()\fP ارائه داد. برای نمونه، این مثال دو اتصال منطقی ایجاد می‌کند: یکی اتصال پیش‌فرض و دیگری اتصال دوم تحت فضای نام \fB/chat\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.connect(\(aqhttp://localhost:5000\(aq, namespaces=[\(aq/chat\(aq]) .EE .UNINDENT .UNINDENT .sp برای تعریف مدیریت‌کننده‌های رویداد روی یک فضای نام، آرگومان \fBnamespace\fP باید به دکوراتور مربوطه اضافه شود: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event(namespace=\(aq/chat\(aq) def my_custom_event(sid, data): pass @sio.on(\(aqconnect\(aq, namespace=\(aq/chat\(aq) def on_connect(): print(\(dqI\(aqm connected to the /chat namespace!\(dq) .EE .UNINDENT .UNINDENT .sp به همین ترتیب، کلاینت می‌تواند با تعیین آن در فراخوانی \fBemit()\fP، رویدادی را روی یک فضای نام به سرور ارسال کند: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.emit(\(aqmy message\(aq, {\(aqfoo\(aq: \(aqbar\(aq}, namespace=\(aq/chat\(aq) .EE .UNINDENT .UNINDENT .sp اگر آرگومان \fBnamespaces\fP در فراخوانی \fBconnect()\fP مشخص نشود، هر فضای نامی که در مدیریت‌کننده‌های رویداد استفاده شده باشد به طور خودکار متصل می‌شود..SS فضاهای نام مبتنی بر کلاس .sp به عنوان جایگزینی برای گرداننده‌های رویداد مبتنی بر دکوراتور، گرداننده‌های رویدادی که متعلق به یک فضای نام هستند می‌توانند به صورت متدهای یک زیرکلاس از \fBsocketio.ClientNamespace\fP \%<#\:socketio\:.ClientNamespace> ایجاد شوند: .INDENT 0.0 .INDENT 3.5 .sp .EX class MyCustomNamespace(socketio.ClientNamespace): def on_connect(self): pass def on_disconnect(self, reason): pass def on_my_event(self, data): self.emit(\(aqmy_response\(aq, data) sio.register_namespace(MyCustomNamespace(\(aq/chat\(aq)) .EE .UNINDENT .UNINDENT .sp برای سرورهای مبتنی بر asyncio، فضاهای نام باید از \fBsocketio.AsyncClientNamespace\fP \%<#\:socketio\:.AsyncClientNamespace> ارث‌بری کنند، و در صورت تمایل می‌توانند گرداننده‌های رویداد را به عنوان کوروتین (coroutine) تعریف نمایند: .INDENT 0.0 .INDENT 3.5 .sp .EX class MyCustomNamespace(socketio.AsyncClientNamespace): def on_connect(self): pass def on_disconnect(self, reason): pass async def on_my_event(self, data): await self.emit(\(aqmy_response\(aq, data) sio.register_namespace(MyCustomNamespace(\(aq/chat\(aq)) .EE .UNINDENT .UNINDENT .sp یک گردانندهٔ فضای نام مبتنی بر کلاس همه‌گیر (catch\-all) را می‌توان با ارسال \fB\(aq*\(aq\fP به عنوان فضای نام هنگام ثبت تعریف کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.register_namespace(MyCustomNamespace(\(aq*\(aq)) .EE .UNINDENT .UNINDENT .sp هنگامی که از فضاهای نام مبتنی بر کلاس استفاده می‌شود، هر رویداد دریافت شده توسط کلاینت به متدی که نام آن، نام رویداد همراه با پیشوند \fBon_\fP است ارسال می‌شود (dispatch). برای نمونه، رویداد \fBmy_event\fP توسط متدی به نام \fBon_my_event\fP\& مدیریت خواهد شد. اگر رویدادی دریافت شود که متد متناظری برای آن در کلاس فضای نام تعریف نشده باشد، آن رویداد نادیده گرفته می‌شود. تمام نام‌های رویداد که در فضاهای نام مبتنی بر کلاس استفاده می‌شوند باید از نویسه‌هایی استفاده کنند که در نام متدها مجاز باشند. .sp جهت سهولت متدهای تعریف‌شده در یک فضای نام مبتنی بر کلاس، نمونهٔ فضای نام شامل نسخه‌هایی از چندین متد از کلاس‌های \fBsocketio.Client\fP \%<#\:socketio\:.Client> و \fBsocketio.AsyncClient\fP \%<#\:socketio\:.AsyncClient> است که در صورت تعیین نشدن آرگومان \fBnamespace\fP، به صورت پیش‌فرض فضای نام مربوطه را در نظر می‌گیرند. .sp در صورتی که یک رویداد، هم یک گرداننده در فضای نام مبتنی بر کلاس و هم یک تابع گردانندهٔ مبتنی بر دکوراتور داشته باشد، تنها تابع گردانندهٔ مستقل فراخوانی می‌شود. .SS قطع اتصال از سرور .sp کلاینت در هر زمان می‌تواند با فراخوانی متد \fBdisconnect()\fP درخواست قطع اتصال از سرور را بدهد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.disconnect() .EE .UNINDENT .UNINDENT .sp برای کلاینت \fBasyncio\fP این یک کوروتین است: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.disconnect() .EE .UNINDENT .UNINDENT.SS "مدیریت وظایف پس‌زمینه (Managing Background Tasks)" .sp هنگامی که اتصال کلاینت به سرور برقرار می‌شود، چند وظیفهٔ پس‌زمینه برای زنده نگه‌داشتن اتصال و مدیریت رویدادهای ورودی ایجاد خواهند شد. برنامه‌ای که روی ریسهٔ اصلی (main thread) اجرا می‌شود برای انجام هر کاری آزاد است، چرا که این امر مانع از عملکرد کلاینت Socket.IO نخواهد شد. .sp اگر برنامه در ریسهٔ اصلی کاری برای انجام دادن ندارد و فقط می‌خواهد تا زمان پایان اتصال با سرور منتظر بماند، می‌تواند متد \fBwait()\fP را فراخوانی کند: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.wait() .EE .UNINDENT .UNINDENT .sp یا در نسخهٔ \fBasyncio\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.wait() .EE .UNINDENT .UNINDENT .sp برای راحتی برنامه، یک تابع کمکی برای راه‌اندازی یک وظیفهٔ پس‌زمینهٔ سفارشی ارائه شده است: .INDENT 0.0 .INDENT 3.5 .sp .EX def my_background_task(my_argument): # do some background work here! pass task = sio.start_background_task(my_background_task, 123) .EE .UNINDENT .UNINDENT .sp آرگومان‌های ارسال‌شده به این متد عبارت‌اند از تابع پس‌زمینه و هرگونه آرگومان موضعی (positional) یا کلیدواژه‌ای (keyword) که تابع باید با آن‌ها فراخوانی شود. .sp این نسخهٔ \fBasyncio\fP است: .INDENT 0.0 .INDENT 3.5 .sp .EX async def my_background_task(my_argument): # do some background work here! pass task = sio.start_background_task(my_background_task, 123) .EE .UNINDENT .UNINDENT .sp توجه داشته باشید که این تابع یک کوروتین (coroutine) نیست، زیرا منتظر پایان یافتن تابع پس‌زمینه نمی‌ماند. خود تابع پس‌زمینه حتماً باید یک کوروتین باشد. .sp متد \fBsleep()\fP تابع کمکی دوم است که برای سهولت برنامه‌هایی که با وظایف پس‌زمینهٔ اختصاصی خود کار می‌کنند فراهم شده است: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.sleep(2) .EE .UNINDENT .UNINDENT .sp یا برای \fBasyncio\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX await sio.sleep(2) .EE .UNINDENT .UNINDENT .sp تنها آرگومان ارسال‌شده به این متد، تعداد ثانیه‌های توقف (sleep) است..SS اشکال‌زدایی و عیب‌یابی (Debugging and Troubleshooting) .sp برای کمک به اشکال‌زدایی مشکلات، کلاینت را می‌توان طوری پیکربندی کرد که لاگ‌ها را در ترمینال خروجی دهد: .INDENT 0.0 .INDENT 3.5 .sp .EX import socketio # standard Python sio = socketio.Client(logger=True, engineio_logger=True) # asyncio sio = socketio.AsyncClient(logger=True, engineio_logger=True) .EE .UNINDENT .UNINDENT .sp آرگومان \fBlogger\fP ثبت وقایع مربوط به پروتکل Socket.IO را کنترل می‌کند، در حالی که \fBengineio_logger\fP لاگ‌های نشأت‌گرفته از لایهٔ انتقال سطح پایین Engine.IO را کنترل می‌نماید. این آرگومان‌ها می‌توانند روی \fBTrue\fP تنظیم شوند تا لاگ‌ها را در \fBstderr\fP خروجی دهند، یا روی شیئی سازگار با بستهٔ \fBlogging\fP پایتون که لاگ‌ها باید به آن ارسال شوند. مقدار \fBFalse\fP ثبت وقایع را غیرفعال می‌کند. .sp ثبت وقایع می‌تواند به شناسایی علت مشکلات اتصال، قطع‌شدن‌های غیرمنتظره و سایر مسائل کمک کند. .SH "سرور SOCKET.IO (THE SOCKET.IO SERVER)" .sp این بسته شامل دو سرور Socket.IO است: .INDENT 0.0 .IP \(bu 2 کلاس \fBsocketio.Server()\fP \%<#\:socketio\:.Server> سروری سازگار با کتابخانهٔ استاندارد پایتون ایجاد می‌کند. .IP \(bu 2 کلاس \fBsocketio.AsyncServer()\fP \%<#\:socketio\:.AsyncServer> سروری سازگار با بستهٔ \fBasyncio\fP ایجاد می‌کند. .UNINDENT .sp متدهای هر دو سرور یکسان هستند، با این تفاوت که در سرور \fBasyncio\fP اکثر متدها به‌صورت کوروتین (coroutine) پیاده‌سازی شده‌اند. .SS نصب (Installation) .sp برای نصب سرور Socket.IO به همراه وابستگی‌های آن، از دستور زیر استفاده کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX pip install python\-socketio .EE .UNINDENT .UNINDENT .SS ایجاد یک نمونه سرور (Creating a Server Instance) .sp یک سرور Socket.IO، نمونه‌ای از کلاس \fBsocketio.Server\fP \%<#\:socketio\:.Server> است: .INDENT 0.0 .INDENT 3.5 .sp .EX import socketio # create a Socket.IO server sio = socketio.Server() .EE .UNINDENT .UNINDENT .sp برای سرورهای مبتنی بر asyncio، کلاس \fBsocketio.AsyncServer\fP \%<#\:socketio\:.AsyncServer> همان سازوکار را در قالبی سازگار با کوروتین‌ها ارائه می‌دهد: .INDENT 0.0 .INDENT 3.5 .sp .EX import socketio # create a Socket.IO server sio = socketio.AsyncServer() .EE .UNINDENT .UNINDENT.SS اجرای سرور .sp برای اجرای برنامه Socket.IO لازم است یک وب‌سرور پیکربندی شود تا درخواست‌های دریافتی از کلاینت‌ها را دریافت کرده و آن‌ها را به نمونهٔ سرور Socket.IO فوروارد کند. برای ساده‌سازی این کار، یکپارچه‌سازی‌های متعددی در دسترس است، از جمله پشتیبانی از استانداردهای WSGI \% و ASGI \%\&. .SS اجرا به عنوان یک برنامه WSGI .sp برای پیکربندی سرور Socket.IO به عنوان یک برنامه WSGI، نمونهٔ سرور را با کلاس \fBsocketio.WSGIApp\fP \%<#\:socketio\:.WSGIApp> کپسوله‌سازی (wrap) کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX # wrap with a WSGI application app = socketio.WSGIApp(sio) .EE .UNINDENT .UNINDENT .sp برنامهٔ WSGI حاصل را می‌توان با وب‌سرورهای پشتیبانی‌شدهٔ WSGI مانند Werkzeug \% برای توسعه و Gunicorn \% برای محیط عملیاتی (production) اجرا کرد. .sp هنگام ترکیب Socket.IO با یک برنامه وب نوشته‌شده با چارچوب‌های WSGI نظیر Flask یا Django، کلاس \fBWSGIApp\fP می‌تواند هر دو برنامه را با یکدیگر پوشش داده و ترافیک را به سمت آن‌ها هدایت کند: .INDENT 0.0 .INDENT 3.5 .sp .EX from mywebapp import app # a Flask, Django, etc. application app = socketio.WSGIApp(sio, app) .EE .UNINDENT .UNINDENT .SS اجرا به عنوان یک برنامه ASGI .sp برای پیکربندی سرور Socket.IO به عنوان یک برنامه ASGI، نمونهٔ سرور را با کلاس \fBsocketio.ASGIApp\fP \%<#\:socketio\:.ASGIApp> کپسوله‌سازی (wrap) کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX # wrap with ASGI application app = socketio.ASGIApp(sio) .EE .UNINDENT .UNINDENT .sp برنامهٔ ASGI حاصل را می‌توان با یک وب‌سرور سازگار با ASGI، مانند Uvicorn \%\& اجرا کرد. .sp همچنین می‌توان Socket.IO را با یک برنامه وب نوشته‌شده با چارچوب‌های وب ASGI مانند FastAPI ترکیب کرد. در این حالت، کلاس \fBASGIApp\fP می‌تواند هر دو برنامه را با یکدیگر پوشش داده و ترافیک را به سمت آن‌ها هدایت کند: .INDENT 0.0 .INDENT 3.5 .sp .EX from mywebapp import app # a FastAPI or other ASGI application app = socketio.ASGIApp(sio, app) .EE .UNINDENT .UNINDENT .SS ارائه فایل‌های ایستا .sp سرور Socket.IO می‌تواند برای ارائه فایل‌های ایستا (static files) به کلاینت‌ها پیکربندی شود. این قابلیت به‌ویژه زمانی مفید است که این بسته بدون یک چارچوب وب جانبی استفاده شود و نیاز به تحویل فایل‌های HTML، CSS و JavaScript به کلاینت‌ها باشد. .sp فایل‌های ایستا با یک دیکشنری پایتون پیکربندی می‌شوند که در آن هر جفت کلید/مقدار یک قانون نگاشت فایل ایستا است. در ساده‌ترین شکل، این دیکشنری یک یا چند نشانی اینترنتی (URL) فایل ایستا را به عنوان کلید، و فایل‌های متناظر در سرور را به عنوان مقدار در بر دارد: .INDENT 0.0 .INDENT 3.5 .sp .EX static_files = { \(aq/\(aq: \(aqlatency.html\(aq, \(aq/static/socket.io.js\(aq: \(aqstatic/socket.io.js\(aq, \(aq/static/style.css\(aq: \(aqstatic/style.css\(aq, } .EE .UNINDENT .UNINDENT .sp با این پیکربندی نمونه، زمانی که سرور درخواستی برای \fB/\fP (نشانی ریشه) دریافت می‌کند، محتویات فایل \fBlatency.html\fP در دایرکتوری فعلی را برمی‌گرداند، و یک نوع محتوا (content type) بر اساس پسوند فایل تعیین می‌کند که در این مورد \fBtext/html\fP خواهد بود. .sp فایل‌های دارای پسوندهای \fB\&.html\fP، \fB\&.css\fP، \fB\&.js\fP، \fB\&.json\fP، \fB\&.jpg\fP، \fB\&.png\fP، \fB\&.gif\fP و \fB\&.txt\fP به‌طور خودکار شناسایی شده و نوع محتوای صحیح به آن‌ها اختصاص می‌یابد. برای فایل‌هایی با سایر پسوندها یا بدون پسوند فایل، نوع محتوای پیش‌فرض \fBapplication/octet\-stream\fP استفاده می‌شود. .sp در صورت تمایل، می‌توان نوع محتوای صریح را برای یک فایل ایستا به شکل زیر مشخص کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX static_files = { \(aq/\(aq: {\(aqfilename\(aq: \(aqlatency.html\(aq, \(aqcontent_type\(aq: \(aqtext/plain\(aq}, } .EE .UNINDENT .UNINDENT .sp همچنین می‌توان یک دایرکتوری کامل را در قالب یک قاعده واحد پیکربندی کرد، به‌گونه‌ای که تمام فایل‌های درون آن به عنوان فایل ایستا ارائه شوند: .INDENT 0.0 .INDENT 3.5 .sp .EX static_files = { \(aq/static\(aq: \(aq./public\(aq, } .EE .UNINDENT .UNINDENT .sp در این مثال، هر فایلی با نشانی که با \fB/static\fP آغاز شود مستقیماً از پوشهٔ \fBpublic\fP در دایرکتوری فعلی ارائه خواهد شد؛ بنابراین به عنوان مثال، نشانی \fB/static/index.html\fP فایل محلی \fB\&./public/index.html\fP و نشانی \fB/static/css/styles.css\fP فایل محلی \fB\&./public/css/styles.css\fP را برمی‌گرداند. .sp اگر نشانی درخواستی به \fB/\fP ختم شود، نام فایل پیش‌فرض \fBindex.html\fP به انتهای آن الحاق می‌گردد. در مثال قبلی، درخواست برای نشانی \fB/static/\fP فایل محلی \fB\&./public/index.html\fP را برمی‌گرداند. نام فایل پیش‌فرض برای ارائه در نشانی‌های ختم‌شده به اسلش را می‌توان در دیکشنری فایل‌های ایستا با یک کلید خالی تنظیم کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX static_files = { \(aq/static\(aq: \(aq./public\(aq, \(aq\(aq: \(aqimage.gif\(aq, } .EE .UNINDENT .UNINDENT .sp با این پیکربندی، درخواستی برای \fB/static/\fP فایل محلی \fB\&./public/image.gif\fP را برمی‌گرداند. در صورت نیاز می‌توان نوع محتوای غیر استاندارد را نیز تعیین کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX static_files = { \(aq/static\(aq: \(aq./public\(aq, \(aq\(aq: {\(aqfilename\(aq: \(aqimage.gif\(aq, \(aqcontent_type\(aq: \(aqtext/plain\(aq}, } .EE .UNINDENT .UNINDENT .sp دیکشنری پیکربندی فایل‌های ایستا به عنوان آرگومان \fBstatic_files\fP به کلاس‌های \fBsocketio.WSGIApp\fP یا \fBsocketio.ASGIApp\fP داده می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX # for standard WSGI applications sio = socketio.Server() app = socketio.WSGIApp(sio, static_files=static_files) # for asyncio\-based ASGI applications sio = socketio.AsyncServer() app = socketio.ASGIApp(sio, static_files=static_files) .EE .UNINDENT .UNINDENT .sp اولویت مسیریابی در این دو کلاس به شرح زیر است: .INDENT 0.0.IP \(bu 2 ابتدا، مسیر در برابر endpoint مربوط به Socket.IO بررسی می‌شود. .IP \(bu 2 سپس در صورت وجود، مسیر با پیکربندی فایل‌های ایستا (static file) سنجیده می‌شود. .IP \(bu 2 اگر مسیر با endpoint پروتکل Socket.IO یا هیچ فایل ایستایی مطابقت نداشت، در صورت پیکربندی، کنترل به برنامه ثانویه واگذار می‌شود؛ در غیر این صورت خطای 404 بازگردانده می‌شود. .UNINDENT .sp نکته: ارائه فایل‌های ایستا تنها برای مقاصد توسعه در نظر گرفته شده است و به همین دلیل فاقد قابلیت‌های مهمی مانند حافظه نهان (caching) است. از آن در محیط عملیاتی (production) استفاده نکنید. .SS "رویدادها (Events)" .sp پروتکل Socket.IO رویدادمحور است. هنگامی که یک کلاینت قصد برقراری ارتباط با سرور را دارد، یا سرور می‌خواهد با یک یا چند کلاینت ارتباط برقرار کند، رویدادی را برای طرف مقابل \fIارسال\fP (\fIemit\fP) می‌کند. هر رویداد دارای یک نام و فهرستی اختیاری از آرگومان‌ها است. .SS "شنود رویدادها (Listening to Events)" .sp برای دریافت رویدادها از کلاینت‌ها، برنامه سمت سرور باید توابع گرداننده رویداد (event handler) را ثبت کند. این توابع زمانی که رویدادهای مربوطه توسط کلاینت‌ها ارسال می‌شوند، فراخوانی می‌گردند. برای ثبت یک گرداننده برای یک رویداد، دکوراتورهای \fBsocketio.Server.event()\fP \%<#\:socketio\:.Server\:.event> یا \fBsocketio.Server.on()\fP \%<#\:socketio\:.Server\:.on> به کار می‌روند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def my_event(sid, data): pass @sio.on(\(aqmy custom event\(aq) def another_event(sid, data): pass .EE .UNINDENT .UNINDENT .sp در مثال نخست، نام رویداد از نام تابع گرداننده گرفته می‌شود. مثال دوم کمی مفصل‌تر است، اما این امکان را فراهم می‌کند که نام رویداد با نام تابع تفاوت داشته باشد یا شامل نویسه‌هایی مانند فاصله باشد که در نام توابع غیرمجاز هستند. .sp برای سرورهای مبتنی بر asyncio، گرداننده‌های رویداد را می‌توان به صورت اختیاری به عنوان کوروتین (coroutine) تعریف کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event async def my_event(sid, data): pass .EE .UNINDENT .UNINDENT .sp آرگومان \fBsid\fP که به تمام گرداننده‌ها ارسال می‌شود، شناسه نشست (session id) در Socket.IO است؛ شناسه‌ای یکتا که Socket.IO به هر اتصال کلاینت اختصاص می‌دهد. تمامی رویدادهای ارسال‌شده توسط یک کلاینت مشخص، مقدار \fBsid\fP یکسانی خواهند داشت. .SS "رویدادهای اتصال و قطع اتصال (Connect and Disconnect Events)" .sp رویدادهای \fBconnect\fP و \fBdisconnect\fP رویدادهای ویژه‌ای هستند؛ این رویدادها هنگامی که کلاینت به سرور متصل یا اتصال آن قطع می‌شود، به طور خودکار فراخوانی می‌گردند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def connect(sid, environ, auth): print(\(aqconnect \(aq, sid) @sio.event def disconnect(sid, reason): print(\(aqdisconnect \(aq, sid, reason) .EE .UNINDENT .UNINDENT .sp رویداد \fBconnect\fP بستری ایده‌آل برای انجام احراز هویت کاربر و هرگونه نگاشت لازم میان هویت‌های کاربر در برنامه و \fBsid\fP اختصاص‌یافته به کلاینت است. .sp علاوه بر \fBsid\fP، گرداننده اتصال آرگومان \fBenviron\fP را نیز دریافت می‌کند که دربردارنده اطلاعات درخواست در قالب استاندارد WSGI به همراه هدرهای HTTP است. این گرداننده همچنین آرگومان \fBauth\fP را به همراه هرگونه جزئیات احراز هویت ارائه‌شده توسط کلاینت، یا در صورت عدم ارسال آن، مقدار \fBNone\fP را دریافت می‌کند. .sp پس از بررسی آرگومان‌ها، گرداننده رویداد connect می‌تواند برای رد اتصال کلاینت مقدار \fBFalse\fP را بازگرداند. در مواردی ارسال داده به کلاینتِ رد شده سودمند است؛ در چنین شرایطی به جای بازگرداندن \fBFalse\fP می‌توان استثنای \fBsocketio.exceptions.ConnectionRefusedError\fP \%<#\:socketio\:.exceptions\:.ConnectionRefusedError> را صادر (raise) کرد، و تمام آرگومان‌های آن به همراه پیام رد شدن برای کلاینت فرستاده خواهد شد: .INDENT 0.0 .INDENT 3.5 .sp .EX from socketio.exceptions import ConnectionRefusedError @sio.event def connect(sid, environ, auth): raise ConnectionRefusedError(\(aqauthentication failed\(aq) .EE .UNINDENT .UNINDENT .sp گرداننده قطع اتصال مقدار \fBsid\fP اختصاص‌یافته به کلاینت و آرگومان \fBreason\fP را که علت قطع اتصال را مشخص می‌کند، دریافت می‌نماید: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def disconnect(sid, reason): if reason == sio.reason.CLIENT_DISCONNECT: print(\(aqthe client disconnected\(aq) elif reason == sio.reason.SERVER_DISCONNECT: print(\(aqthe server disconnected the client\(aq) else: print(\(aqdisconnect reason:\(aq, reason) .EE .UNINDENT .UNINDENT .sp برای مشاهده فهرستی از دلایل احتمالی قطع اتصال، صفت \fBsocketio.Server.reason\fP \%<#\:socketio\:.Server\:.reason> را ببینید..SS گرداننده‌های رویداد همه‌گیر (Catch\-All Event Handlers) .sp یک گرداننده رویداد «همه‌گیر» (catch\-all) برای تمام رویدادهایی که گرداننده مشخصی ندارند فراخوانی می‌شود. شما می‌توانید با استفاده از \fB\(aq*\(aq\fP به عنوان نام رویداد، یک گرداننده همه‌گیر تعریف کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.on(\(aq*\(aq) def any_event(event, sid, data): pass .EE .UNINDENT .UNINDENT .sp سرورهای Asyncio همچنین می‌توانند از یک کوروتین (coroutine) استفاده کنند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.on(\(aq*\(aq) async def any_event(event, sid, data): pass .EE .UNINDENT .UNINDENT .sp یک گرداننده رویداد همه‌گیر، نام رویداد را به عنوان نخستین آرگومان دریافت می‌کند. باقی آرگومان‌ها همانند یک گرداننده رویداد معمولی هستند. .sp توجه داشته باشید که رویدادهای \fBconnect\fP و \fBdisconnect\fP باید به‌طور صریح تعریف شوند و توسط گرداننده رویداد همه‌گیر فراخوانی نمی‌شوند. .SS ارسال رویدادها به کلاینت‌ها (Emitting Events to Clients) .sp پروتکل Socket.IO یک پروتکل دوطرفه است؛ بنابراین سرور در هر زمان می‌تواند رویدادی را به کلاینت‌های متصل خود ارسال کند. متد \fBsocketio.Server.emit()\fP \%<#\:socketio\:.Server\:.emit> برای این منظور به کار می‌رود: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.emit(\(aqmy event\(aq, {\(aqdata\(aq: \(aqfoobar\(aq}) .EE .UNINDENT .UNINDENT .sp نخستین آرگومان، نام رویداد است و پس از آن یک بارداده اختیاری از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP، \fBdict\fP یا \fBtuple\fP\& قرار می‌گیرد. هنگام ارسال یک \fBlist\fP، \fBdict\fP یا \fBtuple\fP، عناصر آن‌ها نیز به همین انواع داده محدود هستند. هنگامی که یک \fBtuple\fP ارسال می‌شود، عناصر آن به عنوان چندین آرگومان به تابع گرداننده رویداد در سمت کلاینت تحویل داده خواهند شد. .sp مثال بالا رویداد را به تمامی کلاینت‌های متصل ارسال می‌کند. گاهی ممکن است سرور بخواهد رویدادی را تنها به یک کلاینت خاص ارسال کند. این امر با افزودن آرگومان \fBto\fP با مقدار \fBsid\fP کلاینت به فراخوانی emit امکان‌پذیر است: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.emit(\(aqmy event\(aq, {\(aqdata\(aq: \(aqfoobar\(aq}, to=user_sid) .EE .UNINDENT .UNINDENT .sp آرگومان \fBto\fP برای شناسایی کلاینتی که باید رویداد را دریافت کند استفاده می‌شود و مقدار آن برابر با \fBsid\fP اختصاص‌یافته به اتصال آن کلاینت با سرور تنظیم می‌گردد. در صورت حذف \fBto\fP، رویداد برای تمامی کلاینت‌های متصل همه‌پخشی (broadcast) می‌شود. .SS تصدیق رویدادها (Acknowledging Events) .sp هنگامی که کلاینت رویدادی را به سرور ارسال می‌کند، می‌تواند به‌صورت اختیاری درخواست دریافت تصدیق (acknowledgment) از سرور را داشته باشد. ارسال پیام‌های تصدیق به‌صورت خودکار توسط سرور Socket.IO مدیریت می‌شود، اما تابع گرداننده رویداد می‌تواند صرفاً با بازگرداندن مجموعه‌ای از مقادیر، آن‌ها را همراه با تصدیق به کلاینت منتقل کند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def my_event(sid, data): # handle the message return \(dqOK\(dq, 123 # <\-\- client will have these as acknowledgement .EE .UNINDENT .UNINDENT.SS "درخواست تأییدیه از کلاینت (Requesting Client Acknowledgements)" .sp مشابه حالتی که کلاینت‌ها می‌توانند از سرور درخواست تأییدیه (acknowledgement) کنند، زمانی که سرور رویدادی را برای یک کلاینت تکی ارسال (emit) می‌کند نیز می‌تواند از کلاینت بخواهد دریافت رویداد را تأیید کند و به‌صورت اختیاری یک یا چند مقدار را به عنوان پاسخ بازگرداند. .sp سرور Socket.IO از دو روش برای کار با تأییدیه‌های کلاینت پشتیبانی می‌کند. راحت‌ترین روش، جایگزین کردن \fBsocketio.Server.emit()\fP \%<#\:socketio\:.Server\:.emit> با \fBsocketio.Server.call()\fP \%<#\:socketio\:.Server\:.call>\& است. متد \fBcall()\fP رویداد را ارسال کرده و سپس تا زمان ارسال تأییدیه توسط کلاینت منتظر می‌ماند، و هر مقداری را که توسط کلاینت ارائه شود بازمی‌گرداند: .INDENT 0.0 .INDENT 3.5 .sp .EX response = sio.call(\(aqmy event\(aq, {\(aqdata\(aq: \(aqfoobar\(aq}, to=user_sid) .EE .UNINDENT .UNINDENT .sp یک راهکار بسیار ابتدایی‌تر برای تأییدیه، استفاده از توابع بازخوانی (callback) است. متد \fBsocketio.Server.emit()\fP \%<#\:socketio\:.Server\:.emit> دارای یک آرگومان اختیاری \fBcallback\fP است که می‌تواند روی یک شیء فراخوان‌پذیر (callable) تنظیم شود. اگر این آرگومان داده شود، شیء فراخوان‌پذیر پس از پردازش رویداد توسط کلاینت فراخوانی خواهد شد و مقادیر بازگردانده‌شده توسط کلاینت به عنوان آرگومان به این تابع ارسال می‌شوند: .INDENT 0.0 .INDENT 3.5 .sp .EX def my_callback(): print(\(dqcallback invoked!\(dq) sio.emit(\(aqmy event\(aq, {\(aqdata\(aq: \(aqfoobar\(aq}, to=user_sid, callback=my_callback) .EE .UNINDENT .UNINDENT .SS "اتاق‌ها (Rooms)" .sp برای سهولت در ارسال رویدادها توسط سرور به گروه‌هایی از کلاینت‌های مرتبط، برنامه کاربردی می‌تواند کلاینت‌های خود را در \(dqاتاق‌ها\(dq (rooms) قرار دهد و سپس پیام‌ها را به این اتاق‌ها ارسال کند. .sp در مثال‌های قبلی، آرگومان \fBto\fP در متد \fBsocketio.SocketIO.emit()\fP برای مشخص کردن یک کلاینت خاص به عنوان گیرنده رویداد استفاده می‌شد. به آرگومان \fBto\fP همچنین می‌توان نام یک اتاق را اختصاص داد، تا تمام کلاینت‌های حاضر در آن اتاق، رویداد را دریافت کنند. .sp برنامه کاربردی می‌تواند به هر تعداد که لازم است اتاق ایجاد کند و با استفاده از متدهای \fBsocketio.Server.enter_room()\fP \%<#\:socketio\:.Server\:.enter_room> و \fBsocketio.Server.leave_room()\fP \%<#\:socketio\:.Server\:.leave_room> کلاینت‌های حاضر در آن‌ها را مدیریت کند. کلاینت‌ها می‌توانند در هر تعداد اتاق که نیاز باشد عضو شوند و در صورت لزوم بین اتاق‌ها جابه‌جا گردند. .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def begin_chat(sid): sio.enter_room(sid, \(aqchat_users\(aq) @sio.event def exit_chat(sid): sio.leave_room(sid, \(aqchat_users\(aq) .EE .UNINDENT .UNINDENT .sp در برنامه‌های گفتگو (chat)، اغلب مطلوب است که یک رویداد به تمام اعضای اتاق به جز یک نفر (که مبدأ و ارسال‌کننده رویداد مانند پیام چت است) همه‌پخشی (broadcast) شود. متد \fBsocketio.Server.emit()\fP \%<#\:socketio\:.Server\:.emit> یک آرگومان اختیاری \fBskip_sid\fP را ارائه می‌دهد تا کلاینتی را که باید در حین همه‌پخشی نادیده گرفته شود مشخص کند. .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def my_message(sid, data): sio.emit(\(aqmy reply\(aq, data, room=\(aqchat_users\(aq, skip_sid=sid) .EE .UNINDENT .UNINDENT.SS فضاهای نام (Namespaces) .sp پروتکل Socket.IO از چندین اتصال منطقی که همگی روی یک اتصال فیزیکی یکسان تسهیم (multiplex) شده‌اند پشتیبانی می‌کند. کلاینت‌ها می‌توانند با تعیین یک \fInamespace\fP متفاوت در هر اتصال، چندین ارتباط را باز کنند. یک فضای نام توسط کلاینت به عنوان یک مسیر پس از نام میزبان و پورت مشخص می‌شود. به عنوان مثال، اتصال به \fIhttp://example.com:8000/chat\fP اتصالی را به فضای نام \fI/chat\fP باز می‌کند\&. .sp هر فضای نام مستقل از سایرین کار می‌کند و دارای شناسه‌های نشست (\fBsid\fPها)، گرداننده‌های رویداد و اتاق‌های مجزا است. فضاهای نام را می‌توان مستقیماً در توابع گرداننده رویداد تعریف کرد، یا اینکه می‌توان آن‌ها را به صورت کلاس ایجاد نمود. .SS فضاهای نام مبتنی بر دکوراتور (Decorator\-Based Namespaces) .sp فضاهای نام مبتنی بر دکوراتور، همان گرداننده‌های رویداد معمولی هستند که آرگومان \fBnamespace\fP را در دکوراتور خود شامل می‌شوند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event(namespace=\(aq/chat\(aq) def my_custom_event(sid, data): pass @sio.on(\(aqmy custom event\(aq, namespace=\(aq/chat\(aq) def my_custom_event(sid, data): pass .EE .UNINDENT .UNINDENT .sp هنگام گسیل (emit) یک رویداد، از آرگومان اختیاری \fBnamespace\fP برای تعیین فضای نامی که رویداد باید روی آن ارسال شود استفاده می‌شود. هنگامی که آرگومان \fBnamespace\fP حذف شود، فضای نام پیش‌فرض Socket.IO که \fB/\fP نام دارد، مورد استفاده قرار می‌گیرد. .sp بسیار مهم است که برنامه‌های استفاده‌کننده از چندین فضای نام، هنگام راه‌اندازی گرداننده‌های رویداد و اتاق‌های خود با استفاده از آرگومان اختیاری \fBnamespace\fP، فضای نام صحیح را مشخص کنند. این آرگومان همچنین باید هنگام گسیل رویدادها ذیل یک فضای نام مشخص شود. اکثر متدها در کلاس \fBsocketio.Server\fP \%<#\:socketio\:.Server> دارای آرگومان اختیاری \fBnamespace\fP هستند. .SS فضاهای نام مبتنی بر کلاس (Class\-Based Namespaces) .sp به عنوان جایگزینی برای فضاهای نام مبتنی بر دکوراتور، گرداننده‌های رویداد متعلق به یک فضای نام می‌توانند به عنوان متدهایی در یک زیرکلاس از \fBsocketio.Namespace\fP \%<#\:socketio\:.Namespace> ایجاد شوند: .INDENT 0.0 .INDENT 3.5 .sp .EX class MyCustomNamespace(socketio.Namespace): def on_connect(self, sid, environ): pass def on_disconnect(self, sid, reason): pass def on_my_event(self, sid, data): self.emit(\(aqmy_response\(aq, data) sio.register_namespace(MyCustomNamespace(\(aq/test\(aq)) .EE .UNINDENT .UNINDENT .sp برای سرورهای مبتنی بر asyncio، فضاهای نام باید از \fBsocketio.AsyncNamespace\fP \%<#\:socketio\:.AsyncNamespace> ارث‌بری کنند، و در صورت تمایل می‌توانند گرداننده‌های رویداد را به عنوان کوروتین (coroutine) تعریف نمایند: .INDENT 0.0 .INDENT 3.5 .sp .EX class MyCustomNamespace(socketio.AsyncNamespace): def on_connect(self, sid, environ): pass def on_disconnect(self, sid, reason): pass async def on_my_event(self, sid, data): await self.emit(\(aqmy_response\(aq, data) sio.register_namespace(MyCustomNamespace(\(aq/test\(aq)) .EE .UNINDENT .UNINDENT .sp هنگامی که از فضاهای نام مبتنی بر کلاس استفاده می‌شود، هر رویداد دریافت‌شده توسط سرور به متدی با نام همان رویداد به همراه پیشوند \fBon_\fP هدایت می‌شود. برای مثال، رویداد \fBmy_event\fP توسط متدی به نام \fBon_my_event\fP مدیریت خواهد شد\&. اگر رویدادی دریافت شود که هیچ متد متناظری برای آن در کلاس فضای نام تعریف نشده باشد، آن رویداد نادیده گرفته می‌شود. تمامی نام‌های رویداد استفاده‌شده در فضاهای نام مبتنی بر کلاس باید از نویسه‌هایی استفاده کنند که در نام متدها مجاز هستند. .sp جهت سهولت برای متدهای تعریف‌شده در یک فضای نام مبتنی بر کلاس، نمونه‌ی فضای نام شامل نسخه‌هایی از چندین متد از کلاس‌های \fBsocketio.Server\fP \%<#\:socketio\:.Server> و \fBsocketio.AsyncServer\fP \%<#\:socketio\:.AsyncServer> است که در صورت ارائه نشدن آرگومان \fBnamespace\fP، به طور پیش‌فرض از فضای نام مربوطه استفاده می‌کنند. .sp در صورتی که یک رویداد دارای یک گرداننده در فضای نام مبتنی بر کلاس باشد و همچنین یک تابع گرداننده مبتنی بر دکوراتور داشته باشد، تنها تابع گرداننده‌ی مستقل فراخوانی می‌شود. .sp توجه به این نکته مهم است که فضاهای نام مبتنی بر کلاس به صورت یگانه‌الگو (singleton) هستند. این بدان معناست که یک نمونه‌ی واحد از کلاس فضای نام برای تمامی کلاینت‌ها استفاده می‌شود، و در نتیجه، از یک نمونه‌ی فضای نام نمی‌توان برای ذخیره اطلاعات خاص هر کلاینت استفاده کرد..SS فضاهای نام همه‌گیر (Catch\-All Namespaces) .sp همانند گرداننده‌های رویداد همه‌گیر (catch\-all)، هنگام تعریف گرداننده‌های رویداد برای هر فضای نام متصلی که گرداننده رویدادِ صریحاً تعریف‌شده‌ای ندارد، می‌توان از یک فضای نام «همه‌گیر» (\(dqcatch\-all\(dq) استفاده کرد. مانند رویدادهای همه‌گیر، از \fB\(aq*\(aq\fP به‌جای فضای نام استفاده می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.on(\(aqmy_event\(aq, namespace=\(aq*\(aq) def my_event_any_namespace(namespace, sid, data): pass .EE .UNINDENT .UNINDENT .sp برای این رویدادها، فضای نام به‌عنوان نخستین آرگومان ارسال می‌شود و به‌دنبال آن، آرگومان‌های معمول رویداد قرار می‌گیرند. .sp یک گرداننده فضای نامِ مبتنی بر کلاس از نوع همه‌گیر (catch\-all) را می‌توان با ارسال \fB\(aq*\(aq\fP به‌عنوان فضای نام در هنگام ثبت (registration) تعریف کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio.register_namespace(MyCustomNamespace(\(aq*\(aq)) .EE .UNINDENT .UNINDENT .sp یک گرداننده «همه‌گیر» (\(dqcatch\-all\(dq) برای تمام رویدادها در تمام فضاهای نام را می‌توان به‌صورت زیر تعریف کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.on(\(aq*\(aq, namespace=\(aq*\(aq) def any_event_any_namespace(event, namespace, sid, data): pass .EE .UNINDENT .UNINDENT .sp گرداننده‌های رویداد با رویدادها و فضاهای نام همه‌گیر، نام رویداد و فضای نام را به‌عنوان آرگومان‌های اول و دوم دریافت می‌کنند. .SS نشست‌های کاربر (User Sessions) .sp سرور می‌تواند اطلاعات مختص برنامه را در یک نشست کاربر (user session) اختصاص‌یافته به هر کلاینت متصل نگهداری کند. برنامه‌ها می‌توانند از نشست کاربر برای ذخیره هرگونه جزئیات درباره کاربر که باید در طول عمر اتصال حفظ شود (مانند نام‌های کاربری یا شناسه کاربری)، استفاده کنند. .sp متدهای \fBsave_session()\fP و \fBget_session()\fP برای ذخیره و بازیابی اطلاعات در نشست کاربر استفاده می‌شوند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def connect(sid, environ): username = authenticate_user(environ) sio.save_session(sid, {\(aqusername\(aq: username}) @sio.event def message(sid, data): session = sio.get_session(sid) print(\(aqmessage from \(aq, session[\(aqusername\(aq]) .EE .UNINDENT .UNINDENT .sp برای سرور \fBasyncio\fP، این متدها از نوع کوروتین (coroutine) هستند: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event async def connect(sid, environ): username = authenticate_user(environ) await sio.save_session(sid, {\(aqusername\(aq: username}) @sio.event async def message(sid, data): session = await sio.get_session(sid) print(\(aqmessage from \(aq, session[\(aqusername\(aq]) .EE .UNINDENT .UNINDENT .sp همچنین نشست را می‌توان با استفاده از مدیر زمینه (context manager) \fIsession()\fP مدیریت کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event def connect(sid, environ): username = authenticate_user(environ) with sio.session(sid) as session: session[\(aqusername\(aq] = username @sio.event def message(sid, data): with sio.session(sid) as session: print(\(aqmessage from \(aq, session[\(aqusername\(aq]) .EE .UNINDENT .UNINDENT .sp برای سرور \fBasyncio\fP، از یک مدیر زمینه ناهمگام (asynchronous context manager) استفاده می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX @sio.event async def connect(sid, environ): username = authenticate_user(environ) async with sio.session(sid) as session: session[\(aqusername\(aq] = username @sio.event async def message(sid, data): async with sio.session(sid) as session: print(\(aqmessage from \(aq, session[\(aqusername\(aq]) .EE .UNINDENT .UNINDENT .sp متدهای \fBget_session()\fP، \fBsave_session()\fP و \fBsession()\fP یک آرگومان اختیاری \fBnamespace\fP می‌پذیرند. اگر این آرگومان ارائه نشود، نشست به فضای نام پیش‌فرض متصل می‌شود. .sp نکته: محتویات نشست کاربر با قطع اتصال کلاینت از بین می‌رود. به‌ویژه، هنگامی که یک کلاینت پس از قطعی غیرمنتظره دوباره به سرور متصل می‌شود، محتویات نشست کاربر حفظ نمی‌گردد..SS کنترل‌های مبدأ متقابل (Cross\-Origin Controls) .sp به دلایل امنیتی، این سرور به‌طور پیش‌فرض سیاست همانند‌مبدأ (same\-origin policy) را اعمال می‌کند. در عمل، این موضوع بیانگر موارد زیر است: .INDENT 0.0 .IP \(bu 2 اگر یک درخواست ورودی HTTP یا WebSocket حاوی سرآیند \fBOrigin\fP باشد، این سرآیند باید با طرحواره (scheme) و میزبان (host) نشانی URL اتصال مطابقت داشته باشد. در صورت عدم تطابق، پاسخی با کد وضعیت 400 بازگردانده شده و اتصال رد می‌شود. .IP \(bu 2 هیچ محدودیتی بر روی درخواست‌های ورودی که فاقد سرآیند \fBOrigin\fP هستند اعمال نمی‌شود. .UNINDENT .sp در صورت نیاز، می‌توان از گزینه \fBcors_allowed_origins\fP برای مجاز کردن سایر مبدأها استفاده کرد. این آرگومان می‌تواند روی یک رشته برای تنظیم یک مبدأ مجاز واحد، یا روی یک فهرست برای مجاز کردن چندین مبدأ تنظیم شود. مقدار ویژه \fB\(aq*\(aq\fP می‌تواند برای دستور دادن به سرور جهت مجاز کردن همه مبدأها استفاده شود، اما این کار باید با احتیاط انجام گیرد، زیرا می‌تواند سرور را در برابر حملات جعل درخواست میان‌وب‌گاهی (CSRF) آسیب‌پذیر کند. .SS پایش و مدیریت (Monitoring and Administration) .sp سرور Socket.IO می‌تواند به‌گونه‌ای پیکربندی شود که اتصالات را از رابط کاربری رسمی Socket.IO Admin UI \%\& بپذیرد. این ابزار اطلاعات بی‌درنگی را درباره کلاینت‌های متصل فعلی، اتاق‌های در حال استفاده و رویدادهای در حال انتشار ارائه می‌دهد. همچنین به یک مدیر امکان می‌دهد رویدادها را به صورت دستی منتشر کرده، تخصیص اتاق‌ها را تغییر دهد و اتصال کلاینت‌ها را قطع کند. نسخه میزبانی‌شده این ابزار در \%\& در دسترس است. .sp با توجه به اینکه فعال‌سازی این قابلیت می‌تواند بر عملکرد سرور تأثیر بگذارد، به‌طور پیش‌فرض غیرفعال است. برای فعال کردن آن، متد \fBinstrument()\fP \%<#\:socketio\:.Server\:.instrument> را فراخوانی کنید. برای مثال: .INDENT 0.0 .INDENT 3.5 .sp .EX import os import socketio sio = socketio.Server(cors_allowed_origins=[ \(aqhttp://localhost:5000\(aq, \(aqhttps://admin.socket.io\(aq, ]) sio.instrument(auth={ \(aqusername\(aq: \(aqadmin\(aq, \(aqpassword\(aq: os.environ[\(aqADMIN_PASSWORD\(aq], }) .EE .UNINDENT .UNINDENT .sp این پیکربندی، سرور را برای پذیرش اتصالات از کلاینت میزبانی‌شده Admin UI تنظیم می‌کند. مدیران سپس می‌توانند \% را در مرورگر وب خود باز کرده و با نام کاربری \fBadmin\fP و گذرواژه ارائه‌شده توسط متغیر محیطی \fBADMIN_PASSWORD\fP وارد شوند. برای اطمینان از اینکه رابط کاربری Admin UI مجاز به برقراری اتصال است، CORS نیز پیکربندی شده است. .sp برای اطلاع از سایر گزینه‌های پیکربندی موجود، به مستندات مرجع مراجعه کنید. .SS اشکال‌زدایی و عیب‌یابی (Debugging and Troubleshooting) .sp برای کمک به شما در اشکال‌زدایی مشکلات، سرور را می‌توان طوری پیکربندی کرد که لاگ‌ها را در پایانه نمایش دهد: .INDENT 0.0 .INDENT 3.5 .sp .EX import socketio # standard Python sio = socketio.Server(logger=True, engineio_logger=True) # asyncio sio = socketio.AsyncServer(logger=True, engineio_logger=True) .EE .UNINDENT .UNINDENT .sp آرگومان \fBlogger\fP گزارش‌گیری مربوط به پروتکل Socket.IO را کنترل می‌کند، در حالی که \fBengineio_logger\fP گزارش‌هایی را کنترل می‌کند که از لایه انتقال سطح‌پایین Engine.IO سرچشمه می‌گیرند. مقدار ارائه‌شده به این آرگومان‌ها رفتار ثبت گزارش را تعیین می‌کند: .INDENT 0.0 .IP \(bu 2 \fBTrue\fP: ارسال لاگ به خروجی \fBstderr\fP در سطح \fBINFO\fP را فعال می‌کند. .IP \(bu 2 \fBFalse\fP: ارسال لاگ به خروجی \fBstderr\fP در سطح \fBERROR\fP را فعال می‌کند. این حالت پیش‌فرض است. .IP \(bu 2 یک نمونه از \fBlogging.Logger\fP: از لاگر ارائه‌شده بدون پیکربندی اضافی استفاده می‌کند. .UNINDENT .sp ثبت گزارش می‌تواند به شناسایی علت مشکلات اتصال، پاسخ‌های 400، عملکرد ضعیف و سایر خطاها کمک کند..SS "همزمانی و یکپارچه‌سازی وب‌سرور (Concurrency and Web Server Integration)" .sp سرور Socket.IO بسته به نیازهای برنامه و وب‌سرور مورد استفاده، می‌تواند با مدل‌های همزمانی متفاوتی پیکربندی شود. مدل همزمانی از طریق آرگومان \fBasync_mode\fP در سرور مشخص می‌شود. برای مثال: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.Server(async_mode=\(aqthreading\(aq) .EE .UNINDENT .UNINDENT .sp زیربخش‌های زیر گزینه‌های همزمانی موجود را برای سرورهای همگام (synchronous) و ناهمگام (asynchronous) شرح می‌دهند. .SS "حالت‌های استاندارد (Standard Modes)" .INDENT 0.0 .IP \(bu 2 \fBthreading\fP: سرور از رشته‌های (threads) پایتون برای همزمانی استفاده خواهد کرد و روی هر وب‌سرور چندرشته‌ای WSGI اجرا خواهد شد. این حالت در صورتی که هیچ کتابخانه همزمانی دیگری نصب نشده باشد، حالت پیش‌فرض است. .IP \(bu 2 \fBgevent\fP: سرور از گرین‌لت‌ها (greenlets) از طریق کتابخانه gevent \% برای همزمانی استفاده خواهد کرد. وب‌سروری که با \fBgevent\fP سازگار باشد مورد نیاز است. .IP \(bu 2 \fBgevent_uwsgi\fP: گونه‌ای از حالت \fBgevent\fP که برای کار با وب‌سرور uWSGI \% طراحی شده است. .IP \(bu 2 \fBeventlet\fP: سرور از گرین‌لت‌ها از طریق کتابخانه eventlet \% برای همزمانی استفاده خواهد کرد. وب‌سروری که با \fBeventlet\fP سازگار باشد مورد نیاز است. استفاده از \fBeventlet\fP به دلیل قرار داشتن این پروژه در حالت نگهداری، توصیه نمی‌شود. .UNINDENT .SS "حالت‌های ناهمگام (Asyncio Modes)" .sp گزینه‌های ناهمگام همگی بر پایه بسته asyncio \% از کتابخانه استاندارد پایتون، با تغییرات جزئی بسته به بستر وب‌سرور مورد استفاده، عمل می‌کنند. .INDENT 0.0 .IP \(bu 2 \fBasgi\fP: استفاده از هر وب‌سرور ASGI \% الزامی است. .IP \(bu 2 \fBaiohttp\fP: استفاده از چارچوب وب و سرور aiohttp \% الزامی است. .IP \(bu 2 \fBtornado\fP: استفاده از چارچوب وب و سرور Tornado \% الزامی است. .IP \(bu 2 \fBsanic\fP: استفاده از چارچوب وب و سرور Sanic \% الزامی است. هنگام استفاده از Sanic، توصیه می‌شود به جای آن از حالت \fBasgi\fP استفاده شود. .UNINDENT .SS "راهبردهای استقرار (Deployment Strategies)" .sp بخش‌های زیر انواع مختلفی از راهبردهای استقرار را برای سرورهای Socket.IO شرح می‌دهند. .SS Gunicorn .sp ساده‌ترین راهبرد استقرار برای سرور Socket.IO استفاده از وب‌سرور محبوب Gunicorn \% در حالت چندرشته‌ای است. سرور Socket.IO باید درون کلاس \fBsocketio.WSGIApp\fP \%<#\:socketio\:.WSGIApp> قرار گیرد تا با پروتکل WSGI سازگار شود: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.Server(async_mode=\(aqthreading\(aq) app = socketio.WSGIApp(sio) .EE .UNINDENT .UNINDENT .sp در صورت تمایل، کلاس \fBsocketio.WSGIApp\fP می‌تواند ترافیکی را که متعلق به Socket.IO نیست به یک برنامه کاربردی WSGI دیگر هدایت کند؛ این ویژگی استقرار یک برنامه وب استاندارد WSGI (توسعه‌یافته با چارچوب‌هایی نظیر Flask یا Django) و سرور Socket.IO را به‌صورت یک بسته واحد امکان‌پذیر می‌سازد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.Server(async_mode=\(aqthreading\(aq) app = socketio.WSGIApp(sio, other_wsgi_app) .EE .UNINDENT .UNINDENT .sp مثال زیر نحوه راه‌اندازی یک برنامه Socket.IO را با استفاده از کلاس ورکر چندرشته‌ای Gunicorn نشان می‌دهد: .INDENT 0.0 .INDENT 3.5 .sp .EX $ gunicorn \-\-workers 1 \-\-threads 100 \-\-bind 127.0.0.1:5000 module:app .EE .UNINDENT .UNINDENT .sp با پیکربندی فوق، سرور قادر خواهد بود نزدیک به ۱۰۰ کلاینت همزمان را مدیریت کند. .sp همچنین امکان استفاده از بیش از یک فرایند ورکر (worker) وجود دارد، اما این حالت نیازمند دو شرط زیر است: .INDENT 0.0 .IP \(bu 2 کلاینت‌ها باید مستقیماً از طریق WebSocket متصل شوند. روش انتقال long\-polling با شیوه توزیع بار (load balancing) درخواست‌ها توسط Gunicorn میان ورکرها ناسازگار است. برای غیرفعال کردن long\-polling در سرور، آرگومان \fBtransports=[\(aqwebsocket\(aq]\fP را در سازنده سرور اضافه کنید. کلاینت‌ها نیز گزینه مشابهی برای برقراری اتصال از طریق WebSocket خواهند داشت. .IP \(bu 2 نمونه‌های \fBsocketio.Server()\fP \%<#\:socketio\:.Server> در هر ورکر باید با یک صف پیام (message queue) پیکربندی شوند تا ورکرها بتوانند با یکدیگر ارتباط برقرار کنند. برای اطلاعات بیشتر، بخش Using a Message Queue را ببینید. .UNINDENT .sp هنگام استفاده از چندین ورکر، تعداد تقریبی اتصالاتی که سرور قادر به پذیرش آن‌ها خواهد بود از ضرب تعداد ورکرها در تعداد رشته‌ها به ازای هر ورکر محاسبه می‌شود. .sp توجه داشته باشید که Gunicorn می‌تواند در کنار \fBuvicorn\fP، \fBgevent\fP و \fBeventlet\fP نیز استفاده شود. این گزینه‌ها در بخش‌های مربوطه در ادامه بررسی شده‌اند..SS Uvicorn (و سایر وب‌سرورهای ASGI) .sp هنگام کار با یک سرور ناهمگام Socket.IO، ساده‌ترین راهبرد استقرار استفاده از یک وب‌سرور ASGI مانند Uvicorn \%\& است. .sp کلاس \fBsocketio.ASGIApp\fP یک برنامه سازگار با ASGI است که می‌تواند ترافیک Socket.IO را به یک نمونه \fBsocketio.AsyncServer\fP هدایت کند: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.AsyncServer(async_mode=\(aqasgi\(aq) app = socketio.ASGIApp(sio) .EE .UNINDENT .UNINDENT .sp در صورت تمایل، کلاس \fBsocketio.ASGIApp\fP می‌تواند هرگونه ترافیکی را که مربوط به Socket.IO نیست به یک برنامه ASGI دیگر هدایت کند؛ این قابلیت امکان استقرار یک برنامه وب استاندارد ASGI ساخته‌شده با فریم‌ورک‌هایی مانند FastAPI به همراه سرور Socket.IO را در قالب یک بسته واحد فراهم می‌سازد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.AsyncServer(async_mode=\(aqasgi\(aq) app = socketio.ASGIApp(sio, other_asgi_app) .EE .UNINDENT .UNINDENT .sp مثال زیر برنامه را با Uvicorn اجرا می‌کند: .INDENT 0.0 .INDENT 3.5 .sp .EX uvicorn \-\-port 5000 module:app .EE .UNINDENT .UNINDENT .sp همچنین می‌توان Uvicorn را از طریق worker مربوط به Gunicorn استفاده کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX gunicorn \-\-workers 1 \-\-worker\-class uvicorn.workers.UvicornWorker \-\-bind 127.0.0.1:5000 .EE .UNINDENT .UNINDENT .sp برای اطلاعات در مورد نحوه استفاده از Gunicorn با چند worker، به بخش Gunicorn در بالا مراجعه کنید. .SS Hypercorn، Daphne و سایر سرورهای ASGI .sp برای استفاده از یک وب‌سرور ASGI به غیر از Uvicorn، برنامه را همان‌طور که در بالا برای Uvicorn نشان داده شد برای ASGI پیکربندی کرده و سپس مطابق مستندات وب‌سرور انتخابی خود، برنامه را راه‌اندازی کنید. .SS Aiohttp .sp گزینه دیگر برای استقرار یک سرور ناهمگام Socket.IO، استفاده از وب‌سرور و فریم‌ورک تحت وب Aiohttp \% است. در صورت نصب بودن کتابخانه، نمونه‌های کلاس \fBsocketio.AsyncServer\fP به‌طور خودکار از Aiohttp استفاده خواهند کرد. برای درخواست صریح استفاده از آن، می‌توان گزینه \fBasync_mode\fP را در سازنده مشخص کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.AsyncServer(async_mode=\(aqaiohttp\(aq) .EE .UNINDENT .UNINDENT .sp سروری که برای Aiohttp پیکربندی شده است باید به یک برنامه موجود متصل (attach) شود: .INDENT 0.0 .INDENT 3.5 .sp .EX app = web.Application() sio.attach(app) .EE .UNINDENT .UNINDENT .sp برنامه Aiohttp می‌تواند مسیرهای معمولی تعریف کند که در کنار سرور Socket.IO همزیستی داشته باشند. یک الگوی رایج، افزودن مسیرهایی است که یک برنامه کلاینت و فایل‌های استاتیک مرتبط را سرویس‌دهی می‌کنند. .sp سپس برنامه Aiohttp به شیوه معمول اجرا می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX if __name__ == \(aq__main__\(aq: web.run_app(app) .EE .UNINDENT .UNINDENT.SS Gevent .sp هنگامی که یک وب‌سرور چندنخی قادر به برآوردن نیازهای همزمانی و مقیاس‌پذیری برنامه نباشد، گزینه‌ای که می‌توان آزمود Gevent \%\& است. Gevent یک کتابخانه همزمانی مبتنی بر هم‌روال (coroutine) بر پایه greenletها است که به‌طور قابل‌توجهی از نخ‌ها (threads) سبک‌تر هستند. .sp نمونه‌های کلاس \fBsocketio.Server\fP در صورت نصب بودن کتابخانه، به‌طور خودکار از Gevent استفاده خواهند کرد. برای درخواست صریح Gevent، می‌توان گزینه \fBasync_mode\fP را در سازنده مشخص کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.Server(async_mode=\(aqgevent\(aq) .EE .UNINDENT .UNINDENT .sp کارساز Socket.IO باید توسط کلاس \fBsocketio.WSGIApp\fP \%<#\:socketio\:.WSGIApp> دربرگرفته (wrap) شود تا با پروتکل WSGI سازگار باشد: .INDENT 0.0 .INDENT 3.5 .sp .EX app = socketio.WSGIApp(sio) .EE .UNINDENT .UNINDENT .sp در صورت تمایل، کلاس \fBsocketio.WSGIApp\fP می‌تواند هر ترافیکی را که متعلق به Socket.IO نیست به یک برنامه WSGI دیگر هدایت کند؛ این امر امکان استقرار همزمان یک برنامه وب استاندارد WSGI ساخته‌شده با چارچوب‌هایی نظیر Flask یا Django را به همراه کارساز Socket.IO به‌صورت یک بسته واحد فراهم می‌سازد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.Server(async_mode=\(aqgevent\(aq) app = socketio.WSGIApp(sio, other_wsgi_app) .EE .UNINDENT .UNINDENT .sp کارساز پیکربندی‌شده برای Gevent، با استفاده از \fBsocketio.WSGIApp\fP ارائه‌شده مانند یک برنامه معمولی WSGI مستقر می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX from gevent import pywsgi pywsgi.WSGIServer((\(aq\(aq, 8000), app).serve_forever() .EE .UNINDENT .UNINDENT .SS Gevent با Gunicorn .sp یک راهکار جایگزین به‌جای اجرای کارساز WSGI به شکل بالا، استفاده از Gunicorn \% به همراه ورکر Gevent آن است. دستور راه‌اندازی برنامه تحت Gunicorn و Gevent در زیر نشان داده شده است: .INDENT 0.0 .INDENT 3.5 .sp .EX $ gunicorn \-k gevent \-w 1 \-b 127.0.0.1:5000 module:app .EE .UNINDENT .UNINDENT .sp برای اطلاعات در مورد نحوه استفاده از Gunicorn با چند ورکر، به بخش Gunicorn در بالا مراجعه کنید. .sp کتابخانه Gevent تابع \fBmonkey_patch()\fP را ارائه می‌دهد که تمام توابع مسدودکننده (blocking) در کتابخانه استاندارد را با نسخه‌های ناهمگام معادل جایگزین می‌کند. گرچه کارساز Socket.IO نیازی به monkey patching ندارد، اما احتمالاً سایر کتابخانه‌ها مانند گرداننده‌های پایگاه‌داده یا صف‌های پیام به آن نیاز خواهند داشت. .SS Gevent با uWSGI .sp هنگام استفاده از کارساز uWSGI در ترکیب با gevent، کارساز Socket.IO می‌تواند از پشتیبانی بومی uWSGI از WebSocket بهره ببرد. .sp نمونه‌های کلاس \fBsocketio.Server\fP در صورتی که هر دو بسته gevent و uWSGI نصب شده و eventlet نصب نشده باشد، به‌طور خودکار از این گزینه برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریح این حالت ناهمگام، می‌توان گزینه \fBasync_mode\fP را در سازنده مشخص کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX # gevent with uWSGI sio = socketio.Server(async_mode=\(aqgevent_uwsgi\(aq) .EE .UNINDENT .UNINDENT .sp توضیح کامل پیکربندی و نحوه استفاده از کارساز uWSGI خارج از دامنه این مستندات است. کارساز uWSGI بسته‌ای نسبتاً پیچیده است که مجموعه گسترده و جامعی از گزینه‌ها را ارائه می‌دهد. برای این‌که انتقال از طریق WebSocket در دسترس باشد، باید با پشتیبانی از WebSocket و SSL کامپایل شده باشد. به عنوان مقدمه، دستور زیر یک کارساز uWSGI را برای مثال \fBlatency.py\fP روی درگاه 5000 راه‌اندازی می‌کند: .INDENT 0.0 .INDENT 3.5 .sp .EX $ uwsgi \-\-http :5000 \-\-gevent 1000 \-\-http\-websockets \-\-master \-\-wsgi\-file latency.py \-\-callable app .EE .UNINDENT .UNINDENT.SS Tornado .sp در صورتی که کتابخانه نصب باشد، نمونه‌های کلاس \fBsocketio.AsyncServer\fP به طور خودکار از Tornado \% استفاده خواهند کرد. برای درخواست صریح استفاده از آن، می‌توان گزینه \fBasync_mode\fP را در سازنده مشخص کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.AsyncServer(async_mode=\(aqtornado\(aq) .EE .UNINDENT .UNINDENT .sp سروری که برای Tornado پیکربندی شده است باید شامل یک request handler برای Socket.IO باشد: .INDENT 0.0 .INDENT 3.5 .sp .EX app = tornado.web.Application( [ (r\(dq/socket.io/\(dq, socketio.get_tornado_handler(sio)), ], # ... other application options ) .EE .UNINDENT .UNINDENT .sp برنامه Tornado می‌تواند مسیرهای دیگری را نیز تعریف کند که در کنار سرور Socket.IO همزیستی داشته باشند. یک الگوی رایج، افزودن مسیرهایی است که یک برنامه کلاینت و فایل‌های ایستای (static) مربوط به آن را ارائه می‌دهند. .sp سپس برنامه Tornado به شیوه معمول اجرا می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX app.listen(port) tornado.ioloop.IOLoop.current().start() .EE .UNINDENT .UNINDENT .SS Eventlet .sp \fBنکته:\fP .INDENT 0.0 .INDENT 3.5 پروژه Eventlet دیگر تحت توسعه فعال نیست و به همین دلیل، توصیه فعلی این است که از آن برای پروژه‌های جدید استفاده نشود. .UNINDENT .UNINDENT .sp بسته \% Eventlet یک کتابخانه شبکه همروند با کارایی بالا برای Python است که از کوروتین‌ها (coroutines) استفاده می‌کند و امکان نوشتن کد را به همان شیوه مورد استفاده در توابع مسدودکننده کتابخانه استاندارد فراهم می‌سازد. یک سرور Socket.IO که با eventlet مستقر شده باشد، به شیوه‌های انتقال (transports) مبتنی بر long\-polling و WebSocket دسترسی دارد. .sp در صورتی که کتابخانه نصب باشد، نمونه‌های کلاس \fBsocketio.Server\fP به طور خودکار از eventlet برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریح استفاده از آن، می‌توان گزینه \fBasync_mode\fP را در سازنده مشخص کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX sio = socketio.Server(async_mode=\(aqeventlet\(aq) .EE .UNINDENT .UNINDENT .sp سروری که برای eventlet پیکربندی شده است، با استفاده از \fBsocketio.WSGIApp\fP ارائه‌شده به عنوان یک برنامه معمولی WSGI مستقر می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX import eventlet app = socketio.WSGIApp(sio) eventlet.wsgi.server(eventlet.listen((\(aq\(aq, 8000)), app) .EE .UNINDENT .UNINDENT.SS Eventlet با Gunicorn .sp یک جایگزین برای اجرای کارساز WSGI مربوط به eventlet مطابق بالا، استفاده از gunicorn \% است، که یک وب‌سرور تمام‌عیار و پایتونی خالص (pure Python) می‌باشد. دستور راه‌اندازی برنامه تحت gunicorn در زیر آورده شده است: .INDENT 0.0 .INDENT 3.5 .sp .EX $ gunicorn \-k eventlet \-w 1 module:app .EE .UNINDENT .UNINDENT .sp برای اطلاعات درباره نحوه استفاده از Gunicorn با چند worker، بخش Gunicorn را در بالا ببینید. .sp بسته Eventlet یک تابع \fBmonkey_patch()\fP ارائه می‌دهد که تمامی توابع مسدودکننده (blocking) در کتابخانه استاندارد را با نسخه‌های ناهمگام معادل جایگزین می‌کند. اگرچه python\-socketio نیازی به monkey patching ندارد، سایر کتابخانه‌ها از جمله درایورهای پایگاه‌داده احتمالاً به آن نیاز خواهند داشت. .SS Sanic .sp \fBنکته:\fP .INDENT 0.0 .INDENT 3.5 یکپارچه‌سازی با Sanic مدت زیادی است که به‌روزرسانی نشده است. در حال حاضر توصیه می‌شود که برنامه‌های Sanic با یکپارچه‌سازی ASGI مستقر شوند. .UNINDENT .UNINDENT .SS استفاده از صف پیام (Message Queue) .sp هنگام کار با برنامه‌های توزیع‌شده، معمولاً دسترسی به قابلیت‌های Socket.IO از طریق چند فرآیند ضروری است. دو مورد کاربرد خاص در این زمینه وجود دارد: .INDENT 0.0 .IP \(bu 2 برنامه‌های با دسترسی‌پذیری بالا (Highly available) ممکن است بخواهند از مقیاس‌پذیری افقی کارساز Socket.IO استفاده کنند تا قادر به مدیریت تعداد بسیار زیادی از کلاینت‌های هم‌روند باشند. .IP \(bu 2 برنامه‌هایی که از صف‌های کاری مانند Celery \% استفاده می‌کنند، ممکن است نیاز داشته باشند پس از اتمام یک وظیفه پس‌زمینه، رویدادی را برای یک کلاینت ارسال (emit) کنند. مناسب‌ترین مکان برای انجام این کار، فرآیند worker است که این وظیفه را پردازش کرده است. .UNINDENT .sp به عنوان راه‌حلی برای مسائل فوق، می‌توان کارساز Socket.IO را به‌گونه‌ای پیکربندی کرد که برای ارتباط با سایر کارسازهای مرتبط Socket.IO یا workerهای کمکی، به یک صف پیام مانند Redis \% یا RabbitMQ \% متصل شود. .SS Redis .sp برای استفاده از صف پیام Redis، باید یک کلاینت پایتونی Redis نصب شود: .INDENT 0.0 .INDENT 3.5 .sp .EX # socketio.Server class pip install redis .EE .UNINDENT .UNINDENT .sp صف Redis از طریق کلاس‌های \fBsocketio.RedisManager\fP \%<#\:socketio\:.RedisManager> و \fBsocketio.AsyncRedisManager\fP \%<#\:socketio\:.AsyncRedisManager> پیکربندی می‌شود. این کلاس‌ها مستقیماً به مخزن Redis متصل شده و از قابلیت pub/sub صف استفاده می‌کنند: .INDENT 0.0 .INDENT 3.5 .sp .EX # socketio.Server class mgr = socketio.RedisManager(\(aqredis://\(aq) sio = socketio.Server(client_manager=mgr) # socketio.AsyncServer class mgr = socketio.AsyncRedisManager(\(aqredis://\(aq) sio = socketio.AsyncServer(client_manager=mgr) .EE .UNINDENT .UNINDENT .sp آرگومان \fBclient_manager\fP به کارساز دستور می‌دهد تا به صف پیام مشخص‌شده متصل شده و با دیگر فرآیندهای متصل به صف هماهنگ شود..SS Kombu .sp بسته Kombu \% یک بستهٔ پایتون است که امکان دسترسی به RabbitMQ و صف‌های پیام بسیار دیگری را فراهم می‌کند. این بسته را می‌توان با pip نصب کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX pip install kombu .EE .UNINDENT .UNINDENT .sp برای استفاده از RabbitMQ یا سایر صف‌های سازگار با پروتکل AMQP، این تنها وابستگی لازم است. اما برای سایر صف‌های پیام، Kombu ممکن است به بسته‌های اضافی نیاز داشته باشد. به عنوان مثال، برای استفاده از صف Redis از طریق Kombu، بسته پایتون مربوط به Redis نیز باید نصب شود: .INDENT 0.0 .INDENT 3.5 .sp .EX pip install redis .EE .UNINDENT .UNINDENT .sp صف از طریق \fBsocketio.KombuManager\fP \%<#\:socketio\:.KombuManager> پیکربندی می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX mgr = socketio.KombuManager(\(aqamqp://\(aq) sio = socketio.Server(client_manager=mgr) .EE .UNINDENT .UNINDENT .sp نشانی URL اتصالی که به سازندهٔ \fBKombuManager\fP داده می‌شود، مستقیماً به شیء Connection در Kombu \% منتقل می‌شود؛ بنابراین برای کسب اطلاعات درباره نحوه ایجاد URL صحیح برای هر صف پیام، باید به مستندات Kombu مراجعه کرد. .sp توجه داشته باشید که Kombu در حال حاضر از asyncio پشتیبانی نمی‌کند، بنابراین نمی‌توان آن را به همراه کلاس \fBsocketio.AsyncServer\fP \%<#\:socketio\:.AsyncServer> به کار برد. .SS Kafka .sp از Apache Kafka \% از طریق بستهٔ kafka\-python \% پشتیبانی می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX pip install kafka\-python .EE .UNINDENT .UNINDENT .sp دسترسی به Kafka از طریق کلاس \fBsocketio.KafkaManager\fP \%<#\:socketio\:.KafkaManager> پیکربندی می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX mgr = socketio.KafkaManager(\(aqkafka://\(aq) sio = socketio.Server(client_manager=mgr) .EE .UNINDENT .UNINDENT .sp توجه داشته باشید که Kafka در حال حاضر از asyncio پشتیبانی نمی‌کند، بنابراین نمی‌توان آن را به همراه کلاس \fBsocketio.AsyncServer\fP \%<#\:socketio\:.AsyncServer> به کار برد. .SS AioPika .sp صف پیام RabbitMQ در برنامه‌های مبتنی بر asyncio از طریق بستهٔ AioPika \% پشتیبانی می‌شود: باید aio_pika را با استفاده از pip نصب کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX pip install aio_pika .EE .UNINDENT .UNINDENT .sp صف RabbitMQ از طریق کلاس \fBsocketio.AsyncAioPikaManager\fP \%<#\:socketio\:.AsyncAioPikaManager> پیکربندی می‌شود: .INDENT 0.0 .INDENT 3.5 .sp .EX mgr = socketio.AsyncAioPikaManager(\(aqamqp://\(aq) sio = socketio.AsyncServer(client_manager=mgr) .EE .UNINDENT .UNINDENT.SS استقرار صف پیام در محیط عملیاتی (Deploying the Message Queue for Production) .sp برای استقرار در محیط عملیاتی، توصیه‌هایی برای حفظ امنیت برنامه شما وجود دارد. .sp پیش از هر چیز، صف پیام هرگز نباید روی یک رابط شبکه عمومی شنود کند، تا اطمینان حاصل شود که کلاینت‌های خارجی هرگز به آن متصل نمی‌شوند. برای استقرار روی یک تک‌گره، صف باید فقط روی \fIlocalhost\fP\& شنود کند. برای یک سیستم چندگره‌ای، استفاده از یک شبکه خصوصی (VPC) که در آن ارتباط بین سرورها بتواند به‌صورت خصوصی انجام شود، به‌شدت توصیه می‌شود. .sp علاوه بر این، تمام صف‌های پیام از احراز هویت و رمزنگاری پشتیبانی می‌کنند که می‌تواند امنیت استقرار را افزایش دهد. احراز هویت تضمین می‌کند که تنها سرورهای Socket.IO و فرایندهای مرتبط دسترسی دارند، در حالی که رمزنگاری از جمع‌آوری داده‌ها توسط شخص ثالثی که در حال شنود روی شبکه است، جلوگیری می‌کند. اعتبارنامه‌های دسترسی را می‌توان در URLهای اتصالی که به مدیران کلاینت ارسال می‌شوند، لحاظ کرد. .SS مقیاس‌پذیری افقی (Horizontal Scaling) .sp پروتکل Socket.IO یک پروتکل با حفظ وضعیت (stateful) است که این امر مقیاس‌پذیری افقی را دشوارتر می‌سازد. هنگام استقرار خوشه‌ای از فرایندهای Socket.IO، تمام فرایندها باید با ارسال آرگومان \fBclient_manager\fP به نمونه سرور، به صف پیام متصل شوند. این قابلیت به workerها امکان می‌دهد تا ارتباط برقرار کرده و عملیات پیچیده‌ای نظیر همه‌پخشی‌ها (broadcasts) را هماهنگ کنند. .sp اگر روش انتقال long\-polling استفاده شود، دو پیش‌نیاز دیگر وجود دارد که باید رعایت شوند: .INDENT 0.0 .IP \(bu 2 هر فرایند Socket.IO باید بتواند چندین درخواست را به‌طور هم‌روند مدیریت کند. این امر به این دلیل لازم است که کلاینت‌های long\-polling دو درخواست را به‌صورت موازی ارسال می‌کنند. فرایندهای worker که در یک زمان تنها می‌توانند یک درخواست را مدیریت کنند، پشتیبانی نمی‌شوند. .IP \(bu 2 توزیع‌کننده بار (load balancer) باید به‌گونه‌ای پیکربندی شود که همیشه درخواست‌های یک کلاینت را به همان فرایند worker هدایت کند، تا همه درخواست‌های ارسالی از یک کلاینت توسط همان گره رسیدگی شوند. توزیع‌کننده‌های بار این مفهوم را \fIsticky sessions\fP یا \fIsession affinity\fP می‌نامند\&. .UNINDENT .SS ارسال رویداد از فرایندهای خارجی (Emitting from external processes) .sp برای اتصال فرایندی غیر از سرور به صف جهت ارسال پیام، می‌توان از همان کلاس‌های مدیر کلاینت به‌صورت شیءهای مستقل استفاده کرد. در این حالت، آرگومان \fBwrite_only\fP باید روی \fBTrue\fP تنظیم شود تا از ایجاد یک ریسه (thread) شنونده که فقط در سرور کاربرد دارد، جلوگیری شود. برای مثال: .INDENT 0.0 .INDENT 3.5 .sp .EX # connect to the redis queue as an external process external_sio = socketio.RedisManager(\(aqredis://\(aq, write_only=True) # emit an event external_sio.emit(\(aqmy event\(aq, data={\(aqfoo\(aq: \(aqbar\(aq}, room=\(aqmy room\(aq) .EE .UNINDENT .UNINDENT .sp یک محدودیت شیء مدیر کلاینت فقط‌نوشتنی (write\-only) این است که هنگام ارسال پیام نمی‌تواند فراخوانی‌های بازگشتی (callbacks) را دریافت کند. هنگامی که فرایند خارجی نیاز به دریافت callbackها دارد، استفاده از یک کلاینت برای اتصال به سرور با پشتیبانی خواندن و نوشتن، گزینه بهتری نسبت به یک مدیر کلاینت فقط‌نوشتنی است. .SH "مرجع API (API REFERENCE)" .SS کلاینت‌های ساده (Simple Clients) .INDENT 0.0 .TP .B class socketio.SimpleClient(*args, **kwargs) یک کلاینت Socket.IO. .sp این کلاس یک کلاینت وب Socket.IO ساده و در عین حال کاملاً سازگار را با پشتیبانی از روش‌های انتقال websocket و long\-polling پیاده‌سازی می‌کند. .sp آرگومان‌های موضعی (positional) و کلیدواژه‌ای (keyword) ارائه‌شده در سازنده، به شیء زیرین \fBsocketio.Client()\fP \%<#\:socketio\:.Client> ارسال می‌شوند. .INDENT 7.0 .TP .B call(event, data=None, timeout=60) ارسال یک رویداد به سرور و انتظار برای پاسخ. .sp این متد یک ارسال رویداد صادر می‌کند و منتظر می‌ماند تا سرور پاسخ یا تأییدیه‌ای (acknowledgement) ارائه دهد. اگر پاسخ پیش از پایان مهلت زمانی دریافت نشود، استثنای \fBTimeoutError\fP برانگیخته می‌شود. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد\&. برای ارسال چندین آرگومان، از یک تاپل استفاده کنید که در آن هر عنصر از یکی از انواع ذکرشده در بالا باشد. .IP \(bu 2 \fBtimeout\fP \-\- مهلت زمانی انتظار. اگر مهلت زمانی پیش از آنکه سرور دریافت رویداد را تأیید کند فرا برسد، استثنای \fBTimeoutError\fP برانگیخته می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B client_class نام مستعار \fBClient\fP \%<#\:socketio\:.Client> .UNINDENT .INDENT 7.0 .TP .B connect(url, headers={}, auth=None, transports=None, namespace=\(aq/\(aq, socketio_path=\(aqsocket.io\(aq, wait_timeout=5) اتصال به یک سرور Socket.IO. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی اینترنتی (URL) سرور Socket.IO. در صورت نیاز سرور می‌تواند شامل پارامترهای سفارشی query string باشد. اگر یک تابع ارائه شده باشد، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت URL فراخوانی خواهد کرد. .IP \(bu 2 \fBheaders\fP \-\- یک دیکشنری حاوی هدرهای سفارشی برای ارسال همراه با درخواست اتصال. اگر یک تابع ارائه شده باشد، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت دیکشنری هدرها فراخوانی خواهد کرد. .IP \(bu 2 \fBauth\fP \-\- داده‌های احراز هویت ارسال‌شده به سرور همراه با درخواست اتصال، که معمولاً یک دیکشنری با یک یا چند جفت کلید/مقدار رشته‌ای است. اگر یک تابع ارائه شده باشد، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت داده‌های احراز هویت فراخوانی خواهد کرد. .IP \(bu 2 \fBtransports\fP \-\- فهرست روش‌های انتقال مجاز. روش‌های انتقال معتبر شامل \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP هستند\&. در صورت عدم ارائه، ابتدا انتقال polling متصل می‌شود و سپس تلاش برای ارتقا به websocket صورت می‌گیرد. .IP \(bu 2 \fBnamespace\fP \-\- فضای نامی که باید به‌صورت رشته به آن متصل شد. در صورت عدم ارائه، از فضای نام پیش‌فرض \fB/\fP استفاده می‌شود. .IP \(bu 2 \fBsocketio_path\fP \-\- نقطه پایانی (endpoint) که سرور Socket.IO در آن نصب شده است. مقدار پیش‌فرض برای بیشتر موارد مناسب است. .IP \(bu 2 \fBwait_timeout\fP \-\- مدت زمانی که کلاینت باید برای برقراری اتصال منتظر بماند. مقدار پیش‌فرض ۵ ثانیه است. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B disconnect() قطع اتصال از سرور. .UNINDENT .INDENT 7.0 .TP .B emit(event, data=None) ارسال یک رویداد به سرور. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد\&. برای ارسال چندین آرگومان، از یک تاپل استفاده کنید که در آن هر عنصر از یکی از انواع ذکرشده در بالا باشد. .UNINDENT .UNINDENT .sp این متد رویداد را برای ارسال زمان‌بندی کرده و بدون انتظار واقعی برای تحویل آن بازمی‌گردد. در مواردی که کلاینت نیاز به اطمینان از دریافت رویداد دارد، باید در عوض از \fBsocketio.SimpleClient.call()\fP استفاده شود. .UNINDENT .INDENT 7.0.TP .B receive(timeout=None) منتظر ماندن برای یک رویداد از سوی سرور. .INDENT 7.0 .TP .B پارامترها \fBtimeout\fP \-\- مهلت زمانی انتظار. اگر قبل از اینکه سرور رویداد را تأیید کند، این زمان به پایان برسد، یک استثنای \fBTimeoutError\fP ایجاد می‌شود. .UNINDENT .sp مقدار بازگشتی یک لیست است که نام رویداد به عنوان اولین عنصر آن قرار دارد. اگر سرور آرگومان‌هایی را همراه رویداد ارسال کرده باشد، آن‌ها به عنوان عناصر اضافی لیست بازگردانده می‌شوند. .UNINDENT .INDENT 7.0 .TP .B property sid شناسه نشست (session ID) دریافت‌شده از سرور. .sp تضمینی وجود ندارد که شناسه نشست در طول چرخه حیات اتصال ثابت بماند، زیرا اتصالات مجدد می‌توانند باعث تغییر آن شوند. .UNINDENT .INDENT 7.0 .TP .B property transport نام لایه انتقال (transport) که در حال حاضر استفاده می‌شود. .sp لایه انتقال به عنوان یک رشته بازگردانده می‌شود و می‌تواند یکی از موارد \fBpolling\fP و \fBwebsocket\fP\& باشد. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.AsyncSimpleClient(*args, **kwargs) یک کلاینت Socket.IO. .sp این کلاس یک کلاینت وب Socket.IO ساده و در عین حال کاملاً سازگار را با پشتیبانی از لایه‌های انتقال websocket و long\-polling پیاده‌سازی می‌کند. .sp آرگومان‌های موقعیتی و کلیدواژه‌ای ارائه‌شده در سازنده، به شیء زیربنایی \fBsocketio.AsyncClient()\fP \%<#\:socketio\:.AsyncClient> ارسال می‌شوند. .INDENT 7.0 .TP .B async call(event, data=None, timeout=60) ارسال یک رویداد به سرور و انتظار برای پاسخ. .sp این متد یک ارسال (emit) انجام می‌دهد و منتظر می‌ماند تا سرور پاسخی یا تأییدیه‌ای ارائه دهد. اگر پاسخ قبل از اتمام مهلت زمانی دریافت نشود، یک استثنای \fBTimeoutError\fP ایجاد می‌شود. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP\& باشد. برای ارسال چندین آرگومان، از یک تاپل استفاده کنید که هر عنصر آن از یکی از انواع ذکرشده در بالا باشد. .IP \(bu 2 \fBtimeout\fP \-\- مهلت زمانی انتظار. اگر قبل از اینکه سرور رویداد را تأیید کند، این زمان به پایان برسد، یک استثنای \fBTimeoutError\fP ایجاد می‌شود. .UNINDENT .UNINDENT .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B client_class نام مستعار برای \fBAsyncClient\fP \%<#\:socketio\:.AsyncClient> .UNINDENT .INDENT 7.0 .TP .B async connect(url, headers={}, auth=None, transports=None, namespace=\(aq/\(aq, socketio_path=\(aqsocket.io\(aq, wait_timeout=5) اتصال به یک سرور Socket.IO. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی اینترنتی (URL) سرور Socket.IO. در صورت نیاز سرور، می‌تواند شامل پارامترهای سفارشی رشته پرس‌وجو (query string) باشد. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را فراخوانی می‌کند تا URL را دریافت کند. .IP \(bu 2 \fBheaders\fP \-\- یک دیکشنری شامل سرایندهای (headers) سفارشی برای ارسال با درخواست اتصال. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت دیکشنری سرایندها فراخوانی می‌کند. .IP \(bu 2 \fBauth\fP \-\- داده‌های احراز هویت ارسال‌شده به سرور همراه با درخواست اتصال، که معمولاً یک دیکشنری با یک یا چند جفت کلید/مقدار رشته‌ای است. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت داده‌های احراز هویت فراخوانی می‌کند. .IP \(bu 2 \fBtransports\fP \-\- لیست لایه‌های انتقال مجاز. لایه‌های انتقال معتبر عبارتند از \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP\&. در صورت ارائه نشدن، ابتدا اتصال لایه انتقال polling برقرار می‌شود، سپس تلاش برای ارتقا به websocket صورت می‌گیرد. .IP \(bu 2 \fBnamespace\fP \-\- فضای نامی (namespace) مورد نظر برای اتصال به صورت یک رشته. در صورت تعیین نشدن، از فضای نامی پیش‌فرض \fB/\fP استفاده می‌شود. .IP \(bu 2 \fBsocketio_path\fP \-\- نقطه پایانی (endpoint) که سرور Socket.IO در آن نصب شده است. مقدار پیش‌فرض برای اکثر موارد مناسب است. .IP \(bu 2 \fBwait_timeout\fP \-\- مدت زمانی که کلاینت باید منتظر اتصال بماند. مقدار پیش‌فرض ۵ ثانیه است. .UNINDENT .UNINDENT .sp نکته: این متد یک کوروتین است. .UNINDENT .INDENT 7.0 .TP .B async disconnect() قطع اتصال از سرور. .sp نکته: این متد یک کوروتین است. .UNINDENT .INDENT 7.0 .TP .B async emit(event, data=None) ارسال یک رویداد به سرور. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP\& باشد. برای ارسال چندین آرگومان، از یک تاپل استفاده کنید که هر عنصر آن از یکی از انواع ذکرشده در بالا باشد. .UNINDENT .UNINDENT .sp نکته: این متد یک کوروتین است. .sp این متد زمان‌بندی ارسال رویداد را انجام داده و بدون اینکه عملاً منتظر تحویل آن بماند، بازمی‌گردد. در مواردی که کلاینت نیاز دارد از دریافت رویداد اطمینان حاصل کند، باید در عوض از \fBsocketio.SimpleClient.call()\fP استفاده شود. .UNINDENT .INDENT 7.0 .TP .B async receive(timeout=None) منتظر ماندن برای یک رویداد از سوی سرور. .INDENT 7.0 .TP .B پارامترها \fBtimeout\fP \-\- مهلت زمانی انتظار. اگر قبل از اینکه سرور رویداد را تأیید کند، این زمان به پایان برسد، یک استثنای \fBTimeoutError\fP ایجاد می‌شود. .UNINDENT .sp نکته: این متد یک کوروتین است. .sp مقدار بازگشتی یک لیست است که نام رویداد به عنوان اولین عنصر آن قرار دارد. اگر سرور آرگومان‌هایی را همراه رویداد ارسال کرده باشد، آن‌ها به عنوان عناصر اضافی لیست بازگردانده می‌شوند. .UNINDENT .INDENT 7.0 .TP .B property sid شناسه نشست دریافت‌شده از سرور. .sp تضمینی وجود ندارد که شناسه نشست در طول چرخه حیات اتصال ثابت بماند، زیرا اتصالات مجدد می‌توانند باعث تغییر آن شوند. .UNINDENT .INDENT 7.0.TP .B property transport نام ترنسپورت در حال استفاده. .sp ترنسپورت به صورت یک رشته بازگردانده می‌شود و می‌تواند یکی از \fBpolling\fP یا \fBwebsocket\fP باشد\&. .UNINDENT .UNINDENT .SS "کلاینت‌ها (Clients)" .INDENT 0.0 .TP .B class socketio.Client(reconnection=True, reconnection_attempts=0, reconnection_delay=1, reconnection_delay_max=5, randomization_factor=0.5, logger=False, serializer=\(aqdefault\(aq, json=None, handle_sigint=True, **kwargs) یک کلاینت Socket.IO. .sp این کلاس یک کلاینت وب کاملاً منطبق بر Socket.IO را همراه با پشتیبانی از ترنسپورت‌های websocket و long\-polling پیاده‌سازی می‌کند. .INDENT 7.0 .TP .B "پارامترها (Parameters)" .INDENT 7.0 .IP \(bu 2 \fBreconnection\fP \-\- اگر کلاینت باید پس از قطعی به‌طور خودکار برای اتصال مجدد به سرور تلاش کند \fBTrue\fP، و برای عدم اتصال مجدد \fBFalse\fP. پیش‌فرض \fBTrue\fP است\&. .IP \(bu 2 \fBreconnection_attempts\fP \-\- تعداد دفعات تلاش برای اتصال مجدد پیش از انصراف، یا 0 برای تلاش‌های بی‌نهایت. پیش‌فرض 0 است. .IP \(bu 2 \fBreconnection_delay\fP \-\- مدت‌زمان انتظار بر حسب ثانیه پیش از نخستین تلاش اتصال مجدد. هر تلاش متوالی این تأخیر را دو برابر می‌کند. .IP \(bu 2 \fBreconnection_delay_max\fP \-\- حداکثر تأخیر میان تلاش‌های اتصال مجدد. .IP \(bu 2 \fBrandomization_factor\fP \-\- ضریب تصادفی‌سازی برای هر تأخیر میان تلاش‌های اتصال مجدد. مقدار پیش‌فرض 0.5 است، به این معنی که هر تأخیر به‌طور تصادفی به میزان +/\- 50% تنظیم می‌شود. .IP \(bu 2 \fBlogger\fP \-\- برای فعال‌سازی لاگینگ روی \fBTrue\fP تنظیم کنید یا یک شیء logger را برای استفاده ارسال نمایید. برای غیرفعال‌سازی لاگینگ روی \fBFalse\fP تنظیم کنید\&. پیش‌فرض \fBFalse\fP است\&. توجه داشته باشید که خطاهای مرگبار حتی زمانی که \fBlogger\fP برابر \fBFalse\fP باشد نیز ثبت می‌شوند\&. .IP \(bu 2 \fBserializer\fP \-\- روش سریال‌سازی مورد استفاده هنگام ارسال بسته‌ها. مقادیر معتبر عبارتند از \fB\(aqdefault\(aq\fP، \fB\(aqpickle\(aq\fP، \fB\(aqmsgpack\(aq\fP و \fB\(aqcbor\(aq\fP\&. همچنین می‌توان یک زیرکلاس از کلاس \fBPacket\fP با پیاده‌سازی سفارشی از متدهای \fBencode()\fP و \fBdecode()\fP ارائه داد. کلاینت و سرور باید از سریال‌سازهای سازگار استفاده کنند. .IP \(bu 2 \fBjson\fP \-\- یک ماژول JSON جایگزین جهت استفاده برای انکود و دیکود بسته‌ها. ماژول‌های json سفارشی باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این یک تنظیم در سطح کل فرایند (process\-wide) است و تمامی سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON مشترک استفاده کنند. .IP \(bu 2 \fBhandle_sigint\fP \-\- روی \fBTrue\fP تنظیم شود تا قطع اتصال هنگام وقفه در فرایند به‌طور خودکار مدیریت شود، یا روی \fBFalse\fP قرار گیرد تا مدیریت وقفه به برنامه فراخواننده واگذار گردد. مدیریت وقفه تنها زمانی می‌تواند فعال شود که نمونه کلاینت در نخ اصلی (main thread) ایجاد شده باشد. .UNINDENT .UNINDENT .sp پیکربندی Engine.IO از تنظیمات زیر پشتیبانی می‌کند: .INDENT 7.0 .TP .B "پارامترها (Parameters)" .INDENT 7.0 .IP \(bu 2 \fBrequest_timeout\fP \-\- مهلت زمانی (timeout) بر حسب ثانیه برای درخواست‌ها. پیش‌فرض 5 ثانیه است. .IP \(bu 2 \fBhttp_session\fP \-\- یک شیء مقداردهی‌شده از \fBrequests.Session\fP جهت استفاده هنگام ارسال درخواست‌ها به سرور. در صورت نیاز به افزودن گزینه‌های خاص کلاینت مانند سرورهای پراکسی، گواهی‌های SSL، بسته سفارشی CA و غیره، از آن استفاده کنید. .IP \(bu 2 \fBssl_verify\fP \-\- مقدار \fBTrue\fP برای بررسی گواهی‌های SSL، یا \fBFalse\fP برای صرف‌نظر از اعتبارسنجی گواهی SSL که امکان اتصال به سرورهای دارای گواهی خودامضا را فراهم می‌کند. پیش‌فرض \fBTrue\fP است\&. .IP \(bu 2 \fBwebsocket_extra_options\fP \-\- دیکشنری حاوی آرگومان‌های کلیدواژه‌ای اضافی که به \fBwebsocket.create_connection()\fP ارسال می‌شوند\&. .IP \(bu 2 \fBengineio_logger\fP \-\- برای فعال‌سازی لاگینگ Engine.IO روی \fBTrue\fP تنظیم کنید یا یک شیء logger را برای استفاده ارسال نمایید. برای غیرفعال‌سازی لاگینگ روی \fBFalse\fP تنظیم کنید\&. پیش‌فرض \fBFalse\fP است\&. توجه داشته باشید که خطاهای مرگبار حتی زمانی که \fBengineio_logger\fP برابر \fBFalse\fP باشد نیز ثبت می‌شوند\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B call(event, data=None, namespace=None, timeout=60) ارسال یک رویداد سفارشی به سرور و انتظار برای دریافت پاسخ. .sp این متد یک ارسال (emit) را همراه با یک کالبک (callback) صادر کرده و پیش از بازگشت، منتظر فراخوانی کالبک می‌ماند. اگر کالبک پیش از اتمام مهلت زمانی فراخوانی نشود، استثنای \fBTimeoutError\fP برانگیخته می‌شود. در صورت قطع شدن اتصال Socket.IO در طول انتظار، این متد همچنان تا رسیدن به مهلت زمانی مشخص‌شده منتظر می‌ماند. .INDENT 7.0 .TP .B "پارامترها (Parameters)" .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده هستند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده ارسالی به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد\&. برای ارسال چندین آرگومان، از یک tuple استفاده کنید که هر عنصر آن از یکی از نوع‌های ذکرشده در بالا باشد. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. در صورت حذف این آرگومان، رویداد به فضای نام پیش‌فرض ارسال می‌شود. .IP \(bu 2 \fBtimeout\fP \-\- مهلت زمانی انتظار. اگر مهلت زمانی پیش از تأیید رویداد توسط سرور به پایان برسد، آنگاه استثنای \fBTimeoutError\fP برانگیخته می‌شود. .UNINDENT .UNINDENT .sp نکته: این متد thread safe (امن در برابر نخ‌ها) نیست. اگر چندین نخ به‌طور هم‌زمان بر روی یک اتصال کلاینت پیام ارسال کنند، پیام‌های متشکل از چندین بسته ممکن است با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت، از راهکارهای استاندارد هم‌روندی (مانند شیء Lock) استفاده کنید. .UNINDENT .INDENT 7.0 .TP .B connect(url, headers={}, auth=None, transports=None, namespaces=None, socketio_path=\(aqsocket.io\(aq, wait=True, wait_timeout=1, retry=False) اتصال به یک سرور Socket.IO. .INDENT 7.0 .TP .B "پارامترها (Parameters)" .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی اینترنتی (URL) سرور Socket.IO. در صورت نیاز سرور می‌تواند شامل پارامترهای سفارشی رشته پرس‌وجو (query string) باشد. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت URL فراخوانی می‌کند. .IP \(bu 2 \fBheaders\fP \-\- یک دیکشنری حاوی سرایندهای (headers) سفارشی جهت ارسال همراه با درخواست اتصال. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را جهت دریافت دیکشنری سرایندها فراخوانی می‌کند. .IP \(bu 2 \fBauth\fP \-\- داده‌های احراز هویت ارسالی به سرور همراه با درخواست اتصال، که معمولاً دیکشنری‌ای با یک یا چند جفت کلید/مقدار رشته‌ای است. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را جهت دریافت داده‌های احراز هویت فراخوانی می‌کند. .IP \(bu 2 \fBtransports\fP \-\- فهرست ترنسپورت‌های مجاز. ترنسپورت‌های معتبر عبارتند از \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP\&. در صورت عدم تعیین، ابتدا ترنسپورت polling متصل شده، سپس ارتقا به websocket تلاش می‌شود. .IP \(bu 2 \fBnamespaces\fP \-\- فضاهای نام برای اتصال، به صورت یک رشته یا فهرستی از رشته‌ها. در صورت عدم تعیین، فضاهای نامی که دارای گرداننده‌های رویداد ثبت‌شده هستند متصل می‌شوند. .IP \(bu 2 \fBsocketio_path\fP \-\- نقطه پایانی (endpoint) که سرور Socket.IO در آن مستقر شده است. مقدار پیش‌فرض برای بیشتر موارد مناسب است. .IP \(bu 2 \fBwait\fP \-\- در صورت تنظیم روی \fBTrue\fP (پیش‌فرض)، فراخوانی تنها زمانی بازمی‌گردد که تمامی فضاهای نام متصل شده باشند. در صورت تنظیم روی \fBFalse\fP، فراخوانی به محض متصل شدن ترنسپورت Engine.IO بازمی‌گردد، و فضاهای نام در پس‌زمینه متصل خواهند شد..IP \(bu 2 \fBwait_timeout\fP \-\- مدت زمانی که کلاینت باید منتظر برقراری اتصال بماند. مقدار پیش‌فرض ۱ ثانیه است. این آرگومان تنها زمانی در نظر گرفته می‌شود که \fBwait\fP روی \fBTrue\fP تنظیم شده باشد\&. .IP \(bu 2 \fBretry\fP \-\- اعمال منطق اتصال مجدد در صورتی که تلاش اولیه برای اتصال ناموفق باشد. مقدار پیش‌فرض \fBFalse\fP است\&. .UNINDENT .UNINDENT .sp مثال استفاده: .INDENT 7.0 .INDENT 3.5 .sp .EX sio = socketio.Client() sio.connect(\(aqhttp://localhost:5000\(aq) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B connected نشان می‌دهد که آیا کلاینت متصل است یا خیر. .UNINDENT .INDENT 7.0 .TP .B disconnect() قطع اتصال از سرور. .UNINDENT .INDENT 7.0 .TP .B emit(event, data=None, namespace=None, callback=None) ارسال یک رویداد سفارشی به سرور. .INDENT 7.0 .TP .B پارامترها (Parameters) .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد\&. برای ارسال چندین آرگومان، از یک تاپل (tuple) استفاده کنید که هر عنصر آن از یکی از انواع ذکرشده در بالا باشد. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد به فضای نام پیش‌فرض ارسال می‌شود. .IP \(bu 2 \fBcallback\fP \-\- در صورت ارائه، این تابع برای اعلام وصول و تأیید دریافت پیام توسط سرور فراخوانی خواهد شد. آرگومان‌هایی که به تابع فرستاده می‌شوند مواردی هستند که توسط سرور فراهم شده‌اند. .UNINDENT .UNINDENT .sp نکته: این متد thread safe نیست. اگر چندین ریسه (thread) به طور هم‌زمان روی یک اتصال کلاینت در حال ارسال پیام باشند، پیام‌های تشکیل‌شده از چندین بسته ممکن است در ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت، از راهکارهای استاندارد هم‌زمانی (مانند شیء Lock) استفاده کنید. .UNINDENT .INDENT 7.0 .TP .B event(*args, **kwargs) دکوراتور برای ثبت یک گرداننده رویداد (event handler). .sp این نسخه ساده‌شده‌ای از متد \fBon()\fP است که نام رویداد را از تابعی که دکوراتور روی آن اعمال شده می‌گیرد. .sp مثال استفاده: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.event def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .sp مثال بالا معادل است با: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.on(\(aqmy_event\(aq) def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .sp می‌توان یک فضای نام سفارشی را به عنوان آرگومان به دکوراتور داد: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.event(namespace=\(aq/test\(aq) def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_sid(namespace=None) مقدار \fBsid\fP مرتبط با یک اتصال را برمی‌گرداند. .INDENT 7.0 .TP .B پارامترها (Parameters) \fBnamespace\fP \-\- فضای نام Socket.IO. در صورت حذف این آرگومان، گرداننده به فضای نام پیش‌فرض مرتبط می‌شود. توجه داشته باشید که برخلاف نسخه‌های پیشین، نسخهٔ فعلی پروتکل Socket.IO از مقادیر \fBsid\fP متفاوتی به ازای هر فضای نام استفاده می‌کند. .UNINDENT .sp این متد مقدار \fBsid\fP را برای فضای نام درخواست‌شده به صورت یک رشته برمی‌گرداند. .UNINDENT .INDENT 7.0 .TP .B namespaces مجموعه‌ای از فضاهای نام (namespaces) متصل‌شده. .UNINDENT .INDENT 7.0 .TP .B on(event, handler=None, namespace=None) ثبت یک گرداننده رویداد. .INDENT 7.0 .TP .B پارامترها (Parameters) .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. از نام رویداد \fB\(aq*\(aq\fP می‌توان برای تعریف یک گردانندهٔ رویداد همه‌گیر (catch\-all) استفاده کرد. .IP \(bu 2 \fBhandler\fP \-\- تابعی که باید برای مدیریت رویداد فراخوانی شود. هنگامی که این پارامتر مشخص نشده باشد، این متد به عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، گرداننده با فضای نام پیش‌فرض مرتبط می‌گردد. با فرستادن \fB\(aq*\(aq\fP به عنوان فضای نام، می‌توان یک فضای نام همه‌گیر (catch\-all) تعریف کرد. .UNINDENT .UNINDENT .sp مثال استفاده: .INDENT 7.0 .INDENT 3.5 .sp .EX # as a decorator: @sio.on(\(aqconnect\(aq) def connect_handler(): print(\(aqConnected!\(aq) # as a method: def message_handler(msg): print(\(aqReceived message: \(aq, msg) sio.send( \(aqresponse\(aq) sio.on(\(aqmessage\(aq, message_handler) .EE .UNINDENT .UNINDENT .sp آرگومان‌های ارسال‌شده به تابع گرداننده به نوع رویداد بستگی دارند: .INDENT 7.0 .IP \(bu 2 گردانندهٔ رویداد \fB\(aqconnect\(aq\fP هیچ آرگومانی نمی‌پذیرد..IP \(bu 2 گردانندهٔ رویداد \fB\(aqdisconnect\(aq\fP هیچ آرگومانی دریافت نمی‌کند. .IP \(bu 2 گردانندهٔ \fB\(aqmessage\(aq\fP و گرداننده‌های مربوط به نام‌های سفارشی رویداد، بار دادهٔ پیام (payload) را به عنوان تنها آرگومان دریافت می‌کنند. هر مقداری که از گردانندهٔ پیام برگردانده شود، به تابع بازخوانی تأیید کلاینت (در صورت وجود) فرستاده خواهد شد. .IP \(bu 2 یک گردانندهٔ همه‌گیر رویداد (catch\-all) نام رویداد را به عنوان نخستین آرگومان دریافت می‌کند، که پس از آن آرگومان‌های اختصاصی آن رویداد قرار می‌گیرند. .IP \(bu 2 یک گردانندهٔ همه‌گیر رویداد فضای نام، فضای نام را به عنوان نخستین آرگومان دریافت می‌کند، که پس از آن آرگومان‌های اختصاصی آن رویداد قرار می‌گیرند. .IP \(bu 2 یک گردانندهٔ ترکیبی همه‌گیر فضای نام و رویداد، نام رویداد را به عنوان نخستین آرگومان و فضای نام را به عنوان دومین آرگومان دریافت می‌کند، که پس از آن آرگومان‌های اختصاصی رویداد قرار می‌گیرند. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B class reason دلایل قطع اتصال. .INDENT 7.0 .TP .B CLIENT_DISCONNECT = \(aqclient disconnect\(aq قطع اتصال آغاز شده توسط کلاینت. .UNINDENT .INDENT 7.0 .TP .B SERVER_DISCONNECT = \(aqserver disconnect\(aq قطع اتصال آغاز شده توسط سرور. .UNINDENT .INDENT 7.0 .TP .B TRANSPORT_ERROR = \(aqtransport error\(aq خطای لایهٔ انتقال. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B register_namespace(namespace_handler) ثبت یک شیء گردانندهٔ فضای نام. .INDENT 7.0 .TP .B پارامترها \fBnamespace_handler\fP \-\- نمونه‌ای از زیرکلاس \fBNamespace\fP \%<#\:socketio\:.Namespace> که تمامی ترافیک رویدادها را برای یک فضای نام مدیریت می‌کند. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B send(data, namespace=None, callback=None) ارسال یک پیام به سرور. .sp این تابع رویدادی با نام \fB\(aqmessage\(aq\fP ارسال می‌کند (emit). برای ارسال نام‌های سفارشی رویداد از \fBemit()\fP استفاده کنید. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد. برای ارسال چندین آرگومان، از یک tuple استفاده کنید که هر عضو آن از یکی از نوع‌های اشاره‌شده در بالا باشد. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد به فضای نام پیش‌فرض ارسال می‌شود. .IP \(bu 2 \fBcallback\fP \-\- در صورت ارائه، این تابع برای تأیید دریافت پیام توسط سرور فراخوانی می‌شود. آرگومان‌هایی که به تابع فرستاده می‌شوند مواردی هستند که توسط سرور تأمین شده‌اند. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B shutdown() متوقف کردن کلاینت. .sp اگر کلاینت به سروری متصل باشد، اتصال آن قطع می‌شود. اگر کلاینت در حال تلاش برای اتصال مجدد به سرور باشد، تلاش‌های اتصال مجدد متوقف می‌شوند. اگر کلاینت به سروری متصل نباشد و تلاشی برای اتصال مجدد نکند، این تابع کاری انجام نمی‌دهد. .UNINDENT .INDENT 7.0 .TP .B sleep(seconds=0) به خواب بردن (sleep) به مدت زمان درخواستی با استفاده از مدل ناهمگام (async) مناسب. .sp این یک تابع کمکی است که برنامه‌ها می‌توانند بدون نگرانی در مورد استفاده از فراخوانی مناسب برای حالت async انتخاب‌شده، از آن برای به خواب بردن یک تسک استفاده کنند. .UNINDENT .INDENT 7.0 .TP .B start_background_task(target, *args, **kwargs) آغاز یک تسک پس‌زمینه با استفاده از مدل async مناسب. .sp این یک تابع کمکی است که برنامه‌ها می‌توانند با استفاده از روشی که با حالت async انتخاب‌شده سازگار است، از آن برای اجرای یک تسک پس‌زمینه استفاده کنند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBtarget\fP \-\- تابع هدف برای اجرا. .IP \(bu 2 \fBargs\fP \-\- آرگومان‌هایی که به تابع فرستاده می‌شوند. .IP \(bu 2 \fBkwargs\fP \-\- آرگومان‌های کلیدواژه‌ای که به تابع فرستاده می‌شوند. .UNINDENT .UNINDENT .sp این تابع شیئی را برمی‌گرداند که نشان‌دهندهٔ تسک پس‌زمینه است و می‌توان متد \fBjoin()\fP آن را برای منتظر ماندن تا تکمیل تسک فراخوانی کرد. .UNINDENT .INDENT 7.0 .TP .B transport() برگرداندن نام روش انتقال استفاده‌شده توسط کلاینت. .sp دو مقدار ممکن که توسط این تابع برگردانده می‌شوند \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP هستند. .UNINDENT .INDENT 7.0 .TP .B wait() منتظر ماندن تا پایان اتصال با سرور. .sp برنامه‌های کلاینت می‌توانند از این تابع برای مسدود کردن رشتهٔ اصلی (main thread) در طول مدت اتصال استفاده کنند. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.AsyncClient(reconnection=True, reconnection_attempts=0, reconnection_delay=1, reconnection_delay_max=5, randomization_factor=0.5, logger=False, serializer=\(aqdefault\(aq, json=None, handle_sigint=True, **kwargs) یک کلاینت Socket.IO برای asyncio. .sp این کلاس یک کلاینت وب Socket.IO کاملاً سازگار را با پشتیبانی از روش‌های انتقال websocket و long\-polling پیاده‌سازی می‌کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBreconnection\fP \-\- اگر کلاینت پس از قطعی باید به‌طور خودکار برای اتصال مجدد به سرور تلاش کند \fBTrue\fP، یا برای متصل نشدن مجدد \fBFalse\fP. پیش‌فرض \fBTrue\fP است. .IP \(bu 2 \fBreconnection_attempts\fP \-\- تعداد تلاش‌های اتصال مجدد پیش از انصراف، یا 0 برای تلاش نامحدود. پیش‌فرض 0 است. .IP \(bu 2 \fBreconnection_delay\fP \-\- مدت‌زمان انتظار به ثانیه پیش از نخستین تلاش اتصال مجدد. هر تلاش متوالی این تأخیر را دو برابر می‌کند. .IP \(bu 2 \fBreconnection_delay_max\fP \-\- بیشینهٔ تأخیر بین تلاش‌های اتصال مجدد. .IP \(bu 2 \fBrandomization_factor\fP \-\- میزان تصادفی‌سازی برای هر تأخیر بین تلاش‌های اتصال مجدد. پیش‌فرض 0.5 است، به این معنی که هر تأخیر به‌طور تصادفی تا +/\- 50% تنظیم می‌شود. .IP \(bu 2 \fBlogger\fP \-\- برای فعال‌سازی گزارش‌گیری روی \fBTrue\fP قرار دهید یا یک شیء logger برای استفاده پاس دهید. برای غیرفعال کردن گزارش‌گیری روی \fBFalse\fP تنظیم کنید. پیش‌فرض \fBFalse\fP است. توجه داشته باشید که خطاهای مهلک حتی زمانی که \fBlogger\fP برابر \fBFalse\fP باشد نیز ثبت می‌شوند. .IP \(bu 2 \fBjson\fP \-\- یک ماژول جایگزین JSON برای کدگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانهٔ استاندارد داشته باشند. این یک تنظیم در سطح کل فرآیند (process\-wide) است؛ تمامی سرورها و کلاینت‌های ایجادشده باید از همان ماژول JSON یکسان استفاده کنند..IP \(bu 2 \fBhandle_sigint\fP \-\- برای مدیریت خودکار قطع اتصال هنگام ایجاد وقفه در فرایند، روی \fBTrue\fP، یا برای واگذاری مدیریت وقفه به برنامهٔ فراخواننده، روی \fBFalse\fP تنظیم شود. مدیریت وقفه تنها زمانی می‌تواند فعال شود که نمونهٔ کلاینت در رشتهٔ اصلی (main thread) ایجاد شده باشد. .UNINDENT .UNINDENT .sp پیکربندی Engine.IO از تنظیمات زیر پشتیبانی می‌کند: .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBrequest_timeout\fP \-\- مهلت زمانی به ثانیه برای درخواست‌ها. مقدار پیش‌فرض ۵ ثانیه است. .IP \(bu 2 \fBhttp_session\fP \-\- یک شیء مقداردهی‌شده از \fBaiohttp.ClientSession\fP برای استفاده هنگام ارسال درخواست‌ها به سرور. در صورتی که نیاز به افزودن گزینه‌های خاص کلاینت مانند سرورهای پروکسی، گواهی‌های SSL، بستهٔ CA سفارشی و غیره دارید، از آن استفاده کنید. .IP \(bu 2 \fBssl_verify\fP \-\- مقدار \fBTrue\fP برای اعتبارسنجی گواهی‌های SSL، یا \fBFalse\fP برای نادیده گرفتن اعتبارسنجی گواهی SSL، که امکان اتصال به سرورهای دارای گواهی‌های خودامضا (self-signed) را فراهم می‌کند. مقدار پیش‌فرض \fBTrue\fP است. .IP \(bu 2 \fBwebsocket_extra_options\fP \-\- دیکشنری حاوی آرگومان‌های کلیدواژه‌ای اضافی که به \fBwebsocket.create_connection()\fP ارسال می‌شوند. .IP \(bu 2 \fBengineio_logger\fP \-\- برای فعال‌سازی ثبت وقایع Engine.IO روی \fBTrue\fP تنظیم کنید یا یک شیء ثبت وقایع (logger) ارسال نمایید. برای غیرفعال‌سازی ثبت وقایع، روی \fBFalse\fP تنظیم کنید. مقدار پیش‌فرض \fBFalse\fP است. توجه داشته باشید که خطاهای مهلک حتی زمانی که \fBengineio_logger\fP برابر با \fBFalse\fP باشد نیز ثبت می‌شوند. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B async call(event, data=None, namespace=None, timeout=60) ارسال (emit) یک رویداد سفارشی به سرور و انتظار برای پاسخ. .sp این متد یک ارسال (emit) به همراه بازخورد (callback) صادر می‌کند و پیش از بازگشت، منتظر فراخوانی بازخورد می‌ماند. اگر بازخورد پیش از اتمام مهلت زمانی فراخوانی نشود، یک استثنای \fBTimeoutError\fP ایجاد می‌شود. در صورتی که اتصال Socket.IO در طول مدت انتظار قطع شود، این متد همچنان تا زمان انقضای مهلت زمانی مشخص‌شده منتظر می‌ماند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد. برای ارسال چندین آرگومان، از یک تاپل (tuple) استفاده کنید که در آن هر عنصر از یکی از انواع ذکرشده در بالا باشد. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد به فضای نام پیش‌فرض ارسال می‌شود. .IP \(bu 2 \fBtimeout\fP \-\- مهلت زمانی انتظار. اگر مهلت زمانی پیش از تأیید رویداد توسط سرور به پایان برسد، یک استثنای \fBTimeoutError\fP ایجاد می‌شود. .UNINDENT .UNINDENT .sp نکته: این متد برای استفاده به صورت هم‌روند (concurrent) طراحی نشده است. اگر چندین تسک به طور همزمان روی یک اتصال کلاینت در حال ارسال باشند، ممکن است پیام‌های متشکل از چند بسته با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت، از راهکارهای استاندارد هم‌روندی (مانند یک شیء Lock) استفاده کنید. .sp نکته ۲: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async connect(url, headers={}, auth=None, transports=None, namespaces=None, socketio_path=\(aqsocket.io\(aq, wait=True, wait_timeout=1, retry=False) اتصال به یک سرور Socket.IO. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی URL سرور Socket.IO. در صورت نیاز سرور، می‌تواند شامل پارامترهای سفارشی رشتهٔ پرس‌وجو (query string) باشد. اگر یک تابع ارائه شود، کلاینت برای دریافت URL در هر بار تلاش برای اتصال یا اتصال مجدد، آن را فراخوانی می‌کند. .IP \(bu 2 \fBheaders\fP \-\- یک دیکشنری حاوی سرایندهای سفارشی جهت ارسال همراه با درخواست اتصال. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت دیکشنری سرایندها فراخوانی می‌کند. .IP \(bu 2 \fBauth\fP \-\- داده‌های احراز هویت ارسال‌شده به سرور همراه با درخواست اتصال، که معمولاً دیکشنری حاوی یک یا چند جفت کلید/مقدار رشته‌ای است. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت داده‌های احراز هویت فراخوانی می‌کند. .IP \(bu 2 \fBtransports\fP \-\- فهرست لایه‌های انتقال (transports) مجاز. گزینه‌های معتبر عبارتند از \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP\&. در صورت عدم تعیین، ابتدا لایهٔ انتقال polling متصل می‌شود، سپس تلاش برای ارتقا به websocket صورت می‌گیرد. .IP \(bu 2 \fBnamespaces\fP \-\- فضاهای نام برای اتصال به صورت یک رشته یا فهرستی از رشته‌ها. در صورت عدم تعیین، فضاهای نامی که دارای گرداننده‌های رویداد ثبت‌شده هستند متصل می‌شوند. .IP \(bu 2 \fBsocketio_path\fP \-\- نقطهٔ پایانی (endpoint) که سرور Socket.IO در آن مستقر است. مقدار پیش‌فرض برای بیشتر موارد مناسب است. .IP \(bu 2 \fBwait\fP \-\- اگر روی \fBTrue\fP (پیش‌فرض) تنظیم شود، فراخوانی تنها زمانی بازمی‌گردد که تمام فضاهای نام متصل شده باشند. اگر روی \fBFalse\fP تنظیم شود، فراخوانی به محض اتصال لایهٔ انتقال Engine.IO بازمی‌گردد و فضاهای نام در پس‌زمینه متصل خواهند شد. .IP \(bu 2 \fBwait_timeout\fP \-\- مدت زمانی که کلاینت باید در انتظار اتصال بماند. مقدار پیش‌فرض ۱ ثانیه است. این آرگومان تنها زمانی در نظر گرفته می‌شود که \fBwait\fP روی \fBTrue\fP تنظیم شده باشد. .IP \(bu 2 \fBretry\fP \-\- اعمال منطق اتصال مجدد در صورتی که تلاش اولیه برای اتصال با شکست مواجه شود. مقدار پیش‌فرض \fBFalse\fP است. .UNINDENT .UNINDENT .sp نکته: این متد یک کوروتین (coroutine) است. .sp نمونه کاربرد: .INDENT 7.0 .INDENT 3.5 .sp .EX sio = socketio.AsyncClient() await sio.connect(\(aqhttp://localhost:5000\(aq) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B connected مشخص می‌کند که آیا کلاینت متصل است یا خیر. .UNINDENT .INDENT 7.0 .TP .B async disconnect() قطع اتصال از سرور. .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async emit(event, data=None, namespace=None, callback=None) ارسال (emit) یک رویداد سفارشی به سرور. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد. برای ارسال چندین آرگومان، از یک تاپل (tuple) استفاده کنید که در آن هر عنصر از یکی از انواع ذکرشده در بالا باشد. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد به فضای نام پیش‌فرض ارسال می‌شود..IP \(bu 2 \fBcallback\fP \-\- در صورت ارائه، این تابع برای تأیید دریافت پیام توسط سرور فراخوانی می‌شود. آرگومان‌هایی که به این تابع فرستاده می‌شوند همان مواردی هستند که توسط سرور ارائه شده‌اند. .UNINDENT .UNINDENT .sp نکته: این متد برای استفاده هم‌روند طراحی نشده است. اگر چندین وظیفه (task) به طور هم‌زمان روی یک اتصال کلاینت در حال ارسال (emit) باشند، پیام‌هایی که از چندین بسته تشکیل شده‌اند ممکن است با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت از راهکارهای استاندارد هم‌روندی (مانند شیء Lock) استفاده کنید. .sp نکته ۲: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B event(*args, **kwargs) دکوراتور برای ثبت یک گرداننده رویداد (event handler). .sp این یک نسخه ساده‌شده از متد \fBon()\fP است که نام رویداد را از تابع دکوره‌شده می‌گیرد. .sp نمونه کاربرد: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.event def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .sp مثال بالا معادل است با: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.on(\(aqmy_event\(aq) def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .sp یک فضای نام (namespace) سفارشی می‌تواند به عنوان آرگومان به دکوراتور داده شود: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.event(namespace=\(aq/test\(aq) def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_sid(namespace=None) مقدار \fBsid\fP مرتبط با یک اتصال را برمی‌گرداند. .INDENT 7.0 .TP .B پارامترها \fBnamespace\fP \-\- فضای نام Socket.IO. در صورت حذف این آرگومان، گرداننده با فضای نام پیش‌فرض مرتبط می‌شود. توجه داشته باشید که برخلاف نسخه‌های پیشین، نسخه فعلی پروتکل Socket.IO از مقادیر \fBsid\fP متفاوتی به ازای هر فضای نام استفاده می‌کند. .UNINDENT .sp این متد \fBsid\fP را برای فضای نام درخواست‌شده در قالب یک رشته برمی‌گرداند. .UNINDENT .INDENT 7.0 .TP .B namespaces مجموعه‌ای از فضاهای نام متصل‌شده. .UNINDENT .INDENT 7.0 .TP .B on(event, handler=None, namespace=None) ثبت یک گرداننده رویداد. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. از نام رویداد \fB\(aq*\(aq\fP می‌توان برای تعریف یک گرداننده رویداد همه‌پوش (catch\-all) استفاده کرد. .IP \(bu 2 \fBhandler\fP \-\- تابعی که باید برای رسیدگی به رویداد فراخوانی شود. هنگامی که این پارامتر ارائه نشود، این متد مانند یک دکوراتور برای تابع گرداننده عمل می‌کند. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای این رویداد. در صورت حذف این آرگومان، گرداننده با فضای نام پیش‌فرض مرتبط می‌شود. یک فضای نام همه‌پوش (catch\-all) را می‌توان با ارسال \fB\(aq*\(aq\fP به عنوان فضای نام تعریف کرد. .UNINDENT .UNINDENT .sp نمونه کاربرد: .INDENT 7.0 .INDENT 3.5 .sp .EX # as a decorator: @sio.on(\(aqconnect\(aq) def connect_handler(): print(\(aqConnected!\(aq) # as a method: def message_handler(msg): print(\(aqReceived message: \(aq, msg) sio.send( \(aqresponse\(aq) sio.on(\(aqmessage\(aq, message_handler) .EE .UNINDENT .UNINDENT .sp آرگومان‌های ارسال‌شده به تابع گرداننده به نوع رویداد بستگی دارند: .INDENT 7.0 .IP \(bu 2 گرداننده رویداد \fB\(aqconnect\(aq\fP هیچ آرگومانی دریافت نمی‌کند. .IP \(bu 2 گرداننده رویداد \fB\(aqdisconnect\(aq\fP هیچ آرگومانی دریافت نمی‌کند. .IP \(bu 2 گرداننده \fB\(aqmessage\(aq\fP و گرداننده‌های نام‌های رویداد سفارشی، محموله پیام (payload) را به عنوان تنها آرگومان دریافت می‌کنند. هر مقداری که از گرداننده پیام بازگردانده شود، در صورت وجود، به تابع بازخوانی تأیید (acknowledgement callback) کلاینت تحویل داده خواهد شد. .IP \(bu 2 یک گرداننده رویداد همه‌پوش (catch\-all)، نام رویداد را به عنوان نخستین آرگومان دریافت می‌کند که در ادامه آرگومان‌های ویژه آن رویداد قرار می‌گیرند. .IP \(bu 2 یک گرداننده رویداد فضای نام همه‌پوش، فضای نام را به عنوان نخستین آرگومان دریافت می‌کند که در ادامه آرگومان‌های ویژه آن رویداد قرار می‌گیرند. .IP \(bu 2 یک گرداننده ترکیبی فضای نام همه‌پوش و رویداد همه‌پوش، نام رویداد را به عنوان نخستین آرگومان و فضای نام را به عنوان دومین آرگومان دریافت می‌کند که در ادامه آرگومان‌های ویژه آن رویداد قرار می‌گیرند. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B class reason دلایل قطع اتصال. .INDENT 7.0 .TP .B CLIENT_DISCONNECT = \(aqclient disconnect\(aq قطع اتصال به درخواست کلاینت. .UNINDENT .INDENT 7.0 .TP .B SERVER_DISCONNECT = \(aqserver disconnect\(aq قطع اتصال به درخواست سرور. .UNINDENT .INDENT 7.0 .TP .B TRANSPORT_ERROR = \(aqtransport error\(aq خطای لایه انتقال (ترابری). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B register_namespace(namespace_handler) ثبت یک شیء گرداننده فضای نام. .INDENT 7.0 .TP .B پارامترها \fBnamespace_handler\fP \-\- نمونه‌ای از یک زیرکلاس \fBNamespace\fP \%<#\:socketio\:.Namespace> که تمام ترافیک رویدادها را برای یک فضای نام مدیریت می‌کند. .UNINDENT .UNINDENT .INDENT 7.0.TP .B async send(data, namespace=None, callback=None) ارسال یک پیام به سرور. .sp این تابع رویدادی با نام \fB\(aqmessage\(aq\fP منتشر می‌کند. برای ایجاد نام‌های رویداد سفارشی از \fBemit()\fP استفاده کنید. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBdata\fP \-\- داده‌ای که باید به سرور ارسال شود. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد. برای ارسال چندین آرگومان، از یک تاپل (tuple) استفاده کنید که هر عنصر آن از یکی از انواع ذکر شده در بالا باشد. .IP \(bu 2 \fBnamespace\fP \-\- فضای‌نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد به فضای‌نام پیش‌فرض ارسال می‌شود. .IP \(bu 2 \fBcallback\fP \-\- در صورت تعیین، این تابع برای تایید دریافت پیام توسط سرور فراخوانی خواهد شد. آرگومان‌هایی که به تابع منتقل می‌شوند همان مواردی هستند که توسط سرور ارائه شده‌اند. .UNINDENT .UNINDENT .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async shutdown() متوقف کردن کلاینت. .sp اگر کلاینت به یک سرور متصل باشد، اتصال آن قطع می‌شود. اگر کلاینت در تلاش برای اتصال مجدد به سرور باشد، تلاش‌های اتصال مجدد متوقف می‌شوند. اگر کلاینت به سروری متصل نبوده و در حال تلاش برای اتصال مجدد نیز نباشد، این تابع هیچ کاری انجام نمی‌دهد. .UNINDENT .INDENT 7.0 .TP .B async sleep(seconds=0) توقف موقت (خوابیدن) به مدت زمان درخواستی با استفاده از مدل ناهمگام (async) مناسب. .sp این یک تابع کمکی است که برنامه‌ها می‌توانند برای به خواب بردن یک وظیفه (task) بدون نیاز به نگرانی درباره فراخوانی مناسب با حالت ناهمگام انتخاب‌شده از آن استفاده کنند. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B start_background_task(target, *args, **kwargs) شروع یک وظیفه پس‌زمینه با استفاده از مدل ناهمگام مناسب. .sp این یک تابع کمکی است که برنامه‌ها می‌توانند برای شروع یک وظیفه پس‌زمینه با استفاده از روش سازگار با حالت ناهمگامِ انتخاب‌شده از آن استفاده کنند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBtarget\fP \-\- تابع هدف برای اجرا. .IP \(bu 2 \fBargs\fP \-\- آرگومان‌هایی که به تابع ارسال می‌شوند. .IP \(bu 2 \fBkwargs\fP \-\- آرگومان‌های کلیدواژه‌ای که به تابع ارسال می‌شوند. .UNINDENT .UNINDENT .sp مقدار بازگشتی یک شیء \fBasyncio.Task\fP است. .UNINDENT .INDENT 7.0 .TP .B transport() بازگرداندن نام روش انتقال (transport) مورد استفاده توسط کلاینت. .sp دو مقدار ممکن که توسط این تابع بازگردانده می‌شوند \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP هستند. .UNINDENT .INDENT 7.0 .TP .B async wait() انتظار تا زمانی که ارتباط با سرور پایان یابد. .sp برنامه‌های کلاینت می‌توانند از این تابع برای مسدود کردن رشته اصلی (main thread) در طول مدت اتصال استفاده کنند. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .UNINDENT.SS سرورها (Servers) .INDENT 0.0 .TP .B class socketio.Server(client_manager=None, logger=False, serializer=\(aqdefault\(aq, json=None, async_handlers=True, always_connect=False, namespaces=None, **kwargs) یک سرور Socket.IO. .sp این کلاس یک وب‌سرور کاملاً منطبق با Socket.IO را همراه با پشتیبانی از ترابری‌های websocket و long\-polling پیاده‌سازی می‌کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBclient_manager\fP \-\- نمونهٔ مدیر کلاینت (client manager) که فهرست کلاینت‌ها را مدیریت خواهد کرد. در صورت عدم ذکر، فهرست کلاینت‌ها در یک ساختار درون‌حافظه‌ای ذخیره می‌شود، بنابراین استفاده از چند سرور متصل به یکدیگر امکان‌پذیر نخواهد بود. .IP \(bu 2 \fBlogger\fP \-\- برای فعال‌سازی گزارش‌گیری روی \fBTrue\fP تنظیم کنید یا یک شیء ثبت لاگ برای استفاده پاس دهید. برای غیرفعال‌سازی، آن را روی \fBFalse\fP تنظیم کنید\&. مقدار پیش‌فرض \fBFalse\fP است\&. توجه داشته باشید که خطاهای مرگبار (fatal) حتی زمانی که \fBlogger\fP برابر \fBFalse\fP است نیز ثبت می‌شوند\&. .IP \(bu 2 \fBserializer\fP \-\- روش سریال‌سازی مورد استفاده هنگام ارسال بسته‌ها. مقادیر معتبر عبارتند از \fB\(aqdefault\(aq\fP، \fB\(aqpickle\(aq\fP، \fB\(aqmsgpack\(aq\fP و \fB\(aqcbor\(aq\fP\&. علاوه بر این، می‌توان یک زیرکلاس از کلاس \fBPacket\fP همراه با پیاده‌سازی سفارشی متدهای \fBencode()\fP و \fBdecode()\fP ارائه داد. کلاینت و سرور باید از سریال‌سازهای سازگار استفاده کنند. .IP \(bu 2 \fBjson\fP \-\- یک ماژول جایگزین JSON برای کدگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانهٔ استاندارد داشته باشند. این یک تنظیم در سطح کل فرآیند (process\-wide) است و همهٔ سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON یکسان استفاده کنند. .IP \(bu 2 \fBasync_handlers\fP \-\- در صورت تنظیم روی \fBTrue\fP، گرداننده‌های رویداد برای یک کلاینت در رشته‌های (threads) جداگانه اجرا می‌شوند. برای اجرای همگام گرداننده‌ها برای یک کلاینت، آن را روی \fBFalse\fP تنظیم کنید\&. مقدار پیش‌فرض \fBTrue\fP است\&. .IP \(bu 2 \fBalways_connect\fP \-\- هنگامی که روی \fBFalse\fP تنظیم شود، اتصالات جدید مشروط و موقتی هستند تا زمانی که گردانندهٔ اتصال مقداری غیر از \fBFalse\fP بازگرداند، که در آن نقطه پذیرفته می‌شوند. وقتی روی \fBTrue\fP تنظیم شود، اتصالات بلافاصله پذیرفته می‌شوند و سپس اگر گردانندهٔ اتصال \fBFalse\fP بازگرداند، دستور قطع اتصال صادر می‌شود. اگر نیاز به انتشار رویدادها از درون گردانندهٔ اتصال دارید و کلاینت شما هنگام دریافت رویدادها پیش از پذیرش اتصال دچار تداخل می‌شود، آن را روی \fBTrue\fP تنظیم کنید. در هر حالت دیگری، از مقدار پیش‌فرض \fBFalse\fP استفاده کنید\&. .IP \(bu 2 \fBnamespaces\fP \-\- فهرستی از فضاهای نام (namespaces) که علاوه بر فضاهای نام دارای گردانندهٔ تعریف‌شده، پذیرفته می‌شوند. مقدار پیش‌فرض \fI[\(aq/\(aq]\fP است که همواره اتصالات به فضای نام پیش‌فرض را می‌پذیرد. برای پذیرش تمام فضاهای نام، روی \fI\(aq*\(aq\fP تنظیم کنید. .IP \(bu 2 \fBkwargs\fP \-\- پارامترهای اتصال برای سرور زیرین Engine.IO. .UNINDENT .UNINDENT .sp پیکربندی Engine.IO از تنظیمات زیر پشتیبانی می‌کند: .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBasync_mode\fP \-\- مدل ناهمگام مورد استفاده. برای مشاهدهٔ شرح گزینه‌های موجود، بخش Deployment را در مستندات بررسی کنید. حالت‌های ناهمگام معتبر عبارتند از \fB\(aqthreading\(aq\fP، \fB\(aqeventlet\(aq\fP، \fB\(aqgevent\(aq\fP و \fB\(aqgevent_uwsgi\(aq\fP\&. اگر این آرگومان مشخص نشود، ابتدا \fB\(aqeventlet\(aq\fP، سپس \fB\(aqgevent_uwsgi\(aq\fP، بعد از آن \fB\(aqgevent\(aq\fP و در نهایت \fB\(aqthreading\(aq\fP امتحان می‌شود\&. نخستین حالت ناهمگامی که تمامی وابستگی‌های آن نصب باشد انتخاب خواهد شد. .IP \(bu 2 \fBping_interval\fP \-\- بازهٔ زمانی بر حسب ثانیه که در آن سرور به کلاینت پینگ ارسال می‌کند. مقدار پیش‌فرض ۲۵ ثانیه است. برای کنترل پیشرفته‌تر، می‌توان یک تاپل دو عضوی تعیین کرد که عدد اول بازهٔ پینگ و عدد دوم دورهٔ مهلت (grace period) اضافه شده توسط سرور است. .IP \(bu 2 \fBping_timeout\fP \-\- مدت‌زمانی بر حسب ثانیه که کلاینت پیش از قطع اتصال، منتظر پاسخ سرور می‌ماند. مقدار پیش‌فرض ۲۰ ثانیه است. .IP \(bu 2 \fBmax_http_buffer_size\fP \-\- حداکثر اندازهٔ مجاز برای پیام‌های دریافتی. مقدار پیش‌فرض ۱٬۰۰۰٬۰۰۰ بایت است. علی‌رغم نام آن، مقدار تعیین‌شده در این آرگومان برای هر دو اتصال HTTP long\-polling و WebSocket اعمال می‌شود. .IP \(bu 2 \fBallow_upgrades\fP \-\- مشخص می‌کند که آیا ارتقای ترابری مجاز باشد یا خیر. مقدار پیش‌فرض \fBTrue\fP است\&. .IP \(bu 2 \fBhttp_compression\fP \-\- مشخص می‌کند که هنگام استفاده از ترابری polling بسته‌ها فشرده‌سازی شوند یا خیر. مقدار پیش‌فرض \fBTrue\fP است\&. .IP \(bu 2 \fBcompression_threshold\fP \-\- پیام‌ها تنها زمانی فشرده‌سازی می‌شوند که اندازهٔ بایتی آن‌ها از این مقدار بیشتر باشد. مقدار پیش‌فرض ۱۰۲۴ بایت است. .IP \(bu 2 \fBcookie\fP \-\- اگر روی یک رشته تنظیم شود، نام کوکی HTTP خواهد بود که سرور حاوی شناسهٔ نشست (session id) کلاینت به آن بازمی‌گرداند. اگر روی یک دیکشنری تنظیم شود، کلید \fB\(aqname\(aq\fP حاوی نام کوکی خواهد بود و سایر کلیدها مشخصه‌های کوکی را تعریف می‌کنند که در آن مقدار هر مشخصه می‌تواند یک رشته، یک فراخوانی‌پذیر (callable) بدون آرگومان، یا یک بولی باشد. در صورت تنظیم روی \fBNone\fP (پیش‌فرض)، هیچ کوکی‌ای به کلاینت ارسال نمی‌شود. .IP \(bu 2 \fBcors_allowed_origins\fP \-\- مبدا یا فهرستی از مبداهایی که مجاز به اتصال به این سرور هستند. به‌طور پیش‌فرض تنها همان مبدا (same origin) مجاز است. این آرگومان را روی \fB\(aq*\(aq\fP تنظیم کنید تا همهٔ مبداها مجاز شوند، یا برای غیرفعال کردن مدیریت CORS آن را روی \fB[]\fP قرار دهید. .IP \(bu 2 \fBcors_credentials\fP \-\- مشخص می‌کند که آیا ارسال اطلاعات هویتی و اعتبارسنجی (کوکی‌ها، احراز هویت) در درخواست‌ها به این سرور مجاز است یا خیر. مقدار پیش‌فرض \fBTrue\fP است\&. .IP \(bu 2 \fBmonitor_clients\fP \-\- در صورت تنظیم روی \fBTrue\fP، یک وظیفهٔ پس‌زمینه اطمینان حاصل می‌کند که کلاینت‌های غیرفعال بسته شوند. برای غیرفعال‌سازی این وظیفهٔ نظارتی، آن را روی \fBFalse\fP تنظیم کنید (توصیه نمی‌شود). مقدار پیش‌فرض \fBTrue\fP است\&. .IP \(bu 2 \fBtransports\fP \-\- فهرست ترابری‌های مجاز. ترابری‌های معتبر شامل \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP هستند\&. مقدار پیش‌فرض \fB[\(aqpolling\(aq, \(aqwebsocket\(aq]\fP است\&. .IP \(bu 2 \fBengineio_logger\fP \-\- برای فعال‌سازی گزارش‌گیری Engine.IO روی \fBTrue\fP تنظیم کنید یا یک شیء ثبت لاگ برای استفاده پاس دهید. برای غیرفعال‌سازی روی \fBFalse\fP تنظیم کنید\&. مقدار پیش‌فرض \fBFalse\fP است\&. توجه داشته باشید که خطاهای مرگبار حتی در صورت \fBFalse\fP بودن \fBengineio_logger\fP نیز ثبت می‌شوند\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B call(event, data=None, to=None, sid=None, namespace=None, timeout=60, ignore_queue=False) ارسال یک رویداد سفارشی به یک کلاینت و انتظار برای دریافت پاسخ. .sp این متد یک ارسال (emit) همراه با بازخوانی (callback) ایجاد می‌کند و پیش از بازگشت، منتظر فراخوانی شدن آن بازخوانی می‌ماند. اگر بازخوانی پیش از پایان مهلت زمانی فراخوانی نشود، یک استثنای \fBTimeoutError\fP صادر می‌شود. اگر اتصال Socket.IO در حین انتظار قطع شود، این متد همچنان تا پایان مهلت زمانی مشخص‌شده منتظر می‌ماند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده‌ای که باید به کلاینت یا کلاینت‌ها ارسال شود. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد\&. برای ارسال چند آرگومان، از یک تاپل استفاده کنید که هر عضو آن یکی از نوع‌های اشاره‌شده در بالا باشد. .IP \(bu 2 \fBto\fP \-\- شناسهٔ نشست (session ID) کلاینت گیرنده. .IP \(bu 2 \fBsid\fP \-\- نام مستعار برای پارامتر \fBto\fP. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. در صورت عدم ذکر این آرگومان، رویداد به فضای نام پیش‌فرض ارسال می‌شود. .IP \(bu 2 \fBtimeout\fP \-\- مهلت زمانی انتظار. اگر مهلت پیش از آنکه کلاینت دریافت رویداد را تأیید کند به پایان برسد، استثنای \fBTimeoutError\fP صادر می‌شود. .IP \(bu 2 \fBignore_queue\fP \-\- تنها زمانی استفاده می‌شود که یک صف پیام (message queue) پیکربندی شده باشد. در صورت تنظیم روی \fBTrue\fP، رویداد مستقیماً و بدون عبور از صف برای کلاینت ارسال می‌شود. این حالت کارآمدتر است، اما تنها زمانی کار می‌کند که از یک فرآیند سرور منفرد استفاده شود. توصیه می‌شود همیشه این پارامتر را با مقدار پیش‌فرض آن، یعنی \fBFalse\fP باقی بگذارید\&. .UNINDENT .UNINDENT.sp نکته: این متد thread-safe نیست. اگر چندین ریسه (thread) به طور هم‌زمان در حال ارسال (emit) به یک کلاینت یکسان باشند، ممکن است پیام‌های تشکیل‌شده از چندین بسته با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت، از راه‌حل‌های همزمانی استاندارد (مانند یک شیء Lock) استفاده کنید. .UNINDENT .INDENT 7.0 .TP .B close_room(room, namespace=None) بستن یک اتاق. .sp این تابع تمام کلاینت‌ها را از اتاق داده‌شده حذف می‌کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBroom\fP \-\- نام اتاق. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B disconnect(sid, namespace=None, ignore_queue=False) قطع اتصال یک کلاینت. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست (Session ID) کلاینت. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای قطع اتصال. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود. .IP \(bu 2 \fBignore_queue\fP \-\- فقط زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. اگر روی \fBTrue\fP تنظیم شود، قطع اتصال به صورت محلی پردازش شده و بدون پخش همگانی (broadcast) در صف انجام می‌گیرد. توصیه می‌شود همیشه این پارامتر با مقدار پیش‌فرض \fBFalse\fP\& رها شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False) ارسال (Emit) یک رویداد سفارشی به یک یا چند کلاینت متصل. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده هستند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده‌ها برای ارسال به کلاینت یا کلاینت‌ها. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP\& باشد. برای ارسال چندین آرگومان، از یک tuple استفاده کنید که هر عنصر آن از یکی از انواع ذکرشده در بالا باشد. .IP \(bu 2 \fBto\fP \-\- دریافت‌کننده پیام. این مقدار می‌تواند روی شناسه نشست یک کلاینت تنظیم شود تا فقط همان کلاینت را مخاطب قرار دهد، یا روی هر اتاق سفارشی ایجادشده توسط برنامه تنظیم شود تا تمام کلاینت‌های آن اتاق را مخاطب قرار دهد، یا روی فهرستی از نام‌های اتاق‌های سفارشی تنظیم گردد. اگر این آرگومان حذف شود، رویداد برای تمام کلاینت‌های متصل پخش همگانی (broadcast) می‌شود. .IP \(bu 2 \fBroom\fP \-\- نام مستعار برای پارامتر \fBto\fP\&. .IP \(bu 2 \fBskip_sid\fP \-\- شناسه نشست کلاینتی که هنگام پخش همگانی به یک اتاق یا به تمام کلاینت‌ها باید نادیده گرفته شود. از این مقدار می‌توان برای جلوگیری از ارسال پیام به خود فرستنده استفاده کرد. برای نادیده گرفتن چندین sid، یک list ارسال کنید. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد در فضای نام پیش‌فرض ارسال می‌شود. .IP \(bu 2 \fBcallback\fP \-\- در صورت ارائه، این تابع برای تأیید دریافت پیام توسط کلاینت فراخوانی خواهد شد. آرگومان‌هایی که به تابع پاس داده می‌شوند همان مواردی هستند که توسط کلاینت فراهم شده‌اند. توابع callback فقط هنگام مخاطب قرار دادن یک کلاینت منفرد قابل استفاده هستند. .IP \(bu 2 \fBignore_queue\fP \-\- فقط زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. اگر روی \fBTrue\fP تنظیم شود، رویداد مستقیماً به کلاینت‌ها ارسال شده و از صف عبور نمی‌کند. این حالت کارآمدتر است، اما تنها زمانی کار می‌کند که از یک فرایند سرور منفرد استفاده شود. توصیه می‌شود همیشه این پارامتر با مقدار پیش‌فرض \fBFalse\fP\& رها شود. .UNINDENT .UNINDENT .sp نکته: این متد thread-safe نیست. اگر چندین ریسه (thread) به طور هم‌زمان در حال ارسال (emit) به یک کلاینت یکسان باشند، ممکن است پیام‌های تشکیل‌شده از چندین بسته با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت، از راه‌حل‌های همزمانی استاندارد (مانند یک شیء Lock) استفاده کنید. .UNINDENT .INDENT 7.0 .TP .B enter_room(sid, room, namespace=None) ورود به یک اتاق. .sp این تابع کلاینت را به یک اتاق اضافه می‌کند. توابع \fBemit()\fP و \fBsend()\fP می‌توانند به صورت اختیاری رویدادها را برای تمام کلاینت‌های موجود در یک اتاق پخش همگانی (broadcast) کنند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست (Session ID) کلاینت. .IP \(bu 2 \fBroom\fP \-\- نام اتاق. اگر اتاق وجود نداشته باشد، ایجاد می‌شود. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B event(*args, **kwargs) دکوراتور برای ثبت یک گرداننده رویداد (event handler). .sp این یک نسخه ساده‌شده از متد \fBon()\fP است که نام رویداد را از تابع دکوره‌شده دریافت می‌کند. .sp مثال کاربرد: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.event def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .sp مثال بالا معادل است با: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.on(\(aqmy_event\(aq) def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .sp یک فضای نام سفارشی می‌تواند به عنوان آرگومان به دکوراتور داده شود: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.event(namespace=\(aq/test\(aq) def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_environ(sid, namespace=None) بازگرداندن دیکشنری WSGI environ برای یک کلاینت. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- نشست کلاینت..IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO. در صورت حذف این آرگومان، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_session(sid, namespace=None) نشست کاربر را برای یک کلاینت برمی‌گرداند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست (session id) کلاینت. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO. در صورت حذف این آرگومان، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .sp مقدار بازگشتی یک دیکشنری است. هیچ تضمینی برای حفظ تغییرات اعمال‌شده در این دیکشنری وجود ندارد مگر اینکه \fBsave_session()\fP فراخوانی شود، یا از مدیر زمینه (context manager) \fBsession\fP استفاده گردد. .UNINDENT .INDENT 7.0 .TP .B handle_request(environ, start_response) یک درخواست HTTP را از سمت کلاینت مدیریت می‌کند. .sp این نقطه ورود برنامه Socket.IO است که از همان رابط برنامه WSGI استفاده می‌کند. در کاربردهای متداول، این تابع توسط نمونه \fBMiddleware\fP \%<#\:socketio\:.Middleware> فراخوانی می‌شود، اما در صورت عدم استفاده از میان‌افزار، می‌توان آن را مستقیماً فراخوانی کرد. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBenviron\fP \-\- محیط WSGI. .IP \(bu 2 \fBstart_response\fP \-\- تابع \fBstart_response\fP در WSGI. .UNINDENT .UNINDENT .sp این تابع بدنه پاسخ HTTP را به عنوان یک دنباله بایت برای تحویل به کلاینت برمی‌گرداند. .UNINDENT .INDENT 7.0 .TP .B instrument(auth=None, mode=\(aqdevelopment\(aq, read_only=False, server_id=None, namespace=\(aq/admin\(aq, server_stats_interval=2) تجهیز و آماده‌سازی سرور Socket.IO برای نظارت با Socket.IO Admin UI \%\&. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBauth\fP \-\- اطلاعات احراز هویت برای دسترسی به Admin UI. به یک دیکشنری با اطلاعات ورود مورد انتظار (معمولاً \fBusername\fP و \fBpassword\fP) یا فهرستی از دیکشنری‌ها در صورتی که بیش از یک دسته اطلاعات احراز هویت مورد نیاز باشد تنظیم می‌شود. برای روش‌های احراز هویت پیچیده‌تر، به یک شیء قابل فراخوانی (callable) تنظیم شود که دیکشنری احراز هویت را به عنوان آرگومان دریافت کرده و در صورت مجاز بودن کاربر \fBTrue\fP یا در غیر این صورت \fBFalse\fP برمی‌گرداند. برای غیرفعال کردن احراز هویت، این آرگومان را روی \fBFalse\fP قرار دهید (توصیه نمی‌شود؛ هرگز این کار را روی یک سرور عملیاتی انجام ندهید). .IP \(bu 2 \fBmode\fP \-\- حالت گزارش‌دهی. مقدار پیش‌فرض \fB\(aqdevelopment\(aq\fP است که بهتر است هنگام اشکال‌زدایی استفاده شود، چرا که ممکن است تأثیر قابل‌توجهی بر عملکرد داشته باشد. برای کاهش میزان اطلاعات گزارش‌شده به Admin UI، آن را روی \fB\(aqproduction\(aq\fP تنظیم کنید. .IP \(bu 2 \fBread_only\fP \-\- در صورت تنظیم روی \fBTrue\fP، رابط کاربری مدیریت به صورت فقط‌خواندنی (read\-only) خواهد بود، بدون امکان تغییر تخصیص اتاق‌ها یا قطع اتصال کلاینت‌ها. مقدار پیش‌فرض \fBFalse\fP است\&. .IP \(bu 2 \fBserver_id\fP \-\- نام سرور برای استفاده در این سرور. در صورت حذف این آرگومان، سرور نام خود را تولید می‌کند. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای استفاده در رابط کاربری مدیریت. مقدار پیش‌فرض \fB/admin\fP است\&. .IP \(bu 2 \fBserver_stats_interval\fP \-\- بازه زمانی بر حسب ثانیه که در آن سرور خلاصه‌ای از آمار خود را برای تمامی مدیران متصل ارسال (emit) می‌کند. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B leave_room(sid, room, namespace=None) ترک یک اتاق. .sp این تابع کلاینت را از یک اتاق خارج می‌کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست (Session ID) کلاینت. .IP \(bu 2 \fBroom\fP \-\- نام اتاق. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. در صورت حذف این آرگومان، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B on(event, handler=None, namespace=None) ثبت یک گرداننده رویداد. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. نام رویداد \fB\(aq*\(aq\fP می‌تواند برای تعریف یک گرداننده رویداد فراگیر (catch\-all) استفاده شود. .IP \(bu 2 \fBhandler\fP \-\- تابعی که باید برای مدیریت رویداد فراخوانی شود. در صورتی که این پارامتر مشخص نشود، این متد به عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. در صورت حذف این آرگومان، گرداننده به فضای نام پیش‌فرض مرتبط می‌شود. با ارسال \fB\(aq*\(aq\fP به عنوان فضای نام، می‌توان یک فضای نام فراگیر (catch\-all) تعریف کرد. .UNINDENT .UNINDENT .sp نمونه استفاده: .INDENT 7.0 .INDENT 3.5 .sp .EX # as a decorator: @sio.on(\(aqconnect\(aq, namespace=\(aq/chat\(aq) def connect_handler(sid, environ): print(\(aqConnection request\(aq) if environ[\(aqREMOTE_ADDR\(aq] in blacklisted: return False # reject # as a method: def message_handler(sid, msg): print(\(aqReceived message: \(aq, msg) sio.send(sid, \(aqresponse\(aq) socket_io.on(\(aqmessage\(aq, namespace=\(aq/chat\(aq, handler=message_handler) .EE .UNINDENT .UNINDENT .sp آرگومان‌های ارسال‌شده به تابع گرداننده به نوع رویداد بستگی دارد: .INDENT 7.0 .IP \(bu 2 گرداننده رویداد \fB\(aqconnect\(aq\fP آرگومان‌های \fBsid\fP (شناسه نشست) برای کلاینت و دیکشنری محیط WSGI را دریافت می‌کند. .IP \(bu 2 گرداننده \fB\(aqdisconnect\(aq\fP شناسه \fBsid\fP کلاینت را به عنوان تنها آرگومان دریافت می‌کند. .IP \(bu 2 گرداننده \fB\(aqmessage\(aq\fP و گرداننده‌های نام‌های رویداد سفارشی، \fBsid\fP کلاینت و محموله پیام را به عنوان آرگومان دریافت می‌کنند. هر مقداری که از یک گرداننده پیام بازگردانده شود، در صورت وجود تابع بازخوانی تأییدیه کلاینت (acknowledgement callback)، به آن ارسال خواهد شد. .IP \(bu 2 یک گرداننده رویداد فراگیر (catch\-all)، نام رویداد را به عنوان آرگومان اول، به همراه آرگومان‌های اختصاصی رویداد دریافت می‌کند. .IP \(bu 2 یک گرداننده رویداد فضای نام فراگیر (catch\-all)، فضای نام را به عنوان آرگومان اول، به همراه آرگومان‌های اختصاصی رویداد دریافت می‌کند. .IP \(bu 2 یک گرداننده ترکیبی فضای نام فراگیر و رویداد فراگیر، نام رویداد را به عنوان آرگومان اول و فضای نام را به عنوان آرگومان دوم، به همراه آرگومان‌های اختصاصی رویداد دریافت می‌کند. .UNINDENT .UNINDENT .INDENT 7.0.TP .B class reason دلایل قطع اتصال. .INDENT 7.0 .TP .B CLIENT_DISCONNECT = \(aqclient disconnect\(aq قطع اتصال آغاز شده از سوی کلاینت. .UNINDENT .INDENT 7.0 .TP .B PING_TIMEOUT = \(aqping timeout\(aq اتمام مهلت پینگ (Ping timeout). .UNINDENT .INDENT 7.0 .TP .B SERVER_DISCONNECT = \(aqserver disconnect\(aq قطع اتصال آغاز شده از سوی سرور. .UNINDENT .INDENT 7.0 .TP .B TRANSPORT_CLOSE = \(aqtransport close\(aq بسته شدن لایه انتقال (Transport close). .UNINDENT .INDENT 7.0 .TP .B TRANSPORT_ERROR = \(aqtransport error\(aq خطای لایه انتقال (Transport error). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B register_namespace(namespace_handler) ثبت یک شیء گرداننده فضای‌نام (namespace handler). .INDENT 7.0 .TP .B پارامترها (Parameters) \fBnamespace_handler\fP \-\- نمونه‌ای از زیرکلاس \fBNamespace\fP \%<#\:socketio\:.Namespace> که تمام ترافیک رویدادها را برای یک فضای‌نام مدیریت می‌کند. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B rooms(sid, namespace=None) اتاق‌هایی را که یک کلاینت در آن‌ها حضور دارد برمی‌گرداند. .INDENT 7.0 .TP .B پارامترها (Parameters) .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست (Session ID) کلاینت. .IP \(bu 2 \fBnamespace\fP \-\- فضای‌نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، از فضای‌نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B save_session(sid, session, namespace=None) ذخیره نشست کاربر برای یک کلاینت. .INDENT 7.0 .TP .B پارامترها (Parameters) .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست کلاینت. .IP \(bu 2 \fBsession\fP \-\- دیکشنری نشست (session dictionary). .IP \(bu 2 \fBnamespace\fP \-\- فضای‌نام Socket.IO. اگر این آرگومان حذف شود، از فضای‌نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False) ارسال یک پیام به یک یا چند کلاینت متصل. .sp این تابع رویدادی با نام \fB\(aqmessage\(aq\fP منتشر می‌کند. برای صدور رویدادهایی با نام‌های سفارشی از \fBemit()\fP استفاده کنید. .INDENT 7.0 .TP .B پارامترها (Parameters) .INDENT 7.0 .IP \(bu 2 \fBdata\fP \-\- داده ارسالی به کلاینت یا کلاینت‌ها. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد. برای ارسال چندین آرگومان، از یک تاپل (tuple) استفاده کنید که هر عنصر آن از یکی از انواع ذکر شده در بالا باشد. .IP \(bu 2 \fBto\fP \-\- گیرنده پیام. این مقدار می‌تواند روی شناسه نشست یک کلاینت تنظیم شود تا فقط آن کلاینت را مخاطب قرار دهد، روی هر اتاق سفارشی ایجادشده توسط برنامه تا تمام کلاینت‌های آن اتاق را مخاطب قرار دهد، یا روی فهرستی از نام‌های سفارشی اتاق‌ها تنظیم شود. اگر این آرگومان حذف شود، رویداد برای تمام کلاینت‌های متصل همگانی (broadcast) می‌شود. .IP \(bu 2 \fBroom\fP \-\- نام مستعار برای پارامتر \fBto\fP. .IP \(bu 2 \fBskip_sid\fP \-\- شناسه نشست کلاینتی که هنگام انتشار همگانی در یک اتاق یا برای تمام کلاینت‌ها باید نادیده گرفته شود. از این مقدار می‌توان برای جلوگیری از ارسال پیام به فرستنده استفاده کرد. برای نادیده گرفتن چندین sid، یک فهرست ارسال کنید. .IP \(bu 2 \fBnamespace\fP \-\- فضای‌نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد در فضای‌نام پیش‌فرض منتشر می‌شود. .IP \(bu 2 \fBcallback\fP \-\- در صورت ارائه، این تابع برای تأیید دریافت پیام توسط کلاینت فراخوانی می‌شود. آرگومان‌هایی که به این تابع منتقل می‌شوند، همان مواردی هستند که توسط کلاینت ارائه شده‌اند. توابع بازخوانی (Callback) فقط هنگام مخاطب قرار دادن یک کلاینت مجزا قابل استفاده هستند. .IP \(bu 2 \fBignore_queue\fP \-\- فقط هنگامی که یک صف پیام (message queue) پیکربندی شده باشد استفاده می‌شود. اگر روی \fBTrue\fP تنظیم شود، رویداد مستقیماً و بدون عبور از صف برای کلاینت‌ها ارسال می‌شود. این روش کارآمدتر است، اما تنها هنگامی کار می‌کند که از یک فرآیند سرور واحد استفاده شود. توصیه می‌شود همیشه این پارامتر را با مقدار پیش‌فرض خود یعنی \fBFalse\fP باقی بگذارید. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B session(sid, namespace=None) بازگرداندن نشست کاربر برای یک کلاینت با نحو مدیر زمینه (context manager). .INDENT 7.0 .TP .B پارامترها (Parameters) \fBsid\fP \-\- شناسه نشست کلاینت. .UNINDENT .sp این یک مدیر زمینه (context manager) است که دیکشنری نشست کاربر را برای کلاینت برمی‌گرداند. هرگونه تغییری که در این دیکشنری درون بلوک مدیر زمینه اعمال شود، دوباره در نشست ذخیره می‌شود. نمونه کاربرد: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.on(\(aqconnect\(aq) def on_connect(sid, environ): username = authenticate_user(environ) if not username: return False with sio.session(sid) as session: session[\(aqusername\(aq] = username @sio.on(\(aqmessage\(aq) def on_message(sid, msg): with sio.session(sid) as session: print(\(aqreceived message from \(aq, session[\(aqusername\(aq]) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B shutdown() توقف وظایف پس‌زمینه Socket.IO. .sp این متد تمام فعالیت‌های پس‌زمینه آغاز شده توسط سرور Socket.IO را متوقف می‌کند. این متد باید پیش از خاموش کردن وب‌سرور فراخوانی شود. .UNINDENT .INDENT 7.0 .TP .B sleep(seconds=0) خوابیدن به میزان زمان درخواستی با استفاده از مدل ناهمگام (async) مناسب. .sp این یک تابع کمکی است که برنامه‌ها می‌توانند از آن برای به خواب بردن یک وظیفه بدون نیاز به نگرانی درباره استفاده از فراخوانی صحیح برای حالت async انتخاب‌شده استفاده کنند. .UNINDENT .INDENT 7.0 .TP .B start_background_task(target, *args, **kwargs) شروع یک وظیفه پس‌زمینه با استفاده از مدل ناهمگام (async) مناسب..sp این یک تابع کمکی است که برنامه‌ها می‌توانند برای شروع یک وظیفه پس‌زمینه با استفاده از روش سازگار با حالت ناهمگام (async mode) انتخاب‌شده، از آن استفاده کنند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBtarget\fP \-\- تابع هدف برای اجرا. .IP \(bu 2 \fBargs\fP \-\- آرگومان‌ها برای ارسال به تابع. .IP \(bu 2 \fBkwargs\fP \-\- آرگومان‌های کلیدواژه‌ای برای ارسال به تابع. .UNINDENT .UNINDENT .sp این تابع شیئی را برمی‌گرداند که نمایندهٔ وظیفه پس‌زمینه است، و می‌توان متد \fBjoin()\fP را روی آن فراخوانی کرد تا منتظر تکمیل وظیفه بماند. .UNINDENT .INDENT 7.0 .TP .B transport(sid, namespace=None) نام روش انتقال (transport) استفاده‌شده توسط کلاینت را برمی‌گرداند. .sp دو مقدار ممکن بازگردانده‌شده توسط این تابع \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP هستند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- نشست (session) کلاینت. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO. در صورت حذف این آرگومان، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.AsyncServer(client_manager=None, logger=False, json=None, async_handlers=True, namespaces=None, **kwargs) یک سرور Socket.IO برای asyncio. .sp این کلاس یک وب‌سرور Socket.IO کاملاً سازگار را با پشتیبانی از روش‌های انتقال websocket و long\-polling، و سازگار با چارچوب asyncio پیاده‌سازی می‌کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBclient_manager\fP \-\- نمونه مدیر کلاینت که فهرست کلاینت‌ها را مدیریت می‌کند. در صورت حذف این مورد، فهرست کلاینت‌ها در یک ساختار درون‌حافظه‌ای ذخیره می‌شود، بنابراین استفاده از چند سرور متصل امکان‌پذیر نخواهد بود. .IP \(bu 2 \fBlogger\fP \-\- برای فعال‌سازی گزارش‌گیری روی \fBTrue\fP تنظیم کنید یا یک شیء logger را برای استفاده بفرستید. برای غیرفعال‌سازی گزارش‌گیری روی \fBFalse\fP قرار دهید. توجه داشته باشید که خطاهای مهلک حتی در صورت \fBFalse\fP بودن \fBlogger\fP نیز ثبت می‌شوند. .IP \(bu 2 \fBjson\fP \-\- یک ماژول جایگزین JSON برای رمزگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این یک تنظیم در سطح کل فرآیند است؛ همه سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON استفاده کنند. .IP \(bu 2 \fBasync_handlers\fP \-\- در صورت تنظیم روی \fBTrue\fP، گرداننده‌های رویداد برای یک کلاینت در ریسمان‌های جداگانه اجرا می‌شوند. برای اجرای همگام گرداننده‌ها برای کلاینت، آن را روی \fBFalse\fP تنظیم کنید. مقدار پیش‌فرض \fBTrue\fP است. .IP \(bu 2 \fBalways_connect\fP \-\- در صورت تنظیم روی \fBFalse\fP، اتصالات جدید موقتی هستند تا زمانی که گرداننده connect مقداری به غیر از \fBFalse\fP برگرداند، که در آن زمان پذیرفته می‌شوند. در صورت تنظیم روی \fBTrue\fP، اتصالات بلافاصله پذیرفته می‌شوند و سپس اگر گرداننده connect مقدار \fBFalse\fP برگرداند، دستور قطع اتصال صادر می‌شود. اگر لازم است از گرداننده connect رویداد منتشر کنید و کلاینت با دریافت رویدادها قبل از پذیرش اتصال دچار سردرگمی می‌شود، آن را روی \fBTrue\fP تنظیم کنید. در هر حالت دیگر از مقدار پیش‌فرض \fBFalse\fP استفاده کنید. .IP \(bu 2 \fBnamespaces\fP \-\- فهرستی از فضاهای نام پذیرفته‌شده، علاوه بر هر فضای نامی که برای آن گرداننده‌ای تعریف شده باشد. مقدار پیش‌فرض \fI[\(aq/\(aq]\fP است که همواره اتصالات به فضای نام پیش‌فرض را می‌پذیرد. برای پذیرش همه فضاهای نام، آن را روی \fI\(aq*\(aq\fP تنظیم کنید. .IP \(bu 2 \fBkwargs\fP \-\- پارامترهای اتصال برای سرور زیرین Engine.IO. .UNINDENT .UNINDENT .sp پیکربندی Engine.IO از تنظیمات زیر پشتیبانی می‌کند: .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBasync_mode\fP \-\- مدل ناهمگام مورد استفاده. برای توضیحات گزینه‌های موجود، بخش Deployment در مستندات را ببینید. حالت‌های ناهمگام معتبر عبارتند از \(dqaiohttp\(dq، \(dqsanic\(dq، \(dqtornado\(dq و \(dqasgi\(dq. اگر این آرگومان داده نشود، ابتدا \(dqaiohttp\(dq، سپس \(dqsanic\(dq، بعد \(dqtornado\(dq و در نهایت \(dqasgi\(dq امتحان می‌شود. نخستین حالت ناهمگامی که تمام وابستگی‌های آن نصب باشد انتخاب می‌شود. .IP \(bu 2 \fBping_interval\fP \-\- بازه زمانی به ثانیه که سرور برای کلاینت پینگ ارسال می‌کند. پیش‌فرض 25 ثانیه است. برای کنترل پیشرفته‌تر، می‌توان یک تاپل دو عنصری مشخص کرد که در آن عدد اول بازه پینگ و عدد دوم مهلت زمانی اضافه‌ای است که سرور اضافه می‌کند. .IP \(bu 2 \fBping_timeout\fP \-\- مدت زمانی به ثانیه که کلاینت پیش از قطع اتصال، منتظر پاسخ سرور می‌ماند. پیش‌فرض 20 ثانیه است. .IP \(bu 2 \fBmax_http_buffer_size\fP \-\- بیشینه اندازه پذیرفته‌شده برای پیام‌های ورودی. مقدار پیش‌فرض 1,000,000 بایت است. بر خلاف نام آن، مقدار مشخص‌شده در این آرگومان برای هر دو اتصال HTTP long\-polling و WebSocket اعمال می‌شود. .IP \(bu 2 \fBallow_upgrades\fP \-\- مجاز بودن یا نبودن ارتقای روش انتقال. پیش‌فرض \fBTrue\fP است. .IP \(bu 2 \fBhttp_compression\fP \-\- فشرده‌سازی بسته‌ها هنگام استفاده از روش انتقال polling. پیش‌فرض \fBTrue\fP است. .IP \(bu 2 \fBcompression_threshold\fP \-\- فشرده‌سازی پیام‌ها تنها در صورتی که اندازه بایت آن‌ها بزرگ‌تر از این مقدار باشد. پیش‌فرض 1024 بایت است. .IP \(bu 2 \fBcookie\fP \-\- در صورت تنظیم روی یک رشته، نام کوکی HTTP خواهد بود که سرور حاوی شناسه نشست کلاینت به کلاینت بازمی‌گرداند. در صورت تنظیم روی یک دیکشنری، کلید \fB\(aqname\(aq\fP حاوی نام کوکی خواهد بود و سایر کلیدها ویژگی‌های کوکی را تعیین می‌کنند، که در آن مقدار هر ویژگی می‌تواند یک رشته، یک تابع فراخوانی‌پذیر بدون آرگومان، یا یک بولی باشد. در صورت تنظیم روی \fBNone\fP (پیش‌فرض)، هیچ کوکی‌ای به کلاینت ارسال نمی‌شود. .IP \(bu 2 \fBcors_allowed_origins\fP \-\- مبدا یا فهرستی از مبداهای مجاز برای اتصال به این سرور. به‌طور پیش‌فرض تنها همان مبدا (same origin) مجاز است. این آرگومان را روی \fB\(aq*\(aq\fP برای مجاز کردن همه مبداها، یا روی \fB[]\fP برای غیرفعال کردن مدیریت CORS تنظیم کنید. .IP \(bu 2 \fBcors_credentials\fP \-\- مجاز بودن یا نبودن اطلاعات اعتبارسنجی (کوکی‌ها، احراز هویت) در درخواست‌ها به این سرور. مقدار پیش‌فرض \fBTrue\fP است. .IP \(bu 2 \fBmonitor_clients\fP \-\- در صورت تنظیم روی \fBTrue\fP، یک وظیفه پس‌زمینه اطمینان حاصل می‌کند که کلاینت‌های غیرفعال بسته شوند. برای غیرفعال‌سازی این وظیفه نظارتی (توصیه نمی‌شود)، آن را روی \fBFalse\fP قرار دهید. مقدار پیش‌فرض \fBTrue\fP است. .IP \(bu 2 \fBtransports\fP \-\- فهرست روش‌های انتقال مجاز. گزینه‌های معتبر \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP هستند. مقدار پیش‌فرض \fB[\(aqpolling\(aq, \(aqwebsocket\(aq]\fP است. .IP \(bu 2 \fBengineio_logger\fP \-\- برای فعال‌سازی گزارش‌گیری Engine.IO روی \fBTrue\fP تنظیم کنید یا یک شیء logger را برای استفاده ارسال نمایید. برای غیرفعال‌سازی، آن را روی \fBFalse\fP قرار دهید. پیش‌فرض \fBFalse\fP است. توجه داشته باشید که خطاهای مهلک حتی زمانی که \fBengineio_logger\fP مقدار \fBFalse\fP دارد نیز ثبت می‌شوند. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B attach(app, socketio_path=\(aqsocket.io\(aq) متصل کردن سرور Socket.IO به یک برنامه. .UNINDENT .INDENT 7.0 .TP .B async call(event, data=None, to=None, sid=None, namespace=None, timeout=60, ignore_queue=False) ارسال یک رویداد سفارشی به یک کلاینت و انتظار برای دریافت پاسخ..sp این متد یک ارسال (emit) به همراه بازخورد (callback) صادر می‌کند و پیش از بازگشت، منتظر فراخوانی بازخورد می‌ماند. اگر بازخورد پیش از اتمام مهلت زمانی (timeout) فراخوانی نشود، یک استثنای \fBTimeoutError\fP ایجاد می‌شود. اگر اتصال Socket.IO در طول زمان انتظار قطع شود، این متد همچنان تا پایان مهلت زمانی مشخص‌شده منتظر می‌ماند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به کلاینت یا کلاینت‌ها. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP\& باشد. برای ارسال چندین آرگومان، از یک tuple استفاده کنید که هر عضو آن از یکی از انواع اشاره‌شده در بالا باشد. .IP \(bu 2 \fBto\fP \-\- شناسه نشست (session ID) کلاینت گیرنده. .IP \(bu 2 \fBsid\fP \-\- نام مستعار برای پارامتر \fBto\fP. .IP \(bu 2 \fBnamespace\fP \-\- فضای‌نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد در فضای‌نام پیش‌فرض منتشر می‌شود. .IP \(bu 2 \fBtimeout\fP \-\- مهلت زمانی انتظار. اگر پیش از تأیید دریافت رویداد توسط کلاینت، مهلت زمانی به پایان برسد، یک استثنای \fBTimeoutError\fP ایجاد می‌شود. .IP \(bu 2 \fBignore_queue\fP \-\- تنها زمانی استفاده می‌شود که یک صف پیام (message queue) پیکربندی شده باشد. اگر روی \fBTrue\fP تنظیم شود، رویداد مستقیماً و بدون عبور از صف برای کلاینت ارسال می‌شود. این روش کارآمدتر است، اما تنها زمانی کار می‌کند که از یک فرآیند سرور تکی استفاده شود. توصیه می‌شود همیشه این پارامتر را روی مقدار پیش‌فرض خود یعنی \fBFalse\fP\& باقی بگذارید. .UNINDENT .UNINDENT .sp نکته: این متد برای استفاده هم‌روند طراحی نشده است. اگر چندین تسک به طور هم‌زمان به یک اتصال کلاینت رویداد ارسال کنند، ممکن است پیام‌های متشکل از چندین بسته با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت، از راهکارهای استاندارد هم‌روندی (مانند شیء Lock) استفاده کنید. .sp نکته ۲: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async close_room(room, namespace=None) بستن یک اتاق. .sp این تابع همه کلاینت‌ها را از اتاق داده‌شده حذف می‌کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBroom\fP \-\- نام اتاق. .IP \(bu 2 \fBnamespace\fP \-\- فضای‌نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، از فضای‌نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async disconnect(sid, namespace=None, ignore_queue=False) قطع اتصال یک کلاینت. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست کلاینت. .IP \(bu 2 \fBnamespace\fP \-\- فضای‌نام Socket.IO برای قطع اتصال. اگر این آرگومان حذف شود، از فضای‌نام پیش‌فرض استفاده می‌شود. .IP \(bu 2 \fBignore_queue\fP \-\- تنها زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. اگر روی \fBTrue\fP تنظیم شود، قطع اتصال به صورت محلی و بدون انتشار در صف پردازش می‌شود. توصیه می‌شود همیشه این پارامتر را روی مقدار پیش‌فرض خود یعنی \fBFalse\fP\& باقی بگذارید. .UNINDENT .UNINDENT .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False) ارسال یک رویداد سفارشی به یک یا چند کلاینت متصل. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. .IP \(bu 2 \fBdata\fP \-\- داده برای ارسال به کلاینت یا کلاینت‌ها. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP\& باشد. برای ارسال چندین آرگومان، از یک tuple استفاده کنید که هر عضو آن از یکی از انواع اشاره‌شده در بالا باشد. .IP \(bu 2 \fBto\fP \-\- گیرنده پیام. این پارامتر می‌تواند روی شناسه نشست یک کلاینت برای مخاطب قرار دادن تنها همان کلاینت، روی هر اتاق سفارشی ایجادشده توسط برنامه برای مخاطب قرار دادن تمام کلاینت‌های آن اتاق، یا روی فهرستی از نام‌های اتاق‌های سفارشی تنظیم شود. اگر این آرگومان حذف شود، رویداد برای تمام کلاینت‌های متصل منتشر (broadcast) می‌شود. .IP \(bu 2 \fBroom\fP \-\- نام مستعار برای پارامتر \fBto\fP. .IP \(bu 2 \fBskip_sid\fP \-\- شناسه نشست کلاینتی که هنگام انتشار برای یک اتاق یا تمام کلاینت‌ها باید نادیده گرفته شود. از این پارامتر می‌توان برای جلوگیری از ارسال پیام به فرستنده استفاده کرد. .IP \(bu 2 \fBnamespace\fP \-\- فضای‌نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد در فضای‌نام پیش‌فرض منتشر می‌شود. .IP \(bu 2 \fBcallback\fP \-\- در صورت ارائه، این تابع برای تأیید دریافت پیام توسط کلاینت فراخوانی خواهد شد. آرگومان‌هایی که به تابع ارسال می‌شوند، همان‌هایی هستند که توسط کلاینت ارائه شده‌اند. توابع بازخورد تنها هنگام مخاطب قرار دادن یک کلاینت واحد قابل استفاده هستند. .IP \(bu 2 \fBignore_queue\fP \-\- تنها زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. اگر روی \fBTrue\fP تنظیم شود، رویداد مستقیماً و بدون عبور از صف برای کلاینت‌ها ارسال می‌شود. این روش کارآمدتر است، اما تنها زمانی کار می‌کند که از یک فرآیند سرور تکی استفاده شود. توصیه می‌شود همیشه این پارامتر را روی مقدار پیش‌فرض خود یعنی \fBFalse\fP\& باقی بگذارید. .UNINDENT .UNINDENT .sp نکته: این متد برای استفاده هم‌روند طراحی نشده است. اگر چندین تسک به طور هم‌زمان به یک اتصال کلاینت رویداد ارسال کنند، ممکن است پیام‌های متشکل از چندین بسته با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت، از راهکارهای استاندارد هم‌روندی (مانند شیء Lock) استفاده کنید. .sp نکته ۲: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async enter_room(sid, room, namespace=None) ورود به یک اتاق. .sp این تابع کلاینت را به یک اتاق اضافه می‌کند. توابع \fBemit()\fP و \fBsend()\fP می‌توانند به صورت اختیاری رویدادها را برای تمام کلاینت‌های یک اتاق منتشر کنند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست کلاینت. .IP \(bu 2 \fBroom\fP \-\- نام اتاق. اگر اتاق وجود نداشته باشد، ایجاد می‌شود. .IP \(bu 2 \fBnamespace\fP \-\- فضای‌نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، از فضای‌نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B event(*args, **kwargs) دکوراتور (Decorator) برای ثبت یک گرداننده رویداد (event handler)..sp این یک نسخهٔ ساده‌شده از متد \fBon()\fP است که نام رویداد را از تابع تزئین‌شده (decorated) دریافت می‌کند. .sp نمونه استفاده: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.event def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .sp مثال بالا معادل است با: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.on(\(aqmy_event\(aq) def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .sp می‌توان یک فضای نام (namespace) سفارشی را به‌عنوان آرگومان به دکوراتور داد: .INDENT 7.0 .INDENT 3.5 .sp .EX @sio.event(namespace=\(aq/test\(aq) def my_event(data): print(\(aqReceived data: \(aq, data) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B get_environ(sid, namespace=None) دیکشنری WSGI environ را برای یک کلاینت بازمی‌گرداند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- نشست (session) کلاینت. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B async get_session(sid, namespace=None) نشست کاربری (user session) را برای یک کلاینت بازمی‌گرداند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست (session id) کلاینت. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .sp مقدار بازگشتی یک دیکشنری است. هیچ تضمینی وجود ندارد که تغییرات اعمال‌شده در این دیکشنری حفظ شوند. اگر می‌خواهید نشست کاربری را تغییر دهید، به‌جای آن از مدیر زمینه (context manager) \fBsession\fP استفاده کنید. .UNINDENT .INDENT 7.0 .TP .B async handle_request(*args, **kwargs) یک درخواست HTTP را از سمت کلاینت مدیریت و پردازش می‌کند. .sp این نقطهٔ ورود برنامهٔ Socket.IO است. این تابع بدنهٔ پاسخ HTTP را جهت ارسال به کلاینت بازمی‌گرداند. .sp نکته: این متد یک coroutine (هم‌روال) است. .UNINDENT .INDENT 7.0 .TP .B instrument(auth=None, mode=\(aqdevelopment\(aq, read_only=False, server_id=None, namespace=\(aq/admin\(aq, server_stats_interval=2) سرور Socket.IO را جهت نظارت و پایش توسط Socket.IO Admin UI \%\& آماده‌سازی و ابزارگذاری (instrument) می‌کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBauth\fP \-\- اطلاعات اعتبارسنجی برای دسترسی به Admin UI. به یک دیکشنری با اطلاعات ورود مورد انتظار (معمولاً \fBusername\fP و \fBpassword\fP) یا لیستی از دیکشنری‌ها در صورتی که به بیش از یک مجموعه اطلاعات اعتبارسنجی نیاز باشد تنظیم می‌شود. برای روش‌های احراز هویت پیچیده‌تر، آن را به یک شیء قابل فراخوانی (callable) تنظیم کنید که دیکشنری اعتبارسنجی را به‌عنوان آرگومان دریافت کرده و در صورت مجاز بودن کاربر \fBTrue\fP یا در غیر این صورت \fBFalse\fP بازمی‌گرداند. برای غیرفعال کردن احراز هویت، این آرگومان را روی \fBFalse\fP تنظیم کنید (توصیه نمی‌شود؛ هرگز این کار را روی سرور عملیاتی یا production انجام ندهید). .IP \(bu 2 \fBmode\fP \-\- حالت گزارش‌دهی. پیش‌فرض \fB\(aqdevelopment\(aq\fP است که بهترین کاربرد آن هنگام اشکال‌زدایی است، زیرا ممکن است تأثیر چشمگیری بر کارایی داشته باشد. برای کاهش میزان اطلاعات گزارش‌شده به رابط Admin UI، آن را روی \fB\(aqproduction\(aq\fP تنظیم کنید. .IP \(bu 2 \fBread_only\fP \-\- اگر روی \fBTrue\fP تنظیم شود، رابط مدیریتی فقط‌خواندنی (read\-only) خواهد بود و امکانی برای تغییر انتساب اتاق‌ها یا قطع اتصال کلاینت‌ها وجود نخواهد داشت. پیش‌فرض \fBFalse\fP است. .IP \(bu 2 \fBserver_id\fP \-\- نام سرور مورد استفاده برای این سرور. اگر این آرگومان حذف شود، سرور نام خود را تولید می‌کند. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای استفاده در رابط مدیریتی. پیش‌فرض \fB/admin\fP است. .IP \(bu 2 \fBserver_stats_interval\fP \-\- بازهٔ زمانی برحسب ثانیه که در آن سرور خلاصه‌ای از آمارهای خود را برای همهٔ مدیران متصل ارسال (emit) می‌کند. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B async leave_room(sid, room, namespace=None) ترک یک اتاق. .sp این تابع کلاینت را از یک اتاق خارج می‌کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست (session ID) کلاینت. .IP \(bu 2 \fBroom\fP \-\- نام اتاق. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای این رویداد. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .sp نکته: این متد یک coroutine (هم‌روال) است. .UNINDENT .INDENT 7.0 .TP .B on(event, handler=None, namespace=None) ثبت یک گردانندهٔ رویداد (event handler). .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP و \fB\(aqdisconnect\(aq\fP رزرو شده‌اند و نباید استفاده شوند. از نام رویداد \fB\(aq*\(aq\fP می‌توان برای تعریف یک گردانندهٔ رویداد فراگیر (catch\-all) استفاده کرد. .IP \(bu 2 \fBhandler\fP \-\- تابعی که باید برای مدیریت رویداد فراخوانی شود. زمانی که این پارامتر مشخص نشده باشد، متد به‌عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، گرداننده با فضای نام پیش‌فرض مرتبط می‌شود. با ارسال \fB\(aq*\(aq\fP به‌عنوان فضای نام، می‌توان یک فضای نام فراگیر (catch\-all) تعریف کرد. .UNINDENT .UNINDENT .sp نمونه استفاده: .INDENT 7.0 .INDENT 3.5.sp .EX # as a decorator: @sio.on(\(aqconnect\(aq, namespace=\(aq/chat\(aq) def connect_handler(sid, environ): print(\(aqConnection request\(aq) if environ[\(aqREMOTE_ADDR\(aq] in blacklisted: return False # reject # as a method: def message_handler(sid, msg): print(\(aqReceived message: \(aq, msg) sio.send(sid, \(aqresponse\(aq) socket_io.on(\(aqmessage\(aq, namespace=\(aq/chat\(aq, handler=message_handler) .EE .UNINDENT .UNINDENT .sp آرگومان‌های ارسال‌شده به تابع گرداننده به نوع رویداد بستگی دارند: .INDENT 7.0 .IP \(bu 2 گرداننده رویداد \fB\(aqconnect\(aq\fP مقدار \fBsid\fP (شناسه نشست) برای کلاینت و دیکشنری محیط WSGI را به عنوان آرگومان دریافت می‌کند. .IP \(bu 2 گرداننده \fB\(aqdisconnect\(aq\fP مقدار \fBsid\fP برای کلاینت را به عنوان تنها آرگومان دریافت می‌کند. .IP \(bu 2 گرداننده \fB\(aqmessage\(aq\fP و گرداننده‌های نام‌های رویداد سفارشی، \fBsid\fP برای کلاینت و بار داده (payload) پیام را به عنوان آرگومان دریافت می‌کنند. هر مقداری که از گرداننده پیام بازگردانده شود، در صورت وجود به تابع فراخوانی بازگشتی (callback) تأییدیه کلاینت ارسال خواهد شد. .IP \(bu 2 یک گرداننده رویداد فراگیر (catch\-all)، نام رویداد را به عنوان آرگومان نخست و پس از آن آرگومان‌های ویژه رویداد را دریافت می‌کند. .IP \(bu 2 یک گرداننده رویداد فضای نام فراگیر، فضای نام را به عنوان آرگومان نخست و پس از آن آرگومان‌های ویژه رویداد را دریافت می‌کند. .IP \(bu 2 یک گرداننده ترکیبی رویداد و فضای نام فراگیر، نام رویداد را به عنوان آرگومان نخست و فضای نام را به عنوان آرگومان دوم، و پس از آن آرگومان‌های ویژه رویداد را دریافت می‌کند. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B class reason دلایل قطع اتصال. .INDENT 7.0 .TP .B CLIENT_DISCONNECT = \(aqclient disconnect\(aq قطع اتصال آغازشده از سوی کلاینت. .UNINDENT .INDENT 7.0 .TP .B PING_TIMEOUT = \(aqping timeout\(aq اتمام مهلت زمانی پینگ (Ping timeout). .UNINDENT .INDENT 7.0 .TP .B SERVER_DISCONNECT = \(aqserver disconnect\(aq قطع اتصال آغازشده از سوی سرور. .UNINDENT .INDENT 7.0 .TP .B TRANSPORT_CLOSE = \(aqtransport close\(aq بسته شدن لایه انتقال (Transport close). .UNINDENT .INDENT 7.0 .TP .B TRANSPORT_ERROR = \(aqtransport error\(aq خطای لایه انتقال (Transport error). .UNINDENT .UNINDENT .INDENT 7.0 .TP .B register_namespace(namespace_handler) ثبت یک شیء گرداننده فضای نام. .INDENT 7.0 .TP .B پارامترها \fBnamespace_handler\fP \-\- نمونه‌ای از زیرکلاس \fBNamespace\fP \%<#\:socketio\:.Namespace> که تمام ترافیک رویداد را برای یک فضای نام مدیریت می‌کند. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B rooms(sid, namespace=None) اتاق‌هایی که کلاینت در آن‌ها حضور دارد را بازمی‌گرداند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست کلاینت. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. در صورت حذف این آرگومان، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B async save_session(sid, session, namespace=None) ذخیره نشست کاربر برای یک کلاینت. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- شناسه نشست کلاینت. .IP \(bu 2 \fBsession\fP \-\- دیکشنری نشست. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO. در صورت حذف این آرگومان، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B async send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False) ارسال یک پیام به یک یا چند کلاینت متصل. .sp این تابع رویدادی با نام \fB\(aqmessage\(aq\fP منتشر می‌کند. برای ارسال نام‌های رویداد سفارشی از \fBemit()\fP استفاده کنید. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBdata\fP \-\- داده ارسالی به کلاینت یا کلاینت‌ها. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد. برای ارسال چندین آرگومان، از یک تاپل (tuple) استفاده کنید که هر عنصر آن از یکی از انواع اشاره‌شده در بالا باشد. .IP \(bu 2 \fBto\fP \-\- گیرنده پیام. این پارامتر می‌تواند روی شناسه نشست یک کلاینت تنظیم شود تا فقط آن کلاینت را مورد خطاب قرار دهد، روی هر اتاق سفارشی ایجادشده توسط برنامه تا تمام کلاینت‌های آن اتاق را خطاب قرار دهد، یا روی فهرستی از نام اتاق‌های سفارشی تنظیم شود. در صورت حذف این آرگومان، رویداد برای تمام کلاینت‌های متصل همه‌پخشی (broadcast) می‌شود. .IP \(bu 2 \fBroom\fP \-\- نام مستعار برای پارامتر \fBto\fP. .IP \(bu 2 \fBskip_sid\fP \-\- شناسه نشست کلاینتی که هنگام همه‌پخشی به یک اتاق یا تمام کلاینت‌ها باید نادیده گرفته شود. از این پارامتر می‌توان برای جلوگیری از ارسال پیام به فرستنده استفاده کرد. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO برای رویداد. در صورت حذف این آرگومان، رویداد در فضای نام پیش‌فرض منتشر می‌شود. .IP \(bu 2 \fBcallback\fP \-\- در صورت ارائه، این تابع فراخوانی خواهد شد تا دریافت پیام توسط کلاینت را تأیید کند. آرگومان‌هایی که به تابع ارسال می‌شوند مواردی هستند که توسط کلاینت ارائه شده‌اند. توابع فراخوانی بازگشتی تنها زمانی قابل استفاده هستند که یک کلاینت به صورت منفرد خطاب قرار گیرد. .IP \(bu 2 \fBignore_queue\fP \-\- تنها زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. در صورت تنظیم روی \fBTrue\fP، رویداد به طور مستقیم و بدون عبور از صف برای کلاینت‌ها منتشر می‌شود. این روش کارآمدتر است، اما تنها در صورتی کار می‌کند که یک فرآیند سرور منفرد به کار گرفته شده باشد. توصیه می‌شود همیشه این پارامتر را روی مقدار پیش‌فرض \fBFalse\fP باقی بگذارید. .UNINDENT .UNINDENT .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B session(sid, namespace=None) بازگرداندن نشست کاربر برای یک کلاینت با نحو مدیریت‌کننده زمینه (context manager). .INDENT 7.0 .TP .B پارامترها \fBsid\fP \-\- شناسه نشست کلاینت. .UNINDENT.sp این یک context manager است که دیکشنری نشست کاربر را برای کلاینت برمی‌گرداند. هرگونه تغییری که درون بلوک context manager روی این دیکشنری اعمال شود، مجدداً در نشست ذخیره خواهد شد. نمونه استفاده: .INDENT 7.0 .INDENT 3.5 .sp .EX @eio.on(\(aqconnect\(aq) async def on_connect(sid, environ): username = authenticate_user(environ) if not username: return False async with eio.session(sid) as session: session[\(aqusername\(aq] = username @eio.on(\(aqmessage\(aq) async def on_message(sid, msg): async with eio.session(sid) as session: print(\(aqreceived message from \(aq, session[\(aqusername\(aq]) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B async shutdown() متوقف کردن وظایف پس‌زمینه Socket.IO. .sp این متد تمام فعالیت‌های پس‌زمینه را که توسط سرور Socket.IO آغاز شده‌اند متوقف می‌کند. این متد باید پیش از خاموش کردن وب‌سرور فراخوانی شود. .UNINDENT .INDENT 7.0 .TP .B async sleep(seconds=0) به خواب رفتن به میزان زمان درخواستی با استفاده از مدل async مناسب. .sp این یک تابع کمکی است که برنامه‌ها می‌توانند از آن برای به خواب بردن یک وظیفه بدون نیاز به نگرانی درباره استفاده از فراخوانی صحیح برای حالت async انتخاب‌شده استفاده کنند. .sp نکته: این متد یک coroutine است. .UNINDENT .INDENT 7.0 .TP .B start_background_task(target, *args, **kwargs) آغاز یک وظیفه پس‌زمینه با استفاده از مدل async مناسب. .sp این یک تابع کمکی است که برنامه‌ها می‌توانند با استفاده از متدی که با حالت async انتخاب‌شده سازگار است، برای شروع یک وظیفه پس‌زمینه از آن بهره ببرند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBtarget\fP \-\- تابع هدف برای اجرا. باید یک coroutine باشد. .IP \(bu 2 \fBargs\fP \-\- آرگومان‌های ارسالی به تابع. .IP \(bu 2 \fBkwargs\fP \-\- آرگومان‌های کلیدواژه‌ای ارسالی به تابع. .UNINDENT .UNINDENT .sp مقدار بازگشتی یک شیء \fBasyncio.Task\fP است. .UNINDENT .INDENT 7.0 .TP .B transport(sid, namespace=None) بازگرداندن نام transport استفاده‌شده توسط کلاینت. .sp دو مقدار ممکن که توسط این تابع بازگردانده می‌شوند \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP\& هستند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsid\fP \-\- نشست کلاینت. .IP \(bu 2 \fBnamespace\fP \-\- فضای نام Socket.IO. در صورت حذف این آرگومان، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.exceptions.ConnectionRefusedError(*args) استثنای رد اتصال (Connection refused). .sp این استثنا می‌تواند هنگامی که اتصال پذیرفته نمی‌شود، از سوی یک گرداننده connect ایجاد (raise) شود. آرگومان‌های مکانی ارائه شده با این استثنا همراه با بسته خطا به کلاینت بازگردانده می‌شوند. .UNINDENT.SS میان‌افزارها (Middlewares) .INDENT 0.0 .TP .B class socketio.WSGIApp(socketio_app, wsgi_app=None, static_files=None, socketio_path=\(aqsocket.io\(aq) میان‌افزار WSGI برای Socket.IO. .sp این میان‌افزار ترافیک را به یک برنامه Socket.IO ارسال می‌کند. همچنین می‌تواند فهرستی از فایل‌های استاتیک را به کلاینت ارائه دهد، یا ترافیک نامرتبط HTTP را به یک برنامه دیگر WSGI هدایت کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsocketio_app\fP \-\- سرور Socket.IO. باید نمونه‌ای از کلاس \fBsocketio.Server\fP باشد. .IP \(bu 2 \fBwsgi_app\fP \-\- برنامه WSGI که سایر ترافیک‌ها را دریافت می‌کند. .IP \(bu 2 \fBstatic_files\fP \-\- یک دیکشنری شامل قوانین نگاشت فایل‌های استاتیک. برای جزئیات در مورد این آرگومان، مستندات را ببینید. .IP \(bu 2 \fBsocketio_path\fP \-\- نقطه پایانی (endpoint) که برنامه Socket.IO باید در آن نصب شود. مقدار پیش‌فرض برای بیشتر موارد مناسب است. .UNINDENT .UNINDENT .sp مثال نحوه استفاده: .INDENT 7.0 .INDENT 3.5 .sp .EX import socketio import eventlet from . import wsgi_app sio = socketio.Server() app = socketio.WSGIApp(sio, wsgi_app) eventlet.wsgi.server(eventlet.listen((\(aq\(aq, 8000)), app) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.ASGIApp(socketio_server, other_asgi_app=None, static_files=None, socketio_path=\(aqsocket.io\(aq, on_startup=None, on_shutdown=None) میان‌افزار برنامه ASGI برای Socket.IO. .sp این میان‌افزار ترافیک را به یک برنامه Socket.IO ارسال می‌کند. همچنین می‌تواند فهرستی از فایل‌های استاتیک را به کلاینت ارائه دهد، یا ترافیک نامرتبط HTTP را به یک برنامه دیگر ASGI هدایت کند. .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBsocketio_server\fP \-\- سرور Socket.IO. باید نمونه‌ای از کلاس \fBsocketio.AsyncServer\fP باشد. .IP \(bu 2 \fBstatic_files\fP \-\- یک دیکشنری شامل قوانین نگاشت فایل‌های استاتیک. برای جزئیات در مورد این آرگومان، مستندات را ببینید. .IP \(bu 2 \fBother_asgi_app\fP \-\- یک برنامه مجزای ASGI که سایر ترافیک‌ها را دریافت می‌کند. .IP \(bu 2 \fBsocketio_path\fP \-\- نقطه پایانی (endpoint) که برنامه Socket.IO باید در آن نصب شود. مقدار پیش‌فرض برای بیشتر موارد مناسب است. با مقدار \fBNone\fP، تمام ترافیک ورودی به سرور Socket.IO هدایت می‌شود، با این فرض که مسیریابی در صورت نیاز توسط لایه دیگری انجام می‌شود. هنگامی که این گزینه روی \fBNone\fP تنظیم شود، \fBstatic_files\fP و \fBother_asgi_app\fP نادیده گرفته می‌شوند. .IP \(bu 2 \fBon_startup\fP \-\- تابعی که هنگام راه‌اندازی برنامه فراخوانی می‌شود؛ می‌تواند کوروتین (coroutine) باشد .IP \(bu 2 \fBon_shutdown\fP \-\- تابعی که هنگام خاموش شدن برنامه فراخوانی می‌شود؛ می‌تواند کوروتین (coroutine) باشد .UNINDENT .UNINDENT .sp مثال نحوه استفاده: .INDENT 7.0 .INDENT 3.5 .sp .EX import socketio import uvicorn sio = socketio.AsyncServer() app = socketio.ASGIApp(sio, static_files={ \(aq/\(aq: \(aqindex.html\(aq, \(aq/static\(aq: \(aq./public\(aq, }) uvicorn.run(app, host=\(aq127.0.0.1\(aq, port=5000) .EE .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.Middleware(socketio_app, wsgi_app=None, socketio_path=\(aqsocket.io\(aq) نام این کلاس به WSGIApp تغییر یافته و اکنون منسوخ (deprecated) شده است. .UNINDENT.SS فضاهای نام (Namespaces) .INDENT 0.0 .TP .B class socketio.ClientNamespace(namespace=None) کلاس پایه برای فضاهای نام مبتنی بر کلاس در سمت کلاینت. .sp یک فضای نام مبتنی بر کلاس، کلاسی است که شامل تمام گرداننده‌های رویداد برای یک فضای نام Socket.IO است. گرداننده‌های رویداد متدهایی از کلاس با پیشوند \fBon_\fP هستند، مانند \fBon_connect\fP، \fBon_disconnect\fP، \fBon_message\fP، \fBon_json\fP و غیره. .INDENT 7.0 .TP .B پارامترها (Parameters) \fBnamespace\fP \-\- فضای نام Socket.IO که باید برای تمام گرداننده‌های رویداد تعریف‌شده در این کلاس استفاده شود. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B call(event, data=None, namespace=None, timeout=None) ارسال یک رویداد سفارشی به سرور و انتظار برای پاسخ. .sp تنها تفاوت با متد \fBsocketio.Client.call()\fP \%<#\:socketio\:.Client\:.call> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B disconnect() قطع اتصال از سرور. .sp تنها تفاوت با متد \fBsocketio.Client.disconnect()\fP \%<#\:socketio\:.Client\:.disconnect> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B emit(event, data=None, namespace=None, callback=None) ارسال یک رویداد سفارشی به سرور. .sp تنها تفاوت با متد \fBsocketio.Client.emit()\fP \%<#\:socketio\:.Client\:.emit> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B send(data, room=None, namespace=None, callback=None) ارسال یک پیام به سرور. .sp تنها تفاوت با متد \fBsocketio.Client.send()\fP \%<#\:socketio\:.Client\:.send> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B trigger_event(event, *args) توزیع یک رویداد به متد گردانندهٔ مناسب. .sp در متداول‌ترین شیوه استفاده، این متد توسط زیرکلاس‌ها بازنویسی (overload) نمی‌شود، زیرا مسیریابی رویدادها به متدها را انجام می‌دهد. با این حال، اگر قواعد توزیع ویژه‌ای نیاز باشد، یا در صورتی که وجود یک متد واحد که تمام رویدادها را دریافت کند مد نظر باشد، می‌توان این متد را رونویسی (override) کرد. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.Namespace(namespace=None) کلاس پایه برای فضاهای نام مبتنی بر کلاس در سمت سرور. .sp یک فضای نام مبتنی بر کلاس، کلاسی است که شامل تمام گرداننده‌های رویداد برای یک فضای نام Socket.IO است. گرداننده‌های رویداد متدهایی از کلاس با پیشوند \fBon_\fP هستند، مانند \fBon_connect\fP، \fBon_disconnect\fP، \fBon_message\fP، \fBon_json\fP و غیره. .INDENT 7.0 .TP .B پارامترها (Parameters) \fBnamespace\fP \-\- فضای نام Socket.IO که باید برای تمام گرداننده‌های رویداد تعریف‌شده در این کلاس استفاده شود. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B call(event, data=None, to=None, sid=None, namespace=None, timeout=None, ignore_queue=False) ارسال یک رویداد سفارشی به یک کلاینت و انتظار برای پاسخ. .sp تنها تفاوت با متد \fBsocketio.Server.call()\fP \%<#\:socketio\:.Server\:.call> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B close_room(room, namespace=None) بستن یک اتاق. .sp تنها تفاوت با متد \fBsocketio.Server.close_room()\fP \%<#\:socketio\:.Server\:.close_room> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B disconnect(sid, namespace=None) قطع اتصال یک کلاینت. .sp تنها تفاوت با متد \fBsocketio.Server.disconnect()\fP \%<#\:socketio\:.Server\:.disconnect> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False) ارسال یک رویداد سفارشی به یک یا چند کلاینت متصل. .sp تنها تفاوت با متد \fBsocketio.Server.emit()\fP \%<#\:socketio\:.Server\:.emit> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B enter_room(sid, room, namespace=None) ورود به یک اتاق. .sp تنها تفاوت با متد \fBsocketio.Server.enter_room()\fP \%<#\:socketio\:.Server\:.enter_room> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B get_session(sid, namespace=None) بازگرداندن نشست کاربر برای یک کلاینت. .sp تنها تفاوت با متد \fBsocketio.Server.get_session()\fP \%<#\:socketio\:.Server\:.get_session> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B leave_room(sid, room, namespace=None) ترک کردن یک اتاق. .sp تنها تفاوت با متد \fBsocketio.Server.leave_room()\fP \%<#\:socketio\:.Server\:.leave_room> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B rooms(sid, namespace=None) بازگرداندن اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد. .sp تنها تفاوت با متد \fBsocketio.Server.rooms()\fP \%<#\:socketio\:.Server\:.rooms> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B save_session(sid, session, namespace=None) ذخیره نشست کاربر برای یک کلاینت. .sp تنها تفاوت با متد \fBsocketio.Server.save_session()\fP \%<#\:socketio\:.Server\:.save_session> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False) ارسال یک پیام به یک یا چند کلاینت متصل. .sp تنها تفاوت با متد \fBsocketio.Server.send()\fP \%<#\:socketio\:.Server\:.send> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B session(sid, namespace=None) بازگرداندن نشست کاربر برای یک کلاینت با نحو مدیر زمینه (context manager). .sp تنها تفاوت با متد \fBsocketio.Server.session()\fP \%<#\:socketio\:.Server\:.session> این است که وقتی آرگومان \fBnamespace\fP داده نشود، از فضای نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0.TP .B trigger_event(event, *args) ارسال یک رخداد به متد گردانندهٔ (handler) مناسب. .sp در متداول‌ترین کاربرد، این متد توسط زیرکلاس‌ها بازنویسی (overload) نمی‌شود، چرا که وظیفهٔ هدایت و توزیع رخدادها به متدها را بر عهده دارد. با این حال، در صورتی که به قواعد توزیع اختصاصی نیاز باشد یا دریافت تمام رخدادها توسط یک متد واحد مد نظر باشد، می‌توان این متد را بازنویسی (override) کرد. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.AsyncClientNamespace(namespace=None) کلاس پایه برای فضاهای‌نام مبتنی بر کلاس سمت کلاینت در asyncio. .sp یک فضای‌نام مبتنی بر کلاس (class\-based namespace)، کلاسی است که شامل تمام گرداننده‌های رخداد برای یک فضای‌نام Socket.IO است. گرداننده‌های رخداد، متدهایی از کلاس با پیشوند \fBon_\fP هستند، مانند \fBon_connect\fP، \fBon_disconnect\fP، \fBon_message\fP، \fBon_json\fP و غیره. این‌ها می‌توانند توابع معمولی یا هم‌روال‌ها (coroutines) باشند. .INDENT 7.0 .TP .B پارامترها (Parameters) \fBnamespace\fP \-\- فضای‌نام Socket.IO برای استفاده با تمامی گرداننده‌های رخداد تعریف‌شده در این کلاس. در صورت حذف این آرگومان، از فضای‌نام پیش‌فرض استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B async call(event, data=None, namespace=None, timeout=None) ارسال یک رخداد سفارشی به سرور و انتظار برای دریافت پاسخ. .sp تنها تفاوت با متد \fBsocketio.Client.call()\fP \%<#\:socketio\:.Client\:.call> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B async disconnect() قطع اتصال کلاینت. .sp تنها تفاوت با متد \fBsocketio.Client.disconnect()\fP \%<#\:socketio\:.Client\:.disconnect> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async emit(event, data=None, namespace=None, callback=None) ارسال یک رخداد سفارشی به سرور. .sp تنها تفاوت با متد \fBsocketio.Client.emit()\fP \%<#\:socketio\:.Client\:.emit> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async send(data, namespace=None, callback=None) ارسال یک پیام به سرور. .sp تنها تفاوت با متد \fBsocketio.Client.send()\fP \%<#\:socketio\:.Client\:.send> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async trigger_event(event, *args) ارسال یک رخداد به متد گردانندهٔ مناسب. .sp در متداول‌ترین کاربرد، این متد توسط زیرکلاس‌ها بازنویسی (overload) نمی‌شود، چرا که وظیفهٔ هدایت رخدادها به متدها را بر عهده دارد. با این حال، در صورتی که به قواعد توزیع اختصاصی نیاز باشد یا دریافت تمام رخدادها در یک متد واحد مد نظر باشد، می‌توان این متد را بازنویسی (override) کرد. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.AsyncNamespace(namespace=None) کلاس پایه برای فضاهای‌نام مبتنی بر کلاس سمت سرور در asyncio. .sp یک فضای‌نام مبتنی بر کلاس، کلاسی است که شامل تمام گرداننده‌های رخداد برای یک فضای‌نام Socket.IO است. گرداننده‌های رخداد، متدهایی از کلاس با پیشوند \fBon_\fP هستند، مانند \fBon_connect\fP، \fBon_disconnect\fP، \fBon_message\fP، \fBon_json\fP و غیره. این‌ها می‌توانند توابع معمولی یا هم‌روال‌ها باشند. .INDENT 7.0 .TP .B پارامترها (Parameters) \fBnamespace\fP \-\- فضای‌نام Socket.IO برای استفاده با تمامی گرداننده‌های رخداد تعریف‌شده در این کلاس. در صورت حذف این آرگومان، از فضای‌نام پیش‌فرض استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B async call(event, data=None, to=None, sid=None, namespace=None, timeout=None, ignore_queue=False) ارسال یک رخداد سفارشی به کلاینت و انتظار برای دریافت پاسخ. .sp تنها تفاوت با متد \fBsocketio.Server.call()\fP \%<#\:socketio\:.Server\:.call> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B async close_room(room, namespace=None) بستن یک اتاق (room). .sp تنها تفاوت با متد \fBsocketio.Server.close_room()\fP \%<#\:socketio\:.Server\:.close_room> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async disconnect(sid, namespace=None) قطع اتصال یک کلاینت. .sp تنها تفاوت با متد \fBsocketio.Server.disconnect()\fP \%<#\:socketio\:.Server\:.disconnect> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False) ارسال یک رخداد سفارشی به یک یا چند کلاینت متصل. .sp تنها تفاوت با متد \fBsocketio.Server.emit()\fP \%<#\:socketio\:.Server\:.emit> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async enter_room(sid, room, namespace=None) ورود به یک اتاق. .sp تنها تفاوت با متد \fBsocketio.Server.enter_room()\fP \%<#\:socketio\:.Server\:.enter_room> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async get_session(sid, namespace=None) بازگرداندن نشست (session) کاربر برای یک کلاینت. .sp تنها تفاوت با متد \fBsocketio.Server.get_session()\fP \%<#\:socketio\:.Server\:.get_session> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async leave_room(sid, room, namespace=None) خروج از یک اتاق. .sp تنها تفاوت با متد \fBsocketio.Server.leave_room()\fP \%<#\:socketio\:.Server\:.leave_room> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B rooms(sid, namespace=None) بازگرداندن اتاق‌هایی که کلاینت در آن‌ها عضو است. .sp تنها تفاوت با متد \fBsocketio.Server.rooms()\fP \%<#\:socketio\:.Server\:.rooms> این است که اگر آرگومان \fBnamespace\fP داده نشود، از فضای‌نام مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0.TP .B async save_session(sid, session, namespace=None) ذخیره نشست کاربر برای یک کلاینت. .sp تنها تفاوت با متد \fBsocketio.Server.save_session()\fP \%<#\:socketio\:.Server\:.save_session> در این است که اگر آرگومان \fBnamespace\fP مشخص نشود، از namespace مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک coroutine است. .UNINDENT .INDENT 7.0 .TP .B async send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False) ارسال یک پیام به یک یا چند کلاینت متصل. .sp تنها تفاوت با متد \fBsocketio.Server.send()\fP \%<#\:socketio\:.Server\:.send> در این است که اگر آرگومان \fBnamespace\fP مشخص نشود، از namespace مرتبط با کلاس استفاده می‌شود. .sp نکته: این متد یک coroutine است. .UNINDENT .INDENT 7.0 .TP .B session(sid, namespace=None) بازگرداندن نشست کاربر برای یک کلاینت با نحو context manager. .sp تنها تفاوت با متد \fBsocketio.Server.session()\fP \%<#\:socketio\:.Server\:.session> در این است که اگر آرگومان \fBnamespace\fP مشخص نشود، از namespace مرتبط با کلاس استفاده می‌شود. .UNINDENT .INDENT 7.0 .TP .B async trigger_event(event, *args) ارسال رویداد به متد گرداننده (handler) مناسب. .sp در رایج‌ترین کاربرد، این متد توسط زیرکلاس‌ها بازنویسی (overload) نمی‌شود، زیرا مسیریابی رویدادها به متدها را انجام می‌دهد. با این حال، اگر به قواعد توزیع ویژه‌ای نیاز باشد یا وجود یک متد واحد که تمام رویدادها را دریافت کند مطلوب باشد، این متد قابل رونویسی (override) است. .sp نکته: این متد یک coroutine است. .UNINDENT .UNINDENT .SS مدیرها (Managers) .INDENT 0.0 .TP .B class socketio.Manager مدیریت اتصالات کلاینت‌ها. .sp این کلاس تمام کلاینت‌ها و اتاق‌هایی را که در آن‌ها حضور دارند ردیابی می‌کند تا از انتشار (broadcasting) پیام‌ها پشتیبانی کند. داده‌های مورد استفاده این کلاس در یک ساختار حافظه‌ای ذخیره می‌شوند، که آن را تنها برای سرویس‌های تک‌پردازشی مناسب می‌سازد. زیرکلاس‌ها می‌توانند پس‌اندهای ذخیره‌سازی پیشرفته‌تری را پیاده‌سازی کنند. .INDENT 7.0 .TP .B close_room(room, namespace) حذف تمام شرکت‌کنندگان از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B connect(eio_sid, namespace) ثبت اتصال یک کلاینت به یک namespace. .UNINDENT .INDENT 7.0 .TP .B disconnect(sid, namespace, **kwargs) ثبت قطع اتصال یک کلاینت از یک namespace. .UNINDENT .INDENT 7.0 .TP .B emit(event, data, namespace, room=None, skip_sid=None, callback=None, to=None, **kwargs) ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمام کلاینت‌های متصل به namespace. .UNINDENT .INDENT 7.0 .TP .B enter_room(sid, namespace, room, eio_sid=None) افزودن یک کلاینت به یک اتاق. .UNINDENT .INDENT 7.0 .TP .B get_namespaces() بازگرداندن یک شئ پیمایش‌پذیر (iterable) شامل نام‌های namespace فعال. .UNINDENT .INDENT 7.0 .TP .B get_participants(namespace, room) بازگرداندن یک شئ پیمایش‌پذیر (iterable) از شرکت‌کنندگان فعال در یک اتاق. .sp توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به سروری که متد در آن فراخوانی شده متصل هستند. در حال حاضر قابلیتی برای جمع‌آوری فهرست کاملی از کاربران در میان چندین سرور وجود ندارد. .UNINDENT .INDENT 7.0 .TP .B get_rooms(sid, namespace) بازگرداندن اتاق‌هایی که کلاینت در آن‌ها حضور دارد. .UNINDENT .INDENT 7.0 .TP .B initialize() پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد مقداردهی اولیه خود را در اینجا اضافه کنند. .UNINDENT .INDENT 7.0 .TP .B leave_room(sid, namespace, room) حذف یک کلاینت از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B pre_disconnect(sid, namespace) قرار دادن کلاینت در فهرست در شرف قطع اتصال (to\-be\-disconnected). .sp این امر به ساختارهای داده کلاینت اجازه می‌دهد هنگام فراخوانی گرداننده قطع اتصال همچنان حضور داشته باشند، در عین حال این واقعیت را مشخص می‌کند که کلاینت به‌زودی خارج خواهد شد. .UNINDENT .INDENT 7.0 .TP .B trigger_callback(sid, id, data) فراخوانی یک callback برنامه. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.PubSubManager(channel=\(aqsocketio\(aq, write_only=False, logger=None, json=None) مدیریت فهرست کلاینت‌های متصل به یک پس‌اند pub/sub. .sp این یک کلاس پایه است که به چندین سرور امکان می‌دهد فهرست کلاینت‌ها را به اشتراک بگذارند، در حالی که سرورها رویدادها را از طریق یک پس‌اند pub/sub تبادل می‌کنند. استفاده از یک پس‌اند pub/sub همچنین به هر کلاینت متصل به پس‌اند اجازه می‌دهد رویدادهایی خطاب به کلاینت‌های Socket.IO ارسال کند. .sp پس‌آیندهای واقعی باید توسط زیرکلاس‌ها پیاده‌سازی شوند؛ این کلاس تنها یک چارچوب عمومی pub/sub ارائه می‌دهد. .INDENT 7.0 .TP .B پارامترها (Parameters) .INDENT 7.0 .IP \(bu 2 \fBchannel\fP \-\- نام کانالی که سرور اعلان‌ها را روی آن ارسال و دریافت می‌کند. .IP \(bu 2 \fBwrite_only\fP \-\- در صورت تنظیم روی \fBTrue\fP، تنها برای ارسال (emit) رویدادها مقداردهی اولیه می‌شود. مقدار پیش‌فرض \fBFalse\fP کلاس را برای ارسال و دریافت مقداردهی اولیه می‌کند. یک نمونه write\-only می‌تواند به صورت مستقل از سرور برای ارسال رویداد به کلاینت‌ها از یک فرایند خارجی استفاده شود. .IP \(bu 2 \fBlogger\fP \-\- یک لاگر سفارشی برای ثبت رویدادها. اگر مشخص نشود، از لاگر سرور استفاده می‌شود. .IP \(bu 2 \fBjson\fP \-\- یک ماژول JSON جایگزین برای استفاده در کدگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که \fBwrite_only\fP روی \fBTrue\fP\& تنظیم شده باشد. در غیر این صورت، از ماژول JSON پیکربندی‌شده در سرور استفاده می‌شود. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B close_room(room, namespace=None) حذف تمام شرکت‌کنندگان از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B connect(eio_sid, namespace) ثبت اتصال یک کلاینت به یک namespace. .UNINDENT .INDENT 7.0 .TP .B disconnect(sid, namespace=None, **kwargs) ثبت قطع اتصال یک کلاینت از یک namespace. .UNINDENT .INDENT 7.0 .TP .B emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs) ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمام کلاینت‌های متصل به namespace..sp این متد وظیفه انتشار پیام به تمامی سرورهایی که از طریق صف پیام متصل هستند را بر عهده دارد. .sp پارامترها همانند \fBServer.emit()\fP \%<#\:socketio\:.Server\:.emit>\& هستند. .UNINDENT .INDENT 7.0 .TP .B enter_room(sid, namespace, room, eio_sid=None) افزودن یک کلاینت به یک اتاق. .UNINDENT .INDENT 7.0 .TP .B get_namespaces() یک iterable از نام‌های namespace فعال را بازمی‌گرداند. .UNINDENT .INDENT 7.0 .TP .B get_participants(namespace, room) یک iterable از شرکت‌کنندگان فعال در یک اتاق را بازمی‌گرداند. .sp توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به سروری که متد در آن فراخوانی شده است متصل باشند. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین سرور وجود ندارد. .UNINDENT .INDENT 7.0 .TP .B get_rooms(sid, namespace) اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد را بازمی‌گرداند. .UNINDENT .INDENT 7.0 .TP .B initialize() پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد راه‌اندازی اولیه خود را در اینجا اضافه کنند. .UNINDENT .INDENT 7.0 .TP .B leave_room(sid, namespace, room) حذف یک کلاینت از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B pre_disconnect(sid, namespace) کلاینت را در فهرست در\-انتظار\-قطع\-اتصال قرار می‌دهد. .sp این کار اجازه می‌دهد ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع ارتباط (disconnect handler) همچنان موجود باشند، اما با این وجود این واقعیت که کلاینت به‌زودی خارج خواهد شد نیز لحاظ گردد. .UNINDENT .INDENT 7.0 .TP .B trigger_callback(sid, id, data) یک callback برنامه را فراخوانی می‌کند. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.KombuManager(url=\(aqamqp://guest:guest@localhost:5672//\(aq, channel=\(aqsocketio\(aq, write_only=False, logger=None, json=None, connection_options=None, exchange_options=None, queue_options=None, producer_options=None) مدیر کلاینت که از kombu برای پیام‌رسانی بین‌فرایندی استفاده می‌کند. .sp این کلاس یک backend مدیریت کلاینت را برای به‌اشتراک‌گذاری رویدادها میان چندین فرایند، با استفاده از RabbitMQ، Redis یا هر سازوکار پیام‌رسانی دیگر پشتیبانی‌شده توسط kombu \%\& پیاده‌سازی می‌کند. .sp برای استفاده از یک backend از نوع kombu، نمونه \fBServer\fP \%<#\:socketio\:.Server> را به‌صورت زیر مقداردهی اولیه کنید: .INDENT 7.0 .INDENT 3.5 .sp .EX url = \(aqamqp://user:password@hostname:port//\(aq server = socketio.Server(client_manager=socketio.KombuManager(url)) .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی URL اتصال برای صف پیام‌رسانی backend. نمونه‌های URL اتصال عبارت‌اند از \fB\(aqamqp://guest:guest@localhost:5672//\(aq\fP و \fB\(aqredis://localhost:6379/\(aq\fP به ترتیب برای RabbitMQ و Redis. برای اطلاعات بیشتر درباره چگونگی ساخت URLهای اتصال، به مستندات kombu \% مراجعه کنید. .IP \(bu 2 \fBchannel\fP \-\- نام کانالی که سرور روی آن اعلان‌ها را ارسال و دریافت می‌کند. باید در تمام سرورها یکسان باشد. .IP \(bu 2 \fBwrite_only\fP \-\- اگر روی \fBTrue\fP تنظیم شود، تنها برای ارسال (emit) رویدادها راه‌اندازی می‌شود. مقدار پیش‌فرض \fBFalse\fP کلاس را برای ارسال و دریافت مقداردهی می‌کند. یک نمونه write\-only می‌تواند مستقل از سرور برای ارسال رویدادها به کلاینت‌ها از طریق یک فرایند خارجی استفاده شود. .IP \(bu 2 \fBlogger\fP \-\- یک ثبت‌کننده وقایع (logger) سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از logger سرور استفاده می‌شود. .IP \(bu 2 \fBjson\fP \-\- یک ماژول جایگزین JSON جهت استفاده برای کدگذاری و کدگشایی بسته‌ها. ماژول‌های json سفارشی باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی استفاده می‌شود که \fBwrite_only\fP روی \fBTrue\fP تنظیم شده باشد؛ در غیر این صورت از ماژول JSON پیکربندی‌شده در سرور استفاده می‌شود. .IP \(bu 2 \fBconnection_options\fP \-\- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به \fBkombu.Connection()\fP\&. .IP \(bu 2 \fBexchange_options\fP \-\- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به \fBkombu.Exchange()\fP\&. .IP \(bu 2 \fBqueue_options\fP \-\- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به \fBkombu.Queue()\fP\&. .IP \(bu 2 \fBproducer_options\fP \-\- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به \fBkombu.Producer()\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B close_room(room, namespace=None) حذف تمام شرکت‌کنندگان از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B connect(eio_sid, namespace) ثبت اتصال یک کلاینت به یک namespace. .UNINDENT .INDENT 7.0 .TP .B disconnect(sid, namespace=None, **kwargs) ثبت قطع اتصال یک کلاینت از یک namespace. .UNINDENT .INDENT 7.0 .TP .B emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs) ارسال یک پیام به یک کلاینت منفرد، یک اتاق، یا تمامی کلاینت‌های متصل به namespace. .sp این متد وظیفه انتشار پیام به تمامی سرورهایی که از طریق صف پیام متصل هستند را بر عهده دارد. .sp پارامترها همانند \fBServer.emit()\fP \%<#\:socketio\:.Server\:.emit>\& هستند. .UNINDENT .INDENT 7.0 .TP .B enter_room(sid, namespace, room, eio_sid=None) افزودن یک کلاینت به یک اتاق. .UNINDENT .INDENT 7.0 .TP .B get_namespaces() یک iterable از نام‌های namespace فعال را بازمی‌گرداند. .UNINDENT .INDENT 7.0 .TP .B get_participants(namespace, room) یک iterable از شرکت‌کنندگان فعال در یک اتاق را بازمی‌گرداند. .sp توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به سروری که متد در آن فراخوانی شده است متصل باشند. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین سرور وجود ندارد. .UNINDENT .INDENT 7.0 .TP .B get_rooms(sid, namespace) اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد را بازمی‌گرداند. .UNINDENT .INDENT 7.0 .TP .B initialize() پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد راه‌اندازی اولیه خود را در اینجا اضافه کنند. .UNINDENT .INDENT 7.0 .TP .B leave_room(sid, namespace, room) حذف یک کلاینت از یک اتاق. .UNINDENT .INDENT 7.0.TP .B pre_disconnect(sid, namespace) قرار دادن کلاینت در فهرست در\-شرف\-قطع ارتباط. .sp این امکان را فراهم می‌کند که ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع ارتباط (disconnect handler) حضور داشته باشند، ولی در عین حال مشخص باشد که کلاینت به‌زودی خارج خواهد شد. .UNINDENT .INDENT 7.0 .TP .B trigger_callback(sid, id, data) فراخوانی یک کال‌بک (callback) برنامه کاربردی. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.RedisManager(url=\(aqredis://localhost:6379/0\(aq, channel=\(aqsocketio\(aq, write_only=False, logger=None, json=None, redis_options=None) مدیر کلاینت مبتنی بر Redis. .sp این کلاس یک پس‌بخش (backend) مبتنی بر Redis را برای هم‌رسانی رویدادها در چندین فرآیند پیاده‌سازی می‌کند. این بخش صرفاً به عنوان نمونه دیگری از نحوه ساخت یک پس‌بخش سفارشی در اینجا نگه داشته شده است، چرا که پس‌بخش kombu برای پشتیبانی از یک صف پیام Redis کاملاً مناسب و کافی است. .sp برای استفاده از یک پس‌بخش Redis، نمونه \fBServer\fP \%<#\:socketio\:.Server> را به صورت زیر مقداردهی اولیه کنید: .INDENT 7.0 .INDENT 3.5 .sp .EX url = \(aqredis://hostname:port/0\(aq server = socketio.Server(client_manager=socketio.RedisManager(url)) .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی اینترنتی (URL) اتصال برای سرور Redis. برای یک ذخیره‌ساز پیش‌فرض Redis که بر روی همان میزبان اجرا می‌شود، از \fBredis://\fP\& استفاده کنید. برای استفاده از یک اتصال TLS، از \fBrediss://\fP\& استفاده کنید. برای استفاده از Redis Sentinel، از \fBredis+sentinel://\fP به همراه فهرستی از میزبان‌ها که با ویرگول از هم جدا شده‌اند و نام سرویس پس از db در مسیر URL استفاده کنید. مثال: \fBredis+sentinel://user:pw@host1:1234,host2:2345/0/myredis\fP\&. .IP \(bu 2 \fBchannel\fP \-\- نام کانالی که سرور اعلان‌ها را در آن ارسال و دریافت می‌کند. باید در تمام سرورها یکسان باشد. .IP \(bu 2 \fBwrite_only\fP \-\- در صورت تنظیم روی \fBTrue\fP، تنها برای انتشار رویدادها مقداردهی اولیه می‌شود. مقدار پیش‌فرض \fBFalse\fP کلاس را برای ارسال و دریافت مقداردهی اولیه می‌کند. یک نمونه فقط\-نوشتنی (write\-only) می‌تواند به صورت مستقل از سرور برای ارسال به کلاینت‌ها از طریق یک فرآیند خارجی مورد استفاده قرار گیرد. .IP \(bu 2 \fBlogger\fP \-\- یک ثبت‌کننده وقایع (logger) سفارشی برای ثبت آن. در صورت مشخص نشدن، از logger سرور استفاده می‌شود. .IP \(bu 2 \fBjson\fP \-\- یک ماژول جایگزین JSON جهت استفاده برای رمزگذاری و رمزگشایی بسته‌ها. ماژول‌های json سفارشی باید توابع \fBdumps\fP و \fBloads\fP را داشته باشند که با نسخه‌های کتابخانه استاندارد سازگار باشند. این تنظیم تنها زمانی اعمال می‌شود که \fBwrite_only\fP روی \fBTrue\fP تنظیم شده باشد\&. در غیر این صورت از ماژول JSON پیکربندی‌شده در سرور استفاده می‌شود. .IP \(bu 2 \fBredis_options\fP \-\- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به \fBRedis.from_url()\fP یا \fBSentinel()\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B close_room(room, namespace=None) حذف تمام شرکت‌کنندگان از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B connect(eio_sid, namespace) ثبت اتصال یک کلاینت به یک namespace. .UNINDENT .INDENT 7.0 .TP .B disconnect(sid, namespace=None, **kwargs) ثبت قطع ارتباط یک کلاینت از یک namespace. .UNINDENT .INDENT 7.0 .TP .B emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs) انتشار یک پیام به یک کلاینت واحد، یک اتاق، یا تمامی کلاینت‌های متصل به namespace. .sp این متد وظیفه بازپخش پیام به تمامی سرورهایی که از طریق صف پیام متصل هستند را بر عهده دارد. .sp پارامترها همانند پارامترهای موجود در \fBServer.emit()\fP \%<#\:socketio\:.Server\:.emit> هستند\&. .UNINDENT .INDENT 7.0 .TP .B enter_room(sid, namespace, room, eio_sid=None) افزودن یک کلاینت به یک اتاق. .UNINDENT .INDENT 7.0 .TP .B get_namespaces() بازگرداندن یک پیمایش‌پذیر (iterable) شامل نام‌های namespace فعال. .UNINDENT .INDENT 7.0 .TP .B get_participants(namespace, room) بازگرداندن یک پیمایش‌پذیر (iterable) شامل شرکت‌کنندگان فعال در یک اتاق. .sp توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگان متصل به همان سروری را بازمی‌گرداند که متد در آن فراخوانی شده است. در حال حاضر قابلیتی برای گردآوری فهرست کاملی از کاربران در میان چندین سرور وجود ندارد. .UNINDENT .INDENT 7.0 .TP .B get_rooms(sid, namespace) بازگرداندن اتاق‌هایی که کلاینت در آن‌ها حضور دارد. .UNINDENT .INDENT 7.0 .TP .B initialize() پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کدهای مقداردهی اولیه خود را در اینجا اضافه کنند. .UNINDENT .INDENT 7.0 .TP .B leave_room(sid, namespace, room) خارج کردن یک کلاینت از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B pre_disconnect(sid, namespace) قرار دادن کلاینت در فهرست در\-شرف\-قطع ارتباط. .sp این امکان را فراهم می‌کند که ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع ارتباط حضور داشته باشند، ولی در عین حال مشخص باشد که کلاینت به‌زودی خارج خواهد شد. .UNINDENT .INDENT 7.0 .TP .B trigger_callback(sid, id, data) فراخوانی یک کال‌بک (callback) برنامه کاربردی. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.KafkaManager(url=\(aqkafka://localhost:9092\(aq, channel=\(aqsocketio\(aq, write_only=False, logger=None, json=None) مدیر کلاینت مبتنی بر Kafka. .sp این کلاس یک پس‌بخش (backend) مبتنی بر Kafka را برای هم‌رسانی رویدادها در میان چندین فرآیند پیاده‌سازی می‌کند. .sp برای استفاده از یک پس‌بخش Kafka، نمونه \fBServer\fP \%<#\:socketio\:.Server> را به صورت زیر مقداردهی اولیه کنید: .INDENT 7.0 .INDENT 3.5 .sp .EX url = \(aqkafka://hostname:port\(aq server = socketio.Server(client_manager=socketio.KafkaManager(url)) .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B پارامترها .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی اینترنتی (URL) اتصال برای سرور Kafka. برای یک ذخیره‌ساز پیش‌فرض Kafka که بر روی همان میزبان اجرا می‌شود، از \fBkafka://\fP\& استفاده کنید. برای یک استقرار با دسترسی‌پذیری بالا (high availability) از Kafka، فهرستی شامل تمامی URLهای اتصال موجود در کلاستر خود را ارسال کنید. .IP \(bu 2 \fBchannel\fP \-\- نام کانال (topic) که سرور اعلان‌ها را در آن ارسال و دریافت می‌کند. باید در تمامی سرورها یکسان باشد. .IP \(bu 2 \fBwrite_only\fP \-\- در صورت تنظیم روی \fBTrue\fP، تنها برای انتشار رویدادها مقداردهی اولیه می‌شود. مقدار پیش‌فرض \fBFalse\fP کلاس را برای ارسال و دریافت مقداردهی اولیه می‌کند. یک نمونه فقط\-نوشتنی (write\-only) می‌تواند به صورت مستقل از سرور برای ارسال به کلاینت‌ها از طریق یک فرآیند خارجی مورد استفاده قرار گیرد..IP \(bu 2 \fBlogger\fP \-\- یک ثبت‌کننده وقایع (logger) سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از ثبت‌کننده وقایع سرور استفاده می‌شود. .IP \(bu 2 \fBjson\fP \-\- یک ماژول JSON جایگزین برای استفاده در رمزگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که \fBwrite_only\fP بر روی \fBTrue\fP تنظیم شده باشد\&. در غیر این صورت از ماژول JSON پیکربندی‌شده در سرور استفاده می‌شود. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B close_room(room, namespace=None) حذف تمام شرکت‌کنندگان از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B connect(eio_sid, namespace) ثبت اتصال یک کلاینت به یک namespace. .UNINDENT .INDENT 7.0 .TP .B disconnect(sid, namespace=None, **kwargs) ثبت قطع اتصال یک کلاینت از یک namespace. .UNINDENT .INDENT 7.0 .TP .B emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs) ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمام کلاینت‌های متصل به namespace. .sp این متد وظیفه انتشار پیام به تمام سرورهایی که از طریق صف پیام متصل هستند را بر عهده دارد. .sp پارامترها مشابه پارامترهای متد \fBServer.emit()\fP \%<#\:socketio\:.Server\:.emit>\& هستند. .UNINDENT .INDENT 7.0 .TP .B enter_room(sid, namespace, room, eio_sid=None) افزودن یک کلاینت به یک اتاق. .UNINDENT .INDENT 7.0 .TP .B get_namespaces() بازگرداندن یک تکرارپذیر (iterable) شامل نام‌های namespace فعال. .UNINDENT .INDENT 7.0 .TP .B get_participants(namespace, room) بازگرداندن یک تکرارپذیر شامل شرکت‌کنندگان فعال در یک اتاق. .sp توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به سروری که متد در آن فراخوانی شده متصل هستند. در حال حاضر قابلیتی برای جمع‌آوری فهرست کامل کاربران در چندین سرور وجود ندارد. .UNINDENT .INDENT 7.0 .TP .B get_rooms(sid, namespace) بازگرداندن اتاق‌هایی که کلاینت در آن‌ها حضور دارد. .UNINDENT .INDENT 7.0 .TP .B initialize() پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد مقداردهی اولیه خود را در اینجا اضافه کنند. .UNINDENT .INDENT 7.0 .TP .B leave_room(sid, namespace, room) خارج کردن یک کلاینت از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B pre_disconnect(sid, namespace) قرار دادن کلاینت در فهرست در شرف قطع اتصال (to\-be\-disconnected). .sp این کار اجازه می‌دهد تا ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع اتصال (disconnect handler) همچنان در دسترس باشند، اما در عین حال این واقعیت که کلاینت به‌زودی قطع خواهد شد نیز مشخص باشد. .UNINDENT .INDENT 7.0 .TP .B trigger_callback(sid, id, data) فراخوانی یک بازفراخوانی (callback) برنامه. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.ZmqManager(url=\(aqzmq+tcp://localhost:5555+5556\(aq, channel=\(aqsocketio\(aq, write_only=False, logger=None, json=None) مدیر کلاینت مبتنی بر zmq. .sp نکته: این پیاده‌سازی zmq در حال حاضر باید به‌صورت آزمایشی در نظر گرفته شود. در حال حاضر، برای استفاده از zmq به eventlet نیاز است. .sp این کلاس یک پس‌بخش zmq را برای اشتراک‌گذاری رویدادها میان چندین پردازه پیاده‌سازی می‌کند. برای استفاده از پس‌بخش zmq، نمونه \fBServer\fP \%<#\:socketio\:.Server> را به‌صورت زیر مقداردهی اولیه کنید: .INDENT 7.0 .INDENT 3.5 .sp .EX url = \(aqzmq+tcp://hostname:port1+port2\(aq server = socketio.Server(client_manager=socketio.ZmqManager(url)) .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B پارامترها (Parameters) .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی اینترنتی (URL) اتصال برای کارگزار پیام zmq که باید فراهم شده و در حال اجرا باشد. .IP \(bu 2 \fBchannel\fP \-\- نام کانالی که سرور اعلان‌ها را روی آن ارسال و دریافت می‌کند. باید در تمام سرورها یکسان باشد. .IP \(bu 2 \fBwrite_only\fP \-\- در صورت تنظیم روی \fBTrue\fP، تنها برای ارسال رویدادها راه‌اندازی می‌شود. مقدار پیش‌فرض \fBFalse\fP کلاس را برای ارسال و دریافت مقداردهی اولیه می‌کند. یک نمونه فقط‌نوشتنی را می‌توان به‌صورت مستقل از سرور برای ارسال به کلاینت‌ها از یک پردازه خارجی استفاده کرد. .IP \(bu 2 \fBlogger\fP \-\- یک ثبت‌کننده وقایع سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از ثبت‌کننده وقایع سرور استفاده می‌شود. .IP \(bu 2 \fBjson\fP \-\- یک ماژول JSON جایگزین برای استفاده در رمزگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که \fBwrite_only\fP بر روی \fBTrue\fP تنظیم شده باشد\&. در غیر این صورت از ماژول JSON پیکربندی‌شده در سرور استفاده می‌شود. .UNINDENT .UNINDENT .sp برای کارکرد zmq_manager، یک کارگزار پیام (message broker) zmq باید در حال اجرا باشد. می‌توانید کارگزار خود را بنویسید یا کارگزار ساده زیر را تطبیق دهید: .INDENT 7.0 .INDENT 3.5 .sp .EX import zmq receiver = zmq.Context().socket(zmq.PULL) receiver.bind(\(dqtcp://*:5555\(dq) publisher = zmq.Context().socket(zmq.PUB) publisher.bind(\(dqtcp://*:5556\(dq) while True: publisher.send(receiver.recv()) .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B close_room(room, namespace=None) حذف تمام شرکت‌کنندگان از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B connect(eio_sid, namespace) ثبت اتصال یک کلاینت به یک namespace. .UNINDENT .INDENT 7.0 .TP .B disconnect(sid, namespace=None, **kwargs) ثبت قطع اتصال یک کلاینت از یک namespace. .UNINDENT .INDENT 7.0 .TP .B emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs) ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمام کلاینت‌های متصل به namespace. .sp این متد وظیفه انتشار پیام به تمام سرورهایی که از طریق صف پیام متصل هستند را بر عهده دارد..sp پارامترها همانند \fBServer.emit()\fP \%<#\:socketio\:.Server\:.emit>\& هستند. .UNINDENT .INDENT 7.0 .TP .B enter_room(sid, namespace, room, eio_sid=None) افزودن یک کلاینت به یک اتاق. .UNINDENT .INDENT 7.0 .TP .B get_namespaces() بازگرداندن یک تکرارپذیر (iterable) شامل نام‌های فضاهای نام فعال. .UNINDENT .INDENT 7.0 .TP .B get_participants(namespace, room) بازگرداندن یک تکرارپذیر شامل شرکت‌کنندگان فعال در یک اتاق. .sp توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به همان سروری که متد در آن فراخوانی شده متصل هستند. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین سرور وجود ندارد. .UNINDENT .INDENT 7.0 .TP .B get_rooms(sid, namespace) بازگرداندن اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد. .UNINDENT .INDENT 7.0 .TP .B initialize() پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد مقداردهی اولیه خود را در اینجا اضافه کنند. .UNINDENT .INDENT 7.0 .TP .B leave_room(sid, namespace, room) حذف یک کلاینت از یک اتاق. .UNINDENT .INDENT 7.0 .TP .B pre_disconnect(sid, namespace) قراردادن کلاینت در فهرست در انتظار قطع اتصال (to\-be\-disconnected). .sp این کار به ساختارهای داده کلاینت اجازه می‌دهد هنگام فراخوانی گرداننده قطع اتصال (disconnect handler) همچنان حضور داشته باشند، در حالی که همچنان این واقعیت را تشخیص می‌دهد که کلاینت به‌زودی خارج خواهد شد. .UNINDENT .INDENT 7.0 .TP .B trigger_callback(sid, id, data) فراخوانی یک بازخورد (callback) برنامه. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.AsyncManager مدیریت فهرست کلاینت‌ها برای یک سرور asyncio. .INDENT 7.0 .TP .B async close_room(room, namespace) حذف تمام شرکت‌کنندگان از یک اتاق. .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async connect(eio_sid, namespace) ثبت اتصال یک کلاینت به یک فضای نام. .sp نکته: این متد یک کوروتین است. .UNINDENT .INDENT 7.0 .TP .B async disconnect(sid, namespace, **kwargs) قطع اتصال یک کلاینت. .sp نکته: این متد یک کوروتین است. .UNINDENT .INDENT 7.0 .TP .B async emit(event, data, namespace, room=None, skip_sid=None, callback=None, to=None, **kwargs) ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمامی کلاینت‌های متصل به فضای نام. .sp نکته: این متد یک کوروتین است. .UNINDENT .INDENT 7.0 .TP .B async enter_room(sid, namespace, room, eio_sid=None) افزودن یک کلاینت به یک اتاق. .sp نکته: این متد یک کوروتین است. .UNINDENT .INDENT 7.0 .TP .B get_namespaces() بازگرداندن یک تکرارپذیر شامل نام‌های فضاهای نام فعال. .UNINDENT .INDENT 7.0 .TP .B get_participants(namespace, room) بازگرداندن یک تکرارپذیر شامل شرکت‌کنندگان فعال در یک اتاق. .sp توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به همان سروری که متد در آن فراخوانی شده متصل هستند. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین سرور وجود ندارد. .UNINDENT .INDENT 7.0 .TP .B get_rooms(sid, namespace) بازگرداندن اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد. .UNINDENT .INDENT 7.0 .TP .B initialize() پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد مقداردهی اولیه خود را در اینجا اضافه کنند. .UNINDENT .INDENT 7.0 .TP .B async leave_room(sid, namespace, room) حذف یک کلاینت از یک اتاق. .sp نکته: این متد یک کوروتین است. .UNINDENT .INDENT 7.0 .TP .B pre_disconnect(sid, namespace) قراردادن کلاینت در فهرست در انتظار قطع اتصال. .sp این کار به ساختارهای داده کلاینت اجازه می‌دهد هنگام فراخوانی گرداننده قطع اتصال همچنان حضور داشته باشند، در حالی که همچنان این واقعیت را تشخیص می‌دهد که کلاینت به‌زودی خارج خواهد شد. .UNINDENT .INDENT 7.0 .TP .B async trigger_callback(sid, id, data) فراخوانی یک بازخورد برنامه. .sp نکته: این متد یک کوروتین است. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.AsyncRedisManager(url=\(aqredis://localhost:6379/0\(aq, channel=\(aqsocketio\(aq, write_only=False, logger=None, json=None, redis_options=None) مدیر کلاینت مبتنی بر Redis برای سرورهای asyncio. .sp این کلاس یک بک‌اند Redis را برای به‌اشتراک‌گذاری رویدادها بین چندین فرآیند پیاده‌سازی می‌کند. .sp برای استفاده از یک بک‌اند Redis، نمونه \fBAsyncServer\fP \%<#\:socketio\:.AsyncServer> را به صورت زیر مقداردهی اولیه کنید: .INDENT 7.0 .INDENT 3.5 .sp .EX url = \(aqredis://hostname:port/0\(aq server = socketio.AsyncServer( client_manager=socketio.AsyncRedisManager(url)) .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B پارامترها (Parameters) .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی وب (URL) اتصال برای سرور Redis. برای یک ذخیره‌ساز پیش‌فرض Redis که روی همان میزبان اجرا می‌شود، از \fBredis://\fP\& استفاده کنید. برای استفاده از یک اتصال TLS، از \fBrediss://\fP\& استفاده کنید. برای استفاده از Redis Sentinel، از \fBredis+sentinel://\fP به همراه فهرستی از میزبان‌ها که با ویرگول از یکدیگر جدا شده‌اند و نام سرویس پس از db در مسیر URL استفاده کنید. مثال: \fBredis+sentinel://user:pw@host1:1234,host2:2345/0/myredis\fP\&. .IP \(bu 2 \fBchannel\fP \-\- نام کانالی که سرور در آن اعلان‌ها را ارسال و دریافت می‌کند. باید در تمامی سرورها یکسان باشد. .IP \(bu 2 \fBwrite_only\fP \-\- در صورت تنظیم روی \fBTrue\fP، تنها برای ارسال (emit) رویدادها مقداردهی اولیه می‌شود. مقدار پیش‌فرض \fBFalse\fP کلاس را هم برای ارسال و هم برای دریافت مقداردهی می‌کند. یک نمونه فقط‌نوشتنی (write\-only) می‌تواند مستقل از سرور برای ارسال به کلاینت‌ها از طریق یک فرآیند خارجی استفاده شود..IP \(bu 2 \fBlogger\fP \-\- یک logger سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از logger کارساز استفاده می‌شود. .IP \(bu 2 \fBjson\fP \-\- یک پودمان JSON جایگزین برای رمزگذاری و رمزگشایی بسته‌ها. پودمان‌های سفارشی json باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که \fBwrite_only\fP روی \fBTrue\fP تنظیم شده باشد\&. در غیر این صورت، از پودمان JSON پیکربندی‌شده در کارساز استفاده می‌شود. .IP \(bu 2 \fBredis_options\fP \-\- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به \fBRedis.from_url()\fP یا \fBSentinel()\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B async close_room(room, namespace=None) حذف تمامی شرکت‌کنندگان از یک اتاق. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async connect(eio_sid, namespace) ثبت اتصال یک کلاینت به یک namespace. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async disconnect(sid, namespace, **kwargs) قطع اتصال یک کلاینت. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs) ارسال یک پیام به یک کلاینت منفرد، یک اتاق یا تمامی کلاینت‌های متصل به namespace. .sp این متد وظیفه انتشار پیام به تمامی کارسازهایی که از طریق صف پیام متصل هستند را بر عهده دارد. .sp پارامترها همانند متد \fBServer.emit()\fP \%<#\:socketio\:.Server\:.emit>\& هستند. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async enter_room(sid, namespace, room, eio_sid=None) افزودن یک کلاینت به یک اتاق. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B get_namespaces() بازگرداندن یک شیء پیمایش‌پذیر (iterable) با نام‌های namespace فعال. .UNINDENT .INDENT 7.0 .TP .B get_participants(namespace, room) بازگرداندن یک شیء پیمایش‌پذیر با شرکت‌کنندگان فعال در یک اتاق. .sp توجه داشته باشید که در سناریوی چندکارسازی (multi\-server) این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به کارسازی که متد در آن فراخوانی شده متصل هستند. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین کارساز وجود ندارد. .UNINDENT .INDENT 7.0 .TP .B get_rooms(sid, namespace) بازگرداندن اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد. .UNINDENT .INDENT 7.0 .TP .B initialize() پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد مقداردهی اولیه خود را در اینجا اضافه کنند. .UNINDENT .INDENT 7.0 .TP .B async leave_room(sid, namespace, room) حذف یک کلاینت از یک اتاق. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B pre_disconnect(sid, namespace) قرار دادن کلاینت در فهرست در\-انتظار\-قطع\-اتصال. .sp این کار اجازه می‌دهد که ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع اتصال حضور داشته باشند، اما همچنان این واقعیت را مشخص می‌کند که کلاینت به‌زودی خارج خواهد شد. .UNINDENT .INDENT 7.0 .TP .B async trigger_callback(sid, id, data) فراخوانی یک تابع بازگشتی (callback) برنامه. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class socketio.AsyncAioPikaManager(url=\(aqamqp://guest:guest@localhost:5672//\(aq, channel=\(aqsocketio\(aq, write_only=False, logger=None, json=None) مدیر کلاینتی که از aio_pika برای پیام‌رسانی بین‌فرایندی تحت asyncio استفاده می‌کند. .sp این کلاس یک پسانه مدیر کلاینت را برای همرسانی رویدادها میان چندین فرایند با استفاده از RabbitMQ پیاده‌سازی می‌کند. .sp برای استفاده از پسانه aio_pika، نمونه \fBServer\fP \%<#\:socketio\:.Server> را به‌صورت زیر مقداردهی اولیه کنید: .INDENT 7.0 .INDENT 3.5 .sp .EX url = \(aqamqp://user:password@hostname:port//\(aq server = socketio.Server(client_manager=socketio.AsyncAioPikaManager( url)) .EE .UNINDENT .UNINDENT .INDENT 7.0 .TP .B پارامترها (Parameters) .INDENT 7.0 .IP \(bu 2 \fBurl\fP \-\- نشانی URL اتصال برای صف پیام‌رسانی پسانه. نمونه‌ای از URLهای اتصال \fB\(aqamqp://guest:guest@localhost:5672//\(aq\fP برای RabbitMQ است. .IP \(bu 2 \fBchannel\fP \-\- نام کانالی که کارساز اعلان‌ها را روی آن ارسال و دریافت می‌کند. باید در تمام کارسازها یکسان باشد. با این مدیر، نام کانال همان نام exchange در rabbitmq است. .IP \(bu 2 \fBwrite_only\fP \-\- اگر روی \fBTrue\fP تنظیم شود، تنها برای ارسال (emit) رویدادها مقداردهی می‌شود. مقدار پیش‌فرض \fBFalse\fP کلاس را برای ارسال و دریافت مقداردهی می‌کند. یک نمونه فقط‌نوشتنی (write\-only) می‌تواند مستقل از کارساز برای ارسال پیام به کلاینت‌ها از طریق یک فرایند خارجی استفاده شود. .IP \(bu 2 \fBlogger\fP \-\- یک logger سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از logger کارساز استفاده می‌شود. .IP \(bu 2 \fBjson\fP \-\- یک پودمان JSON جایگزین برای رمزگذاری و رمزگشایی بسته‌ها. پودمان‌های سفارشی json باید توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که \fBwrite_only\fP روی \fBTrue\fP تنظیم شده باشد\&. در غیر این صورت، از پودمان JSON پیکربندی‌شده در کارساز استفاده می‌شود. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B async close_room(room, namespace=None) حذف تمامی شرکت‌کنندگان از یک اتاق. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async connect(eio_sid, namespace) ثبت اتصال یک کلاینت به یک namespace. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async disconnect(sid, namespace, **kwargs) قطع اتصال یک کلاینت. .sp نکته: این متد یک هم‌روال (coroutine) است. .UNINDENT .INDENT 7.0.TP .B async emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs) ارسال یک پیام به یک کلاینت منفرد، یک اتاق، یا تمامی کلاینت‌های متصل به namespace. .sp این متد مدیریت انتشار پیام به تمام کارسازهای متصل از طریق صف پیام (message queue) را بر عهده دارد. .sp پارامترها مشابه موارد موجود در \fBServer.emit()\fP \%<#\:socketio\:.Server\:.emit>\& هستند. .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B async enter_room(sid, namespace, room, eio_sid=None) افزودن یک کلاینت به یک اتاق. .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B get_namespaces() بازگرداندن یک شیء تکرارپذیر (iterable) شامل نام‌های namespace فعال. .UNINDENT .INDENT 7.0 .TP .B get_participants(namespace, room) بازگرداندن یک شیء تکرارپذیر (iterable) شامل شرکت‌کنندگان فعال در یک اتاق. .sp توجه داشته باشید که در سناریوی چندکارسازی (multi\-server)، این متد تنها شرکت‌کنندگان متصل به کارسازی را برمی‌گرداند که متد در آن فراخوانی شده است. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین کارساز وجود ندارد. .UNINDENT .INDENT 7.0 .TP .B get_rooms(sid, namespace) بازگرداندن اتاق‌هایی که کلاینت در آن‌ها عضو است. .UNINDENT .INDENT 7.0 .TP .B initialize() پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد مقداردهی اولیه خود را در اینجا قرار دهند. .UNINDENT .INDENT 7.0 .TP .B async leave_room(sid, namespace, room) حذف یک کلاینت از یک اتاق. .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .INDENT 7.0 .TP .B pre_disconnect(sid, namespace) قرار دادن کلاینت در فهرست در\-حال\-قطع\-اتصال (to\-be\-disconnected). .sp این کار اجازه می‌دهد ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع ارتباط (disconnect handler) همچنان موجود باشند، در حالی که همچنان این موضوع که کلاینت به‌زودی قطع خواهد شد لحاظ می‌شود. .UNINDENT .INDENT 7.0 .TP .B async trigger_callback(sid, id, data) فراخوانی یک کال‌بک (callback) برنامه. .sp نکته: این متد یک کوروتین (coroutine) است. .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 نمایه \%<> .IP \(bu 2 نمایه ماژول \%<> .IP \(bu 2 صفحه جستجو \%<> .UNINDENT .SH "نویسندگان (AUTHORS)" Miguel Grinberg .SH "کپی‌رایت و تکثیر (COPYRIGHT)" 2018, Miguel Grinberg .\" End of generated man page.