نام (NAME)

python-socketio - مستندات کتابخانه python-socketio

این پروژه کلاینت‌ها و سرورهای Socket.IO را پیاده‌سازی می‌کند که می‌توانند به‌صورت مستقل یا یکپارچه‌شده با انواع فریم‌ورک‌های وب Python اجرا شوند.

شروع به کار (GETTING STARTED)

‏Socket.IO چیست؟

پروتکل Socket.IO یک پروتکل انتقال است که امکان برقراری ارتباط دوسویه، بلادرنگ و مبتنی بر رویداد را میان کلاینت‌ها (معمولاً، اما نه لزوماً، مرورگرهای وب) و یک سرور فراهم می‌کند. پیاده‌سازی‌های رسمی مؤلفه‌های کلاینت و سرور به زبان JavaScript نوشته شده‌اند. این بسته، پیاده‌سازی‌های Python هر دو مؤلفه را در قالب نسخه‌های استاندارد و asyncio ارائه می‌دهد.

سازگاری نسخه‌ها

پروتکل Socket.IO چندین بازنگری را پشت سر گذاشته است و برخی از آن‌ها تغییرات ناسازگار با نسخه‌های پیشین (backward incompatible) داشته‌اند؛ بدین معنا که کلاینت و سرور برای کارکرد صحیح باید از نسخه‌های سازگار استفاده کنند.

اگر از کلاینت و سرور Python استفاده می‌کنید، ساده‌ترین راه برای اطمینان از سازگاری، به‌کارگیری نسخه‌ای یکسان از این بسته برای هر دو بخش کلاینت و سرور است. چنانچه از این بسته همراه با کلاینت یا سرور دیگری استفاده می‌کنید، باید از سازگاری نسخه‌ها با یکدیگر اطمینان حاصل کنید.

جدول سازگاری نسخه در زیر، نگاشت میان نسخه‌های این بسته با نسخه‌های پیاده‌سازی مرجع JavaScript و همچنین نسخه‌های پروتکل‌های Socket.IO و Engine.IO را نمایش می‌دهد.

نسخه JavaScript Socket.IO	بازنگری پروتکل Socket.IO	بازنگری پروتکل Engine.IO	نسخه python-socketio	نسخه python-engineio
0.9.x	1, 2	1, 2	پشتیبانی نمی‌شود	پشتیبانی نمی‌شود
1.x و 2.x	3, 4	3	4.x	3.x
3.x و 4.x	5	4	5.x	4.x
"مثال‌های کلاینت (Client Examples)"
مثال زیر یک کلاینت سادهٔ Python را نشان می‌دهد:
0.0
3.5
import socketio
sio = socketio.Client()
@sio.event
def connect():
print('connection established')
@sio.event
def my_message(data):
print('message received with ', data)
sio.emit('my response', {'response': 'my response'})
@sio.event
def disconnect():
print('disconnected from server')
sio.connect('http://localhost:5000')
sio.wait()
0u
0u
در زیر کلاینت مشابهی آمده است که برای asyncio کدنویسی شده است (تنها ویژهٔ Python 3.5 یا بالاتر):
0.0
3.5
import asyncio
import socketio
sio = socketio.AsyncClient()
@sio.event
async def connect():
print('connection established')
@sio.event
async def my_message(data):
print('message received with ', data)
await sio.emit('my response', {'response': 'my response'})
@sio.event
async def disconnect():
print('disconnected from server')
async def main():
await sio.connect('http://localhost:5000')
await sio.wait()
if __name__ == '__main__':
asyncio.run(main())
0u
0u
"ویژگی‌های کلاینت (Client Features)"
0.0
• 2
می‌تواند به سایر سرورهای Socket.IO که با سرور مرجع JavaScript Socket.IO
سازگار هستند، متصل شود.
• 2
سازگار با Python 3.8 یا بالاتر.
• 2
دو نسخه از کلاینت، یکی برای Python استاندارد و دیگری برای
asyncio.
• 2
از یک معماری مبتنی بر رویداد پیاده‌سازی‌شده با دکوراتورها استفاده می‌کند که
جزئیات پروتکل را پنهان می‌سازد.
• 2
روش‌های انتقال HTTP long-polling و WebSocket را پیاده‌سازی می‌کند.
• 2
در صورت قطع اتصال، به‌طور خودکار مجدداً به سرور متصل می‌شود.
"مثال‌های سرور (Server Examples)"
برنامه زیر یک نمونه سرور مقدماتی است که از سرور ناهمگام
Eventlet استفاده می‌کند:
0.0
3.5
import eventlet
import socketio
sio = socketio.Server()
app = socketio.WSGIApp(sio, static_files={
'/': {'content_type': 'text/html', 'filename': 'index.html'}
})
@sio.event
def connect(sid, environ):
print('connect ', sid)
@sio.event
def my_message(sid, data):
print('message ', data)
@sio.event
def disconnect(sid):
print('disconnect ', sid)
if __name__ == '__main__':
eventlet.wsgi.server(eventlet.listen(('', 5000)), app)
0u
0u
در زیر برنامه مشابهی آمده است که برای asyncio (تنها Python 3.5+) و وب‌سرور
Uvicorn نوشته شده است:
0.0
3.5
from aiohttp import web
import socketio
sio = socketio.AsyncServer()
app = web.Application()
sio.attach(app)
async def index(request):
"""Serve the client-side application."""
with open('index.html') as f:
return web.Response(text=f.read(), content_type='text/html')
@sio.event
def connect(sid, environ):
print("connect ", sid)
@sio.event
async def chat_message(sid, data):
print("message ", data)
@sio.event
def disconnect(sid):
print('disconnect ', sid)
app.router.add_static('/static', 'static')
app.router.add_get('/', index)
if __name__ == '__main__':
web.run_app(app)
0u
0u
"ویژگی‌های سرور (Server Features)"
0.0
• 2
امکان اتصال به سرورهایی که سایر کلاینت‌های Socket.IO سازگار با کلاینت مرجع JavaScript را اجرا می‌کنند.
• 2
سازگار با Python 3.8+.
• 2
دو نسخه از سرور، یکی برای Python استاندارد و دیگری برای
asyncio.
• 2
پشتیبانی از تعداد زیادی کلاینت حتی روی سخت‌افزارهای معمولی به دلیل ناهمگام بودن.
• 2
امکان میزبانی روی هر وب‌سرور WSGI https://wsgi.readthedocs.io/en/latest/index.html یا
ASGI https://asgi.readthedocs.io/en/latest از جمله
Gunicorn https://gunicorn.org، Uvicorn https://github.com/encode/uvicorn،
eventlet http://eventlet.net و gevent http://www.gevent.org.
• 2
امکان ادغام با برنامه‌های WSGI نوشته‌شده در فریم‌ورک‌هایی مانند Flask، Django
و غیره.
• 2
امکان ادغام با برنامه‌های asyncio مانند aiohttp http://aiohttp.readthedocs.io،
FastAPI https://fastapi.tiangolo.com، sanic http://sanic.readthedocs.io
و tornado http://www.tornadoweb.org.
• 2
ارسال همگانی پیام‌ها به تمام کلاینت‌های متصل، یا به زیرمجموعه‌هایی از آن‌ها که به "اتاق‌ها" (rooms) تخصیص یافته‌اند.
• 2
پشتیبانی اختیاری از چندین سرور متصل از طریق صف پیام (messaging queue) مانند Redis یا RabbitMQ.
• 2
ارسال پیام به کلاینت‌ها از فرایندهای خارجی، مانند workerهای Celery یا اسکریپت‌های کمکی.
• 2
معماری رویدادمحور (Event-based) پیاده‌سازی‌شده با دکوراتورها که جزئیات پروتکل را پنهان می‌کند.
• 2
پشتیبانی از روش‌های انتقال (transports) HTTP long-polling و WebSocket.
• 2
پشتیبانی از مرورگرهای XHR2 و XHR.
• 2
پشتیبانی از پیام‌های متنی و باینری (binary).
• 2
پشتیبانی از فشرده‌سازی HTTP به روش‌های gzip و deflate.
• 2
پاسخ‌های CORS با قابلیت پیکربندی، جهت جلوگیری از مشکلات cross-origin در مرورگرها.
"کلاینت‌های SOCKET.IO (THE SOCKET.IO CLIENTS)"
این بسته شامل دو کلاینت Socket.IO است:
0.0
• 2
یک کلاینت "ساده"، که یک API سرراست ارائه می‌دهد و برای اکثر برنامه‌ها کافی است
• 2
یک کلاینت "رویداد-محور"، که دسترسی به تمام ویژگی‌های پروتکل Socket.IO را فراهم می‌سازد
0u
هر یک از این کلاینت‌ها در دو گونه عرضه می‌شوند: یکی برای کتابخانه استاندارد Python، و دیگری برای برنامه‌های ناهمگام ساخته‌شده با بسته asyncio.
نصب
برای نصب کلاینت استاندارد Python به همراه وابستگی‌های آن، از دستور زیر استفاده کنید:
0.0
3.5
pip install "python-socketio[client]"
0u
0u
اگر در عوض قصد دارید از کلاینت asyncio استفاده کنید، از این دستور استفاده کنید:
0.0
3.5
pip install "python-socketio[asyncio_client]"
0u
0u
استفاده از کلاینت ساده
مزیت کلاینت ساده این است که منطق مورد نیاز برای برقراری و نگه‌داری اتصال Socket.IO را انتزاع می‌کند. این کلاینت قطع اتصال و اتصال مجدد را به‌شکلی کاملاً شفاف، بدون افزودن هیچ‌گونه پیچیدگی به برنامه مدیریت می‌نماید.
ایجاد یک نمونه از کلاینت
ساده‌ترین روش برای ایجاد یک کلاینت Socket.IO، استفاده از رابط context manager است:
0.0
3.5
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!
0u
0u
با این روش، context manager تضمین می‌کند که کلاینت پیش از خروج از بلوک with یا async with به‌درستی قطع اتصال شود.
در صورت تمایل، کلاینت می‌تواند به‌صورت دستی نمونه‌سازی شود:
0.0
3.5
import socketio
# standard Python
sio = socketio.SimpleClient()
# asyncio
sio = socketio.AsyncSimpleClient()
0u
اتصال به یک سرور با فراخوانی متد connect() برقرار می‌شود:
0.0
3.5
sio.connect('http://localhost:5000')
0u
0u
در مورد کلاینت asyncio، این متد یک کوروتین (coroutine) است:
0.0
3.5
await sio.connect('http://localhost:5000')
0u
0u
به‌طور پیش‌فرض کلاینت ابتدا با استفاده از روش انتقال long-polling به سرور متصل می‌شود، و سپس تلاش می‌کند تا اتصال را برای استفاده از WebSocket ارتقا دهد. برای اتصال مستقیم با استفاده از WebSocket، از آرگومان transports استفاده کنید:
0.0
3.5
sio.connect('http://localhost:5000', transports=['websocket'])
0u
0u
پس از برقراری اتصال، سرور یک شناسه نشست یکتا به کلاینت اختصاص می‌دهد. برنامه می‌تواند این شناسه را در ویژگی sid بیابد:
0.0
3.5
print('my sid is', sio.sid)
0u
0u
روش انتقال Socket.IO که در این اتصال استفاده می‌شود را می‌توان از ویژگی transport به دست آورد:
0.0
3.5
print('my transport is', sio.transport)
0u
0u
روش انتقال به صورت یک رشته بازگردانده می‌شود و می‌تواند 'websocket' یا 'polling' باشد.
پشتیبانی از TLS/SSL (TLS/SSL Support)
کلاینت از اتصالات TLS/SSL پشتیبانی می‌کند. برای فعال کردن آن، از یک نشانی اینترنتی (URL) اتصال با https:// استفاده کنید:
0.0
3.5
sio.connect('https://example.com')
0u
0u
یا هنگام استفاده از asyncio:
0.0
3.5
await sio.connect('https://example.com')
0u
0u
کلاینت به‌طور پیش‌فرض گواهی‌های سرور را بررسی و تأیید می‌کند. برای کسب اطلاعات درباره نحوه سفارشی‌سازی این رفتار، به مستندات کلاینت رویدادمحور مراجعه کنید..SS "ارسال رویدادها (Emitting Events)"
کلاینت می‌تواند با استفاده از متد emit() یک رویداد را به سرور ارسال کند:
0.0
3.5
sio.emit('my message', {'foo': 'bar'})
0u
0u
یا در صورت استفاده از asyncio، به‌صورت یک کوروتین:
0.0
3.5
await sio.emit('my message', {'foo': 'bar'})
0u
0u
آرگومان‌های ارائه‌شده به این متد، نام رویدادی است که باید ارسال شود و داده‌های
اختیاری که به سرور ارسال می‌شوند. داده‌ها می‌توانند از نوع str،
bytes، dict، list یا tuple باشند. هنگام ارسال یک list یا یک
tuple، عناصر موجود در آن باید از هر یک از انواع مجاز به جز tuple باشند.
هنگامی که از یک تاپل استفاده می‌شود، عناصر آن تاپل به‌صورت آرگومان‌های مجزا
به تابع مدیریت رویداد در سمت سرور منتقل خواهند شد.
"دریافت رویدادها (Receiving Events)"
کلاینت می‌تواند با استفاده از متد receive() منتظر بماند تا سرور یک رویداد را
ارسال کند:
0.0
3.5
event = sio.receive()
print(f'received event: "{event[0]}" with arguments {event[1:]}')
0u
0u
هنگام استفاده از asyncio، این متد باید با await فراخوانی شود:
0.0
3.5
event = await sio.receive()
print(f'received event: "{event[0]}" with arguments {event[1:]}')
0u
0u
مقدار بازگشتی receive() یک لیست است. نخستین عنصر این لیست نام رویداد
است، در حالی که سایر عناصر، آرگومان‌های ارسال‌شده از سوی سرور هستند.
با روش استفاده‌ای که در بالا نشان داده شد، متد receive() تنها زمانی برمی‌گردد که
رویدادی از سرور دریافت شود. می‌توان یک مهلت زمانی اختیاری (timeout) بر حسب ثانیه ارسال کرد
تا از انتظار همیشگی کلاینت جلوگیری شود:
0.0
3.5
from socketio.exceptions import TimeoutError
try:
event = sio.receive(timeout=5)
except TimeoutError:
print('timed out waiting for event')
else:
print('received event:', event)
0u
0u
یا با asyncio:
0.0
3.5
from socketio.exceptions import TimeoutError
try:
event = await sio.receive(timeout=5)
except TimeoutError:
print('timed out waiting for event')
else:
print('received event:', event)
0u
در هر زمان کلاینت می‌تواند با فراخوانی متد disconnect()، درخواست قطع اتصال از سرور را بدهد:
0.0
3.5
sio.disconnect()
0u
0u
برای کلاینت asyncio این یک هم‌روال (coroutine) است:
0.0
3.5
await sio.disconnect()
0u
0u
"اشکال‌زدایی و عیب‌یابی (Debugging and Troubleshooting)"
برای کمک به اشکال‌زدایی مشکلات، می‌توان کلاینت را برای ارسال لاگ‌ها به ترمینال پیکربندی کرد:
0.0
3.5
import socketio
# standard Python
sio = socketio.Client(logger=True, engineio_logger=True)
# asyncio
sio = socketio.AsyncClient(logger=True, engineio_logger=True)
0u
0u
آرگومان logger ثبت لاگ‌های مربوط به پروتکل Socket.IO را کنترل می‌کند، در حالی که engineio_logger لاگ‌های نشئت‌گرفته از لایهٔ انتقال سطح پایین Engine.IO را کنترل می‌نماید. مقداری که به این آرگومان‌ها اختصاص می‌یابد رفتار ثبت لاگ را تعیین می‌کند:
0.0
• 2
True: خروجی لاگ را در stderr در سطح INFO فعال می‌کند.
• 2
False: خروجی لاگ را در stderr در سطح ERROR فعال می‌کند. این مقدار پیش‌فرض است.
• 2
یک نمونه از logging.Logger: از لاگر ارائه‌شده بدون نیاز به پیکربندی اضافی استفاده می‌کند.
0u
ثبت لاگ می‌تواند به شناسایی علت مشکلات اتصال، قطع ارتباط‌های غیرمنتظره و سایر مسائل کمک کند.
"استفاده از کلاینت رویدادمحور (Using the Event-Driven Client)"
"ایجاد یک نمونه از کلاینت (Creating a Client Instance)"
برای نمونه‌سازی از یک کلاینت Socket.IO، کافی است یک نمونه از کلاس کلاینت مناسب ایجاد کنید:
0.0
3.5
import socketio
# standard Python
sio = socketio.Client()
# asyncio
sio = socketio.AsyncClient()
0u
0u
"تعریف گرداننده‌های رویداد (Defining Event Handlers)"
پروتکل Socket.IO مبتنی بر رویداد است. هنگامی که سرور می‌خواهد با کلاینت ارتباط برقرار کند، یک رویداد را منتشر (emit) می‌کند. هر رویداد دارای یک نام و فهرستی از آرگومان‌ها است. کلاینت توابع گردانندهٔ رویداد را با دکوراتورهای socketio.Client.event() <#socketio.Client.event> یا socketio.Client.on() <#socketio.Client.on> ثبت می‌کند:
0.0
3.5
@sio.event
def message(data):
print('I received a message!')
@sio.on('my message')
def on_message(data):
print('I received a message!')
0u
0u
در مثال اول، نام رویداد از نام تابع گرداننده گرفته می‌شود. مثال دوم کمی مفصل‌تر است، اما این امکان را فراهم می‌سازد که نام رویداد با نام تابع متفاوت باشد یا شامل نویسه‌هایی شود که در نام توابع غیرمجاز هستند، مانند فاصله‌ها.
برای کلاینت asyncio، گرداننده‌های رویداد می‌توانند همانند بالا توابعی معمولی باشند، یا این که به صورت هم‌روال (coroutine) تعریف شوند:
0.0
3.5
@sio.event
async def message(data):
print('I received a message!')
0u
0u
اگر سرور به همراه رویداد آرگومان‌هایی ارسال کند، آن آرگومان‌ها به تابع گرداننده تحویل داده می‌شوند..SS گرداننده‌های همه‌گیر رویداد و فضای‌نام (Catch-All Event and Namespace Handlers)
یک گردانندهٔ رویداد «همه‌گیر» (catch-all) برای تمام رویدادهایی که گردانندهٔ
مشخصی ندارند فراخوانی می‌شود. می‌توانید با استفاده از *''** به عنوان
نام رویداد، یک گردانندهٔ همه‌گیر تعریف کنید:
0.0
3.5
@sio.on('*')
def any_event(event, sid, data):
pass
0u
0u
سرورهای Asyncio همچنین می‌توانند از یک هم‌روال (coroutine) استفاده کنند:
0.0
3.5
@sio.on('*')
async def any_event(event, sid, data):
pass
0u
0u
یک گردانندهٔ رویداد همه‌گیر، نام رویداد را به عنوان نخستین آرگومان دریافت می‌کند.
باقی آرگومان‌ها همانند یک گردانندهٔ رویداد معمولی هستند.
رویدادهای connect و disconnect باید به‌طور صریح تعریف شوند و توسط
گردانندهٔ رویداد همه‌گیر فراخوانی نمی‌شوند.
به‌طور مشابه، یک گردانندهٔ فضای‌نام «همه‌گیر» برای تمام فضاهای نام متصلی که
گردانندهٔ رویداد صریحاً تعریف‌شده‌ای ندارند فراخوانی می‌شود. همانند رویدادهای
همه‌گیر، از *''** به جای نام فضای‌نام استفاده می‌شود:
0.0
3.5
@sio.on('my_event', namespace='*')
def my_event_any_namespace(namespace, sid, data):
pass
0u
0u
برای این رویدادها، فضای‌نام به عنوان نخستین آرگومان ارسال شده و به دنبال آن
آرگومان‌های معمول رویداد قرار می‌گیرند.
در نهایت، تعریف یک گردانندهٔ «همه‌گیر» برای تمام رویدادها در تمامی فضاهای نام
نیز امکان‌پذیر است:
0.0
3.5
@sio.on('', namespace='')
def any_event_any_namespace(event, namespace, sid, data):
pass
0u
0u
گرداننده‌های رویداد با رویدادها و فضاهای نام همه‌گیر، نام رویداد و نام فضای‌نام
را به عنوان آرگومان‌های اول و دوم دریافت می‌کنند.
گرداننده‌های رویداد اتصال، خطای اتصال و قطع اتصال (Connect, Connect Error and Disconnect Event Handlers)
رویدادهای connect، connect_error و disconnect خاص هستند؛ آن‌ها
هنگام اتصال کلاینت به سرور یا قطع اتصال از آن، به‌طور خودکار فراخوانی می‌شوند:
0.0
3.5
@sio.event
def connect():
print("I'm connected!")
@sio.event
def connect_error(data):
print("The connection failed!")
@sio.event
def disconnect(reason):
print("I'm disconnected! reason:", reason)
0u
0u
گردانندهٔ connect_error هنگامی که تلاشی برای اتصال با شکست مواجه شود فراخوانی
می‌گردد. اگر سرور آرگومان‌هایی ارائه دهد، این مقادیر به گرداننده منتقل می‌شوند.
سرور می‌تواند از یک آرگومان برای ارائهٔ اطلاعات مربوط به شکست اتصال به کلاینت
استفاده کند.
گردانندهٔ disconnect برای قطع اتصال‌های آغاز شده توسط برنامه، آغاز شده
توسط سرور، یا قطع اتصال‌های تصادفی مانند خرابی‌های شبکه فراخوانی می‌شود.
در صورت وقوع یک قطع اتصال تصادفی، کلاینت بلافاصله پس از فراخوانی گردانندهٔ قطع
اتصال، برای اتصال مجدد تلاش خواهد کرد. به محض برقراری مجدد اتصال، گردانندهٔ
connect بار دیگر فراخوانی خواهد شد. این گرداننده یک آرگومان reason دریافت
می‌کند که علت قطع اتصال را مشخص می‌کند:
0.0
3.5
@sio.event
def disconnect(reason):
if reason == sio.reason.CLIENT_DISCONNECT:
print('the client disconnected')
elif reason == sio.reason.SERVER_DISCONNECT:
print('the server disconnected the client')
else:
print('disconnect reason:', reason)
0u
0u
برای فهرستی از دلایل ممکن قطع اتصال، صفت socketio.Client.reason <#socketio.Client.reason>
را ببینید.
رویدادهای connect، connect_error و disconnect باید صریحاً تعریف
شوند و توسط یک گردانندهٔ رویداد همه‌گیر فراخوانی نمی‌شوند..SS اتصال به سرور
اتصال به یک سرور با فراخوانی متد connect() برقرار می‌شود:
0.0
3.5
sio.connect('http://localhost:5000')
0u
0u
در مورد کلاینت asyncio، این متد یک کوروتین (coroutine) است:
0.0
3.5
await sio.connect('http://localhost:5000')
0u
0u
به محض اتصال، سرور یک شناسه نشست یکتا به کلاینت اختصاص می‌دهد.
برنامه می‌تواند این شناسه را در صفت sid بیابد:
0.0
3.5
print('my sid is', sio.sid)
0u
0u
روش انتقال Socket.IO که در اتصال استفاده می‌شود را می‌توان از صفت
transport به دست آورد:
0.0
3.5
print('my transport is', sio.transport)
0u
0u
نوع انتقال به‌صورت یک رشته مشخص می‌شود و می‌تواند 'websocket' یا
'polling' باشد.
پشتیبانی از TLS/SSL
کلاینت از اتصالات TLS/SSL پشتیبانی می‌کند. برای فعال‌سازی آن، از یک URL
اتصال با https:// استفاده کنید:
0.0
3.5
sio.connect('https://example.com')
0u
0u
یا هنگام استفاده از asyncio:
0.0
3.5
await sio.connect('https://example.com')
0u
0u
کلاینت به‌طور پیش‌فرض گواهی سرور را اعتبارسنجی می‌کند. برای غیرفعال کردن
اعتبارسنجی گواهی یا استفاده از گزینه‌های کمتر رایج مانند گواهی‌های کلاینت،
کلاینت باید با یک شیء نشست HTTP سفارشی که با گزینه‌های مورد نظر TLS/SSL
پیکربندی شده است، مقداردهی اولیه شود.
مثال زیر اعتبارسنجی گواهی سرور را غیرفعال می‌کند که هنگام اتصال به سروری که
از یک گواهی خودامضا (self-signed) استفاده می‌کند، می‌تواند مفید باشد:
0.0
3.5
http_session = requests.Session()
http_session.verify = False
sio = socketio.Client(http_session=http_session)
sio.connect('https://example.com')
0u
0u
و هنگام استفاده از asyncio:
0.0
3.5
connector = aiohttp.TCPConnector(ssl=False)
http_session = aiohttp.ClientSession(connector=connector)
sio = socketio.AsyncClient(http_session=http_session)
await sio.connect('https://example.com')
0u
0u
به جای غیرفعال کردن اعتبارسنجی گواهی، می‌توانید یک بسته مرجع صدور گواهی
(CA bundle) سفارشی برای اعتبارسنجی گواهی در برابر آن ارائه دهید:
0.0
3.5
http_session = requests.Session()
http_session.verify = '/path/to/ca.pem'
sio = socketio.Client(http_session=http_session)
sio.connect('https://example.com')
0u
0u
و برای asyncio:
0.0
3.5
ssl_context = ssl.create_default_context()
ssl_context.load_verify_locations('/path/to/ca.pem')
connector = aiohttp.TCPConnector(ssl=ssl_context)
http_session = aiohttp.ClientSession(connector=connector)
sio = socketio.AsyncClient(http_session=http_session)
await sio.connect('https://example.com')
0u
0u
در ادامه نحوه استفاده از یک گواهی کلاینت برای احراز هویت در برابر سرور نشان داده شده است:
0.0
3.5
http_session = requests.Session()
http_session.cert = ('/path/to/client/cert.pem', '/path/to/client/key.pem')
sio = socketio.Client(http_session=http_session)
sio.connect('https://example.com')
0u
0u
و برای asyncio:
0.0
3.5
ssl_context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
ssl_context.load_cert_chain('/path/to/client/cert.pem',
'/path/to/client/key.pem')
connector = aiohttp.TCPConnector(ssl=ssl_context)
http_session = aiohttp.ClientSession(connector=connector)
sio = socketio.AsyncClient(http_session=http_session)
await sio.connect('https://example.com')
0u
کلاینت می‌تواند با استفاده از متد emit() یک رویداد را به سرور ارسال کند:
0.0
3.5
sio.emit('my message', {'foo': 'bar'})
0u
0u
یا در صورت استفاده از asyncio، به عنوان یک کوروتین:
0.0
3.5
await sio.emit('my message', {'foo': 'bar'})
0u
0u
آرگومان‌های ارائه‌شده به این متد، نام رویداد ارسالی و داده‌های اختیاری هستند که به سرور منتقل می‌شوند. داده‌ها می‌توانند از نوع str، bytes، dict، list یا tuple باشند. هنگام ارسال یک list یا یک tuple، عناصر موجود در آن باید از هر یک از انواع مجاز به جز tuple باشند. هنگامی که از یک تاپل استفاده می‌شود، عناصر تاپل به عنوان آرگومان‌های مجزا به تابع مدیریت رویداد در سمت سرور ارسال خواهند شد.
متد emit() را می‌توان درون یک مدیریت‌کننده رویداد به عنوان پاسخی به یک رویداد سرور، یا در هر بخش دیگری از برنامه، از جمله در وظایف پس‌زمینه فراخوانی کرد.
"کال‌بک‌های رویداد (Event Callbacks)"
هنگامی که یک سرور رویدادی را به کلاینت ارسال می‌کند، می‌تواند به صورت اختیاری یک تابع کال‌بک (callback) ارائه دهد تا پس از پردازش رویداد توسط سرور، به عنوان راهی برای تأیید دریافت فراخوانی شود. اگرچه این موضوع به طور کامل توسط سرور مدیریت می‌شود، اما کلاینت می‌تواند فهرستی از مقادیر بازگشتی را برای ارسال به تابع کال‌بک تعیین‌شده توسط سرور فراهم کند. این کار به سادگی با بازگرداندن مقادیر مورد نظر از تابع مدیریت‌کننده انجام می‌شود:
0.0
3.5
@sio.event
def my_event(sid, data):
# handle the message
return "OK", 123
0u
0u
به همین ترتیب، کلاینت می‌تواند درخواست کند که پس از پردازش یک رویداد توسط سرور، یک تابع کال‌بک فراخوانی شود. متد socketio.Server.emit() <#socketio.Server.emit> یک آرگومان اختیاری callback دارد که می‌توان آن را روی یک شیء قابل فراخوانی (callable) تنظیم کرد. اگر این آرگومان مشخص شود، پس از پردازش رویداد توسط سرور، شیء قابل فراخوانی اجرا خواهد شد و هر مقداری که توسط مدیریت‌کننده سرور بازگردانده شود، به عنوان آرگومان به این تابع ارسال می‌گردد.
"فضاهای نام (Namespaces)"
پروتکل Socket.IO از چندین اتصال منطقی پشتیبانی می‌کند که همگی روی همان اتصال فیزیکی تسهیم (multiplex) می‌شوند. کلاینت‌ها می‌توانند با تعیین یک namespace متفاوت روی هر کدام، چندین اتصال برقرار کنند. فضاهای نام از قواعد ساختاری مسیر که با یک اسلش رو به جلو آغاز می‌شود استفاده می‌کنند. فهرستی از فضاهای نام را می‌توان توسط کلاینت در فراخوانی connect() ارائه داد. برای نمونه، این مثال دو اتصال منطقی ایجاد می‌کند: یکی اتصال پیش‌فرض و دیگری اتصال دوم تحت فضای نام /chat:
0.0
3.5
sio.connect('http://localhost:5000', namespaces=['/chat'])
0u
0u
برای تعریف مدیریت‌کننده‌های رویداد روی یک فضای نام، آرگومان namespace باید به دکوراتور مربوطه اضافه شود:
0.0
3.5
@sio.event(namespace='/chat')
def my_custom_event(sid, data):
pass
@sio.on('connect', namespace='/chat')
def on_connect():
print("I'm connected to the /chat namespace!")
0u
0u
به همین ترتیب، کلاینت می‌تواند با تعیین آن در فراخوانی emit()، رویدادی را روی یک فضای نام به سرور ارسال کند:
0.0
3.5
sio.emit('my message', {'foo': 'bar'}, namespace='/chat')
0u
0u
اگر آرگومان namespaces در فراخوانی connect() مشخص نشود، هر فضای نامی که در مدیریت‌کننده‌های رویداد استفاده شده باشد به طور خودکار متصل می‌شود..SS فضاهای نام مبتنی بر کلاس
به عنوان جایگزینی برای گرداننده‌های رویداد مبتنی بر دکوراتور، گرداننده‌های رویدادی
که متعلق به یک فضای نام هستند می‌توانند به صورت متدهای یک زیرکلاس از
socketio.ClientNamespace <#socketio.ClientNamespace> ایجاد شوند:
0.0
3.5
class MyCustomNamespace(socketio.ClientNamespace):
def on_connect(self):
pass
def on_disconnect(self, reason):
pass
def on_my_event(self, data):
self.emit('my_response', data)
sio.register_namespace(MyCustomNamespace('/chat'))
0u
0u
برای سرورهای مبتنی بر asyncio، فضاهای نام باید از
socketio.AsyncClientNamespace <#socketio.AsyncClientNamespace> ارث‌بری کنند، و در صورت
تمایل می‌توانند گرداننده‌های رویداد را به عنوان کوروتین (coroutine) تعریف نمایند:
0.0
3.5
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('my_response', data)
sio.register_namespace(MyCustomNamespace('/chat'))
0u
0u
یک گردانندهٔ فضای نام مبتنی بر کلاس همه‌گیر (catch-all) را می‌توان با ارسال *''** به عنوان
فضای نام هنگام ثبت تعریف کرد:
0.0
3.5
sio.register_namespace(MyCustomNamespace('*'))
0u
0u
هنگامی که از فضاهای نام مبتنی بر کلاس استفاده می‌شود، هر رویداد دریافت شده توسط کلاینت به
متدی که نام آن، نام رویداد همراه با پیشوند on_ است ارسال می‌شود (dispatch). برای
نمونه، رویداد my_event توسط متدی به نام on_my_event مدیریت خواهد شد.
اگر رویدادی دریافت شود که متد متناظری برای آن در کلاس فضای نام تعریف نشده باشد،
آن رویداد نادیده گرفته می‌شود. تمام نام‌های رویداد که در فضاهای نام مبتنی بر کلاس
استفاده می‌شوند باید از نویسه‌هایی استفاده کنند که در نام متدها مجاز باشند.
جهت سهولت متدهای تعریف‌شده در یک فضای نام مبتنی بر کلاس، نمونهٔ فضای نام
شامل نسخه‌هایی از چندین متد از کلاس‌های
socketio.Client <#socketio.Client> و socketio.AsyncClient <#socketio.AsyncClient> است که
در صورت تعیین نشدن آرگومان namespace، به صورت پیش‌فرض فضای نام مربوطه را در نظر می‌گیرند.
در صورتی که یک رویداد، هم یک گرداننده در فضای نام مبتنی بر کلاس و هم یک تابع
گردانندهٔ مبتنی بر دکوراتور داشته باشد، تنها تابع گردانندهٔ مستقل فراخوانی می‌شود.
قطع اتصال از سرور
کلاینت در هر زمان می‌تواند با فراخوانی متد disconnect() درخواست قطع
اتصال از سرور را بدهد:
0.0
3.5
sio.disconnect()
0u
0u
برای کلاینت asyncio این یک کوروتین است:
0.0
3.5
await sio.disconnect()
0u
هنگامی که اتصال کلاینت به سرور برقرار می‌شود، چند وظیفهٔ پس‌زمینه برای زنده نگه‌داشتن اتصال و مدیریت رویدادهای ورودی ایجاد خواهند شد. برنامه‌ای که روی ریسهٔ اصلی (main thread) اجرا می‌شود برای انجام هر کاری آزاد است، چرا که این امر مانع از عملکرد کلاینت Socket.IO نخواهد شد.
اگر برنامه در ریسهٔ اصلی کاری برای انجام دادن ندارد و فقط می‌خواهد تا زمان پایان اتصال با سرور منتظر بماند، می‌تواند متد wait() را فراخوانی کند:
0.0
3.5
sio.wait()
0u
0u
یا در نسخهٔ asyncio:
0.0
3.5
await sio.wait()
0u
0u
برای راحتی برنامه، یک تابع کمکی برای راه‌اندازی یک وظیفهٔ پس‌زمینهٔ سفارشی ارائه شده است:
0.0
3.5
def my_background_task(my_argument):
# do some background work here!
pass
task = sio.start_background_task(my_background_task, 123)
0u
0u
آرگومان‌های ارسال‌شده به این متد عبارت‌اند از تابع پس‌زمینه و هرگونه آرگومان موضعی (positional) یا کلیدواژه‌ای (keyword) که تابع باید با آن‌ها فراخوانی شود.
این نسخهٔ asyncio است:
0.0
3.5
async def my_background_task(my_argument):
# do some background work here!
pass
task = sio.start_background_task(my_background_task, 123)
0u
0u
توجه داشته باشید که این تابع یک کوروتین (coroutine) نیست، زیرا منتظر پایان یافتن تابع پس‌زمینه نمی‌ماند. خود تابع پس‌زمینه حتماً باید یک کوروتین باشد.
متد sleep() تابع کمکی دوم است که برای سهولت برنامه‌هایی که با وظایف پس‌زمینهٔ اختصاصی خود کار می‌کنند فراهم شده است:
0.0
3.5
sio.sleep(2)
0u
0u
یا برای asyncio:
0.0
3.5
await sio.sleep(2)
0u
0u
تنها آرگومان ارسال‌شده به این متد، تعداد ثانیه‌های توقف (sleep) است..SS اشکال‌زدایی و عیب‌یابی (Debugging and Troubleshooting)
برای کمک به اشکال‌زدایی مشکلات، کلاینت را می‌توان طوری پیکربندی کرد که لاگ‌ها را در ترمینال خروجی دهد:
0.0
3.5
import socketio
# standard Python
sio = socketio.Client(logger=True, engineio_logger=True)
# asyncio
sio = socketio.AsyncClient(logger=True, engineio_logger=True)
0u
0u
آرگومان logger ثبت وقایع مربوط به پروتکل Socket.IO را کنترل می‌کند، در حالی که engineio_logger لاگ‌های نشأت‌گرفته از لایهٔ انتقال سطح پایین Engine.IO را کنترل می‌نماید. این آرگومان‌ها می‌توانند روی True تنظیم شوند تا لاگ‌ها را در stderr خروجی دهند، یا روی شیئی سازگار با بستهٔ logging پایتون که لاگ‌ها باید به آن ارسال شوند. مقدار False ثبت وقایع را غیرفعال می‌کند.
ثبت وقایع می‌تواند به شناسایی علت مشکلات اتصال، قطع‌شدن‌های غیرمنتظره و سایر مسائل کمک کند.
"سرور SOCKET.IO (THE SOCKET.IO SERVER)"
این بسته شامل دو سرور Socket.IO است:
0.0
• 2
کلاس socketio.Server() <#socketio.Server> سروری سازگار با کتابخانهٔ استاندارد پایتون ایجاد می‌کند.
• 2
کلاس socketio.AsyncServer() <#socketio.AsyncServer> سروری سازگار با بستهٔ asyncio ایجاد می‌کند.
0u
متدهای هر دو سرور یکسان هستند، با این تفاوت که در سرور asyncio اکثر متدها به‌صورت کوروتین (coroutine) پیاده‌سازی شده‌اند.
نصب (Installation)
برای نصب سرور Socket.IO به همراه وابستگی‌های آن، از دستور زیر استفاده کنید:
0.0
3.5
pip install python-socketio
0u
0u
ایجاد یک نمونه سرور (Creating a Server Instance)
یک سرور Socket.IO، نمونه‌ای از کلاس socketio.Server <#socketio.Server> است:
0.0
3.5
import socketio
# create a Socket.IO server
sio = socketio.Server()
0u
0u
برای سرورهای مبتنی بر asyncio، کلاس socketio.AsyncServer <#socketio.AsyncServer> همان سازوکار را در قالبی سازگار با کوروتین‌ها ارائه می‌دهد:
0.0
3.5
import socketio
# create a Socket.IO server
sio = socketio.AsyncServer()
0u
برای اجرای برنامه Socket.IO لازم است یک وب‌سرور پیکربندی شود تا
درخواست‌های دریافتی از کلاینت‌ها را دریافت کرده و آن‌ها را به نمونهٔ
سرور Socket.IO فوروارد کند. برای ساده‌سازی این کار، یکپارچه‌سازی‌های
متعددی در دسترس است، از جمله پشتیبانی از استانداردهای WSGI https://wsgi.readthedocs.io/en/latest/what.html
و ASGI https://asgi.readthedocs.io/en/latest.
اجرا به عنوان یک برنامه WSGI
برای پیکربندی سرور Socket.IO به عنوان یک برنامه WSGI، نمونهٔ سرور را با
کلاس socketio.WSGIApp <#socketio.WSGIApp> کپسوله‌سازی (wrap) کنید:
0.0
3.5
# wrap with a WSGI application
app = socketio.WSGIApp(sio)
0u
0u
برنامهٔ WSGI حاصل را می‌توان با وب‌سرورهای پشتیبانی‌شدهٔ WSGI مانند
Werkzeug https://werkzeug.palletsprojects.com برای توسعه و
Gunicorn https://gunicorn.org برای محیط عملیاتی (production) اجرا کرد.
هنگام ترکیب Socket.IO با یک برنامه وب نوشته‌شده با چارچوب‌های WSGI
نظیر Flask یا Django، کلاس WSGIApp می‌تواند هر دو برنامه را با یکدیگر
پوشش داده و ترافیک را به سمت آن‌ها هدایت کند:
0.0
3.5
from mywebapp import app # a Flask, Django, etc. application
app = socketio.WSGIApp(sio, app)
0u
0u
اجرا به عنوان یک برنامه ASGI
برای پیکربندی سرور Socket.IO به عنوان یک برنامه ASGI، نمونهٔ سرور را با
کلاس socketio.ASGIApp <#socketio.ASGIApp> کپسوله‌سازی (wrap) کنید:
0.0
3.5
# wrap with ASGI application
app = socketio.ASGIApp(sio)
0u
0u
برنامهٔ ASGI حاصل را می‌توان با یک وب‌سرور سازگار با ASGI، مانند
Uvicorn https://www.uvicorn.org اجرا کرد.
همچنین می‌توان Socket.IO را با یک برنامه وب نوشته‌شده با چارچوب‌های وب
ASGI مانند FastAPI ترکیب کرد. در این حالت، کلاس ASGIApp می‌تواند هر دو
برنامه را با یکدیگر پوشش داده و ترافیک را به سمت آن‌ها هدایت کند:
0.0
3.5
from mywebapp import app # a FastAPI or other ASGI application
app = socketio.ASGIApp(sio, app)
0u
0u
ارائه فایل‌های ایستا
سرور Socket.IO می‌تواند برای ارائه فایل‌های ایستا (static files) به کلاینت‌ها
پیکربندی شود. این قابلیت به‌ویژه زمانی مفید است که این بسته بدون یک چارچوب وب
جانبی استفاده شود و نیاز به تحویل فایل‌های HTML، CSS و JavaScript به کلاینت‌ها باشد.
فایل‌های ایستا با یک دیکشنری پایتون پیکربندی می‌شوند که در آن هر جفت کلید/مقدار
یک قانون نگاشت فایل ایستا است. در ساده‌ترین شکل، این دیکشنری یک یا چند نشانی اینترنتی
(URL) فایل ایستا را به عنوان کلید، و فایل‌های متناظر در سرور را به عنوان مقدار در بر دارد:
0.0
3.5
static_files = {
'/': 'latency.html',
'/static/socket.io.js': 'static/socket.io.js',
'/static/style.css': 'static/style.css',
}
0u
0u
با این پیکربندی نمونه، زمانی که سرور درخواستی برای / (نشانی ریشه) دریافت
می‌کند، محتویات فایل latency.html در دایرکتوری فعلی را برمی‌گرداند، و یک
نوع محتوا (content type) بر اساس پسوند فایل تعیین می‌کند که در این مورد
text/html خواهد بود.
فایل‌های دارای پسوندهای .html، .css، .js، .json،
.jpg، .png، .gif و .txt به‌طور خودکار شناسایی
شده و نوع محتوای صحیح به آن‌ها اختصاص می‌یابد. برای فایل‌هایی با سایر پسوندها
یا بدون پسوند فایل، نوع محتوای پیش‌فرض application/octet-stream استفاده می‌شود.
در صورت تمایل، می‌توان نوع محتوای صریح را برای یک فایل ایستا به شکل زیر مشخص کرد:
0.0
3.5
static_files = {
'/': {'filename': 'latency.html', 'content_type': 'text/plain'},
}
0u
0u
همچنین می‌توان یک دایرکتوری کامل را در قالب یک قاعده واحد پیکربندی کرد،
به‌گونه‌ای که تمام فایل‌های درون آن به عنوان فایل ایستا ارائه شوند:
0.0
3.5
static_files = {
'/static': './public',
}
0u
0u
در این مثال، هر فایلی با نشانی که با /static آغاز شود مستقیماً از پوشهٔ
public در دایرکتوری فعلی ارائه خواهد شد؛ بنابراین به عنوان مثال، نشانی
/static/index.html فایل محلی ./public/index.html و نشانی
/static/css/styles.css فایل محلی ./public/css/styles.css را
برمی‌گرداند.
اگر نشانی درخواستی به / ختم شود، نام فایل پیش‌فرض index.html
به انتهای آن الحاق می‌گردد. در مثال قبلی، درخواست برای نشانی /static/
فایل محلی ./public/index.html را برمی‌گرداند. نام فایل پیش‌فرض برای
ارائه در نشانی‌های ختم‌شده به اسلش را می‌توان در دیکشنری فایل‌های ایستا با یک
کلید خالی تنظیم کرد:
0.0
3.5
static_files = {
'/static': './public',
'': 'image.gif',
}
0u
0u
با این پیکربندی، درخواستی برای /static/ فایل محلی ./public/image.gif
را برمی‌گرداند. در صورت نیاز می‌توان نوع محتوای غیر استاندارد را نیز تعیین کرد:
0.0
3.5
static_files = {
'/static': './public',
'': {'filename': 'image.gif', 'content_type': 'text/plain'},
}
0u
0u
دیکشنری پیکربندی فایل‌های ایستا به عنوان آرگومان static_files به
کلاس‌های socketio.WSGIApp یا socketio.ASGIApp داده می‌شود:
0.0
3.5
# 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)
0u
0u
اولویت مسیریابی در این دو کلاس به شرح زیر است:
0.0.IP
ابتدا، مسیر در برابر endpoint مربوط به Socket.IO بررسی می‌شود.
• 2
سپس در صورت وجود، مسیر با پیکربندی فایل‌های ایستا (static file) سنجیده می‌شود.
• 2
اگر مسیر با endpoint پروتکل Socket.IO یا هیچ فایل ایستایی مطابقت نداشت، در صورت پیکربندی، کنترل به برنامه ثانویه واگذار می‌شود؛ در غیر این صورت خطای 404 بازگردانده می‌شود.
0u
نکته: ارائه فایل‌های ایستا تنها برای مقاصد توسعه در نظر گرفته شده است و به همین دلیل فاقد قابلیت‌های مهمی مانند حافظه نهان (caching) است. از آن در محیط عملیاتی (production) استفاده نکنید.
"رویدادها (Events)"
پروتکل Socket.IO رویدادمحور است. هنگامی که یک کلاینت قصد برقراری ارتباط با سرور را دارد، یا سرور می‌خواهد با یک یا چند کلاینت ارتباط برقرار کند، رویدادی را برای طرف مقابل ارسال (emit) می‌کند. هر رویداد دارای یک نام و فهرستی اختیاری از آرگومان‌ها است.
"شنود رویدادها (Listening to Events)"
برای دریافت رویدادها از کلاینت‌ها، برنامه سمت سرور باید توابع گرداننده رویداد (event handler) را ثبت کند. این توابع زمانی که رویدادهای مربوطه توسط کلاینت‌ها ارسال می‌شوند، فراخوانی می‌گردند. برای ثبت یک گرداننده برای یک رویداد، دکوراتورهای
socketio.Server.event() <#socketio.Server.event> یا socketio.Server.on() <#socketio.Server.on> به کار می‌روند:
0.0
3.5
@sio.event
def my_event(sid, data):
pass
@sio.on('my custom event')
def another_event(sid, data):
pass
0u
0u
در مثال نخست، نام رویداد از نام تابع گرداننده گرفته می‌شود. مثال دوم کمی مفصل‌تر است، اما این امکان را فراهم می‌کند که نام رویداد با نام تابع تفاوت داشته باشد یا شامل نویسه‌هایی مانند فاصله باشد که در نام توابع غیرمجاز هستند.
برای سرورهای مبتنی بر asyncio، گرداننده‌های رویداد را می‌توان به صورت اختیاری به عنوان کوروتین (coroutine) تعریف کرد:
0.0
3.5
@sio.event
async def my_event(sid, data):
pass
0u
0u
آرگومان sid که به تمام گرداننده‌ها ارسال می‌شود، شناسه نشست (session id) در Socket.IO است؛ شناسه‌ای یکتا که Socket.IO به هر اتصال کلاینت اختصاص می‌دهد. تمامی رویدادهای ارسال‌شده توسط یک کلاینت مشخص، مقدار sid یکسانی خواهند داشت.
"رویدادهای اتصال و قطع اتصال (Connect and Disconnect Events)"
رویدادهای connect و disconnect رویدادهای ویژه‌ای هستند؛ این رویدادها هنگامی که کلاینت به سرور متصل یا اتصال آن قطع می‌شود، به طور خودکار فراخوانی می‌گردند:
0.0
3.5
@sio.event
def connect(sid, environ, auth):
print('connect ', sid)
@sio.event
def disconnect(sid, reason):
print('disconnect ', sid, reason)
0u
0u
رویداد connect بستری ایده‌آل برای انجام احراز هویت کاربر و هرگونه نگاشت لازم میان هویت‌های کاربر در برنامه و sid اختصاص‌یافته به کلاینت است.
علاوه بر sid، گرداننده اتصال آرگومان environ را نیز دریافت می‌کند که دربردارنده اطلاعات درخواست در قالب استاندارد WSGI به همراه هدرهای HTTP است. این گرداننده همچنین آرگومان auth را به همراه هرگونه جزئیات احراز هویت ارائه‌شده توسط کلاینت، یا در صورت عدم ارسال آن، مقدار None را دریافت می‌کند.
پس از بررسی آرگومان‌ها، گرداننده رویداد connect می‌تواند برای رد اتصال کلاینت مقدار False را بازگرداند. در مواردی ارسال داده به کلاینتِ رد شده سودمند است؛ در چنین شرایطی به جای بازگرداندن False می‌توان استثنای
socketio.exceptions.ConnectionRefusedError <#socketio.exceptions.ConnectionRefusedError> را صادر (raise) کرد،
و تمام آرگومان‌های آن به همراه پیام رد شدن برای کلاینت فرستاده خواهد شد:
0.0
3.5
from socketio.exceptions import ConnectionRefusedError
@sio.event
def connect(sid, environ, auth):
raise ConnectionRefusedError('authentication failed')
0u
0u
گرداننده قطع اتصال مقدار sid اختصاص‌یافته به کلاینت و آرگومان reason را که علت قطع اتصال را مشخص می‌کند، دریافت می‌نماید:
0.0
3.5
@sio.event
def disconnect(sid, reason):
if reason == sio.reason.CLIENT_DISCONNECT:
print('the client disconnected')
elif reason == sio.reason.SERVER_DISCONNECT:
print('the server disconnected the client')
else:
print('disconnect reason:', reason)
0u
0u
برای مشاهده فهرستی از دلایل احتمالی قطع اتصال، صفت socketio.Server.reason <#socketio.Server.reason> را ببینید..SS گرداننده‌های رویداد همه‌گیر (Catch-All Event Handlers)
یک گرداننده رویداد «همه‌گیر» (catch-all) برای تمام رویدادهایی که گرداننده مشخصی ندارند فراخوانی می‌شود. شما می‌توانید با استفاده از *''** به عنوان نام رویداد، یک گرداننده همه‌گیر تعریف کنید:
0.0
3.5
@sio.on('*')
def any_event(event, sid, data):
pass
0u
0u
سرورهای Asyncio همچنین می‌توانند از یک کوروتین (coroutine) استفاده کنند:
0.0
3.5
@sio.on('*')
async def any_event(event, sid, data):
pass
0u
0u
یک گرداننده رویداد همه‌گیر، نام رویداد را به عنوان نخستین آرگومان دریافت می‌کند. باقی آرگومان‌ها همانند یک گرداننده رویداد معمولی هستند.
توجه داشته باشید که رویدادهای connect و disconnect باید به‌طور صریح تعریف شوند و توسط گرداننده رویداد همه‌گیر فراخوانی نمی‌شوند.
ارسال رویدادها به کلاینت‌ها (Emitting Events to Clients)
پروتکل Socket.IO یک پروتکل دوطرفه است؛ بنابراین سرور در هر زمان می‌تواند رویدادی را به کلاینت‌های متصل خود ارسال کند. متد socketio.Server.emit() <#socketio.Server.emit> برای این منظور به کار می‌رود:
0.0
3.5
sio.emit('my event', {'data': 'foobar'})
0u
0u
نخستین آرگومان، نام رویداد است و پس از آن یک بارداده اختیاری از نوع str، bytes، list، dict یا tuple قرار می‌گیرد. هنگام ارسال یک list، dict یا tuple، عناصر آن‌ها نیز به همین انواع داده محدود هستند. هنگامی که یک tuple ارسال می‌شود، عناصر آن به عنوان چندین آرگومان به تابع گرداننده رویداد در سمت کلاینت تحویل داده خواهند شد.
مثال بالا رویداد را به تمامی کلاینت‌های متصل ارسال می‌کند. گاهی ممکن است سرور بخواهد رویدادی را تنها به یک کلاینت خاص ارسال کند. این امر با افزودن آرگومان to با مقدار sid کلاینت به فراخوانی emit امکان‌پذیر است:
0.0
3.5
sio.emit('my event', {'data': 'foobar'}, to=user_sid)
0u
0u
آرگومان to برای شناسایی کلاینتی که باید رویداد را دریافت کند استفاده می‌شود و مقدار آن برابر با sid اختصاص‌یافته به اتصال آن کلاینت با سرور تنظیم می‌گردد. در صورت حذف to، رویداد برای تمامی کلاینت‌های متصل همه‌پخشی (broadcast) می‌شود.
تصدیق رویدادها (Acknowledging Events)
هنگامی که کلاینت رویدادی را به سرور ارسال می‌کند، می‌تواند به‌صورت اختیاری درخواست دریافت تصدیق (acknowledgment) از سرور را داشته باشد. ارسال پیام‌های تصدیق به‌صورت خودکار توسط سرور Socket.IO مدیریت می‌شود، اما تابع گرداننده رویداد می‌تواند صرفاً با بازگرداندن مجموعه‌ای از مقادیر، آن‌ها را همراه با تصدیق به کلاینت منتقل کند:
0.0
3.5
@sio.event
def my_event(sid, data):
# handle the message
return "OK", 123 # <-- client will have these as acknowledgement
0u
مشابه حالتی که کلاینت‌ها می‌توانند از سرور درخواست تأییدیه (acknowledgement) کنند، زمانی که
سرور رویدادی را برای یک کلاینت تکی ارسال (emit) می‌کند نیز می‌تواند از کلاینت بخواهد دریافت
رویداد را تأیید کند و به‌صورت اختیاری یک یا چند مقدار را به عنوان پاسخ بازگرداند.
سرور Socket.IO از دو روش برای کار با تأییدیه‌های کلاینت پشتیبانی می‌کند.
راحت‌ترین روش، جایگزین کردن socketio.Server.emit() <#socketio.Server.emit> با
socketio.Server.call() <#socketio.Server.call> است. متد call() رویداد را ارسال کرده و
سپس تا زمان ارسال تأییدیه توسط کلاینت منتظر می‌ماند، و هر مقداری را که توسط
کلاینت ارائه شود بازمی‌گرداند:
0.0
3.5
response = sio.call('my event', {'data': 'foobar'}, to=user_sid)
0u
0u
یک راهکار بسیار ابتدایی‌تر برای تأییدیه، استفاده از توابع بازخوانی (callback) است. متد
socketio.Server.emit() <#socketio.Server.emit> دارای یک آرگومان اختیاری callback است که
می‌تواند روی یک شیء فراخوان‌پذیر (callable) تنظیم شود. اگر این آرگومان داده شود، شیء فراخوان‌پذیر
پس از پردازش رویداد توسط کلاینت فراخوانی خواهد شد و مقادیر بازگردانده‌شده توسط کلاینت
به عنوان آرگومان به این تابع ارسال می‌شوند:
0.0
3.5
def my_callback():
print("callback invoked!")
sio.emit('my event', {'data': 'foobar'}, to=user_sid, callback=my_callback)
0u
0u
"اتاق‌ها (Rooms)"
برای سهولت در ارسال رویدادها توسط سرور به گروه‌هایی از کلاینت‌های مرتبط،
برنامه کاربردی می‌تواند کلاینت‌های خود را در "اتاق‌ها" (rooms) قرار دهد و سپس پیام‌ها را به
این اتاق‌ها ارسال کند.
در مثال‌های قبلی، آرگومان to در متد socketio.SocketIO.emit()
برای مشخص کردن یک کلاینت خاص به عنوان گیرنده رویداد استفاده می‌شد.
به آرگومان to همچنین می‌توان نام یک اتاق را اختصاص داد، تا تمام کلاینت‌های حاضر در
آن اتاق، رویداد را دریافت کنند.
برنامه کاربردی می‌تواند به هر تعداد که لازم است اتاق ایجاد کند و با استفاده از متدهای
socketio.Server.enter_room() <#socketio.Server.enter_room> و
socketio.Server.leave_room() <#socketio.Server.leave_room> کلاینت‌های حاضر در آن‌ها را
مدیریت کند. کلاینت‌ها می‌توانند در هر تعداد اتاق که نیاز باشد عضو شوند و در صورت لزوم بین
اتاق‌ها جابه‌جا گردند.
0.0
3.5
@sio.event
def begin_chat(sid):
sio.enter_room(sid, 'chat_users')
@sio.event
def exit_chat(sid):
sio.leave_room(sid, 'chat_users')
0u
0u
در برنامه‌های گفتگو (chat)، اغلب مطلوب است که یک رویداد به تمام اعضای اتاق به جز
یک نفر (که مبدأ و ارسال‌کننده رویداد مانند پیام چت است) همه‌پخشی (broadcast) شود. متد
socketio.Server.emit() <#socketio.Server.emit> یک آرگومان اختیاری skip_sid را
ارائه می‌دهد تا کلاینتی را که باید در حین همه‌پخشی نادیده گرفته شود مشخص کند.
0.0
3.5
@sio.event
def my_message(sid, data):
sio.emit('my reply', data, room='chat_users', skip_sid=sid)
0u
پروتکل Socket.IO از چندین اتصال منطقی که همگی روی یک اتصال فیزیکی یکسان تسهیم (multiplex) شده‌اند پشتیبانی می‌کند. کلاینت‌ها می‌توانند با تعیین یک namespace متفاوت در هر اتصال، چندین ارتباط را باز کنند. یک فضای نام توسط کلاینت به عنوان یک مسیر پس از نام میزبان و پورت مشخص می‌شود. به عنوان مثال، اتصال به http://example.com:8000/chat اتصالی را به فضای نام /chat باز می‌کند.
هر فضای نام مستقل از سایرین کار می‌کند و دارای شناسه‌های نشست (sidها)، گرداننده‌های رویداد و اتاق‌های مجزا است. فضاهای نام را می‌توان مستقیماً در توابع گرداننده رویداد تعریف کرد، یا اینکه می‌توان آن‌ها را به صورت کلاس ایجاد نمود.
فضاهای نام مبتنی بر دکوراتور (Decorator-Based Namespaces)
فضاهای نام مبتنی بر دکوراتور، همان گرداننده‌های رویداد معمولی هستند که آرگومان namespace را در دکوراتور خود شامل می‌شوند:
0.0
3.5
@sio.event(namespace='/chat')
def my_custom_event(sid, data):
pass
@sio.on('my custom event', namespace='/chat')
def my_custom_event(sid, data):
pass
0u
0u
هنگام گسیل (emit) یک رویداد، از آرگومان اختیاری namespace برای تعیین فضای نامی که رویداد باید روی آن ارسال شود استفاده می‌شود. هنگامی که آرگومان namespace حذف شود، فضای نام پیش‌فرض Socket.IO که / نام دارد، مورد استفاده قرار می‌گیرد.
بسیار مهم است که برنامه‌های استفاده‌کننده از چندین فضای نام، هنگام راه‌اندازی گرداننده‌های رویداد و اتاق‌های خود با استفاده از آرگومان اختیاری namespace، فضای نام صحیح را مشخص کنند. این آرگومان همچنین باید هنگام گسیل رویدادها ذیل یک فضای نام مشخص شود. اکثر متدها در کلاس socketio.Server <#socketio.Server> دارای آرگومان اختیاری namespace هستند.
فضاهای نام مبتنی بر کلاس (Class-Based Namespaces)
به عنوان جایگزینی برای فضاهای نام مبتنی بر دکوراتور، گرداننده‌های رویداد متعلق به یک فضای نام می‌توانند به عنوان متدهایی در یک زیرکلاس از socketio.Namespace <#socketio.Namespace> ایجاد شوند:
0.0
3.5
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('my_response', data)
sio.register_namespace(MyCustomNamespace('/test'))
0u
0u
برای سرورهای مبتنی بر asyncio، فضاهای نام باید از socketio.AsyncNamespace <#socketio.AsyncNamespace> ارث‌بری کنند، و در صورت تمایل می‌توانند گرداننده‌های رویداد را به عنوان کوروتین (coroutine) تعریف نمایند:
0.0
3.5
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('my_response', data)
sio.register_namespace(MyCustomNamespace('/test'))
0u
0u
هنگامی که از فضاهای نام مبتنی بر کلاس استفاده می‌شود، هر رویداد دریافت‌شده توسط سرور به متدی با نام همان رویداد به همراه پیشوند on_ هدایت می‌شود. برای مثال، رویداد my_event توسط متدی به نام on_my_event مدیریت خواهد شد. اگر رویدادی دریافت شود که هیچ متد متناظری برای آن در کلاس فضای نام تعریف نشده باشد، آن رویداد نادیده گرفته می‌شود. تمامی نام‌های رویداد استفاده‌شده در فضاهای نام مبتنی بر کلاس باید از نویسه‌هایی استفاده کنند که در نام متدها مجاز هستند.
جهت سهولت برای متدهای تعریف‌شده در یک فضای نام مبتنی بر کلاس، نمونه‌ی فضای نام شامل نسخه‌هایی از چندین متد از کلاس‌های socketio.Server <#socketio.Server> و socketio.AsyncServer <#socketio.AsyncServer> است که در صورت ارائه نشدن آرگومان namespace، به طور پیش‌فرض از فضای نام مربوطه استفاده می‌کنند.
در صورتی که یک رویداد دارای یک گرداننده در فضای نام مبتنی بر کلاس باشد و همچنین یک تابع گرداننده مبتنی بر دکوراتور داشته باشد، تنها تابع گرداننده‌ی مستقل فراخوانی می‌شود.
توجه به این نکته مهم است که فضاهای نام مبتنی بر کلاس به صورت یگانه‌الگو (singleton) هستند. این بدان معناست که یک نمونه‌ی واحد از کلاس فضای نام برای تمامی کلاینت‌ها استفاده می‌شود، و در نتیجه، از یک نمونه‌ی فضای نام نمی‌توان برای ذخیره اطلاعات خاص هر کلاینت استفاده کرد..SS فضاهای نام همه‌گیر (Catch-All Namespaces)
همانند گرداننده‌های رویداد همه‌گیر (catch-all)، هنگام تعریف گرداننده‌های رویداد برای هر فضای نام متصلی که گرداننده رویدادِ صریحاً تعریف‌شده‌ای ندارد، می‌توان از یک فضای نام «همه‌گیر» ("catch-all") استفاده کرد. مانند رویدادهای همه‌گیر، از *''** به‌جای فضای نام استفاده می‌شود:
0.0
3.5
@sio.on('my_event', namespace='*')
def my_event_any_namespace(namespace, sid, data):
pass
0u
0u
برای این رویدادها، فضای نام به‌عنوان نخستین آرگومان ارسال می‌شود و به‌دنبال آن، آرگومان‌های معمول رویداد قرار می‌گیرند.
یک گرداننده فضای نامِ مبتنی بر کلاس از نوع همه‌گیر (catch-all) را می‌توان با ارسال *''** به‌عنوان فضای نام در هنگام ثبت (registration) تعریف کرد:
0.0
3.5
sio.register_namespace(MyCustomNamespace('*'))
0u
0u
یک گرداننده «همه‌گیر» ("catch-all") برای تمام رویدادها در تمام فضاهای نام را می‌توان به‌صورت زیر تعریف کرد:
0.0
3.5
@sio.on('', namespace='')
def any_event_any_namespace(event, namespace, sid, data):
pass
0u
0u
گرداننده‌های رویداد با رویدادها و فضاهای نام همه‌گیر، نام رویداد و فضای نام را به‌عنوان آرگومان‌های اول و دوم دریافت می‌کنند.
نشست‌های کاربر (User Sessions)
سرور می‌تواند اطلاعات مختص برنامه را در یک نشست کاربر (user session) اختصاص‌یافته به هر کلاینت متصل نگهداری کند. برنامه‌ها می‌توانند از نشست کاربر برای ذخیره هرگونه جزئیات درباره کاربر که باید در طول عمر اتصال حفظ شود (مانند نام‌های کاربری یا شناسه کاربری)، استفاده کنند.
متدهای save_session() و get_session() برای ذخیره و بازیابی اطلاعات در نشست کاربر استفاده می‌شوند:
0.0
3.5
@sio.event
def connect(sid, environ):
username = authenticate_user(environ)
sio.save_session(sid, {'username': username})
@sio.event
def message(sid, data):
session = sio.get_session(sid)
print('message from ', session['username'])
0u
0u
برای سرور asyncio، این متدها از نوع کوروتین (coroutine) هستند:
0.0
3.5
@sio.event
async def connect(sid, environ):
username = authenticate_user(environ)
await sio.save_session(sid, {'username': username})
@sio.event
async def message(sid, data):
session = await sio.get_session(sid)
print('message from ', session['username'])
0u
0u
همچنین نشست را می‌توان با استفاده از مدیر زمینه (context manager) session() مدیریت کرد:
0.0
3.5
@sio.event
def connect(sid, environ):
username = authenticate_user(environ)
with sio.session(sid) as session:
session['username'] = username
@sio.event
def message(sid, data):
with sio.session(sid) as session:
print('message from ', session['username'])
0u
0u
برای سرور asyncio، از یک مدیر زمینه ناهمگام (asynchronous context manager) استفاده می‌شود:
0.0
3.5
@sio.event
async def connect(sid, environ):
username = authenticate_user(environ)
async with sio.session(sid) as session:
session['username'] = username
@sio.event
async def message(sid, data):
async with sio.session(sid) as session:
print('message from ', session['username'])
0u
0u
متدهای get_session()، save_session() و session() یک آرگومان اختیاری namespace می‌پذیرند. اگر این آرگومان ارائه نشود، نشست به فضای نام پیش‌فرض متصل می‌شود.
نکته: محتویات نشست کاربر با قطع اتصال کلاینت از بین می‌رود. به‌ویژه، هنگامی که یک کلاینت پس از قطعی غیرمنتظره دوباره به سرور متصل می‌شود، محتویات نشست کاربر حفظ نمی‌گردد..SS کنترل‌های مبدأ متقابل (Cross-Origin Controls)
به دلایل امنیتی، این سرور به‌طور پیش‌فرض سیاست همانند‌مبدأ (same-origin policy) را اعمال می‌کند. در عمل، این موضوع بیانگر موارد زیر است:
0.0
• 2
اگر یک درخواست ورودی HTTP یا WebSocket حاوی سرآیند Origin باشد، این سرآیند باید با طرحواره (scheme) و میزبان (host) نشانی URL اتصال مطابقت داشته باشد. در صورت عدم تطابق، پاسخی با کد وضعیت 400 بازگردانده شده و اتصال رد می‌شود.
• 2
هیچ محدودیتی بر روی درخواست‌های ورودی که فاقد سرآیند Origin هستند اعمال نمی‌شود.
0u
در صورت نیاز، می‌توان از گزینه cors_allowed_origins برای مجاز کردن سایر مبدأها استفاده کرد. این آرگومان می‌تواند روی یک رشته برای تنظیم یک مبدأ مجاز واحد، یا روی یک فهرست برای مجاز کردن چندین مبدأ تنظیم شود. مقدار ویژه *''** می‌تواند برای دستور دادن به سرور جهت مجاز کردن همه مبدأها استفاده شود، اما این کار باید با احتیاط انجام گیرد، زیرا می‌تواند سرور را در برابر حملات جعل درخواست میان‌وب‌گاهی (CSRF) آسیب‌پذیر کند.
پایش و مدیریت (Monitoring and Administration)
سرور Socket.IO می‌تواند به‌گونه‌ای پیکربندی شود که اتصالات را از رابط کاربری رسمی Socket.IO Admin UI https://socket.io/docs/v4/admin-ui بپذیرد. این ابزار اطلاعات بی‌درنگی را درباره کلاینت‌های متصل فعلی، اتاق‌های در حال استفاده و رویدادهای در حال انتشار ارائه می‌دهد. همچنین به یک مدیر امکان می‌دهد رویدادها را به صورت دستی منتشر کرده، تخصیص اتاق‌ها را تغییر دهد و اتصال کلاینت‌ها را قطع کند. نسخه میزبانی‌شده این ابزار در https://admin.socket.io در دسترس است.
با توجه به اینکه فعال‌سازی این قابلیت می‌تواند بر عملکرد سرور تأثیر بگذارد، به‌طور پیش‌فرض غیرفعال است. برای فعال کردن آن، متد
instrument() <#socketio.Server.instrument> را فراخوانی کنید. برای مثال:
0.0
3.5
import os
import socketio
sio = socketio.Server(cors_allowed_origins=[
'http://localhost:5000',
'https://admin.socket.io',
])
sio.instrument(auth={
'username': 'admin',
'password': os.environ['ADMIN_PASSWORD'],
})
0u
0u
این پیکربندی، سرور را برای پذیرش اتصالات از کلاینت میزبانی‌شده Admin UI تنظیم می‌کند. مدیران سپس می‌توانند https://admin.socket.io را در مرورگر وب خود باز کرده و با نام کاربری admin و گذرواژه ارائه‌شده توسط متغیر محیطی ADMIN_PASSWORD وارد شوند. برای اطمینان از اینکه رابط کاربری Admin UI مجاز به برقراری اتصال است، CORS نیز پیکربندی شده است.
برای اطلاع از سایر گزینه‌های پیکربندی موجود، به مستندات مرجع مراجعه کنید.
اشکال‌زدایی و عیب‌یابی (Debugging and Troubleshooting)
برای کمک به شما در اشکال‌زدایی مشکلات، سرور را می‌توان طوری پیکربندی کرد که لاگ‌ها را در پایانه نمایش دهد:
0.0
3.5
import socketio
# standard Python
sio = socketio.Server(logger=True, engineio_logger=True)
# asyncio
sio = socketio.AsyncServer(logger=True, engineio_logger=True)
0u
0u
آرگومان logger گزارش‌گیری مربوط به پروتکل Socket.IO را کنترل می‌کند، در حالی که engineio_logger گزارش‌هایی را کنترل می‌کند که از لایه انتقال سطح‌پایین Engine.IO سرچشمه می‌گیرند. مقدار ارائه‌شده به این آرگومان‌ها رفتار ثبت گزارش را تعیین می‌کند:
0.0
• 2
True: ارسال لاگ به خروجی stderr در سطح INFO را فعال می‌کند.
• 2
False: ارسال لاگ به خروجی stderr در سطح ERROR را فعال می‌کند. این حالت پیش‌فرض است.
• 2
یک نمونه از logging.Logger: از لاگر ارائه‌شده بدون پیکربندی اضافی استفاده می‌کند.
0u
ثبت گزارش می‌تواند به شناسایی علت مشکلات اتصال، پاسخ‌های 400، عملکرد ضعیف و سایر خطاها کمک کند..SS "همزمانی و یکپارچه‌سازی وب‌سرور (Concurrency and Web Server Integration)"
سرور Socket.IO بسته به نیازهای برنامه و وب‌سرور مورد استفاده، می‌تواند با مدل‌های
همزمانی متفاوتی پیکربندی شود. مدل همزمانی از طریق آرگومان async_mode در
سرور مشخص می‌شود. برای مثال:
0.0
3.5
sio = socketio.Server(async_mode='threading')
0u
0u
زیربخش‌های زیر گزینه‌های همزمانی موجود را برای سرورهای همگام (synchronous) و
ناهمگام (asynchronous) شرح می‌دهند.
"حالت‌های استاندارد (Standard Modes)"
0.0
• 2
threading: سرور از رشته‌های (threads) پایتون برای همزمانی استفاده خواهد کرد
و روی هر وب‌سرور چندرشته‌ای WSGI اجرا خواهد شد. این حالت در صورتی که هیچ کتابخانه
همزمانی دیگری نصب نشده باشد، حالت پیش‌فرض است.
• 2
gevent: سرور از گرین‌لت‌ها (greenlets) از طریق کتابخانه
gevent http://www.gevent.org برای همزمانی استفاده خواهد کرد. وب‌سروری که
با gevent سازگار باشد مورد نیاز است.
• 2
gevent_uwsgi: گونه‌ای از حالت gevent که برای کار با وب‌سرور
uWSGI https://uwsgi-docs.readthedocs.io/en/latest طراحی شده است.
• 2
eventlet: سرور از گرین‌لت‌ها از طریق کتابخانه
eventlet http://eventlet.net برای همزمانی استفاده خواهد کرد. وب‌سروری که
با eventlet سازگار باشد مورد نیاز است. استفاده از eventlet به دلیل
قرار داشتن این پروژه در حالت نگهداری، توصیه نمی‌شود.
0u
"حالت‌های ناهمگام (Asyncio Modes)"
گزینه‌های ناهمگام همگی بر پایه بسته
asyncio https://docs.python.org/3/library/asyncio.html از
کتابخانه استاندارد پایتون، با تغییرات جزئی بسته به بستر وب‌سرور مورد استفاده،
عمل می‌کنند.
0.0
• 2
asgi: استفاده از هر وب‌سرور
ASGI https://asgi.readthedocs.io/en/latest الزامی است.
• 2
aiohttp: استفاده از چارچوب وب و سرور aiohttp http://aiohttp.readthedocs.io
الزامی است.
• 2
tornado: استفاده از چارچوب وب و سرور Tornado http://www.tornadoweb.org
الزامی است.
• 2
sanic: استفاده از چارچوب وب و سرور Sanic http://sanic.readthedocs.io
الزامی است. هنگام استفاده از Sanic، توصیه می‌شود به جای آن از حالت asgi
استفاده شود.
0u
"راهبردهای استقرار (Deployment Strategies)"
بخش‌های زیر انواع مختلفی از راهبردهای استقرار را برای سرورهای Socket.IO شرح می‌دهند.
Gunicorn
ساده‌ترین راهبرد استقرار برای سرور Socket.IO استفاده از وب‌سرور محبوب
Gunicorn http://gunicorn.org در حالت چندرشته‌ای است. سرور Socket.IO
باید درون کلاس socketio.WSGIApp <#socketio.WSGIApp> قرار گیرد
تا با پروتکل WSGI سازگار شود:
0.0
3.5
sio = socketio.Server(async_mode='threading')
app = socketio.WSGIApp(sio)
0u
0u
در صورت تمایل، کلاس socketio.WSGIApp می‌تواند ترافیکی را که متعلق به
Socket.IO نیست به یک برنامه کاربردی WSGI دیگر هدایت کند؛ این ویژگی استقرار
یک برنامه وب استاندارد WSGI (توسعه‌یافته با چارچوب‌هایی نظیر Flask یا Django)
و سرور Socket.IO را به‌صورت یک بسته واحد امکان‌پذیر می‌سازد:
0.0
3.5
sio = socketio.Server(async_mode='threading')
app = socketio.WSGIApp(sio, other_wsgi_app)
0u
0u
مثال زیر نحوه راه‌اندازی یک برنامه Socket.IO را با استفاده از کلاس ورکر
چندرشته‌ای Gunicorn نشان می‌دهد:
0.0
3.5
$ gunicorn --workers 1 --threads 100 --bind 127.0.0.1:5000 module:app
0u
0u
با پیکربندی فوق، سرور قادر خواهد بود نزدیک به ۱۰۰ کلاینت همزمان را مدیریت کند.
همچنین امکان استفاده از بیش از یک فرایند ورکر (worker) وجود دارد، اما این حالت
نیازمند دو شرط زیر است:
0.0
• 2
کلاینت‌ها باید مستقیماً از طریق WebSocket متصل شوند. روش انتقال
long-polling با شیوه توزیع بار (load balancing) درخواست‌ها توسط Gunicorn میان
ورکرها ناسازگار است. برای غیرفعال کردن long-polling در سرور، آرگومان
transports=['websocket'] را در سازنده سرور اضافه کنید. کلاینت‌ها نیز
گزینه مشابهی برای برقراری اتصال از طریق WebSocket خواهند داشت.
• 2
نمونه‌های socketio.Server() <#socketio.Server> در هر ورکر باید با
یک صف پیام (message queue) پیکربندی شوند تا ورکرها بتوانند با یکدیگر ارتباط
برقرار کنند. برای اطلاعات بیشتر، بخش Using a Message Queue را ببینید.
0u
هنگام استفاده از چندین ورکر، تعداد تقریبی اتصالاتی که سرور قادر به پذیرش آن‌ها
خواهد بود از ضرب تعداد ورکرها در تعداد رشته‌ها به ازای هر ورکر محاسبه می‌شود.
توجه داشته باشید که Gunicorn می‌تواند در کنار uvicorn، gevent و
eventlet نیز استفاده شود. این گزینه‌ها در بخش‌های مربوطه در ادامه بررسی
شده‌اند..SS Uvicorn (و سایر وب‌سرورهای ASGI)
هنگام کار با یک سرور ناهمگام Socket.IO، ساده‌ترین راهبرد استقرار استفاده از یک وب‌سرور ASGI مانند
Uvicorn https://www.uvicorn.org است.
کلاس socketio.ASGIApp یک برنامه سازگار با ASGI است که می‌تواند ترافیک Socket.IO را به یک نمونه socketio.AsyncServer هدایت کند:
0.0
3.5
sio = socketio.AsyncServer(async_mode='asgi')
app = socketio.ASGIApp(sio)
0u
0u
در صورت تمایل، کلاس socketio.ASGIApp می‌تواند هرگونه ترافیکی را که مربوط به Socket.IO نیست به یک برنامه ASGI دیگر هدایت کند؛ این قابلیت امکان استقرار یک برنامه وب استاندارد ASGI ساخته‌شده با فریم‌ورک‌هایی مانند FastAPI به همراه سرور Socket.IO را در قالب یک بسته واحد فراهم می‌سازد:
0.0
3.5
sio = socketio.AsyncServer(async_mode='asgi')
app = socketio.ASGIApp(sio, other_asgi_app)
0u
0u
مثال زیر برنامه را با Uvicorn اجرا می‌کند:
0.0
3.5
uvicorn --port 5000 module:app
0u
0u
همچنین می‌توان Uvicorn را از طریق worker مربوط به Gunicorn استفاده کرد:
0.0
3.5
gunicorn --workers 1 --worker-class uvicorn.workers.UvicornWorker --bind 127.0.0.1:5000
0u
0u
برای اطلاعات در مورد نحوه استفاده از Gunicorn با چند worker، به بخش Gunicorn در بالا مراجعه کنید.
Hypercorn، Daphne و سایر سرورهای ASGI
برای استفاده از یک وب‌سرور ASGI به غیر از Uvicorn، برنامه را همان‌طور که در بالا برای Uvicorn نشان داده شد برای ASGI پیکربندی کرده و سپس مطابق مستندات وب‌سرور انتخابی خود، برنامه را راه‌اندازی کنید.
Aiohttp
گزینه دیگر برای استقرار یک سرور ناهمگام Socket.IO، استفاده از وب‌سرور و فریم‌ورک تحت وب Aiohttp http://aiohttp.readthedocs.io است. در صورت نصب بودن کتابخانه، نمونه‌های کلاس socketio.AsyncServer به‌طور خودکار از Aiohttp استفاده خواهند کرد. برای درخواست صریح استفاده از آن، می‌توان گزینه async_mode را در سازنده مشخص کرد:
0.0
3.5
sio = socketio.AsyncServer(async_mode='aiohttp')
0u
0u
سروری که برای Aiohttp پیکربندی شده است باید به یک برنامه موجود متصل (attach) شود:
0.0
3.5
app = web.Application()
sio.attach(app)
0u
0u
برنامه Aiohttp می‌تواند مسیرهای معمولی تعریف کند که در کنار سرور Socket.IO همزیستی داشته باشند. یک الگوی رایج، افزودن مسیرهایی است که یک برنامه کلاینت و فایل‌های استاتیک مرتبط را سرویس‌دهی می‌کنند.
سپس برنامه Aiohttp به شیوه معمول اجرا می‌شود:
0.0
3.5
if __name__ == '__main__':
web.run_app(app)
0u
هنگامی که یک وب‌سرور چندنخی قادر به برآوردن نیازهای همزمانی و مقیاس‌پذیری برنامه نباشد، گزینه‌ای که می‌توان آزمود
Gevent http://www.gevent.org است. Gevent یک کتابخانه همزمانی مبتنی بر هم‌روال (coroutine)
بر پایه greenletها است که به‌طور قابل‌توجهی از نخ‌ها (threads) سبک‌تر هستند.
نمونه‌های کلاس socketio.Server در صورت نصب بودن کتابخانه، به‌طور خودکار از Gevent استفاده خواهند کرد. برای درخواست صریح Gevent،
می‌توان گزینه async_mode را در سازنده مشخص کرد:
0.0
3.5
sio = socketio.Server(async_mode='gevent')
0u
0u
کارساز Socket.IO باید توسط کلاس socketio.WSGIApp <#socketio.WSGIApp> دربرگرفته (wrap) شود
تا با پروتکل WSGI سازگار باشد:
0.0
3.5
app = socketio.WSGIApp(sio)
0u
0u
در صورت تمایل، کلاس socketio.WSGIApp می‌تواند هر ترافیکی را که متعلق به Socket.IO نیست
به یک برنامه WSGI دیگر هدایت کند؛ این امر امکان استقرار همزمان یک برنامه وب استاندارد WSGI ساخته‌شده با چارچوب‌هایی
نظیر Flask یا Django را به همراه کارساز Socket.IO به‌صورت یک بسته واحد فراهم می‌سازد:
0.0
3.5
sio = socketio.Server(async_mode='gevent')
app = socketio.WSGIApp(sio, other_wsgi_app)
0u
0u
کارساز پیکربندی‌شده برای Gevent، با استفاده از socketio.WSGIApp ارائه‌شده
مانند یک برنامه معمولی WSGI مستقر می‌شود:
0.0
3.5
from gevent import pywsgi
pywsgi.WSGIServer(('', 8000), app).serve_forever()
0u
0u
Gevent با Gunicorn
یک راهکار جایگزین به‌جای اجرای کارساز WSGI به شکل بالا، استفاده از
Gunicorn <gunicorn.org> به همراه ورکر Gevent آن است. دستور راه‌اندازی
برنامه تحت Gunicorn و Gevent در زیر نشان داده شده است:
0.0
3.5
$ gunicorn -k gevent -w 1 -b 127.0.0.1:5000 module:app
0u
0u
برای اطلاعات در مورد نحوه استفاده از Gunicorn با چند ورکر، به بخش Gunicorn در بالا مراجعه کنید.
کتابخانه Gevent تابع monkey_patch() را ارائه می‌دهد که تمام توابع مسدودکننده (blocking)
در کتابخانه استاندارد را با نسخه‌های ناهمگام معادل جایگزین می‌کند. گرچه کارساز Socket.IO نیازی به monkey patching ندارد،
اما احتمالاً سایر کتابخانه‌ها مانند گرداننده‌های پایگاه‌داده یا صف‌های پیام به آن نیاز خواهند داشت.
Gevent با uWSGI
هنگام استفاده از کارساز uWSGI در ترکیب با gevent، کارساز Socket.IO می‌تواند
از پشتیبانی بومی uWSGI از WebSocket بهره ببرد.
نمونه‌های کلاس socketio.Server در صورتی که هر دو بسته gevent و uWSGI نصب شده و eventlet نصب نشده باشد،
به‌طور خودکار از این گزینه برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریح این حالت ناهمگام،
می‌توان گزینه async_mode را در سازنده مشخص کرد:
0.0
3.5
# gevent with uWSGI
sio = socketio.Server(async_mode='gevent_uwsgi')
0u
0u
توضیح کامل پیکربندی و نحوه استفاده از کارساز uWSGI خارج از دامنه این مستندات است.
کارساز uWSGI بسته‌ای نسبتاً پیچیده است که مجموعه گسترده و جامعی از گزینه‌ها را ارائه می‌دهد.
برای این‌که انتقال از طریق WebSocket در دسترس باشد، باید با پشتیبانی از WebSocket و SSL کامپایل شده باشد.
به عنوان مقدمه، دستور زیر یک کارساز uWSGI را برای مثال latency.py روی درگاه 5000 راه‌اندازی می‌کند:
0.0
3.5
$ uwsgi --http :5000 --gevent 1000 --http-websockets --master --wsgi-file latency.py --callable app
0u
در صورتی که کتابخانه نصب باشد، نمونه‌های کلاس socketio.AsyncServer به طور خودکار از Tornado http://www.tornadoweb.org استفاده خواهند کرد. برای درخواست صریح استفاده از آن، می‌توان گزینه async_mode را در سازنده مشخص کرد:
0.0
3.5
sio = socketio.AsyncServer(async_mode='tornado')
0u
0u
سروری که برای Tornado پیکربندی شده است باید شامل یک request handler برای Socket.IO باشد:
0.0
3.5
app = tornado.web.Application(
[
(r"/socket.io/", socketio.get_tornado_handler(sio)),
],
# ... other application options
)
0u
0u
برنامه Tornado می‌تواند مسیرهای دیگری را نیز تعریف کند که در کنار سرور Socket.IO همزیستی داشته باشند. یک الگوی رایج، افزودن مسیرهایی است که یک برنامه کلاینت و فایل‌های ایستای (static) مربوط به آن را ارائه می‌دهند.
سپس برنامه Tornado به شیوه معمول اجرا می‌شود:
0.0
3.5
app.listen(port)
tornado.ioloop.IOLoop.current().start()
0u
0u
Eventlet
نکته:
0.0
3.5
پروژه Eventlet دیگر تحت توسعه فعال نیست و به همین دلیل، توصیه فعلی این است که از آن برای پروژه‌های جدید استفاده نشود.
0u
0u
بسته http://eventlet.net Eventlet یک کتابخانه شبکه همروند با کارایی بالا برای Python است که از کوروتین‌ها (coroutines) استفاده می‌کند و امکان نوشتن کد را به همان شیوه مورد استفاده در توابع مسدودکننده کتابخانه استاندارد فراهم می‌سازد. یک سرور Socket.IO که با eventlet مستقر شده باشد، به شیوه‌های انتقال (transports) مبتنی بر long-polling و WebSocket دسترسی دارد.
در صورتی که کتابخانه نصب باشد، نمونه‌های کلاس socketio.Server به طور خودکار از eventlet برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریح استفاده از آن، می‌توان گزینه async_mode را در سازنده مشخص کرد:
0.0
3.5
sio = socketio.Server(async_mode='eventlet')
0u
0u
سروری که برای eventlet پیکربندی شده است، با استفاده از socketio.WSGIApp ارائه‌شده به عنوان یک برنامه معمولی WSGI مستقر می‌شود:
0.0
3.5
import eventlet
app = socketio.WSGIApp(sio)
eventlet.wsgi.server(eventlet.listen(('', 8000)), app)
0u
یک جایگزین برای اجرای کارساز WSGI مربوط به eventlet مطابق بالا، استفاده از
gunicorn <gunicorn.org> است، که یک وب‌سرور تمام‌عیار و پایتونی خالص (pure Python) می‌باشد.
دستور راه‌اندازی برنامه تحت gunicorn در زیر آورده شده است:
0.0
3.5
$ gunicorn -k eventlet -w 1 module:app
0u
0u
برای اطلاعات درباره نحوه استفاده از Gunicorn با چند worker، بخش Gunicorn را در بالا ببینید.
بسته Eventlet یک تابع monkey_patch() ارائه می‌دهد که تمامی توابع مسدودکننده (blocking)
در کتابخانه استاندارد را با نسخه‌های ناهمگام معادل جایگزین می‌کند. اگرچه
python-socketio نیازی به monkey patching ندارد، سایر کتابخانه‌ها از جمله
درایورهای پایگاه‌داده احتمالاً به آن نیاز خواهند داشت.
Sanic
نکته:
0.0
3.5
یکپارچه‌سازی با Sanic مدت زیادی است که به‌روزرسانی نشده است. در حال حاضر
توصیه می‌شود که برنامه‌های Sanic با یکپارچه‌سازی ASGI مستقر شوند.
0u
0u
استفاده از صف پیام (Message Queue)
هنگام کار با برنامه‌های توزیع‌شده، معمولاً دسترسی به قابلیت‌های
Socket.IO از طریق چند فرآیند ضروری است. دو مورد کاربرد خاص در این زمینه وجود دارد:
0.0
• 2
برنامه‌های با دسترسی‌پذیری بالا (Highly available) ممکن است بخواهند از مقیاس‌پذیری افقی
کارساز Socket.IO استفاده کنند تا قادر به مدیریت تعداد بسیار زیادی از کلاینت‌های هم‌روند باشند.
• 2
برنامه‌هایی که از صف‌های کاری مانند
Celery http://www.celeryproject.org استفاده می‌کنند، ممکن است نیاز داشته باشند پس از اتمام یک وظیفه پس‌زمینه، رویدادی را برای یک کلاینت ارسال (emit) کنند. مناسب‌ترین مکان برای انجام این کار، فرآیند worker است که این وظیفه را پردازش کرده است.
0u
به عنوان راه‌حلی برای مسائل فوق، می‌توان کارساز Socket.IO را به‌گونه‌ای پیکربندی کرد
که برای ارتباط با سایر کارسازهای مرتبط Socket.IO یا workerهای کمکی، به یک صف پیام مانند
Redis http://redis.io یا
RabbitMQ https://www.rabbitmq.com متصل شود.
Redis
برای استفاده از صف پیام Redis، باید یک کلاینت پایتونی Redis نصب شود:
0.0
3.5
# socketio.Server class
pip install redis
0u
0u
صف Redis از طریق کلاس‌های socketio.RedisManager <#socketio.RedisManager> و
socketio.AsyncRedisManager <#socketio.AsyncRedisManager> پیکربندی می‌شود. این کلاس‌ها مستقیماً
به مخزن Redis متصل شده و از قابلیت pub/sub صف استفاده می‌کنند:
0.0
3.5
# socketio.Server class
mgr = socketio.RedisManager('redis://')
sio = socketio.Server(client_manager=mgr)
# socketio.AsyncServer class
mgr = socketio.AsyncRedisManager('redis://')
sio = socketio.AsyncServer(client_manager=mgr)
0u
0u
آرگومان client_manager به کارساز دستور می‌دهد تا به صف پیام مشخص‌شده متصل شده
و با دیگر فرآیندهای متصل به صف هماهنگ شود..SS Kombu
بسته Kombu http://kombu.readthedocs.org/en/latest یک بستهٔ پایتون است که
امکان دسترسی به RabbitMQ و صف‌های پیام بسیار دیگری را فراهم می‌کند. این بسته را
می‌توان با pip نصب کرد:
0.0
3.5
pip install kombu
0u
0u
برای استفاده از RabbitMQ یا سایر صف‌های سازگار با پروتکل AMQP، این تنها
وابستگی لازم است. اما برای سایر صف‌های پیام، Kombu ممکن است به بسته‌های
اضافی نیاز داشته باشد. به عنوان مثال، برای استفاده از صف Redis از طریق Kombu،
بسته پایتون مربوط به Redis نیز باید نصب شود:
0.0
3.5
pip install redis
0u
0u
صف از طریق socketio.KombuManager <#socketio.KombuManager> پیکربندی می‌شود:
0.0
3.5
mgr = socketio.KombuManager('amqp://')
sio = socketio.Server(client_manager=mgr)
0u
0u
نشانی URL اتصالی که به سازندهٔ KombuManager داده می‌شود، مستقیماً به شیء
Connection در Kombu http://kombu.readthedocs.org/en/latest/userguide/connections.html
منتقل می‌شود؛ بنابراین برای کسب اطلاعات درباره نحوه ایجاد URL صحیح برای هر صف پیام،
باید به مستندات Kombu مراجعه کرد.
توجه داشته باشید که Kombu در حال حاضر از asyncio پشتیبانی نمی‌کند، بنابراین نمی‌توان
آن را به همراه کلاس socketio.AsyncServer <#socketio.AsyncServer> به کار برد.
Kafka
از Apache Kafka https://kafka.apache.org از طریق بستهٔ
kafka-python https://kafka-python.readthedocs.io/en/master/index.html
پشتیبانی می‌شود:
0.0
3.5
pip install kafka-python
0u
0u
دسترسی به Kafka از طریق کلاس socketio.KafkaManager <#socketio.KafkaManager>
پیکربندی می‌شود:
0.0
3.5
mgr = socketio.KafkaManager('kafka://')
sio = socketio.Server(client_manager=mgr)
0u
0u
توجه داشته باشید که Kafka در حال حاضر از asyncio پشتیبانی نمی‌کند، بنابراین نمی‌توان
آن را به همراه کلاس socketio.AsyncServer <#socketio.AsyncServer> به کار برد.
AioPika
صف پیام RabbitMQ در برنامه‌های مبتنی بر asyncio از طریق بستهٔ
AioPika https://aio-pika.readthedocs.io/en/latest پشتیبانی می‌شود:
باید aio_pika را با استفاده از pip نصب کنید:
0.0
3.5
pip install aio_pika
0u
0u
صف RabbitMQ از طریق کلاس
socketio.AsyncAioPikaManager <#socketio.AsyncAioPikaManager> پیکربندی می‌شود:
0.0
3.5
mgr = socketio.AsyncAioPikaManager('amqp://')
sio = socketio.AsyncServer(client_manager=mgr)
0u
برای استقرار در محیط عملیاتی، توصیه‌هایی برای حفظ امنیت برنامه شما وجود دارد.
پیش از هر چیز، صف پیام هرگز نباید روی یک رابط شبکه عمومی شنود کند، تا اطمینان حاصل شود که کلاینت‌های خارجی هرگز به آن متصل نمی‌شوند. برای استقرار روی یک تک‌گره، صف باید فقط روی localhost شنود کند. برای یک سیستم چندگره‌ای، استفاده از یک شبکه خصوصی (VPC) که در آن ارتباط بین سرورها بتواند به‌صورت خصوصی انجام شود، به‌شدت توصیه می‌شود.
علاوه بر این، تمام صف‌های پیام از احراز هویت و رمزنگاری پشتیبانی می‌کنند که می‌تواند امنیت استقرار را افزایش دهد. احراز هویت تضمین می‌کند که تنها سرورهای Socket.IO و فرایندهای مرتبط دسترسی دارند، در حالی که رمزنگاری از جمع‌آوری داده‌ها توسط شخص ثالثی که در حال شنود روی شبکه است، جلوگیری می‌کند. اعتبارنامه‌های دسترسی را می‌توان در URLهای اتصالی که به مدیران کلاینت ارسال می‌شوند، لحاظ کرد.
مقیاس‌پذیری افقی (Horizontal Scaling)
پروتکل Socket.IO یک پروتکل با حفظ وضعیت (stateful) است که این امر مقیاس‌پذیری افقی را دشوارتر می‌سازد. هنگام استقرار خوشه‌ای از فرایندهای Socket.IO، تمام فرایندها باید با ارسال آرگومان client_manager به نمونه سرور، به صف پیام متصل شوند. این قابلیت به workerها امکان می‌دهد تا ارتباط برقرار کرده و عملیات پیچیده‌ای نظیر همه‌پخشی‌ها (broadcasts) را هماهنگ کنند.
اگر روش انتقال long-polling استفاده شود، دو پیش‌نیاز دیگر وجود دارد که باید رعایت شوند:
0.0
• 2
هر فرایند Socket.IO باید بتواند چندین درخواست را به‌طور هم‌روند مدیریت کند. این امر به این دلیل لازم است که کلاینت‌های long-polling دو درخواست را به‌صورت موازی ارسال می‌کنند. فرایندهای worker که در یک زمان تنها می‌توانند یک درخواست را مدیریت کنند، پشتیبانی نمی‌شوند.
• 2
توزیع‌کننده بار (load balancer) باید به‌گونه‌ای پیکربندی شود که همیشه درخواست‌های یک کلاینت را به همان فرایند worker هدایت کند، تا همه درخواست‌های ارسالی از یک کلاینت توسط همان گره رسیدگی شوند. توزیع‌کننده‌های بار این مفهوم را sticky sessions یا session affinity می‌نامند.
0u
ارسال رویداد از فرایندهای خارجی (Emitting from external processes)
برای اتصال فرایندی غیر از سرور به صف جهت ارسال پیام، می‌توان از همان کلاس‌های مدیر کلاینت به‌صورت شیءهای مستقل استفاده کرد. در این حالت، آرگومان write_only باید روی True تنظیم شود تا از ایجاد یک ریسه (thread) شنونده که فقط در سرور کاربرد دارد، جلوگیری شود. برای مثال:
0.0
3.5
# connect to the redis queue as an external process
external_sio = socketio.RedisManager('redis://', write_only=True)
# emit an event
external_sio.emit('my event', data={'foo': 'bar'}, room='my room')
0u
0u
یک محدودیت شیء مدیر کلاینت فقط‌نوشتنی (write-only) این است که هنگام ارسال پیام نمی‌تواند فراخوانی‌های بازگشتی (callbacks) را دریافت کند. هنگامی که فرایند خارجی نیاز به دریافت callbackها دارد، استفاده از یک کلاینت برای اتصال به سرور با پشتیبانی خواندن و نوشتن، گزینه بهتری نسبت به یک مدیر کلاینت فقط‌نوشتنی است.
"مرجع API (API REFERENCE)"
کلاینت‌های ساده (Simple Clients)
0.0
class socketio.SimpleClient(args, *kwargs)
یک کلاینت Socket.IO.
این کلاس یک کلاینت وب Socket.IO ساده و در عین حال کاملاً سازگار را با پشتیبانی از روش‌های انتقال websocket و long-polling پیاده‌سازی می‌کند.
آرگومان‌های موضعی (positional) و کلیدواژه‌ای (keyword) ارائه‌شده در سازنده، به شیء زیرین socketio.Client() <#socketio.Client> ارسال می‌شوند.
7.0
call(event, data=None, timeout=60)
ارسال یک رویداد به سرور و انتظار برای پاسخ.
این متد یک ارسال رویداد صادر می‌کند و منتظر می‌ماند تا سرور پاسخ یا تأییدیه‌ای (acknowledgement) ارائه دهد. اگر پاسخ پیش از پایان مهلت زمانی دریافت نشود، استثنای TimeoutError برانگیخته می‌شود.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect' رزرو
شده‌اند و نباید استفاده شوند.
• 2
data -- داده برای ارسال به سرور. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک تاپل استفاده کنید که در آن هر عنصر از
یکی از انواع ذکرشده در بالا باشد.
• 2
timeout -- مهلت زمانی انتظار. اگر مهلت زمانی پیش از آنکه
سرور دریافت رویداد را تأیید کند فرا برسد، استثنای
TimeoutError برانگیخته می‌شود.
0u
0u
0u
7.0
client_class
نام مستعار Client <#socketio.Client>
0u
7.0
connect(url, headers={}, auth=None, transports=None, namespace='/', socketio_path='socket.io', wait_timeout=5)
اتصال به یک سرور Socket.IO.
7.0
پارامترها
7.0
• 2
url -- نشانی اینترنتی (URL) سرور Socket.IO. در صورت نیاز
سرور می‌تواند شامل پارامترهای سفارشی query string باشد. اگر یک
تابع ارائه شده باشد، کلاینت در هر بار تلاش برای اتصال یا اتصال
مجدد، آن را برای دریافت URL فراخوانی خواهد کرد.
• 2
headers -- یک دیکشنری حاوی هدرهای سفارشی برای ارسال همراه
با درخواست اتصال. اگر یک تابع ارائه شده باشد، کلاینت
در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای
دریافت دیکشنری هدرها فراخوانی خواهد کرد.
• 2
auth -- داده‌های احراز هویت ارسال‌شده به سرور همراه با
درخواست اتصال، که معمولاً یک دیکشنری با یک یا
چند جفت کلید/مقدار رشته‌ای است. اگر یک تابع ارائه شده باشد،
کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت
داده‌های احراز هویت فراخوانی خواهد کرد.
• 2
transports -- فهرست روش‌های انتقال مجاز. روش‌های انتقال معتبر
شامل 'polling' و 'websocket' هستند. در صورت عدم
ارائه، ابتدا انتقال polling متصل می‌شود و سپس
تلاش برای ارتقا به websocket صورت می‌گیرد.
• 2
namespace -- فضای نامی که باید به‌صورت رشته به آن متصل شد. در صورت
عدم ارائه، از فضای نام پیش‌فرض / استفاده می‌شود.
• 2
socketio_path -- نقطه پایانی (endpoint) که سرور Socket.IO در آن
نصب شده است. مقدار پیش‌فرض برای بیشتر
موارد مناسب است.
• 2
wait_timeout -- مدت زمانی که کلاینت باید برای برقراری
اتصال منتظر بماند. مقدار پیش‌فرض ۵
ثانیه است.
0u
0u
0u
7.0
disconnect()
قطع اتصال از سرور.
0u
7.0
emit(event, data=None)
ارسال یک رویداد به سرور.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect' رزرو
شده‌اند و نباید استفاده شوند.
• 2
data -- داده برای ارسال به سرور. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک تاپل استفاده کنید که در آن هر عنصر از
یکی از انواع ذکرشده در بالا باشد.
0u
0u
این متد رویداد را برای ارسال زمان‌بندی کرده و بدون انتظار واقعی
برای تحویل آن بازمی‌گردد. در مواردی که کلاینت نیاز به اطمینان
از دریافت رویداد دارد، باید در عوض از socketio.SimpleClient.call()
استفاده شود.
0u
7.0.TP
receive(timeout=None)
منتظر ماندن برای یک رویداد از سوی سرور.
7.0
پارامترها
timeout -- مهلت زمانی انتظار. اگر قبل از اینکه سرور رویداد را
تأیید کند، این زمان به پایان برسد، یک
استثنای TimeoutError ایجاد می‌شود.
0u
مقدار بازگشتی یک لیست است که نام رویداد به عنوان اولین عنصر آن قرار دارد. اگر
سرور آرگومان‌هایی را همراه رویداد ارسال کرده باشد، آن‌ها به عنوان عناصر
اضافی لیست بازگردانده می‌شوند.
0u
7.0
property sid
شناسه نشست (session ID) دریافت‌شده از سرور.
تضمینی وجود ندارد که شناسه نشست در طول چرخه حیات اتصال ثابت بماند،
زیرا اتصالات مجدد می‌توانند باعث تغییر آن شوند.
0u
7.0
property transport
نام لایه انتقال (transport) که در حال حاضر استفاده می‌شود.
لایه انتقال به عنوان یک رشته بازگردانده می‌شود و می‌تواند یکی از موارد polling
و websocket باشد.
0u
0u
0.0
class socketio.AsyncSimpleClient(args, *kwargs)
یک کلاینت Socket.IO.
این کلاس یک کلاینت وب Socket.IO ساده و در عین حال کاملاً سازگار را
با پشتیبانی از لایه‌های انتقال websocket و long-polling پیاده‌سازی می‌کند.
آرگومان‌های موقعیتی و کلیدواژه‌ای ارائه‌شده در سازنده، به شیء
زیربنایی socketio.AsyncClient() <#socketio.AsyncClient> ارسال می‌شوند.
7.0
async call(event, data=None, timeout=60)
ارسال یک رویداد به سرور و انتظار برای پاسخ.
این متد یک ارسال (emit) انجام می‌دهد و منتظر می‌ماند تا سرور پاسخی یا
تأییدیه‌ای ارائه دهد. اگر پاسخ قبل از اتمام مهلت زمانی دریافت نشود،
یک استثنای TimeoutError ایجاد می‌شود.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect'
رزرو شده‌اند و نباید استفاده شوند.
• 2
data -- داده برای ارسال به سرور. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک تاپل استفاده کنید که هر عنصر آن از
یکی از انواع ذکرشده در بالا باشد.
• 2
timeout -- مهلت زمانی انتظار. اگر قبل از اینکه سرور رویداد را
تأیید کند، این زمان به پایان برسد، یک
استثنای TimeoutError ایجاد می‌شود.
0u
0u
نکته: این متد یک کوروتین (coroutine) است.
0u
7.0
client_class
نام مستعار برای AsyncClient <#socketio.AsyncClient>
0u
7.0
async connect(url, headers={}, auth=None, transports=None, namespace='/', socketio_path='socket.io', wait_timeout=5)
اتصال به یک سرور Socket.IO.
7.0
پارامترها
7.0
• 2
url -- نشانی اینترنتی (URL) سرور Socket.IO. در صورت نیاز سرور،
می‌تواند شامل پارامترهای سفارشی رشته پرس‌وجو (query string) باشد. اگر
یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال
مجدد، آن را فراخوانی می‌کند تا URL را دریافت
کند.
• 2
headers -- یک دیکشنری شامل سرایندهای (headers) سفارشی برای ارسال با
درخواست اتصال. اگر یک تابع ارائه شود،
کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت دیکشنری
سرایندها فراخوانی می‌کند.
• 2
auth -- داده‌های احراز هویت ارسال‌شده به سرور همراه با
درخواست اتصال، که معمولاً یک دیکشنری با یک یا
چند جفت کلید/مقدار رشته‌ای است. اگر یک تابع ارائه شود،
کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت داده‌های
احراز هویت فراخوانی می‌کند.
• 2
transports -- لیست لایه‌های انتقال مجاز. لایه‌های انتقال معتبر
عبارتند از 'polling' و 'websocket'. در صورت
ارائه نشدن، ابتدا اتصال لایه انتقال polling برقرار می‌شود،
سپس تلاش برای ارتقا به websocket صورت می‌گیرد.
• 2
namespace -- فضای نامی (namespace) مورد نظر برای اتصال به صورت یک رشته. در صورت
تعیین نشدن، از فضای نامی پیش‌فرض / استفاده می‌شود.
• 2
socketio_path -- نقطه پایانی (endpoint) که سرور Socket.IO در آن
نصب شده است. مقدار پیش‌فرض برای
اکثر موارد مناسب است.
• 2
wait_timeout -- مدت زمانی که کلاینت باید منتظر اتصال
بماند. مقدار پیش‌فرض ۵ ثانیه است.
0u
0u
نکته: این متد یک کوروتین است.
0u
7.0
async disconnect()
قطع اتصال از سرور.
نکته: این متد یک کوروتین است.
0u
7.0
async emit(event, data=None)
ارسال یک رویداد به سرور.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect'
رزرو شده‌اند و نباید استفاده شوند.
• 2
data -- داده برای ارسال به سرور. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک تاپل استفاده کنید که هر عنصر آن از
یکی از انواع ذکرشده در بالا باشد.
0u
0u
نکته: این متد یک کوروتین است.
این متد زمان‌بندی ارسال رویداد را انجام داده و بدون اینکه عملاً
منتظر تحویل آن بماند، بازمی‌گردد. در مواردی که کلاینت نیاز دارد از دریافت
رویداد اطمینان حاصل کند، باید در عوض از socketio.SimpleClient.call()
استفاده شود.
0u
7.0
async receive(timeout=None)
منتظر ماندن برای یک رویداد از سوی سرور.
7.0
پارامترها
timeout -- مهلت زمانی انتظار. اگر قبل از اینکه سرور رویداد را
تأیید کند، این زمان به پایان برسد، یک
استثنای TimeoutError ایجاد می‌شود.
0u
نکته: این متد یک کوروتین است.
مقدار بازگشتی یک لیست است که نام رویداد به عنوان اولین عنصر آن قرار دارد. اگر
سرور آرگومان‌هایی را همراه رویداد ارسال کرده باشد، آن‌ها به عنوان عناصر
اضافی لیست بازگردانده می‌شوند.
0u
7.0
property sid
شناسه نشست دریافت‌شده از سرور.
تضمینی وجود ندارد که شناسه نشست در طول چرخه حیات اتصال ثابت بماند،
زیرا اتصالات مجدد می‌توانند باعث تغییر آن شوند.
0u
7.0.TP
property transport
نام ترنسپورت در حال استفاده.
ترنسپورت به صورت یک رشته بازگردانده می‌شود و می‌تواند یکی از polling
یا websocket باشد.
0u
0u
"کلاینت‌ها (Clients)"
0.0
class socketio.Client(reconnection=True, reconnection_attempts=0, reconnection_delay=1, reconnection_delay_max=5, randomization_factor=0.5, logger=False, serializer='default', json=None, handle_sigint=True, **kwargs)
یک کلاینت Socket.IO.
این کلاس یک کلاینت وب کاملاً منطبق بر Socket.IO را همراه با پشتیبانی از
ترنسپورت‌های websocket و long-polling پیاده‌سازی می‌کند.
7.0
"پارامترها (Parameters)"
7.0
• 2
reconnection -- اگر کلاینت باید پس از قطعی به‌طور خودکار برای
اتصال مجدد به سرور تلاش کند True، و برای عدم اتصال مجدد
False. پیش‌فرض True است.
• 2
reconnection_attempts -- تعداد دفعات تلاش برای اتصال مجدد
پیش از انصراف، یا 0 برای تلاش‌های بی‌نهایت.
پیش‌فرض 0 است.
• 2
reconnection_delay -- مدت‌زمان انتظار بر حسب ثانیه پیش از نخستین
تلاش اتصال مجدد. هر تلاش متوالی
این تأخیر را دو برابر می‌کند.
• 2
reconnection_delay_max -- حداکثر تأخیر میان تلاش‌های اتصال
مجدد.
• 2
randomization_factor -- ضریب تصادفی‌سازی برای هر تأخیر میان
تلاش‌های اتصال مجدد. مقدار پیش‌فرض 0.5 است،
به این معنی که هر تأخیر به‌طور تصادفی
به میزان +/- 50% تنظیم می‌شود.
• 2
logger -- برای فعال‌سازی لاگینگ روی True تنظیم کنید یا یک شیء logger را برای
استفاده ارسال نمایید. برای غیرفعال‌سازی لاگینگ روی False تنظیم کنید. پیش‌فرض
False است. توجه داشته باشید که خطاهای مرگبار حتی زمانی که
logger برابر False باشد نیز ثبت می‌شوند.
• 2
serializer -- روش سریال‌سازی مورد استفاده هنگام ارسال
بسته‌ها. مقادیر معتبر عبارتند از 'default'، 'pickle'،
'msgpack' و 'cbor'. همچنین می‌توان یک زیرکلاس
از کلاس Packet با پیاده‌سازی سفارشی از
متدهای encode() و decode() ارائه
داد. کلاینت و سرور باید از سریال‌سازهای سازگار
استفاده کنند.
• 2
json -- یک ماژول JSON جایگزین جهت استفاده برای انکود و دیکود
بسته‌ها. ماژول‌های json سفارشی باید توابع dumps و loads
سازگار با نسخه‌های کتابخانه استاندارد داشته
باشند. این یک تنظیم در سطح کل فرایند (process-wide) است و تمامی
سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON مشترک استفاده کنند.
• 2
handle_sigint -- روی True تنظیم شود تا قطع اتصال هنگام
وقفه در فرایند به‌طور خودکار مدیریت شود، یا روی False قرار گیرد تا
مدیریت وقفه به برنامه فراخواننده واگذار گردد.
مدیریت وقفه تنها زمانی می‌تواند فعال شود که
نمونه کلاینت در نخ اصلی (main thread) ایجاد شده باشد.
0u
0u
پیکربندی Engine.IO از تنظیمات زیر پشتیبانی می‌کند:
7.0
"پارامترها (Parameters)"
7.0
• 2
request_timeout -- مهلت زمانی (timeout) بر حسب ثانیه برای درخواست‌ها. پیش‌فرض
5 ثانیه است.
• 2
http_session -- یک شیء مقداردهی‌شده از requests.Session جهت استفاده
هنگام ارسال درخواست‌ها به سرور. در صورت نیاز به
افزودن گزینه‌های خاص کلاینت مانند سرورهای پراکسی،
گواهی‌های SSL، بسته سفارشی CA و غیره، از آن استفاده کنید.
• 2
ssl_verify -- مقدار True برای بررسی گواهی‌های SSL، یا False برای
صرف‌نظر از اعتبارسنجی گواهی SSL که امکان اتصال به سرورهای
دارای گواهی خودامضا را فراهم می‌کند.
پیش‌فرض True است.
• 2
websocket_extra_options -- دیکشنری حاوی آرگومان‌های کلیدواژه‌ای
اضافی که به
websocket.create_connection() ارسال می‌شوند.
• 2
engineio_logger -- برای فعال‌سازی لاگینگ Engine.IO روی True تنظیم کنید یا
یک شیء logger را برای استفاده ارسال نمایید. برای غیرفعال‌سازی لاگینگ روی
False تنظیم کنید. پیش‌فرض False است. توجه داشته باشید که
خطاهای مرگبار حتی زمانی که
engineio_logger برابر False باشد نیز ثبت می‌شوند.
0u
0u
7.0
call(event, data=None, namespace=None, timeout=60)
ارسال یک رویداد سفارشی به سرور و انتظار برای دریافت پاسخ.
این متد یک ارسال (emit) را همراه با یک کالبک (callback) صادر کرده و پیش از
بازگشت، منتظر فراخوانی کالبک می‌ماند. اگر کالبک پیش از اتمام مهلت زمانی
فراخوانی نشود، استثنای TimeoutError برانگیخته می‌شود. در صورت قطع
شدن اتصال Socket.IO در طول انتظار، این متد همچنان تا رسیدن به مهلت
زمانی مشخص‌شده منتظر می‌ماند.
7.0
"پارامترها (Parameters)"
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect'
رزرو شده هستند و نباید استفاده شوند.
• 2
data -- داده ارسالی به سرور. داده می‌تواند از نوع
str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک tuple استفاده کنید که هر عنصر آن از
یکی از نوع‌های ذکرشده در بالا باشد.
• 2
namespace -- فضای نام Socket.IO برای رویداد. در صورت حذف
این آرگومان، رویداد به فضای نام
پیش‌فرض ارسال می‌شود.
• 2
timeout -- مهلت زمانی انتظار. اگر مهلت زمانی پیش از تأیید
رویداد توسط سرور به پایان برسد، آنگاه استثنای
TimeoutError برانگیخته می‌شود.
0u
0u
نکته: این متد thread safe (امن در برابر نخ‌ها) نیست. اگر چندین نخ به‌طور
هم‌زمان بر روی یک اتصال کلاینت پیام ارسال کنند، پیام‌های متشکل از
چندین بسته ممکن است با ترتیبی نادرست ارسال شوند. برای جلوگیری از این
وضعیت، از راهکارهای استاندارد هم‌روندی (مانند شیء Lock) استفاده کنید.
0u
7.0
connect(url, headers={}, auth=None, transports=None, namespaces=None, socketio_path='socket.io', wait=True, wait_timeout=1, retry=False)
اتصال به یک سرور Socket.IO.
7.0
"پارامترها (Parameters)"
7.0
• 2
url -- نشانی اینترنتی (URL) سرور Socket.IO. در صورت نیاز
سرور می‌تواند شامل پارامترهای سفارشی رشته پرس‌وجو (query string) باشد.
اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال
یا اتصال مجدد، آن را برای دریافت URL فراخوانی
می‌کند.
• 2
headers -- یک دیکشنری حاوی سرایندهای (headers) سفارشی جهت ارسال همراه
با درخواست اتصال. اگر یک تابع ارائه شود،
کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را جهت
دریافت دیکشنری سرایندها فراخوانی می‌کند.
• 2
auth -- داده‌های احراز هویت ارسالی به سرور همراه با درخواست
اتصال، که معمولاً دیکشنری‌ای با یک یا چند
جفت کلید/مقدار رشته‌ای است. اگر یک تابع ارائه شود،
کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را جهت دریافت
داده‌های احراز هویت فراخوانی می‌کند.
• 2
transports -- فهرست ترنسپورت‌های مجاز. ترنسپورت‌های معتبر
عبارتند از 'polling' و 'websocket'. در صورت
عدم تعیین، ابتدا ترنسپورت polling متصل شده،
سپس ارتقا به websocket تلاش می‌شود.
• 2
namespaces -- فضاهای نام برای اتصال، به صورت یک رشته یا فهرستی از
رشته‌ها. در صورت عدم تعیین، فضاهای نامی که دارای گرداننده‌های
رویداد ثبت‌شده هستند متصل می‌شوند.
• 2
socketio_path -- نقطه پایانی (endpoint) که سرور Socket.IO در آن
مستقر شده است. مقدار پیش‌فرض برای
بیشتر موارد مناسب است.
• 2
wait -- در صورت تنظیم روی True (پیش‌فرض)، فراخوانی تنها زمانی بازمی‌گردد
که تمامی فضاهای نام متصل شده باشند. در صورت تنظیم روی
False، فراخوانی به محض متصل شدن ترنسپورت Engine.IO بازمی‌گردد،
و فضاهای نام در پس‌زمینه متصل خواهند شد..IP • 2
wait_timeout -- مدت زمانی که کلاینت باید منتظر برقراری
اتصال بماند. مقدار پیش‌فرض ۱ ثانیه است. این
آرگومان تنها زمانی در نظر گرفته می‌شود که wait روی
True تنظیم شده باشد.
• 2
retry -- اعمال منطق اتصال مجدد در صورتی که تلاش اولیه
برای اتصال ناموفق باشد. مقدار پیش‌فرض False است.
0u
0u
مثال استفاده:
7.0
3.5
sio = socketio.Client()
sio.connect('http://localhost:5000')
0u
0u
0u
7.0
connected
نشان می‌دهد که آیا کلاینت متصل است یا خیر.
0u
7.0
disconnect()
قطع اتصال از سرور.
0u
7.0
emit(event, data=None, namespace=None, callback=None)
ارسال یک رویداد سفارشی به سرور.
7.0
پارامترها (Parameters)
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect'
رزرو شده‌اند و نباید استفاده شوند.
• 2
data -- داده برای ارسال به سرور. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک تاپل (tuple) استفاده کنید که هر عنصر آن از
یکی از انواع ذکرشده در بالا باشد.
• 2
namespace -- فضای نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، رویداد به فضای نام
پیش‌فرض ارسال می‌شود.
• 2
callback -- در صورت ارائه، این تابع برای اعلام وصول و تأیید
دریافت پیام توسط سرور فراخوانی خواهد شد. آرگومان‌هایی
که به تابع فرستاده می‌شوند مواردی هستند که
توسط سرور فراهم شده‌اند.
0u
0u
نکته: این متد thread safe نیست. اگر چندین ریسه (thread) به طور
هم‌زمان روی یک اتصال کلاینت در حال ارسال پیام باشند، پیام‌های
تشکیل‌شده از چندین بسته ممکن است در ترتیبی نادرست ارسال شوند. برای
جلوگیری از این وضعیت، از راهکارهای استاندارد هم‌زمانی (مانند شیء
Lock) استفاده کنید.
0u
7.0
event(args, *kwargs)
دکوراتور برای ثبت یک گرداننده رویداد (event handler).
این نسخه ساده‌شده‌ای از متد on() است که نام
رویداد را از تابعی که دکوراتور روی آن اعمال شده می‌گیرد.
مثال استفاده:
7.0
3.5
@sio.event
def my_event(data):
print('Received data: ', data)
0u
0u
مثال بالا معادل است با:
7.0
3.5
@sio.on('my_event')
def my_event(data):
print('Received data: ', data)
0u
0u
می‌توان یک فضای نام سفارشی را به عنوان آرگومان به دکوراتور داد:
7.0
3.5
@sio.event(namespace='/test')
def my_event(data):
print('Received data: ', data)
0u
0u
0u
7.0
get_sid(namespace=None)
مقدار sid مرتبط با یک اتصال را برمی‌گرداند.
7.0
پارامترها (Parameters)
namespace -- فضای نام Socket.IO. در صورت حذف این آرگومان،
گرداننده به فضای نام پیش‌فرض
مرتبط می‌شود. توجه داشته باشید که برخلاف نسخه‌های پیشین، نسخهٔ
فعلی پروتکل Socket.IO از مقادیر sid متفاوتی
به ازای هر فضای نام استفاده می‌کند.
0u
این متد مقدار sid را برای فضای نام درخواست‌شده به صورت یک
رشته برمی‌گرداند.
0u
7.0
namespaces
مجموعه‌ای از فضاهای نام (namespaces) متصل‌شده.
0u
7.0
on(event, handler=None, namespace=None)
ثبت یک گرداننده رویداد.
7.0
پارامترها (Parameters)
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect'
رزرو شده‌اند و نباید استفاده شوند. از نام رویداد *''**
می‌توان برای تعریف یک گردانندهٔ رویداد همه‌گیر (catch-all) استفاده کرد.
• 2
handler -- تابعی که باید برای مدیریت رویداد فراخوانی
شود. هنگامی که این پارامتر مشخص نشده باشد، این متد به عنوان
یک دکوراتور برای تابع گرداننده عمل می‌کند.
• 2
namespace -- فضای نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، گرداننده با فضای نام
پیش‌فرض مرتبط می‌گردد. با فرستادن *''** به عنوان
فضای نام، می‌توان یک فضای نام همه‌گیر (catch-all) تعریف کرد.
0u
0u
مثال استفاده:
7.0
3.5
# as a decorator:
@sio.on('connect')
def connect_handler():
print('Connected!')
# as a method:
def message_handler(msg):
print('Received message: ', msg)
sio.send( 'response')
sio.on('message', message_handler)
0u
0u
آرگومان‌های ارسال‌شده به تابع گرداننده به نوع رویداد بستگی دارند:
7.0
• 2
گردانندهٔ رویداد 'connect' هیچ آرگومانی نمی‌پذیرد..IP • 2
گردانندهٔ رویداد 'disconnect' هیچ آرگومانی دریافت نمی‌کند.
• 2
گردانندهٔ 'message' و گرداننده‌های مربوط به نام‌های سفارشی رویداد، بار دادهٔ پیام (payload) را به عنوان تنها آرگومان دریافت می‌کنند. هر مقداری که از گردانندهٔ پیام برگردانده شود، به تابع بازخوانی تأیید کلاینت (در صورت وجود) فرستاده خواهد شد.
• 2
یک گردانندهٔ همه‌گیر رویداد (catch-all) نام رویداد را به عنوان نخستین آرگومان دریافت می‌کند، که پس از آن آرگومان‌های اختصاصی آن رویداد قرار می‌گیرند.
• 2
یک گردانندهٔ همه‌گیر رویداد فضای نام، فضای نام را به عنوان نخستین آرگومان دریافت می‌کند، که پس از آن آرگومان‌های اختصاصی آن رویداد قرار می‌گیرند.
• 2
یک گردانندهٔ ترکیبی همه‌گیر فضای نام و رویداد، نام رویداد را به عنوان نخستین آرگومان و فضای نام را به عنوان دومین آرگومان دریافت می‌کند، که پس از آن آرگومان‌های اختصاصی رویداد قرار می‌گیرند.
0u
0u
7.0
class reason
دلایل قطع اتصال.
7.0
CLIENT_DISCONNECT = 'client disconnect'
قطع اتصال آغاز شده توسط کلاینت.
0u
7.0
SERVER_DISCONNECT = 'server disconnect'
قطع اتصال آغاز شده توسط سرور.
0u
7.0
TRANSPORT_ERROR = 'transport error'
خطای لایهٔ انتقال.
0u
0u
7.0
register_namespace(namespace_handler)
ثبت یک شیء گردانندهٔ فضای نام.
7.0
پارامترها
namespace_handler -- نمونه‌ای از زیرکلاس Namespace <#socketio.Namespace>
که تمامی ترافیک رویدادها را برای یک فضای نام مدیریت می‌کند.
0u
0u
7.0
send(data, namespace=None, callback=None)
ارسال یک پیام به سرور.
این تابع رویدادی با نام 'message' ارسال می‌کند (emit). برای ارسال
نام‌های سفارشی رویداد از emit() استفاده کنید.
7.0
پارامترها
7.0
• 2
data -- داده برای ارسال به سرور. داده می‌تواند از نوع
str، bytes، list یا dict باشد. برای ارسال چندین
آرگومان، از یک tuple استفاده کنید که هر عضو آن از یکی از
نوع‌های اشاره‌شده در بالا باشد.
• 2
namespace -- فضای نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، رویداد به فضای نام پیش‌فرض ارسال می‌شود.
• 2
callback -- در صورت ارائه، این تابع برای تأیید دریافت پیام
توسط سرور فراخوانی می‌شود. آرگومان‌هایی که به تابع فرستاده می‌شوند
مواردی هستند که توسط سرور تأمین شده‌اند.
0u
0u
0u
7.0
shutdown()
متوقف کردن کلاینت.
اگر کلاینت به سروری متصل باشد، اتصال آن قطع می‌شود. اگر کلاینت
در حال تلاش برای اتصال مجدد به سرور باشد، تلاش‌های اتصال مجدد متوقف
می‌شوند. اگر کلاینت به سروری متصل نباشد و تلاشی برای اتصال مجدد نکند،
این تابع کاری انجام نمی‌دهد.
0u
7.0
sleep(seconds=0)
به خواب بردن (sleep) به مدت زمان درخواستی با استفاده از مدل ناهمگام
(async) مناسب.
این یک تابع کمکی است که برنامه‌ها می‌توانند بدون نگرانی در مورد استفاده از
فراخوانی مناسب برای حالت async انتخاب‌شده، از آن برای به خواب بردن
یک تسک استفاده کنند.
0u
7.0
start_background_task(target, args, *kwargs)
آغاز یک تسک پس‌زمینه با استفاده از مدل async مناسب.
این یک تابع کمکی است که برنامه‌ها می‌توانند با استفاده از روشی که با
حالت async انتخاب‌شده سازگار است، از آن برای اجرای یک تسک
پس‌زمینه استفاده کنند.
7.0
پارامترها
7.0
• 2
target -- تابع هدف برای اجرا.
• 2
args -- آرگومان‌هایی که به تابع فرستاده می‌شوند.
• 2
kwargs -- آرگومان‌های کلیدواژه‌ای که به تابع فرستاده می‌شوند.
0u
0u
این تابع شیئی را برمی‌گرداند که نشان‌دهندهٔ تسک پس‌زمینه است و می‌توان
متد join() آن را برای منتظر ماندن تا تکمیل تسک فراخوانی کرد.
0u
7.0
transport()
برگرداندن نام روش انتقال استفاده‌شده توسط کلاینت.
دو مقدار ممکن که توسط این تابع برگردانده می‌شوند 'polling'
و 'websocket' هستند.
0u
7.0
wait()
منتظر ماندن تا پایان اتصال با سرور.
برنامه‌های کلاینت می‌توانند از این تابع برای مسدود کردن رشتهٔ اصلی
(main thread) در طول مدت اتصال استفاده کنند.
0u
0u
0.0
class socketio.AsyncClient(reconnection=True, reconnection_attempts=0, reconnection_delay=1, reconnection_delay_max=5, randomization_factor=0.5, logger=False, serializer='default', json=None, handle_sigint=True, **kwargs)
یک کلاینت Socket.IO برای asyncio.
این کلاس یک کلاینت وب Socket.IO کاملاً سازگار را با پشتیبانی از
روش‌های انتقال websocket و long-polling پیاده‌سازی می‌کند.
7.0
پارامترها
7.0
• 2
reconnection -- اگر کلاینت پس از قطعی باید به‌طور خودکار
برای اتصال مجدد به سرور تلاش کند True، یا برای متصل نشدن مجدد
False. پیش‌فرض True است.
• 2
reconnection_attempts -- تعداد تلاش‌های اتصال مجدد پیش از انصراف،
یا 0 برای تلاش نامحدود. پیش‌فرض 0 است.
• 2
reconnection_delay -- مدت‌زمان انتظار به ثانیه پیش از نخستین تلاش
اتصال مجدد. هر تلاش متوالی این تأخیر را دو برابر می‌کند.
• 2
reconnection_delay_max -- بیشینهٔ تأخیر بین تلاش‌های اتصال مجدد.
• 2
randomization_factor -- میزان تصادفی‌سازی برای هر تأخیر بین تلاش‌های
اتصال مجدد. پیش‌فرض 0.5 است، به این معنی که هر تأخیر به‌طور
تصادفی تا +/- 50% تنظیم می‌شود.
• 2
logger -- برای فعال‌سازی گزارش‌گیری روی True قرار دهید یا یک شیء
logger برای استفاده پاس دهید. برای غیرفعال کردن گزارش‌گیری روی False
تنظیم کنید. پیش‌فرض False است. توجه داشته باشید که خطاهای مهلک
حتی زمانی که logger برابر False باشد نیز ثبت می‌شوند.
• 2
json -- یک ماژول جایگزین JSON برای کدگذاری و رمزگشایی بسته‌ها.
ماژول‌های سفارشی json باید توابع dumps و loads سازگار با نسخه‌های
کتابخانهٔ استاندارد داشته باشند. این یک تنظیم در سطح کل فرآیند
(process-wide) است؛ تمامی سرورها و کلاینت‌های ایجادشده باید از همان ماژول
JSON یکسان استفاده کنند..IP • 2
handle_sigint -- برای مدیریت خودکار قطع اتصال هنگام ایجاد وقفه در فرایند، روی True، یا برای واگذاری مدیریت وقفه به برنامهٔ فراخواننده، روی False تنظیم شود. مدیریت وقفه تنها زمانی می‌تواند فعال شود که نمونهٔ کلاینت در رشتهٔ اصلی (main thread) ایجاد شده باشد.
0u
0u
پیکربندی Engine.IO از تنظیمات زیر پشتیبانی می‌کند:
7.0
پارامترها
7.0
• 2
request_timeout -- مهلت زمانی به ثانیه برای درخواست‌ها. مقدار پیش‌فرض ۵ ثانیه است.
• 2
http_session -- یک شیء مقداردهی‌شده از aiohttp.ClientSession برای استفاده هنگام ارسال درخواست‌ها به سرور. در صورتی که نیاز به افزودن گزینه‌های خاص کلاینت مانند سرورهای پروکسی، گواهی‌های SSL، بستهٔ CA سفارشی و غیره دارید، از آن استفاده کنید.
• 2
ssl_verify -- مقدار True برای اعتبارسنجی گواهی‌های SSL، یا False برای نادیده گرفتن اعتبارسنجی گواهی SSL، که امکان اتصال به سرورهای دارای گواهی‌های خودامضا (self-signed) را فراهم می‌کند. مقدار پیش‌فرض True است.
• 2
websocket_extra_options -- دیکشنری حاوی آرگومان‌های کلیدواژه‌ای اضافی که به websocket.create_connection() ارسال می‌شوند.
• 2
engineio_logger -- برای فعال‌سازی ثبت وقایع Engine.IO روی True تنظیم کنید یا یک شیء ثبت وقایع (logger) ارسال نمایید. برای غیرفعال‌سازی ثبت وقایع، روی False تنظیم کنید. مقدار پیش‌فرض False است. توجه داشته باشید که خطاهای مهلک حتی زمانی که engineio_logger برابر با False باشد نیز ثبت می‌شوند.
0u
0u
7.0
async call(event, data=None, namespace=None, timeout=60)
ارسال (emit) یک رویداد سفارشی به سرور و انتظار برای پاسخ.
این متد یک ارسال (emit) به همراه بازخورد (callback) صادر می‌کند و پیش از بازگشت، منتظر فراخوانی بازخورد می‌ماند. اگر بازخورد پیش از اتمام مهلت زمانی فراخوانی نشود، یک استثنای TimeoutError ایجاد می‌شود. در صورتی که اتصال Socket.IO در طول مدت انتظار قطع شود، این متد همچنان تا زمان انقضای مهلت زمانی مشخص‌شده منتظر می‌ماند.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد 'connect'، 'message' و 'disconnect' رزرو شده‌اند و نباید استفاده شوند.
• 2
data -- داده برای ارسال به سرور. داده می‌تواند از نوع str، bytes، list یا dict باشد. برای ارسال چندین آرگومان، از یک تاپل (tuple) استفاده کنید که در آن هر عنصر از یکی از انواع ذکرشده در بالا باشد.
• 2
namespace -- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد به فضای نام پیش‌فرض ارسال می‌شود.
• 2
timeout -- مهلت زمانی انتظار. اگر مهلت زمانی پیش از تأیید رویداد توسط سرور به پایان برسد، یک استثنای TimeoutError ایجاد می‌شود.
0u
0u
نکته: این متد برای استفاده به صورت هم‌روند (concurrent) طراحی نشده است. اگر چندین تسک به طور همزمان روی یک اتصال کلاینت در حال ارسال باشند، ممکن است پیام‌های متشکل از چند بسته با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت، از راهکارهای استاندارد هم‌روندی (مانند یک شیء Lock) استفاده کنید.
نکته ۲: این متد یک کوروتین (coroutine) است.
0u
7.0
async connect(url, headers={}, auth=None, transports=None, namespaces=None, socketio_path='socket.io', wait=True, wait_timeout=1, retry=False)
اتصال به یک سرور Socket.IO.
7.0
پارامترها
7.0
• 2
url -- نشانی URL سرور Socket.IO. در صورت نیاز سرور، می‌تواند شامل پارامترهای سفارشی رشتهٔ پرس‌وجو (query string) باشد. اگر یک تابع ارائه شود، کلاینت برای دریافت URL در هر بار تلاش برای اتصال یا اتصال مجدد، آن را فراخوانی می‌کند.
• 2
headers -- یک دیکشنری حاوی سرایندهای سفارشی جهت ارسال همراه با درخواست اتصال. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت دیکشنری سرایندها فراخوانی می‌کند.
• 2
auth -- داده‌های احراز هویت ارسال‌شده به سرور همراه با درخواست اتصال، که معمولاً دیکشنری حاوی یک یا چند جفت کلید/مقدار رشته‌ای است. اگر یک تابع ارائه شود، کلاینت در هر بار تلاش برای اتصال یا اتصال مجدد، آن را برای دریافت داده‌های احراز هویت فراخوانی می‌کند.
• 2
transports -- فهرست لایه‌های انتقال (transports) مجاز. گزینه‌های معتبر عبارتند از 'polling' و 'websocket'. در صورت عدم تعیین، ابتدا لایهٔ انتقال polling متصل می‌شود، سپس تلاش برای ارتقا به websocket صورت می‌گیرد.
• 2
namespaces -- فضاهای نام برای اتصال به صورت یک رشته یا فهرستی از رشته‌ها. در صورت عدم تعیین، فضاهای نامی که دارای گرداننده‌های رویداد ثبت‌شده هستند متصل می‌شوند.
• 2
socketio_path -- نقطهٔ پایانی (endpoint) که سرور Socket.IO در آن مستقر است. مقدار پیش‌فرض برای بیشتر موارد مناسب است.
• 2
wait -- اگر روی True (پیش‌فرض) تنظیم شود، فراخوانی تنها زمانی بازمی‌گردد که تمام فضاهای نام متصل شده باشند. اگر روی False تنظیم شود، فراخوانی به محض اتصال لایهٔ انتقال Engine.IO بازمی‌گردد و فضاهای نام در پس‌زمینه متصل خواهند شد.
• 2
wait_timeout -- مدت زمانی که کلاینت باید در انتظار اتصال بماند. مقدار پیش‌فرض ۱ ثانیه است. این آرگومان تنها زمانی در نظر گرفته می‌شود که wait روی True تنظیم شده باشد.
• 2
retry -- اعمال منطق اتصال مجدد در صورتی که تلاش اولیه برای اتصال با شکست مواجه شود. مقدار پیش‌فرض False است.
0u
0u
نکته: این متد یک کوروتین (coroutine) است.
نمونه کاربرد:
7.0
3.5
sio = socketio.AsyncClient()
await sio.connect('http://localhost:5000')
0u
0u
0u
7.0
connected
مشخص می‌کند که آیا کلاینت متصل است یا خیر.
0u
7.0
async disconnect()
قطع اتصال از سرور.
نکته: این متد یک کوروتین (coroutine) است.
0u
7.0
async emit(event, data=None, namespace=None, callback=None)
ارسال (emit) یک رویداد سفارشی به سرور.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد 'connect'، 'message' و 'disconnect' رزرو شده‌اند و نباید استفاده شوند.
• 2
data -- داده برای ارسال به سرور. داده می‌تواند از نوع str، bytes، list یا dict باشد. برای ارسال چندین آرگومان، از یک تاپل (tuple) استفاده کنید که در آن هر عنصر از یکی از انواع ذکرشده در بالا باشد.
• 2
namespace -- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، رویداد به فضای نام پیش‌فرض ارسال می‌شود..IP • 2
callback -- در صورت ارائه، این تابع برای تأیید دریافت پیام توسط سرور فراخوانی می‌شود. آرگومان‌هایی که به این تابع فرستاده می‌شوند همان مواردی هستند که توسط سرور ارائه شده‌اند.
0u
0u
نکته: این متد برای استفاده هم‌روند طراحی نشده است. اگر چندین وظیفه (task) به طور هم‌زمان روی یک اتصال کلاینت در حال ارسال (emit) باشند، پیام‌هایی که از چندین بسته تشکیل شده‌اند ممکن است با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت از راهکارهای استاندارد هم‌روندی (مانند شیء Lock) استفاده کنید.
نکته ۲: این متد یک کوروتین (coroutine) است.
0u
7.0
event(args, *kwargs)
دکوراتور برای ثبت یک گرداننده رویداد (event handler).
این یک نسخه ساده‌شده از متد on() است که نام رویداد را از تابع دکوره‌شده می‌گیرد.
نمونه کاربرد:
7.0
3.5
@sio.event
def my_event(data):
print('Received data: ', data)
0u
0u
مثال بالا معادل است با:
7.0
3.5
@sio.on('my_event')
def my_event(data):
print('Received data: ', data)
0u
0u
یک فضای نام (namespace) سفارشی می‌تواند به عنوان آرگومان به دکوراتور داده شود:
7.0
3.5
@sio.event(namespace='/test')
def my_event(data):
print('Received data: ', data)
0u
0u
0u
7.0
get_sid(namespace=None)
مقدار sid مرتبط با یک اتصال را برمی‌گرداند.
7.0
پارامترها
namespace -- فضای نام Socket.IO. در صورت حذف این آرگومان، گرداننده با فضای نام پیش‌فرض مرتبط می‌شود. توجه داشته باشید که برخلاف نسخه‌های پیشین، نسخه فعلی پروتکل Socket.IO از مقادیر sid متفاوتی به ازای هر فضای نام استفاده می‌کند.
0u
این متد sid را برای فضای نام درخواست‌شده در قالب یک رشته برمی‌گرداند.
0u
7.0
namespaces
مجموعه‌ای از فضاهای نام متصل‌شده.
0u
7.0
on(event, handler=None, namespace=None)
ثبت یک گرداننده رویداد.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد 'connect'، 'message' و 'disconnect' رزرو شده‌اند و نباید استفاده شوند. از نام رویداد *''** می‌توان برای تعریف یک گرداننده رویداد همه‌پوش (catch-all) استفاده کرد.
• 2
handler -- تابعی که باید برای رسیدگی به رویداد فراخوانی شود. هنگامی که این پارامتر ارائه نشود، این متد مانند یک دکوراتور برای تابع گرداننده عمل می‌کند.
• 2
namespace -- فضای نام Socket.IO برای این رویداد. در صورت حذف این آرگومان، گرداننده با فضای نام پیش‌فرض مرتبط می‌شود. یک فضای نام همه‌پوش (catch-all) را می‌توان با ارسال *''** به عنوان فضای نام تعریف کرد.
0u
0u
نمونه کاربرد:
7.0
3.5
# as a decorator:
@sio.on('connect')
def connect_handler():
print('Connected!')
# as a method:
def message_handler(msg):
print('Received message: ', msg)
sio.send( 'response')
sio.on('message', message_handler)
0u
0u
آرگومان‌های ارسال‌شده به تابع گرداننده به نوع رویداد بستگی دارند:
7.0
• 2
گرداننده رویداد 'connect' هیچ آرگومانی دریافت نمی‌کند.
• 2
گرداننده رویداد 'disconnect' هیچ آرگومانی دریافت نمی‌کند.
• 2
گرداننده 'message' و گرداننده‌های نام‌های رویداد سفارشی، محموله پیام (payload) را به عنوان تنها آرگومان دریافت می‌کنند. هر مقداری که از گرداننده پیام بازگردانده شود، در صورت وجود، به تابع بازخوانی تأیید (acknowledgement callback) کلاینت تحویل داده خواهد شد.
• 2
یک گرداننده رویداد همه‌پوش (catch-all)، نام رویداد را به عنوان نخستین آرگومان دریافت می‌کند که در ادامه آرگومان‌های ویژه آن رویداد قرار می‌گیرند.
• 2
یک گرداننده رویداد فضای نام همه‌پوش، فضای نام را به عنوان نخستین آرگومان دریافت می‌کند که در ادامه آرگومان‌های ویژه آن رویداد قرار می‌گیرند.
• 2
یک گرداننده ترکیبی فضای نام همه‌پوش و رویداد همه‌پوش، نام رویداد را به عنوان نخستین آرگومان و فضای نام را به عنوان دومین آرگومان دریافت می‌کند که در ادامه آرگومان‌های ویژه آن رویداد قرار می‌گیرند.
0u
0u
7.0
class reason
دلایل قطع اتصال.
7.0
CLIENT_DISCONNECT = 'client disconnect'
قطع اتصال به درخواست کلاینت.
0u
7.0
SERVER_DISCONNECT = 'server disconnect'
قطع اتصال به درخواست سرور.
0u
7.0
TRANSPORT_ERROR = 'transport error'
خطای لایه انتقال (ترابری).
0u
0u
7.0
register_namespace(namespace_handler)
ثبت یک شیء گرداننده فضای نام.
7.0
پارامترها
namespace_handler -- نمونه‌ای از یک زیرکلاس Namespace <#socketio.Namespace> که تمام ترافیک رویدادها را برای یک فضای نام مدیریت می‌کند.
0u
0u
7.0.TP
async send(data, namespace=None, callback=None)
ارسال یک پیام به سرور.
این تابع رویدادی با نام 'message' منتشر می‌کند. برای ایجاد نام‌های رویداد سفارشی از
emit() استفاده کنید.
7.0
پارامترها
7.0
• 2
data -- داده‌ای که باید به سرور ارسال شود. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک تاپل (tuple) استفاده کنید که هر عنصر آن از
یکی از انواع ذکر شده در بالا باشد.
• 2
namespace -- فضای‌نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، رویداد به
فضای‌نام پیش‌فرض ارسال می‌شود.
• 2
callback -- در صورت تعیین، این تابع برای تایید
دریافت پیام توسط سرور فراخوانی خواهد شد. آرگومان‌هایی
که به تابع منتقل می‌شوند همان مواردی هستند که توسط
سرور ارائه شده‌اند.
0u
0u
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async shutdown()
متوقف کردن کلاینت.
اگر کلاینت به یک سرور متصل باشد، اتصال آن قطع می‌شود. اگر
کلاینت در تلاش برای اتصال مجدد به سرور باشد، تلاش‌های اتصال مجدد
متوقف می‌شوند. اگر کلاینت به سروری متصل نبوده و در حال تلاش برای
اتصال مجدد نیز نباشد، این تابع هیچ کاری انجام نمی‌دهد.
0u
7.0
async sleep(seconds=0)
توقف موقت (خوابیدن) به مدت زمان درخواستی با استفاده از مدل ناهمگام (async)
مناسب.
این یک تابع کمکی است که برنامه‌ها می‌توانند برای به خواب بردن یک
وظیفه (task) بدون نیاز به نگرانی درباره فراخوانی مناسب با حالت
ناهمگام انتخاب‌شده از آن استفاده کنند.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
start_background_task(target, args, *kwargs)
شروع یک وظیفه پس‌زمینه با استفاده از مدل ناهمگام مناسب.
این یک تابع کمکی است که برنامه‌ها می‌توانند برای شروع یک
وظیفه پس‌زمینه با استفاده از روش سازگار با حالت ناهمگامِ
انتخاب‌شده از آن استفاده کنند.
7.0
پارامترها
7.0
• 2
target -- تابع هدف برای اجرا.
• 2
args -- آرگومان‌هایی که به تابع ارسال می‌شوند.
• 2
kwargs -- آرگومان‌های کلیدواژه‌ای که به تابع ارسال می‌شوند.
0u
0u
مقدار بازگشتی یک شیء asyncio.Task است.
0u
7.0
transport()
بازگرداندن نام روش انتقال (transport) مورد استفاده توسط کلاینت.
دو مقدار ممکن که توسط این تابع بازگردانده می‌شوند 'polling'
و 'websocket' هستند.
0u
7.0
async wait()
انتظار تا زمانی که ارتباط با سرور پایان یابد.
برنامه‌های کلاینت می‌توانند از این تابع برای مسدود کردن رشته اصلی (main thread)
در طول مدت اتصال استفاده کنند.
نکته: این متد یک هم‌روال (coroutine) است.
0u
0.0
class socketio.Server(client_manager=None, logger=False, serializer='default', json=None, async_handlers=True, always_connect=False, namespaces=None, **kwargs)
یک سرور Socket.IO.
این کلاس یک وب‌سرور کاملاً منطبق با Socket.IO را همراه با پشتیبانی از ترابری‌های websocket و long-polling پیاده‌سازی می‌کند.
7.0
پارامترها
7.0
• 2
client_manager -- نمونهٔ مدیر کلاینت (client manager) که فهرست کلاینت‌ها را مدیریت خواهد کرد. در صورت عدم ذکر، فهرست کلاینت‌ها در یک ساختار درون‌حافظه‌ای ذخیره می‌شود، بنابراین استفاده از چند سرور متصل به یکدیگر امکان‌پذیر نخواهد بود.
• 2
logger -- برای فعال‌سازی گزارش‌گیری روی True تنظیم کنید یا یک شیء ثبت لاگ برای استفاده پاس دهید. برای غیرفعال‌سازی، آن را روی False تنظیم کنید. مقدار پیش‌فرض False است. توجه داشته باشید که خطاهای مرگبار (fatal) حتی زمانی که logger برابر False است نیز ثبت می‌شوند.
• 2
serializer -- روش سریال‌سازی مورد استفاده هنگام ارسال بسته‌ها. مقادیر معتبر عبارتند از 'default'، 'pickle'، 'msgpack' و 'cbor'. علاوه بر این، می‌توان یک زیرکلاس از کلاس Packet همراه با پیاده‌سازی سفارشی متدهای encode() و decode() ارائه داد. کلاینت و سرور باید از سریال‌سازهای سازگار استفاده کنند.
• 2
json -- یک ماژول جایگزین JSON برای کدگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید توابع dumps و loads سازگار با نسخه‌های کتابخانهٔ استاندارد داشته باشند. این یک تنظیم در سطح کل فرآیند (process-wide) است و همهٔ سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON یکسان استفاده کنند.
• 2
async_handlers -- در صورت تنظیم روی True، گرداننده‌های رویداد برای یک کلاینت در رشته‌های (threads) جداگانه اجرا می‌شوند. برای اجرای همگام گرداننده‌ها برای یک کلاینت، آن را روی False تنظیم کنید. مقدار پیش‌فرض True است.
• 2
always_connect -- هنگامی که روی False تنظیم شود، اتصالات جدید مشروط و موقتی هستند تا زمانی که گردانندهٔ اتصال مقداری غیر از False بازگرداند، که در آن نقطه پذیرفته می‌شوند. وقتی روی True تنظیم شود، اتصالات بلافاصله پذیرفته می‌شوند و سپس اگر گردانندهٔ اتصال False بازگرداند، دستور قطع اتصال صادر می‌شود. اگر نیاز به انتشار رویدادها از درون گردانندهٔ اتصال دارید و کلاینت شما هنگام دریافت رویدادها پیش از پذیرش اتصال دچار تداخل می‌شود، آن را روی True تنظیم کنید. در هر حالت دیگری، از مقدار پیش‌فرض False استفاده کنید.
• 2
namespaces -- فهرستی از فضاهای نام (namespaces) که علاوه بر فضاهای نام دارای گردانندهٔ تعریف‌شده، پذیرفته می‌شوند. مقدار پیش‌فرض ['/'] است که همواره اتصالات به فضای نام پیش‌فرض را می‌پذیرد. برای پذیرش تمام فضاهای نام، روی ''* تنظیم کنید.
• 2
kwargs -- پارامترهای اتصال برای سرور زیرین Engine.IO.
0u
0u
پیکربندی Engine.IO از تنظیمات زیر پشتیبانی می‌کند:
7.0
پارامترها
7.0
• 2
async_mode -- مدل ناهمگام مورد استفاده. برای مشاهدهٔ شرح گزینه‌های موجود، بخش Deployment را در مستندات بررسی کنید. حالت‌های ناهمگام معتبر عبارتند از 'threading'، 'eventlet'، 'gevent' و 'gevent_uwsgi'. اگر این آرگومان مشخص نشود، ابتدا 'eventlet'، سپس 'gevent_uwsgi'، بعد از آن 'gevent' و در نهایت 'threading' امتحان می‌شود. نخستین حالت ناهمگامی که تمامی وابستگی‌های آن نصب باشد انتخاب خواهد شد.
• 2
ping_interval -- بازهٔ زمانی بر حسب ثانیه که در آن سرور به کلاینت پینگ ارسال می‌کند. مقدار پیش‌فرض ۲۵ ثانیه است. برای کنترل پیشرفته‌تر، می‌توان یک تاپل دو عضوی تعیین کرد که عدد اول بازهٔ پینگ و عدد دوم دورهٔ مهلت (grace period) اضافه شده توسط سرور است.
• 2
ping_timeout -- مدت‌زمانی بر حسب ثانیه که کلاینت پیش از قطع اتصال، منتظر پاسخ سرور می‌ماند. مقدار پیش‌فرض ۲۰ ثانیه است.
• 2
max_http_buffer_size -- حداکثر اندازهٔ مجاز برای پیام‌های دریافتی. مقدار پیش‌فرض ۱٬۰۰۰٬۰۰۰ بایت است. علی‌رغم نام آن، مقدار تعیین‌شده در این آرگومان برای هر دو اتصال HTTP long-polling و WebSocket اعمال می‌شود.
• 2
allow_upgrades -- مشخص می‌کند که آیا ارتقای ترابری مجاز باشد یا خیر. مقدار پیش‌فرض True است.
• 2
http_compression -- مشخص می‌کند که هنگام استفاده از ترابری polling بسته‌ها فشرده‌سازی شوند یا خیر. مقدار پیش‌فرض True است.
• 2
compression_threshold -- پیام‌ها تنها زمانی فشرده‌سازی می‌شوند که اندازهٔ بایتی آن‌ها از این مقدار بیشتر باشد. مقدار پیش‌فرض ۱۰۲۴ بایت است.
• 2
cookie -- اگر روی یک رشته تنظیم شود، نام کوکی HTTP خواهد بود که سرور حاوی شناسهٔ نشست (session id) کلاینت به آن بازمی‌گرداند. اگر روی یک دیکشنری تنظیم شود، کلید 'name' حاوی نام کوکی خواهد بود و سایر کلیدها مشخصه‌های کوکی را تعریف می‌کنند که در آن مقدار هر مشخصه می‌تواند یک رشته، یک فراخوانی‌پذیر (callable) بدون آرگومان، یا یک بولی باشد. در صورت تنظیم روی None (پیش‌فرض)، هیچ کوکی‌ای به کلاینت ارسال نمی‌شود.
• 2
cors_allowed_origins -- مبدا یا فهرستی از مبداهایی که مجاز به اتصال به این سرور هستند. به‌طور پیش‌فرض تنها همان مبدا (same origin) مجاز است. این آرگومان را روی *''** تنظیم کنید تا همهٔ مبداها مجاز شوند، یا برای غیرفعال کردن مدیریت CORS آن را روی [] قرار دهید.
• 2
cors_credentials -- مشخص می‌کند که آیا ارسال اطلاعات هویتی و اعتبارسنجی (کوکی‌ها، احراز هویت) در درخواست‌ها به این سرور مجاز است یا خیر. مقدار پیش‌فرض True است.
• 2
monitor_clients -- در صورت تنظیم روی True، یک وظیفهٔ پس‌زمینه اطمینان حاصل می‌کند که کلاینت‌های غیرفعال بسته شوند. برای غیرفعال‌سازی این وظیفهٔ نظارتی، آن را روی False تنظیم کنید (توصیه نمی‌شود). مقدار پیش‌فرض True است.
• 2
transports -- فهرست ترابری‌های مجاز. ترابری‌های معتبر شامل 'polling' و 'websocket' هستند. مقدار پیش‌فرض ['polling', 'websocket'] است.
• 2
engineio_logger -- برای فعال‌سازی گزارش‌گیری Engine.IO روی True تنظیم کنید یا یک شیء ثبت لاگ برای استفاده پاس دهید. برای غیرفعال‌سازی روی False تنظیم کنید. مقدار پیش‌فرض False است. توجه داشته باشید که خطاهای مرگبار حتی در صورت False بودن engineio_logger نیز ثبت می‌شوند.
0u
0u
7.0
call(event, data=None, to=None, sid=None, namespace=None, timeout=60, ignore_queue=False)
ارسال یک رویداد سفارشی به یک کلاینت و انتظار برای دریافت پاسخ.
این متد یک ارسال (emit) همراه با بازخوانی (callback) ایجاد می‌کند و پیش از بازگشت، منتظر فراخوانی شدن آن بازخوانی می‌ماند. اگر بازخوانی پیش از پایان مهلت زمانی فراخوانی نشود، یک استثنای TimeoutError صادر می‌شود. اگر اتصال Socket.IO در حین انتظار قطع شود، این متد همچنان تا پایان مهلت زمانی مشخص‌شده منتظر می‌ماند.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد 'connect'، 'message' و 'disconnect' رزرو شده‌اند و نباید استفاده شوند.
• 2
data -- داده‌ای که باید به کلاینت یا کلاینت‌ها ارسال شود. داده می‌تواند از نوع str، bytes، list یا dict باشد. برای ارسال چند آرگومان، از یک تاپل استفاده کنید که هر عضو آن یکی از نوع‌های اشاره‌شده در بالا باشد.
• 2
to -- شناسهٔ نشست (session ID) کلاینت گیرنده.
• 2
sid -- نام مستعار برای پارامتر to.
• 2
namespace -- فضای نام Socket.IO برای رویداد. در صورت عدم ذکر این آرگومان، رویداد به فضای نام پیش‌فرض ارسال می‌شود.
• 2
timeout -- مهلت زمانی انتظار. اگر مهلت پیش از آنکه کلاینت دریافت رویداد را تأیید کند به پایان برسد، استثنای TimeoutError صادر می‌شود.
• 2
ignore_queue -- تنها زمانی استفاده می‌شود که یک صف پیام (message queue) پیکربندی شده باشد. در صورت تنظیم روی True، رویداد مستقیماً و بدون عبور از صف برای کلاینت ارسال می‌شود. این حالت کارآمدتر است، اما تنها زمانی کار می‌کند که از یک فرآیند سرور منفرد استفاده شود. توصیه می‌شود همیشه این پارامتر را با مقدار پیش‌فرض آن، یعنی False باقی بگذارید.
0u
نکته: این متد thread-safe نیست. اگر چندین ریسه (thread) به طور هم‌زمان
در حال ارسال (emit) به یک کلاینت یکسان باشند، ممکن است پیام‌های تشکیل‌شده از
چندین بسته با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت،
از راه‌حل‌های همزمانی استاندارد (مانند یک شیء Lock) استفاده کنید.
0u
7.0
close_room(room, namespace=None)
بستن یک اتاق.
این تابع تمام کلاینت‌ها را از اتاق داده‌شده حذف می‌کند.
7.0
پارامترها
7.0
• 2
room -- نام اتاق.
• 2
namespace -- فضای نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
7.0
disconnect(sid, namespace=None, ignore_queue=False)
قطع اتصال یک کلاینت.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست (Session ID) کلاینت.
• 2
namespace -- فضای نام Socket.IO برای قطع اتصال. اگر این
آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود.
• 2
ignore_queue -- فقط زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. اگر
روی True تنظیم شود، قطع اتصال به صورت محلی پردازش شده و
بدون پخش همگانی (broadcast) در صف انجام می‌گیرد. توصیه می‌شود
همیشه این پارامتر با مقدار پیش‌فرض
False رها شود.
0u
0u
0u
7.0
emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)
ارسال (Emit) یک رویداد سفارشی به یک یا چند کلاینت متصل.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect'
رزرو شده هستند و نباید استفاده شوند.
• 2
data -- داده‌ها برای ارسال به کلاینت یا کلاینت‌ها. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک tuple استفاده کنید که هر عنصر آن از
یکی از انواع ذکرشده در بالا باشد.
• 2
to -- دریافت‌کننده پیام. این مقدار می‌تواند روی شناسه نشست یک کلاینت
تنظیم شود تا فقط همان کلاینت را مخاطب قرار دهد، یا روی هر
اتاق سفارشی ایجادشده توسط برنامه تنظیم شود تا تمام کلاینت‌های آن اتاق را مخاطب
قرار دهد، یا روی فهرستی از نام‌های اتاق‌های سفارشی تنظیم گردد. اگر این
آرگومان حذف شود، رویداد برای تمام کلاینت‌های متصل پخش همگانی (broadcast) می‌شود.
• 2
room -- نام مستعار برای پارامتر to.
• 2
skip_sid -- شناسه نشست کلاینتی که هنگام پخش همگانی به یک اتاق یا
به تمام کلاینت‌ها باید نادیده گرفته شود. از این مقدار می‌توان برای جلوگیری
از ارسال پیام به خود فرستنده استفاده کرد. برای نادیده گرفتن
چندین sid، یک list ارسال کنید.
• 2
namespace -- فضای نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، رویداد در فضای نام
پیش‌فرض ارسال می‌شود.
• 2
callback -- در صورت ارائه، این تابع برای تأیید دریافت پیام
توسط کلاینت فراخوانی خواهد شد. آرگومان‌هایی که به تابع پاس داده می‌شوند
همان مواردی هستند که توسط کلاینت فراهم شده‌اند. توابع callback فقط هنگام
مخاطب قرار دادن یک کلاینت منفرد قابل استفاده هستند.
• 2
ignore_queue -- فقط زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. اگر
روی True تنظیم شود، رویداد مستقیماً به کلاینت‌ها ارسال شده و از
صف عبور نمی‌کند. این حالت کارآمدتر است، اما تنها زمانی کار می‌کند
که از یک فرایند سرور منفرد استفاده شود. توصیه می‌شود
همیشه این پارامتر با مقدار پیش‌فرض
False رها شود.
0u
0u
نکته: این متد thread-safe نیست. اگر چندین ریسه (thread) به طور هم‌زمان
در حال ارسال (emit) به یک کلاینت یکسان باشند، ممکن است پیام‌های تشکیل‌شده از
چندین بسته با ترتیبی نادرست ارسال شوند. برای جلوگیری از این وضعیت،
از راه‌حل‌های همزمانی استاندارد (مانند یک شیء Lock) استفاده کنید.
0u
7.0
enter_room(sid, room, namespace=None)
ورود به یک اتاق.
این تابع کلاینت را به یک اتاق اضافه می‌کند. توابع emit() و
send() می‌توانند به صورت اختیاری رویدادها را برای تمام کلاینت‌های
موجود در یک اتاق پخش همگانی (broadcast) کنند.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست (Session ID) کلاینت.
• 2
room -- نام اتاق. اگر اتاق وجود نداشته باشد، ایجاد می‌شود.
• 2
namespace -- فضای نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
7.0
event(args, *kwargs)
دکوراتور برای ثبت یک گرداننده رویداد (event handler).
این یک نسخه ساده‌شده از متد on() است که نام رویداد را
از تابع دکوره‌شده دریافت می‌کند.
مثال کاربرد:
7.0
3.5
@sio.event
def my_event(data):
print('Received data: ', data)
0u
0u
مثال بالا معادل است با:
7.0
3.5
@sio.on('my_event')
def my_event(data):
print('Received data: ', data)
0u
0u
یک فضای نام سفارشی می‌تواند به عنوان آرگومان به دکوراتور داده شود:
7.0
3.5
@sio.event(namespace='/test')
def my_event(data):
print('Received data: ', data)
0u
0u
0u
7.0
get_environ(sid, namespace=None)
بازگرداندن دیکشنری WSGI environ برای یک کلاینت.
7.0
پارامترها
7.0
• 2
sid -- نشست کلاینت..IP • 2
namespace -- فضای نام Socket.IO. در صورت حذف این آرگومان،
از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
7.0
get_session(sid, namespace=None)
نشست کاربر را برای یک کلاینت برمی‌گرداند.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست (session id) کلاینت.
• 2
namespace -- فضای نام Socket.IO. در صورت حذف این آرگومان،
از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
مقدار بازگشتی یک دیکشنری است. هیچ تضمینی برای حفظ تغییرات اعمال‌شده در این
دیکشنری وجود ندارد مگر اینکه save_session() فراخوانی شود، یا از مدیر زمینه (context manager)
session استفاده گردد.
0u
7.0
handle_request(environ, start_response)
یک درخواست HTTP را از سمت کلاینت مدیریت می‌کند.
این نقطه ورود برنامه Socket.IO است که از همان رابط برنامه WSGI استفاده
می‌کند. در کاربردهای متداول، این تابع توسط نمونه Middleware
<#socketio.Middleware> فراخوانی می‌شود، اما در صورت عدم استفاده از
میان‌افزار، می‌توان آن را مستقیماً فراخوانی کرد.
7.0
پارامترها
7.0
• 2
environ -- محیط WSGI.
• 2
start_response -- تابع start_response در WSGI.
0u
0u
این تابع بدنه پاسخ HTTP را به عنوان یک دنباله بایت برای تحویل به کلاینت
برمی‌گرداند.
0u
7.0
instrument(auth=None, mode='development', read_only=False, server_id=None, namespace='/admin', server_stats_interval=2)
تجهیز و آماده‌سازی سرور Socket.IO برای نظارت با Socket.IO
Admin UI https://socket.io/docs/v4/admin-ui.
7.0
پارامترها
7.0
• 2
auth -- اطلاعات احراز هویت برای دسترسی به Admin UI. به یک دیکشنری با
اطلاعات ورود مورد انتظار (معمولاً username و password) یا
فهرستی از دیکشنری‌ها در صورتی که بیش از یک دسته اطلاعات احراز هویت مورد نیاز
باشد تنظیم می‌شود. برای روش‌های احراز هویت پیچیده‌تر، به یک شیء قابل فراخوانی (callable)
تنظیم شود که دیکشنری احراز هویت را به عنوان آرگومان دریافت کرده و در صورت مجاز بودن
کاربر True یا در غیر این صورت False برمی‌گرداند. برای غیرفعال کردن
احراز هویت، این آرگومان را روی False قرار دهید (توصیه نمی‌شود؛ هرگز این کار را
روی یک سرور عملیاتی انجام ندهید).
• 2
mode -- حالت گزارش‌دهی. مقدار پیش‌فرض 'development' است
که بهتر است هنگام اشکال‌زدایی استفاده شود، چرا که ممکن است تأثیر قابل‌توجهی بر عملکرد
داشته باشد. برای کاهش میزان اطلاعات گزارش‌شده به Admin UI، آن را
روی 'production' تنظیم کنید.
• 2
read_only -- در صورت تنظیم روی True، رابط کاربری مدیریت به صورت
فقط‌خواندنی (read-only) خواهد بود، بدون امکان تغییر تخصیص اتاق‌ها یا قطع اتصال کلاینت‌ها.
مقدار پیش‌فرض False است.
• 2
server_id -- نام سرور برای استفاده در این سرور. در صورت حذف این آرگومان،
سرور نام خود را تولید می‌کند.
• 2
namespace -- فضای نام Socket.IO برای استفاده در رابط کاربری مدیریت.
مقدار پیش‌فرض /admin است.
• 2
server_stats_interval -- بازه زمانی بر حسب ثانیه که در آن سرور خلاصه‌ای
از آمار خود را برای تمامی مدیران متصل ارسال (emit) می‌کند.
0u
0u
0u
7.0
leave_room(sid, room, namespace=None)
ترک یک اتاق.
این تابع کلاینت را از یک اتاق خارج می‌کند.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست (Session ID) کلاینت.
• 2
room -- نام اتاق.
• 2
namespace -- فضای نام Socket.IO برای رویداد. در صورت حذف این آرگومان،
از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
7.0
on(event, handler=None, namespace=None)
ثبت یک گرداننده رویداد.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect' رزرو
شده‌اند و نباید استفاده شوند. نام رویداد *''** می‌تواند برای تعریف
یک گرداننده رویداد فراگیر (catch-all) استفاده شود.
• 2
handler -- تابعی که باید برای مدیریت رویداد فراخوانی شود. در صورتی که
این پارامتر مشخص نشود، این متد به عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند.
• 2
namespace -- فضای نام Socket.IO برای رویداد. در صورت حذف این آرگومان،
گرداننده به فضای نام پیش‌فرض مرتبط می‌شود. با ارسال *''** به عنوان
فضای نام، می‌توان یک فضای نام فراگیر (catch-all) تعریف کرد.
0u
0u
نمونه استفاده:
7.0
3.5
# as a decorator:
@sio.on('connect', namespace='/chat')
def connect_handler(sid, environ):
print('Connection request')
if environ['REMOTE_ADDR'] in blacklisted:
return False # reject
# as a method:
def message_handler(sid, msg):
print('Received message: ', msg)
sio.send(sid, 'response')
socket_io.on('message', namespace='/chat', handler=message_handler)
0u
0u
آرگومان‌های ارسال‌شده به تابع گرداننده به نوع رویداد بستگی دارد:
7.0
• 2
گرداننده رویداد 'connect' آرگومان‌های sid (شناسه نشست) برای
کلاینت و دیکشنری محیط WSGI را دریافت می‌کند.
• 2
گرداننده 'disconnect' شناسه sid کلاینت را به عنوان تنها
آرگومان دریافت می‌کند.
• 2
گرداننده 'message' و گرداننده‌های نام‌های رویداد سفارشی، sid
کلاینت و محموله پیام را به عنوان آرگومان دریافت می‌کنند. هر مقداری که از یک گرداننده
پیام بازگردانده شود، در صورت وجود تابع بازخوانی تأییدیه کلاینت (acknowledgement callback)،
به آن ارسال خواهد شد.
• 2
یک گرداننده رویداد فراگیر (catch-all)، نام رویداد را به عنوان آرگومان اول،
به همراه آرگومان‌های اختصاصی رویداد دریافت می‌کند.
• 2
یک گرداننده رویداد فضای نام فراگیر (catch-all)، فضای نام را به عنوان آرگومان اول،
به همراه آرگومان‌های اختصاصی رویداد دریافت می‌کند.
• 2
یک گرداننده ترکیبی فضای نام فراگیر و رویداد فراگیر، نام رویداد را به عنوان
آرگومان اول و فضای نام را به عنوان آرگومان دوم، به همراه آرگومان‌های اختصاصی رویداد
دریافت می‌کند.
0u
0u
7.0.TP
class reason
دلایل قطع اتصال.
7.0
CLIENT_DISCONNECT = 'client disconnect'
قطع اتصال آغاز شده از سوی کلاینت.
0u
7.0
PING_TIMEOUT = 'ping timeout'
اتمام مهلت پینگ (Ping timeout).
0u
7.0
SERVER_DISCONNECT = 'server disconnect'
قطع اتصال آغاز شده از سوی سرور.
0u
7.0
TRANSPORT_CLOSE = 'transport close'
بسته شدن لایه انتقال (Transport close).
0u
7.0
TRANSPORT_ERROR = 'transport error'
خطای لایه انتقال (Transport error).
0u
0u
7.0
register_namespace(namespace_handler)
ثبت یک شیء گرداننده فضای‌نام (namespace handler).
7.0
پارامترها (Parameters)
namespace_handler -- نمونه‌ای از زیرکلاس Namespace <#socketio.Namespace>
که تمام ترافیک رویدادها را برای یک فضای‌نام
مدیریت می‌کند.
0u
0u
7.0
rooms(sid, namespace=None)
اتاق‌هایی را که یک کلاینت در آن‌ها حضور دارد برمی‌گرداند.
7.0
پارامترها (Parameters)
7.0
• 2
sid -- شناسه نشست (Session ID) کلاینت.
• 2
namespace -- فضای‌نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، از فضای‌نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
7.0
save_session(sid, session, namespace=None)
ذخیره نشست کاربر برای یک کلاینت.
7.0
پارامترها (Parameters)
7.0
• 2
sid -- شناسه نشست کلاینت.
• 2
session -- دیکشنری نشست (session dictionary).
• 2
namespace -- فضای‌نام Socket.IO. اگر این آرگومان حذف شود،
از فضای‌نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
7.0
send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)
ارسال یک پیام به یک یا چند کلاینت متصل.
این تابع رویدادی با نام 'message' منتشر می‌کند. برای
صدور رویدادهایی با نام‌های سفارشی از emit() استفاده کنید.
7.0
پارامترها (Parameters)
7.0
• 2
data -- داده ارسالی به کلاینت یا کلاینت‌ها. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک تاپل (tuple) استفاده کنید که هر عنصر آن از
یکی از انواع ذکر شده در بالا باشد.
• 2
to -- گیرنده پیام. این مقدار می‌تواند روی شناسه نشست یک کلاینت
تنظیم شود تا فقط آن کلاینت را مخاطب قرار دهد، روی هر اتاق
سفارشی ایجادشده توسط برنامه تا تمام کلاینت‌های آن اتاق را مخاطب
قرار دهد، یا روی فهرستی از نام‌های سفارشی اتاق‌ها تنظیم شود. اگر این
آرگومان حذف شود، رویداد برای تمام کلاینت‌های متصل همگانی (broadcast)
می‌شود.
• 2
room -- نام مستعار برای پارامتر to.
• 2
skip_sid -- شناسه نشست کلاینتی که هنگام انتشار همگانی در
یک اتاق یا برای تمام کلاینت‌ها باید نادیده گرفته شود. از این مقدار می‌توان
برای جلوگیری از ارسال پیام به فرستنده استفاده کرد. برای
نادیده گرفتن چندین sid، یک فهرست ارسال کنید.
• 2
namespace -- فضای‌نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، رویداد در فضای‌نام
پیش‌فرض منتشر می‌شود.
• 2
callback -- در صورت ارائه، این تابع برای تأیید دریافت پیام
توسط کلاینت فراخوانی می‌شود. آرگومان‌هایی که به این تابع منتقل
می‌شوند، همان مواردی هستند که توسط کلاینت ارائه شده‌اند. توابع بازخوانی
(Callback) فقط هنگام مخاطب قرار دادن یک کلاینت مجزا قابل استفاده هستند.
• 2
ignore_queue -- فقط هنگامی که یک صف پیام (message queue) پیکربندی شده باشد استفاده می‌شود. اگر
روی True تنظیم شود، رویداد مستقیماً و بدون عبور
از صف برای کلاینت‌ها ارسال می‌شود. این روش کارآمدتر است، اما
تنها هنگامی کار می‌کند که از یک فرآیند سرور واحد استفاده شود.
توصیه می‌شود همیشه این پارامتر را با مقدار پیش‌فرض خود یعنی
False باقی بگذارید.
0u
0u
0u
7.0
session(sid, namespace=None)
بازگرداندن نشست کاربر برای یک کلاینت با نحو مدیر زمینه (context manager).
7.0
پارامترها (Parameters)
sid -- شناسه نشست کلاینت.
0u
این یک مدیر زمینه (context manager) است که دیکشنری نشست کاربر را برای
کلاینت برمی‌گرداند. هرگونه تغییری که در این دیکشنری درون بلوک مدیر زمینه
اعمال شود، دوباره در نشست ذخیره می‌شود. نمونه کاربرد:
7.0
3.5
@sio.on('connect')
def on_connect(sid, environ):
username = authenticate_user(environ)
if not username:
return False
with sio.session(sid) as session:
session['username'] = username
@sio.on('message')
def on_message(sid, msg):
with sio.session(sid) as session:
print('received message from ', session['username'])
0u
0u
0u
7.0
shutdown()
توقف وظایف پس‌زمینه Socket.IO.
این متد تمام فعالیت‌های پس‌زمینه آغاز شده توسط سرور Socket.IO
را متوقف می‌کند. این متد باید پیش از خاموش کردن وب‌سرور فراخوانی شود.
0u
7.0
sleep(seconds=0)
خوابیدن به میزان زمان درخواستی با استفاده از مدل ناهمگام (async)
مناسب.
این یک تابع کمکی است که برنامه‌ها می‌توانند از آن برای به خواب بردن
یک وظیفه بدون نیاز به نگرانی درباره استفاده از فراخوانی صحیح برای حالت
async انتخاب‌شده استفاده کنند.
0u
7.0
start_background_task(target, args, *kwargs)
شروع یک وظیفه پس‌زمینه با استفاده از مدل ناهمگام (async) مناسب..sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای شروع یک
وظیفه پس‌زمینه با استفاده از روش سازگار با حالت ناهمگام
(async mode) انتخاب‌شده، از آن استفاده کنند.
7.0
پارامترها
7.0
• 2
target -- تابع هدف برای اجرا.
• 2
args -- آرگومان‌ها برای ارسال به تابع.
• 2
kwargs -- آرگومان‌های کلیدواژه‌ای برای ارسال به تابع.
0u
0u
این تابع شیئی را برمی‌گرداند که نمایندهٔ وظیفه پس‌زمینه است،
و می‌توان متد join() را روی آن فراخوانی کرد تا منتظر
تکمیل وظیفه بماند.
0u
7.0
transport(sid, namespace=None)
نام روش انتقال (transport) استفاده‌شده توسط کلاینت را برمی‌گرداند.
دو مقدار ممکن بازگردانده‌شده توسط این تابع 'polling'
و 'websocket' هستند.
7.0
پارامترها
7.0
• 2
sid -- نشست (session) کلاینت.
• 2
namespace -- فضای نام Socket.IO. در صورت حذف این آرگومان،
از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
0u
0.0
class socketio.AsyncServer(client_manager=None, logger=False, json=None, async_handlers=True, namespaces=None, **kwargs)
یک سرور Socket.IO برای asyncio.
این کلاس یک وب‌سرور Socket.IO کاملاً سازگار را با پشتیبانی از
روش‌های انتقال websocket و long-polling، و سازگار با چارچوب
asyncio پیاده‌سازی می‌کند.
7.0
پارامترها
7.0
• 2
client_manager -- نمونه مدیر کلاینت که فهرست کلاینت‌ها را
مدیریت می‌کند. در صورت حذف این مورد، فهرست کلاینت‌ها در یک
ساختار درون‌حافظه‌ای ذخیره می‌شود، بنابراین استفاده از چند
سرور متصل امکان‌پذیر نخواهد بود.
• 2
logger -- برای فعال‌سازی گزارش‌گیری روی True تنظیم کنید
یا یک شیء logger را برای استفاده بفرستید. برای غیرفعال‌سازی
گزارش‌گیری روی False قرار دهید. توجه داشته باشید که خطاهای
مهلک حتی در صورت False بودن logger نیز ثبت می‌شوند.
• 2
json -- یک ماژول جایگزین JSON برای رمزگذاری و رمزگشایی
بسته‌ها. ماژول‌های سفارشی json باید توابع dumps و loads
سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این یک
تنظیم در سطح کل فرآیند است؛ همه سرورها و کلاینت‌های
نمونه‌سازی‌شده باید از یک ماژول JSON استفاده کنند.
• 2
async_handlers -- در صورت تنظیم روی True، گرداننده‌های
رویداد برای یک کلاینت در ریسمان‌های جداگانه اجرا می‌شوند.
برای اجرای همگام گرداننده‌ها برای کلاینت، آن را روی False
تنظیم کنید. مقدار پیش‌فرض True است.
• 2
always_connect -- در صورت تنظیم روی False، اتصالات جدید
موقتی هستند تا زمانی که گرداننده connect مقداری به غیر از
False برگرداند، که در آن زمان پذیرفته می‌شوند. در صورت
تنظیم روی True، اتصالات بلافاصله پذیرفته می‌شوند و سپس اگر
گرداننده connect مقدار False برگرداند، دستور قطع اتصال
صادر می‌شود. اگر لازم است از گرداننده connect رویداد منتشر کنید
و کلاینت با دریافت رویدادها قبل از پذیرش اتصال دچار سردرگمی می‌شود،
آن را روی True تنظیم کنید. در هر حالت دیگر از مقدار
پیش‌فرض False استفاده کنید.
• 2
namespaces -- فهرستی از فضاهای نام پذیرفته‌شده، علاوه بر هر
فضای نامی که برای آن گرداننده‌ای تعریف شده باشد. مقدار پیش‌فرض
['/'] است که همواره اتصالات به فضای نام پیش‌فرض را
می‌پذیرد. برای پذیرش همه فضاهای نام، آن را روی ''*
تنظیم کنید.
• 2
kwargs -- پارامترهای اتصال برای سرور زیرین Engine.IO.
0u
0u
پیکربندی Engine.IO از تنظیمات زیر پشتیبانی می‌کند:
7.0
پارامترها
7.0
• 2
async_mode -- مدل ناهمگام مورد استفاده. برای توضیحات
گزینه‌های موجود، بخش Deployment در مستندات را ببینید.
حالت‌های ناهمگام معتبر عبارتند از "aiohttp"،
"sanic"، "tornado" و "asgi". اگر این آرگومان
داده نشود، ابتدا "aiohttp"، سپس "sanic"، بعد
"tornado" و در نهایت "asgi" امتحان می‌شود. نخستین
حالت ناهمگامی که تمام وابستگی‌های آن نصب باشد انتخاب می‌شود.
• 2
ping_interval -- بازه زمانی به ثانیه که سرور برای کلاینت
پینگ ارسال می‌کند. پیش‌فرض 25 ثانیه است. برای کنترل پیشرفته‌تر،
می‌توان یک تاپل دو عنصری مشخص کرد که در آن عدد اول بازه پینگ و
عدد دوم مهلت زمانی اضافه‌ای است که سرور اضافه می‌کند.
• 2
ping_timeout -- مدت زمانی به ثانیه که کلاینت پیش از قطع
اتصال، منتظر پاسخ سرور می‌ماند. پیش‌فرض 20 ثانیه است.
• 2
max_http_buffer_size -- بیشینه اندازه پذیرفته‌شده برای
پیام‌های ورودی. مقدار پیش‌فرض 1,000,000 بایت است. بر خلاف نام آن،
مقدار مشخص‌شده در این آرگومان برای هر دو اتصال HTTP long-polling
و WebSocket اعمال می‌شود.
• 2
allow_upgrades -- مجاز بودن یا نبودن ارتقای روش انتقال.
پیش‌فرض True است.
• 2
http_compression -- فشرده‌سازی بسته‌ها هنگام استفاده از
روش انتقال polling. پیش‌فرض True است.
• 2
compression_threshold -- فشرده‌سازی پیام‌ها تنها در صورتی که
اندازه بایت آن‌ها بزرگ‌تر از این مقدار باشد. پیش‌فرض 1024
بایت است.
• 2
cookie -- در صورت تنظیم روی یک رشته، نام کوکی HTTP خواهد بود
که سرور حاوی شناسه نشست کلاینت به کلاینت بازمی‌گرداند. در صورت
تنظیم روی یک دیکشنری، کلید 'name' حاوی نام کوکی خواهد بود
و سایر کلیدها ویژگی‌های کوکی را تعیین می‌کنند، که در آن مقدار هر
ویژگی می‌تواند یک رشته، یک تابع فراخوانی‌پذیر بدون آرگومان، یا
یک بولی باشد. در صورت تنظیم روی None (پیش‌فرض)، هیچ کوکی‌ای
به کلاینت ارسال نمی‌شود.
• 2
cors_allowed_origins -- مبدا یا فهرستی از مبداهای مجاز برای
اتصال به این سرور. به‌طور پیش‌فرض تنها همان مبدا (same origin)
مجاز است. این آرگومان را روی *''** برای مجاز کردن همه
مبداها، یا روی [] برای غیرفعال کردن مدیریت CORS تنظیم کنید.
• 2
cors_credentials -- مجاز بودن یا نبودن اطلاعات اعتبارسنجی
(کوکی‌ها، احراز هویت) در درخواست‌ها به این سرور. مقدار پیش‌فرض
True است.
• 2
monitor_clients -- در صورت تنظیم روی True، یک وظیفه
پس‌زمینه اطمینان حاصل می‌کند که کلاینت‌های غیرفعال بسته شوند.
برای غیرفعال‌سازی این وظیفه نظارتی (توصیه نمی‌شود)، آن را روی
False قرار دهید. مقدار پیش‌فرض True است.
• 2
transports -- فهرست روش‌های انتقال مجاز. گزینه‌های معتبر
'polling' و 'websocket' هستند. مقدار پیش‌فرض
['polling', 'websocket'] است.
• 2
engineio_logger -- برای فعال‌سازی گزارش‌گیری Engine.IO روی
True تنظیم کنید یا یک شیء logger را برای استفاده ارسال نمایید.
برای غیرفعال‌سازی، آن را روی False قرار دهید. پیش‌فرض
False است. توجه داشته باشید که خطاهای مهلک حتی زمانی که
engineio_logger مقدار False دارد نیز ثبت می‌شوند.
0u
0u
7.0
attach(app, socketio_path='socket.io')
متصل کردن سرور Socket.IO به یک برنامه.
0u
7.0
async call(event, data=None, to=None, sid=None, namespace=None, timeout=60, ignore_queue=False)
ارسال یک رویداد سفارشی به یک کلاینت و انتظار برای دریافت پاسخ..sp
این متد یک ارسال (emit) به همراه بازخورد (callback) صادر می‌کند و پیش از بازگشت، منتظر فراخوانی بازخورد می‌ماند. اگر بازخورد پیش از اتمام مهلت زمانی (timeout) فراخوانی نشود، یک استثنای TimeoutError ایجاد می‌شود. اگر اتصال Socket.IO در طول زمان انتظار قطع شود، این متد همچنان تا پایان مهلت زمانی مشخص‌شده منتظر می‌ماند.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect'
رزرو شده‌اند و نباید استفاده شوند.
• 2
data -- داده برای ارسال به کلاینت یا کلاینت‌ها. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک tuple استفاده کنید که هر عضو آن از
یکی از انواع اشاره‌شده در بالا باشد.
• 2
to -- شناسه نشست (session ID) کلاینت گیرنده.
• 2
sid -- نام مستعار برای پارامتر to.
• 2
namespace -- فضای‌نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، رویداد در فضای‌نام
پیش‌فرض منتشر می‌شود.
• 2
timeout -- مهلت زمانی انتظار. اگر پیش از تأیید دریافت
رویداد توسط کلاینت، مهلت زمانی به پایان برسد، یک
استثنای TimeoutError ایجاد می‌شود.
• 2
ignore_queue -- تنها زمانی استفاده می‌شود که یک صف پیام (message queue) پیکربندی شده باشد. اگر
روی True تنظیم شود، رویداد مستقیماً و
بدون عبور از صف برای کلاینت ارسال می‌شود.
این روش کارآمدتر است، اما تنها زمانی کار می‌کند که از
یک فرآیند سرور تکی استفاده شود. توصیه می‌شود
همیشه این پارامتر را روی مقدار پیش‌فرض خود
یعنی False باقی بگذارید.
0u
0u
نکته: این متد برای استفاده هم‌روند طراحی نشده است. اگر چندین
تسک به طور هم‌زمان به یک اتصال کلاینت رویداد ارسال کنند، ممکن است
پیام‌های متشکل از چندین بسته با ترتیبی نادرست
ارسال شوند. برای جلوگیری از این وضعیت، از راهکارهای استاندارد هم‌روندی (مانند شیء Lock)
استفاده کنید.
نکته ۲: این متد یک کوروتین (coroutine) است.
0u
7.0
async close_room(room, namespace=None)
بستن یک اتاق.
این تابع همه کلاینت‌ها را از اتاق داده‌شده حذف می‌کند.
7.0
پارامترها
7.0
• 2
room -- نام اتاق.
• 2
namespace -- فضای‌نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، از فضای‌نام پیش‌فرض استفاده می‌شود.
0u
0u
نکته: این متد یک کوروتین (coroutine) است.
0u
7.0
async disconnect(sid, namespace=None, ignore_queue=False)
قطع اتصال یک کلاینت.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست کلاینت.
• 2
namespace -- فضای‌نام Socket.IO برای قطع اتصال. اگر این
آرگومان حذف شود، از فضای‌نام پیش‌فرض استفاده می‌شود.
• 2
ignore_queue -- تنها زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. اگر
روی True تنظیم شود، قطع اتصال به صورت
محلی و بدون انتشار در صف پردازش می‌شود. توصیه
می‌شود همیشه این پارامتر را روی مقدار
پیش‌فرض خود یعنی False باقی بگذارید.
0u
0u
نکته: این متد یک کوروتین (coroutine) است.
0u
7.0
async emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)
ارسال یک رویداد سفارشی به یک یا چند کلاینت متصل.
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد
'connect'، 'message' و 'disconnect'
رزرو شده‌اند و نباید استفاده شوند.
• 2
data -- داده برای ارسال به کلاینت یا کلاینت‌ها. داده می‌تواند از
نوع str، bytes، list یا dict باشد. برای ارسال
چندین آرگومان، از یک tuple استفاده کنید که هر عضو آن از
یکی از انواع اشاره‌شده در بالا باشد.
• 2
to -- گیرنده پیام. این پارامتر می‌تواند روی
شناسه نشست یک کلاینت برای مخاطب قرار دادن تنها همان کلاینت، روی
هر اتاق سفارشی ایجادشده توسط برنامه برای مخاطب قرار دادن تمام
کلاینت‌های آن اتاق، یا روی فهرستی از نام‌های اتاق‌های سفارشی
تنظیم شود. اگر این آرگومان حذف شود، رویداد برای
تمام کلاینت‌های متصل منتشر (broadcast) می‌شود.
• 2
room -- نام مستعار برای پارامتر to.
• 2
skip_sid -- شناسه نشست کلاینتی که هنگام انتشار برای یک اتاق
یا تمام کلاینت‌ها باید نادیده گرفته شود. از این پارامتر می‌توان برای
جلوگیری از ارسال پیام به فرستنده استفاده کرد.
• 2
namespace -- فضای‌نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، رویداد در فضای‌نام
پیش‌فرض منتشر می‌شود.
• 2
callback -- در صورت ارائه، این تابع برای تأیید
دریافت پیام توسط کلاینت فراخوانی خواهد شد. آرگومان‌هایی
که به تابع ارسال می‌شوند، همان‌هایی هستند که توسط کلاینت
ارائه شده‌اند. توابع بازخورد تنها هنگام
مخاطب قرار دادن یک کلاینت واحد قابل استفاده هستند.
• 2
ignore_queue -- تنها زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. اگر
روی True تنظیم شود، رویداد مستقیماً و
بدون عبور از صف برای کلاینت‌ها ارسال می‌شود.
این روش کارآمدتر است، اما تنها زمانی کار می‌کند که از
یک فرآیند سرور تکی استفاده شود. توصیه می‌شود
همیشه این پارامتر را روی مقدار پیش‌فرض خود
یعنی False باقی بگذارید.
0u
0u
نکته: این متد برای استفاده هم‌روند طراحی نشده است. اگر چندین
تسک به طور هم‌زمان به یک اتصال کلاینت رویداد ارسال کنند، ممکن است
پیام‌های متشکل از چندین بسته با ترتیبی نادرست
ارسال شوند. برای جلوگیری از این وضعیت، از راهکارهای استاندارد هم‌روندی (مانند شیء Lock)
استفاده کنید.
نکته ۲: این متد یک کوروتین (coroutine) است.
0u
7.0
async enter_room(sid, room, namespace=None)
ورود به یک اتاق.
این تابع کلاینت را به یک اتاق اضافه می‌کند. توابع emit() و
send() می‌توانند به صورت اختیاری رویدادها را برای تمام
کلاینت‌های یک اتاق منتشر کنند.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست کلاینت.
• 2
room -- نام اتاق. اگر اتاق وجود نداشته باشد، ایجاد می‌شود.
• 2
namespace -- فضای‌نام Socket.IO برای رویداد. اگر این
آرگومان حذف شود، از فضای‌نام پیش‌فرض استفاده می‌شود.
0u
0u
نکته: این متد یک کوروتین (coroutine) است.
0u
7.0
event(args, *kwargs)
دکوراتور (Decorator) برای ثبت یک گرداننده رویداد (event handler)..sp
این یک نسخهٔ ساده‌شده از متد on() است که نام رویداد را از تابع تزئین‌شده (decorated) دریافت می‌کند.
نمونه استفاده:
7.0
3.5
@sio.event
def my_event(data):
print('Received data: ', data)
0u
0u
مثال بالا معادل است با:
7.0
3.5
@sio.on('my_event')
def my_event(data):
print('Received data: ', data)
0u
0u
می‌توان یک فضای نام (namespace) سفارشی را به‌عنوان آرگومان به دکوراتور داد:
7.0
3.5
@sio.event(namespace='/test')
def my_event(data):
print('Received data: ', data)
0u
0u
0u
7.0
get_environ(sid, namespace=None)
دیکشنری WSGI environ را برای یک کلاینت بازمی‌گرداند.
7.0
پارامترها
7.0
• 2
sid -- نشست (session) کلاینت.
• 2
namespace -- فضای نام Socket.IO. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
7.0
async get_session(sid, namespace=None)
نشست کاربری (user session) را برای یک کلاینت بازمی‌گرداند.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست (session id) کلاینت.
• 2
namespace -- فضای نام Socket.IO. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
مقدار بازگشتی یک دیکشنری است. هیچ تضمینی وجود ندارد که تغییرات اعمال‌شده در این دیکشنری حفظ شوند. اگر می‌خواهید نشست کاربری را تغییر دهید، به‌جای آن از مدیر زمینه (context manager) session استفاده کنید.
0u
7.0
async handle_request(args, *kwargs)
یک درخواست HTTP را از سمت کلاینت مدیریت و پردازش می‌کند.
این نقطهٔ ورود برنامهٔ Socket.IO است. این تابع بدنهٔ پاسخ HTTP را جهت ارسال به کلاینت بازمی‌گرداند.
نکته: این متد یک coroutine (هم‌روال) است.
0u
7.0
instrument(auth=None, mode='development', read_only=False, server_id=None, namespace='/admin', server_stats_interval=2)
سرور Socket.IO را جهت نظارت و پایش توسط Socket.IO Admin UI https://socket.io/docs/v4/admin-ui آماده‌سازی و ابزارگذاری (instrument) می‌کند.
7.0
پارامترها
7.0
• 2
auth -- اطلاعات اعتبارسنجی برای دسترسی به Admin UI. به یک دیکشنری با اطلاعات ورود مورد انتظار (معمولاً username و password) یا لیستی از دیکشنری‌ها در صورتی که به بیش از یک مجموعه اطلاعات اعتبارسنجی نیاز باشد تنظیم می‌شود. برای روش‌های احراز هویت پیچیده‌تر، آن را به یک شیء قابل فراخوانی (callable) تنظیم کنید که دیکشنری اعتبارسنجی را به‌عنوان آرگومان دریافت کرده و در صورت مجاز بودن کاربر True یا در غیر این صورت False بازمی‌گرداند. برای غیرفعال کردن احراز هویت، این آرگومان را روی False تنظیم کنید (توصیه نمی‌شود؛ هرگز این کار را روی سرور عملیاتی یا production انجام ندهید).
• 2
mode -- حالت گزارش‌دهی. پیش‌فرض 'development' است که بهترین کاربرد آن هنگام اشکال‌زدایی است، زیرا ممکن است تأثیر چشمگیری بر کارایی داشته باشد. برای کاهش میزان اطلاعات گزارش‌شده به رابط Admin UI، آن را روی 'production' تنظیم کنید.
• 2
read_only -- اگر روی True تنظیم شود، رابط مدیریتی فقط‌خواندنی (read-only) خواهد بود و امکانی برای تغییر انتساب اتاق‌ها یا قطع اتصال کلاینت‌ها وجود نخواهد داشت. پیش‌فرض False است.
• 2
server_id -- نام سرور مورد استفاده برای این سرور. اگر این آرگومان حذف شود، سرور نام خود را تولید می‌کند.
• 2
namespace -- فضای نام Socket.IO برای استفاده در رابط مدیریتی. پیش‌فرض /admin است.
• 2
server_stats_interval -- بازهٔ زمانی برحسب ثانیه که در آن سرور خلاصه‌ای از آمارهای خود را برای همهٔ مدیران متصل ارسال (emit) می‌کند.
0u
0u
0u
7.0
async leave_room(sid, room, namespace=None)
ترک یک اتاق.
این تابع کلاینت را از یک اتاق خارج می‌کند.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست (session ID) کلاینت.
• 2
room -- نام اتاق.
• 2
namespace -- فضای نام Socket.IO برای این رویداد. اگر این آرگومان حذف شود، از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
نکته: این متد یک coroutine (هم‌روال) است.
0u
7.0
on(event, handler=None, namespace=None)
ثبت یک گردانندهٔ رویداد (event handler).
7.0
پارامترها
7.0
• 2
event -- نام رویداد. می‌تواند هر رشته‌ای باشد. نام‌های رویداد 'connect'، 'message' و 'disconnect' رزرو شده‌اند و نباید استفاده شوند. از نام رویداد *''** می‌توان برای تعریف یک گردانندهٔ رویداد فراگیر (catch-all) استفاده کرد.
• 2
handler -- تابعی که باید برای مدیریت رویداد فراخوانی شود. زمانی که این پارامتر مشخص نشده باشد، متد به‌عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند.
• 2
namespace -- فضای نام Socket.IO برای رویداد. اگر این آرگومان حذف شود، گرداننده با فضای نام پیش‌فرض مرتبط می‌شود. با ارسال *''** به‌عنوان فضای نام، می‌توان یک فضای نام فراگیر (catch-all) تعریف کرد.
0u
0u
نمونه استفاده:
7.0
3.5.sp
# as a decorator:
@sio.on('connect', namespace='/chat')
def connect_handler(sid, environ):
print('Connection request')
if environ['REMOTE_ADDR'] in blacklisted:
return False # reject
# as a method:
def message_handler(sid, msg):
print('Received message: ', msg)
sio.send(sid, 'response')
socket_io.on('message', namespace='/chat', handler=message_handler)
0u
0u
آرگومان‌های ارسال‌شده به تابع گرداننده به نوع رویداد بستگی دارند:
7.0
• 2
گرداننده رویداد 'connect' مقدار sid (شناسه نشست) برای کلاینت و دیکشنری محیط WSGI را به عنوان آرگومان دریافت می‌کند.
• 2
گرداننده 'disconnect' مقدار sid برای کلاینت را به عنوان تنها آرگومان دریافت می‌کند.
• 2
گرداننده 'message' و گرداننده‌های نام‌های رویداد سفارشی، sid برای کلاینت و بار داده (payload) پیام را به عنوان آرگومان دریافت می‌کنند. هر مقداری که از گرداننده پیام بازگردانده شود، در صورت وجود به تابع فراخوانی بازگشتی (callback) تأییدیه کلاینت ارسال خواهد شد.
• 2
یک گرداننده رویداد فراگیر (catch-all)، نام رویداد را به عنوان آرگومان نخست و پس از آن آرگومان‌های ویژه رویداد را دریافت می‌کند.
• 2
یک گرداننده رویداد فضای نام فراگیر، فضای نام را به عنوان آرگومان نخست و پس از آن آرگومان‌های ویژه رویداد را دریافت می‌کند.
• 2
یک گرداننده ترکیبی رویداد و فضای نام فراگیر، نام رویداد را به عنوان آرگومان نخست و فضای نام را به عنوان آرگومان دوم، و پس از آن آرگومان‌های ویژه رویداد را دریافت می‌کند.
0u
0u
7.0
class reason
دلایل قطع اتصال.
7.0
CLIENT_DISCONNECT = 'client disconnect'
قطع اتصال آغازشده از سوی کلاینت.
0u
7.0
PING_TIMEOUT = 'ping timeout'
اتمام مهلت زمانی پینگ (Ping timeout).
0u
7.0
SERVER_DISCONNECT = 'server disconnect'
قطع اتصال آغازشده از سوی سرور.
0u
7.0
TRANSPORT_CLOSE = 'transport close'
بسته شدن لایه انتقال (Transport close).
0u
7.0
TRANSPORT_ERROR = 'transport error'
خطای لایه انتقال (Transport error).
0u
0u
7.0
register_namespace(namespace_handler)
ثبت یک شیء گرداننده فضای نام.
7.0
پارامترها
namespace_handler -- نمونه‌ای از زیرکلاس Namespace <#socketio.Namespace> که تمام ترافیک رویداد را برای یک فضای نام مدیریت می‌کند.
0u
0u
7.0
rooms(sid, namespace=None)
اتاق‌هایی که کلاینت در آن‌ها حضور دارد را بازمی‌گرداند.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست کلاینت.
• 2
namespace -- فضای نام Socket.IO برای رویداد. در صورت حذف این آرگومان، از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
7.0
async save_session(sid, session, namespace=None)
ذخیره نشست کاربر برای یک کلاینت.
7.0
پارامترها
7.0
• 2
sid -- شناسه نشست کلاینت.
• 2
session -- دیکشنری نشست.
• 2
namespace -- فضای نام Socket.IO. در صورت حذف این آرگومان، از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
7.0
async send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)
ارسال یک پیام به یک یا چند کلاینت متصل.
این تابع رویدادی با نام 'message' منتشر می‌کند. برای ارسال نام‌های رویداد سفارشی از emit() استفاده کنید.
7.0
پارامترها
7.0
• 2
data -- داده ارسالی به کلاینت یا کلاینت‌ها. داده می‌تواند از نوع str، bytes، list یا dict باشد. برای ارسال چندین آرگومان، از یک تاپل (tuple) استفاده کنید که هر عنصر آن از یکی از انواع اشاره‌شده در بالا باشد.
• 2
to -- گیرنده پیام. این پارامتر می‌تواند روی شناسه نشست یک کلاینت تنظیم شود تا فقط آن کلاینت را مورد خطاب قرار دهد، روی هر اتاق سفارشی ایجادشده توسط برنامه تا تمام کلاینت‌های آن اتاق را خطاب قرار دهد، یا روی فهرستی از نام اتاق‌های سفارشی تنظیم شود. در صورت حذف این آرگومان، رویداد برای تمام کلاینت‌های متصل همه‌پخشی (broadcast) می‌شود.
• 2
room -- نام مستعار برای پارامتر to.
• 2
skip_sid -- شناسه نشست کلاینتی که هنگام همه‌پخشی به یک اتاق یا تمام کلاینت‌ها باید نادیده گرفته شود. از این پارامتر می‌توان برای جلوگیری از ارسال پیام به فرستنده استفاده کرد.
• 2
namespace -- فضای نام Socket.IO برای رویداد. در صورت حذف این آرگومان، رویداد در فضای نام پیش‌فرض منتشر می‌شود.
• 2
callback -- در صورت ارائه، این تابع فراخوانی خواهد شد تا دریافت پیام توسط کلاینت را تأیید کند. آرگومان‌هایی که به تابع ارسال می‌شوند مواردی هستند که توسط کلاینت ارائه شده‌اند. توابع فراخوانی بازگشتی تنها زمانی قابل استفاده هستند که یک کلاینت به صورت منفرد خطاب قرار گیرد.
• 2
ignore_queue -- تنها زمانی استفاده می‌شود که یک صف پیام پیکربندی شده باشد. در صورت تنظیم روی True، رویداد به طور مستقیم و بدون عبور از صف برای کلاینت‌ها منتشر می‌شود. این روش کارآمدتر است، اما تنها در صورتی کار می‌کند که یک فرآیند سرور منفرد به کار گرفته شده باشد. توصیه می‌شود همیشه این پارامتر را روی مقدار پیش‌فرض False باقی بگذارید.
0u
0u
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
session(sid, namespace=None)
بازگرداندن نشست کاربر برای یک کلاینت با نحو مدیریت‌کننده زمینه (context manager).
7.0
پارامترها
sid -- شناسه نشست کلاینت.
این یک context manager است که دیکشنری نشست کاربر را برای
کلاینت برمی‌گرداند. هرگونه تغییری که درون بلوک context manager روی این
دیکشنری اعمال شود، مجدداً در نشست ذخیره خواهد شد. نمونه استفاده:
7.0
3.5
@eio.on('connect')
async def on_connect(sid, environ):
username = authenticate_user(environ)
if not username:
return False
async with eio.session(sid) as session:
session['username'] = username
@eio.on('message')
async def on_message(sid, msg):
async with eio.session(sid) as session:
print('received message from ', session['username'])
0u
0u
0u
7.0
async shutdown()
متوقف کردن وظایف پس‌زمینه Socket.IO.
این متد تمام فعالیت‌های پس‌زمینه را که توسط سرور Socket.IO آغاز شده‌اند
متوقف می‌کند. این متد باید پیش از خاموش کردن وب‌سرور فراخوانی شود.
0u
7.0
async sleep(seconds=0)
به خواب رفتن به میزان زمان درخواستی با استفاده از مدل async مناسب.
این یک تابع کمکی است که برنامه‌ها می‌توانند از آن برای به خواب بردن یک وظیفه
بدون نیاز به نگرانی درباره استفاده از فراخوانی صحیح برای حالت async انتخاب‌شده
استفاده کنند.
نکته: این متد یک coroutine است.
0u
7.0
start_background_task(target, args, *kwargs)
آغاز یک وظیفه پس‌زمینه با استفاده از مدل async مناسب.
این یک تابع کمکی است که برنامه‌ها می‌توانند با استفاده از متدی که با حالت
async انتخاب‌شده سازگار است، برای شروع یک وظیفه پس‌زمینه از آن بهره ببرند.
7.0
پارامترها
7.0
• 2
target -- تابع هدف برای اجرا. باید یک coroutine باشد.
• 2
args -- آرگومان‌های ارسالی به تابع.
• 2
kwargs -- آرگومان‌های کلیدواژه‌ای ارسالی به تابع.
0u
0u
مقدار بازگشتی یک شیء asyncio.Task است.
0u
7.0
transport(sid, namespace=None)
بازگرداندن نام transport استفاده‌شده توسط کلاینت.
دو مقدار ممکن که توسط این تابع بازگردانده می‌شوند 'polling'
و 'websocket' هستند.
7.0
پارامترها
7.0
• 2
sid -- نشست کلاینت.
• 2
namespace -- فضای نام Socket.IO. در صورت حذف این آرگومان،
از فضای نام پیش‌فرض استفاده می‌شود.
0u
0u
0u
0u
0.0
class socketio.exceptions.ConnectionRefusedError(*args)
استثنای رد اتصال (Connection refused).
این استثنا می‌تواند هنگامی که اتصال پذیرفته نمی‌شود، از سوی یک گرداننده connect
ایجاد (raise) شود. آرگومان‌های مکانی ارائه شده با این استثنا همراه با بسته خطا
به کلاینت بازگردانده می‌شوند.
0.0
class socketio.WSGIApp(socketio_app, wsgi_app=None, static_files=None, socketio_path='socket.io')
میان‌افزار WSGI برای Socket.IO.
این میان‌افزار ترافیک را به یک برنامه Socket.IO ارسال می‌کند. همچنین می‌تواند
فهرستی از فایل‌های استاتیک را به کلاینت ارائه دهد، یا ترافیک نامرتبط HTTP
را به یک برنامه دیگر WSGI هدایت کند.
7.0
پارامترها
7.0
• 2
socketio_app -- سرور Socket.IO. باید نمونه‌ای از کلاس
socketio.Server باشد.
• 2
wsgi_app -- برنامه WSGI که سایر ترافیک‌ها را دریافت می‌کند.
• 2
static_files -- یک دیکشنری شامل قوانین نگاشت فایل‌های استاتیک. برای
جزئیات در مورد این آرگومان، مستندات را ببینید.
• 2
socketio_path -- نقطه پایانی (endpoint) که برنامه Socket.IO باید در
آن نصب شود. مقدار پیش‌فرض برای بیشتر موارد
مناسب است.
0u
0u
مثال نحوه استفاده:
7.0
3.5
import socketio
import eventlet
from . import wsgi_app
sio = socketio.Server()
app = socketio.WSGIApp(sio, wsgi_app)
eventlet.wsgi.server(eventlet.listen(('', 8000)), app)
0u
0u
0u
0.0
class socketio.ASGIApp(socketio_server, other_asgi_app=None, static_files=None, socketio_path='socket.io', on_startup=None, on_shutdown=None)
میان‌افزار برنامه ASGI برای Socket.IO.
این میان‌افزار ترافیک را به یک برنامه Socket.IO ارسال می‌کند. همچنین
می‌تواند فهرستی از فایل‌های استاتیک را به کلاینت ارائه دهد، یا ترافیک
نامرتبط HTTP را به یک برنامه دیگر ASGI هدایت کند.
7.0
پارامترها
7.0
• 2
socketio_server -- سرور Socket.IO. باید نمونه‌ای از کلاس
socketio.AsyncServer باشد.
• 2
static_files -- یک دیکشنری شامل قوانین نگاشت فایل‌های استاتیک. برای
جزئیات در مورد این آرگومان، مستندات را ببینید.
• 2
other_asgi_app -- یک برنامه مجزای ASGI که سایر ترافیک‌ها را دریافت می‌کند.
• 2
socketio_path -- نقطه پایانی (endpoint) که برنامه Socket.IO باید در
آن نصب شود. مقدار پیش‌فرض برای بیشتر موارد مناسب است. با
مقدار None، تمام ترافیک ورودی به سرور Socket.IO هدایت
می‌شود، با این فرض که مسیریابی در صورت نیاز توسط لایه
دیگری انجام می‌شود. هنگامی که این گزینه روی None
تنظیم شود، static_files و other_asgi_app نادیده
گرفته می‌شوند.
• 2
on_startup -- تابعی که هنگام راه‌اندازی برنامه فراخوانی می‌شود؛ می‌تواند
کوروتین (coroutine) باشد
• 2
on_shutdown -- تابعی که هنگام خاموش شدن برنامه فراخوانی می‌شود؛ می‌تواند
کوروتین (coroutine) باشد
0u
0u
مثال نحوه استفاده:
7.0
3.5
import socketio
import uvicorn
sio = socketio.AsyncServer()
app = socketio.ASGIApp(sio, static_files={
'/': 'index.html',
'/static': './public',
})
uvicorn.run(app, host='127.0.0.1', port=5000)
0u
0u
0u
0.0
class socketio.Middleware(socketio_app, wsgi_app=None, socketio_path='socket.io')
نام این کلاس به WSGIApp تغییر یافته و اکنون منسوخ (deprecated) شده است.
0.0
class socketio.ClientNamespace(namespace=None)
کلاس پایه برای فضاهای نام مبتنی بر کلاس در سمت کلاینت.
یک فضای نام مبتنی بر کلاس، کلاسی است که شامل تمام گرداننده‌های رویداد
برای یک فضای نام Socket.IO است. گرداننده‌های رویداد متدهایی از کلاس
با پیشوند on_ هستند، مانند on_connect، on_disconnect،
on_message، on_json و غیره.
7.0
پارامترها (Parameters)
namespace -- فضای نام Socket.IO که باید برای تمام گرداننده‌های رویداد
تعریف‌شده در این کلاس استفاده شود. اگر این آرگومان
حذف شود، از فضای نام پیش‌فرض استفاده می‌شود.
0u
7.0
call(event, data=None, namespace=None, timeout=None)
ارسال یک رویداد سفارشی به سرور و انتظار برای پاسخ.
تنها تفاوت با متد socketio.Client.call() <#socketio.Client.call> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
disconnect()
قطع اتصال از سرور.
تنها تفاوت با متد socketio.Client.disconnect() <#socketio.Client.disconnect> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
emit(event, data=None, namespace=None, callback=None)
ارسال یک رویداد سفارشی به سرور.
تنها تفاوت با متد socketio.Client.emit() <#socketio.Client.emit> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
send(data, room=None, namespace=None, callback=None)
ارسال یک پیام به سرور.
تنها تفاوت با متد socketio.Client.send() <#socketio.Client.send> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
trigger_event(event, *args)
توزیع یک رویداد به متد گردانندهٔ مناسب.
در متداول‌ترین شیوه استفاده، این متد توسط زیرکلاس‌ها بازنویسی (overload) نمی‌شود،
زیرا مسیریابی رویدادها به متدها را انجام می‌دهد. با این حال، اگر
قواعد توزیع ویژه‌ای نیاز باشد، یا در صورتی که وجود یک متد واحد
که تمام رویدادها را دریافت کند مد نظر باشد، می‌توان این متد را رونویسی (override) کرد.
0u
0u
0.0
class socketio.Namespace(namespace=None)
کلاس پایه برای فضاهای نام مبتنی بر کلاس در سمت سرور.
یک فضای نام مبتنی بر کلاس، کلاسی است که شامل تمام گرداننده‌های رویداد
برای یک فضای نام Socket.IO است. گرداننده‌های رویداد متدهایی از کلاس
با پیشوند on_ هستند، مانند on_connect، on_disconnect،
on_message، on_json و غیره.
7.0
پارامترها (Parameters)
namespace -- فضای نام Socket.IO که باید برای تمام گرداننده‌های رویداد
تعریف‌شده در این کلاس استفاده شود. اگر این آرگومان
حذف شود، از فضای نام پیش‌فرض استفاده می‌شود.
0u
7.0
call(event, data=None, to=None, sid=None, namespace=None, timeout=None, ignore_queue=False)
ارسال یک رویداد سفارشی به یک کلاینت و انتظار برای پاسخ.
تنها تفاوت با متد socketio.Server.call() <#socketio.Server.call> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
close_room(room, namespace=None)
بستن یک اتاق.
تنها تفاوت با متد socketio.Server.close_room() <#socketio.Server.close_room> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
disconnect(sid, namespace=None)
قطع اتصال یک کلاینت.
تنها تفاوت با متد socketio.Server.disconnect() <#socketio.Server.disconnect> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)
ارسال یک رویداد سفارشی به یک یا چند کلاینت متصل.
تنها تفاوت با متد socketio.Server.emit() <#socketio.Server.emit> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
enter_room(sid, room, namespace=None)
ورود به یک اتاق.
تنها تفاوت با متد socketio.Server.enter_room() <#socketio.Server.enter_room> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
get_session(sid, namespace=None)
بازگرداندن نشست کاربر برای یک کلاینت.
تنها تفاوت با متد socketio.Server.get_session() <#socketio.Server.get_session>
این است که وقتی آرگومان namespace داده نشود، از
فضای نام مرتبط با کلاس استفاده می‌شود.
0u
7.0
leave_room(sid, room, namespace=None)
ترک کردن یک اتاق.
تنها تفاوت با متد socketio.Server.leave_room() <#socketio.Server.leave_room> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
rooms(sid, namespace=None)
بازگرداندن اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد.
تنها تفاوت با متد socketio.Server.rooms() <#socketio.Server.rooms> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
save_session(sid, session, namespace=None)
ذخیره نشست کاربر برای یک کلاینت.
تنها تفاوت با متد socketio.Server.save_session() <#socketio.Server.save_session>
این است که وقتی آرگومان namespace داده نشود، از
فضای نام مرتبط با کلاس استفاده می‌شود.
0u
7.0
send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)
ارسال یک پیام به یک یا چند کلاینت متصل.
تنها تفاوت با متد socketio.Server.send() <#socketio.Server.send> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0
session(sid, namespace=None)
بازگرداندن نشست کاربر برای یک کلاینت با نحو مدیر زمینه (context manager).
تنها تفاوت با متد socketio.Server.session() <#socketio.Server.session> این است
که وقتی آرگومان namespace داده نشود، از فضای نام
مرتبط با کلاس استفاده می‌شود.
0u
7.0.TP
trigger_event(event, *args)
ارسال یک رخداد به متد گردانندهٔ (handler) مناسب.
در متداول‌ترین کاربرد، این متد توسط زیرکلاس‌ها بازنویسی (overload) نمی‌شود،
چرا که وظیفهٔ هدایت و توزیع رخدادها به متدها را بر عهده دارد. با این حال، در
صورتی که به قواعد توزیع اختصاصی نیاز باشد یا دریافت تمام رخدادها توسط یک متد
واحد مد نظر باشد، می‌توان این متد را بازنویسی (override) کرد.
0u
0u
0.0
class socketio.AsyncClientNamespace(namespace=None)
کلاس پایه برای فضاهای‌نام مبتنی بر کلاس سمت کلاینت در asyncio.
یک فضای‌نام مبتنی بر کلاس (class-based namespace)، کلاسی است که شامل تمام
گرداننده‌های رخداد برای یک فضای‌نام Socket.IO است. گرداننده‌های رخداد، متدهایی
از کلاس با پیشوند on_ هستند، مانند on_connect، on_disconnect،
on_message، on_json و غیره. این‌ها می‌توانند توابع معمولی یا
هم‌روال‌ها (coroutines) باشند.
7.0
پارامترها (Parameters)
namespace -- فضای‌نام Socket.IO برای استفاده با تمامی گرداننده‌های رخداد
تعریف‌شده در این کلاس. در صورت حذف این آرگومان، از فضای‌نام پیش‌فرض استفاده می‌شود.
0u
7.0
async call(event, data=None, namespace=None, timeout=None)
ارسال یک رخداد سفارشی به سرور و انتظار برای دریافت پاسخ.
تنها تفاوت با متد socketio.Client.call() <#socketio.Client.call> این
است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
0u
7.0
async disconnect()
قطع اتصال کلاینت.
تنها تفاوت با متد socketio.Client.disconnect() <#socketio.Client.disconnect>
این است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async emit(event, data=None, namespace=None, callback=None)
ارسال یک رخداد سفارشی به سرور.
تنها تفاوت با متد socketio.Client.emit() <#socketio.Client.emit> این
است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async send(data, namespace=None, callback=None)
ارسال یک پیام به سرور.
تنها تفاوت با متد socketio.Client.send() <#socketio.Client.send> این
است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async trigger_event(event, *args)
ارسال یک رخداد به متد گردانندهٔ مناسب.
در متداول‌ترین کاربرد، این متد توسط زیرکلاس‌ها بازنویسی (overload) نمی‌شود،
چرا که وظیفهٔ هدایت رخدادها به متدها را بر عهده دارد. با این حال، در صورتی که
به قواعد توزیع اختصاصی نیاز باشد یا دریافت تمام رخدادها در یک متد واحد مد نظر باشد،
می‌توان این متد را بازنویسی (override) کرد.
نکته: این متد یک هم‌روال (coroutine) است.
0u
0u
0.0
class socketio.AsyncNamespace(namespace=None)
کلاس پایه برای فضاهای‌نام مبتنی بر کلاس سمت سرور در asyncio.
یک فضای‌نام مبتنی بر کلاس، کلاسی است که شامل تمام گرداننده‌های رخداد برای یک
فضای‌نام Socket.IO است. گرداننده‌های رخداد، متدهایی از کلاس با پیشوند on_
هستند، مانند on_connect، on_disconnect، on_message،
on_json و غیره. این‌ها می‌توانند توابع معمولی یا هم‌روال‌ها باشند.
7.0
پارامترها (Parameters)
namespace -- فضای‌نام Socket.IO برای استفاده با تمامی گرداننده‌های رخداد
تعریف‌شده در این کلاس. در صورت حذف این آرگومان، از فضای‌نام پیش‌فرض استفاده می‌شود.
0u
7.0
async call(event, data=None, to=None, sid=None, namespace=None, timeout=None, ignore_queue=False)
ارسال یک رخداد سفارشی به کلاینت و انتظار برای دریافت پاسخ.
تنها تفاوت با متد socketio.Server.call() <#socketio.Server.call> این
است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
0u
7.0
async close_room(room, namespace=None)
بستن یک اتاق (room).
تنها تفاوت با متد socketio.Server.close_room() <#socketio.Server.close_room>
این است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async disconnect(sid, namespace=None)
قطع اتصال یک کلاینت.
تنها تفاوت با متد socketio.Server.disconnect() <#socketio.Server.disconnect>
این است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)
ارسال یک رخداد سفارشی به یک یا چند کلاینت متصل.
تنها تفاوت با متد socketio.Server.emit() <#socketio.Server.emit> این
است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async enter_room(sid, room, namespace=None)
ورود به یک اتاق.
تنها تفاوت با متد socketio.Server.enter_room() <#socketio.Server.enter_room>
این است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async get_session(sid, namespace=None)
بازگرداندن نشست (session) کاربر برای یک کلاینت.
تنها تفاوت با متد socketio.Server.get_session() <#socketio.Server.get_session>
این است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async leave_room(sid, room, namespace=None)
خروج از یک اتاق.
تنها تفاوت با متد socketio.Server.leave_room() <#socketio.Server.leave_room>
این است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
rooms(sid, namespace=None)
بازگرداندن اتاق‌هایی که کلاینت در آن‌ها عضو است.
تنها تفاوت با متد socketio.Server.rooms() <#socketio.Server.rooms> این
است که اگر آرگومان namespace داده نشود، از فضای‌نام مرتبط با کلاس استفاده
می‌شود.
0u
7.0.TP
async save_session(sid, session, namespace=None)
ذخیره نشست کاربر برای یک کلاینت.
تنها تفاوت با متد socketio.Server.save_session() <#socketio.Server.save_session> در این است که اگر آرگومان namespace مشخص نشود، از namespace مرتبط با کلاس استفاده می‌شود.
نکته: این متد یک coroutine است.
0u
7.0
async send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)
ارسال یک پیام به یک یا چند کلاینت متصل.
تنها تفاوت با متد socketio.Server.send() <#socketio.Server.send> در این است که اگر آرگومان namespace مشخص نشود، از namespace مرتبط با کلاس استفاده می‌شود.
نکته: این متد یک coroutine است.
0u
7.0
session(sid, namespace=None)
بازگرداندن نشست کاربر برای یک کلاینت با نحو context manager.
تنها تفاوت با متد socketio.Server.session() <#socketio.Server.session> در این است که اگر آرگومان namespace مشخص نشود، از namespace مرتبط با کلاس استفاده می‌شود.
0u
7.0
async trigger_event(event, *args)
ارسال رویداد به متد گرداننده (handler) مناسب.
در رایج‌ترین کاربرد، این متد توسط زیرکلاس‌ها بازنویسی (overload) نمی‌شود، زیرا مسیریابی رویدادها به متدها را انجام می‌دهد. با این حال، اگر به قواعد توزیع ویژه‌ای نیاز باشد یا وجود یک متد واحد که تمام رویدادها را دریافت کند مطلوب باشد، این متد قابل رونویسی (override) است.
نکته: این متد یک coroutine است.
0u
0u
مدیرها (Managers)
0.0
class socketio.Manager
مدیریت اتصالات کلاینت‌ها.
این کلاس تمام کلاینت‌ها و اتاق‌هایی را که در آن‌ها حضور دارند ردیابی می‌کند تا از انتشار (broadcasting) پیام‌ها پشتیبانی کند. داده‌های مورد استفاده این کلاس در یک ساختار حافظه‌ای ذخیره می‌شوند، که آن را تنها برای سرویس‌های تک‌پردازشی مناسب می‌سازد. زیرکلاس‌ها می‌توانند پس‌اندهای ذخیره‌سازی پیشرفته‌تری را پیاده‌سازی کنند.
7.0
close_room(room, namespace)
حذف تمام شرکت‌کنندگان از یک اتاق.
0u
7.0
connect(eio_sid, namespace)
ثبت اتصال یک کلاینت به یک namespace.
0u
7.0
disconnect(sid, namespace, **kwargs)
ثبت قطع اتصال یک کلاینت از یک namespace.
0u
7.0
emit(event, data, namespace, room=None, skip_sid=None, callback=None, to=None, **kwargs)
ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمام کلاینت‌های متصل به namespace.
0u
7.0
enter_room(sid, namespace, room, eio_sid=None)
افزودن یک کلاینت به یک اتاق.
0u
7.0
get_namespaces()
بازگرداندن یک شئ پیمایش‌پذیر (iterable) شامل نام‌های namespace فعال.
0u
7.0
get_participants(namespace, room)
بازگرداندن یک شئ پیمایش‌پذیر (iterable) از شرکت‌کنندگان فعال در یک اتاق.
توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به سروری که متد در آن فراخوانی شده متصل هستند. در حال حاضر قابلیتی برای جمع‌آوری فهرست کاملی از کاربران در میان چندین سرور وجود ندارد.
0u
7.0
get_rooms(sid, namespace)
بازگرداندن اتاق‌هایی که کلاینت در آن‌ها حضور دارد.
0u
7.0
initialize()
پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد مقداردهی اولیه خود را در اینجا اضافه کنند.
0u
7.0
leave_room(sid, namespace, room)
حذف یک کلاینت از یک اتاق.
0u
7.0
pre_disconnect(sid, namespace)
قرار دادن کلاینت در فهرست در شرف قطع اتصال (to-be-disconnected).
این امر به ساختارهای داده کلاینت اجازه می‌دهد هنگام فراخوانی گرداننده قطع اتصال همچنان حضور داشته باشند، در عین حال این واقعیت را مشخص می‌کند که کلاینت به‌زودی خارج خواهد شد.
0u
7.0
trigger_callback(sid, id, data)
فراخوانی یک callback برنامه.
0u
0u
0.0
class socketio.PubSubManager(channel='socketio', write_only=False, logger=None, json=None)
مدیریت فهرست کلاینت‌های متصل به یک پس‌اند pub/sub.
این یک کلاس پایه است که به چندین سرور امکان می‌دهد فهرست کلاینت‌ها را به اشتراک بگذارند، در حالی که سرورها رویدادها را از طریق یک پس‌اند pub/sub تبادل می‌کنند. استفاده از یک پس‌اند pub/sub همچنین به هر کلاینت متصل به پس‌اند اجازه می‌دهد رویدادهایی خطاب به کلاینت‌های Socket.IO ارسال کند.
پس‌آیندهای واقعی باید توسط زیرکلاس‌ها پیاده‌سازی شوند؛ این کلاس تنها یک چارچوب عمومی pub/sub ارائه می‌دهد.
7.0
پارامترها (Parameters)
7.0
• 2
channel -- نام کانالی که سرور اعلان‌ها را روی آن ارسال و دریافت می‌کند.
• 2
write_only -- در صورت تنظیم روی True، تنها برای ارسال (emit) رویدادها مقداردهی اولیه می‌شود. مقدار پیش‌فرض False کلاس را برای ارسال و دریافت مقداردهی اولیه می‌کند. یک نمونه write-only می‌تواند به صورت مستقل از سرور برای ارسال رویداد به کلاینت‌ها از یک فرایند خارجی استفاده شود.
• 2
logger -- یک لاگر سفارشی برای ثبت رویدادها. اگر مشخص نشود، از لاگر سرور استفاده می‌شود.
• 2
json -- یک ماژول JSON جایگزین برای استفاده در کدگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید توابع dumps و loads سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که write_only روی True تنظیم شده باشد. در غیر این صورت، از ماژول JSON پیکربندی‌شده در سرور استفاده می‌شود.
0u
0u
7.0
close_room(room, namespace=None)
حذف تمام شرکت‌کنندگان از یک اتاق.
0u
7.0
connect(eio_sid, namespace)
ثبت اتصال یک کلاینت به یک namespace.
0u
7.0
disconnect(sid, namespace=None, **kwargs)
ثبت قطع اتصال یک کلاینت از یک namespace.
0u
7.0
emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)
ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمام کلاینت‌های متصل به namespace..sp
این متد وظیفه انتشار پیام به تمامی سرورهایی که از طریق صف پیام متصل هستند را بر عهده دارد.
پارامترها همانند Server.emit() <#socketio.Server.emit> هستند.
0u
7.0
enter_room(sid, namespace, room, eio_sid=None)
افزودن یک کلاینت به یک اتاق.
0u
7.0
get_namespaces()
یک iterable از نام‌های namespace فعال را بازمی‌گرداند.
0u
7.0
get_participants(namespace, room)
یک iterable از شرکت‌کنندگان فعال در یک اتاق را بازمی‌گرداند.
توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به سروری که متد در آن فراخوانی شده است متصل باشند. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین سرور وجود ندارد.
0u
7.0
get_rooms(sid, namespace)
اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد را بازمی‌گرداند.
0u
7.0
initialize()
پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد راه‌اندازی اولیه خود را در اینجا اضافه کنند.
0u
7.0
leave_room(sid, namespace, room)
حذف یک کلاینت از یک اتاق.
0u
7.0
pre_disconnect(sid, namespace)
کلاینت را در فهرست در-انتظار-قطع-اتصال قرار می‌دهد.
این کار اجازه می‌دهد ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع ارتباط (disconnect handler) همچنان موجود باشند، اما با این وجود این واقعیت که کلاینت به‌زودی خارج خواهد شد نیز لحاظ گردد.
0u
7.0
trigger_callback(sid, id, data)
یک callback برنامه را فراخوانی می‌کند.
0u
0u
0.0
class socketio.KombuManager(url='amqp://guest:guest@localhost:5672//', channel='socketio', write_only=False, logger=None, json=None, connection_options=None, exchange_options=None, queue_options=None, producer_options=None)
مدیر کلاینت که از kombu برای پیام‌رسانی بین‌فرایندی استفاده می‌کند.
این کلاس یک backend مدیریت کلاینت را برای به‌اشتراک‌گذاری رویدادها میان چندین فرایند، با استفاده از RabbitMQ، Redis یا هر سازوکار پیام‌رسانی دیگر پشتیبانی‌شده توسط kombu http://kombu.readthedocs.org/en/latest پیاده‌سازی می‌کند.
برای استفاده از یک backend از نوع kombu، نمونه Server <#socketio.Server> را به‌صورت زیر مقداردهی اولیه کنید:
7.0
3.5
url = 'amqp://user:password@hostname:port//'
server = socketio.Server(client_manager=socketio.KombuManager(url))
0u
0u
7.0
پارامترها
7.0
• 2
url -- نشانی URL اتصال برای صف پیام‌رسانی backend. نمونه‌های URL اتصال عبارت‌اند از 'amqp://guest:guest@localhost:5672//' و 'redis://localhost:6379/' به ترتیب برای RabbitMQ و Redis. برای اطلاعات بیشتر درباره چگونگی ساخت URLهای اتصال، به مستندات kombu http://kombu.readthedocs.org/en/latest/userguide/connections.html#urls مراجعه کنید.
• 2
channel -- نام کانالی که سرور روی آن اعلان‌ها را ارسال و دریافت می‌کند. باید در تمام سرورها یکسان باشد.
• 2
write_only -- اگر روی True تنظیم شود، تنها برای ارسال (emit) رویدادها راه‌اندازی می‌شود. مقدار پیش‌فرض False کلاس را برای ارسال و دریافت مقداردهی می‌کند. یک نمونه write-only می‌تواند مستقل از سرور برای ارسال رویدادها به کلاینت‌ها از طریق یک فرایند خارجی استفاده شود.
• 2
logger -- یک ثبت‌کننده وقایع (logger) سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از logger سرور استفاده می‌شود.
• 2
json -- یک ماژول جایگزین JSON جهت استفاده برای کدگذاری و کدگشایی بسته‌ها. ماژول‌های json سفارشی باید توابع dumps و loads سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی استفاده می‌شود که write_only روی True تنظیم شده باشد؛ در غیر این صورت از ماژول JSON پیکربندی‌شده در سرور استفاده می‌شود.
• 2
connection_options -- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به kombu.Connection().
• 2
exchange_options -- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به kombu.Exchange().
• 2
queue_options -- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به kombu.Queue().
• 2
producer_options -- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به kombu.Producer().
0u
0u
7.0
close_room(room, namespace=None)
حذف تمام شرکت‌کنندگان از یک اتاق.
0u
7.0
connect(eio_sid, namespace)
ثبت اتصال یک کلاینت به یک namespace.
0u
7.0
disconnect(sid, namespace=None, **kwargs)
ثبت قطع اتصال یک کلاینت از یک namespace.
0u
7.0
emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)
ارسال یک پیام به یک کلاینت منفرد، یک اتاق، یا تمامی کلاینت‌های متصل به namespace.
این متد وظیفه انتشار پیام به تمامی سرورهایی که از طریق صف پیام متصل هستند را بر عهده دارد.
پارامترها همانند Server.emit() <#socketio.Server.emit> هستند.
0u
7.0
enter_room(sid, namespace, room, eio_sid=None)
افزودن یک کلاینت به یک اتاق.
0u
7.0
get_namespaces()
یک iterable از نام‌های namespace فعال را بازمی‌گرداند.
0u
7.0
get_participants(namespace, room)
یک iterable از شرکت‌کنندگان فعال در یک اتاق را بازمی‌گرداند.
توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به سروری که متد در آن فراخوانی شده است متصل باشند. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین سرور وجود ندارد.
0u
7.0
get_rooms(sid, namespace)
اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد را بازمی‌گرداند.
0u
7.0
initialize()
پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد راه‌اندازی اولیه خود را در اینجا اضافه کنند.
0u
7.0
leave_room(sid, namespace, room)
حذف یک کلاینت از یک اتاق.
0u
7.0.TP
pre_disconnect(sid, namespace)
قرار دادن کلاینت در فهرست در-شرف-قطع ارتباط.
این امکان را فراهم می‌کند که ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع ارتباط (disconnect handler) حضور داشته باشند، ولی در عین حال مشخص باشد که کلاینت به‌زودی خارج خواهد شد.
0u
7.0
trigger_callback(sid, id, data)
فراخوانی یک کال‌بک (callback) برنامه کاربردی.
0u
0u
0.0
class socketio.RedisManager(url='redis://localhost:6379/0', channel='socketio', write_only=False, logger=None, json=None, redis_options=None)
مدیر کلاینت مبتنی بر Redis.
این کلاس یک پس‌بخش (backend) مبتنی بر Redis را برای هم‌رسانی رویدادها در چندین فرآیند پیاده‌سازی می‌کند. این بخش صرفاً به عنوان نمونه دیگری از نحوه ساخت یک پس‌بخش سفارشی در اینجا نگه داشته شده است، چرا که پس‌بخش kombu برای پشتیبانی از یک صف پیام Redis کاملاً مناسب و کافی است.
برای استفاده از یک پس‌بخش Redis، نمونه Server <#socketio.Server> را به صورت زیر مقداردهی اولیه کنید:
7.0
3.5
url = 'redis://hostname:port/0'
server = socketio.Server(client_manager=socketio.RedisManager(url))
0u
0u
7.0
پارامترها
7.0
• 2
url -- نشانی اینترنتی (URL) اتصال برای سرور Redis. برای یک ذخیره‌ساز پیش‌فرض Redis که بر روی همان میزبان اجرا می‌شود، از redis:// استفاده کنید. برای استفاده از یک اتصال TLS، از rediss:// استفاده کنید. برای استفاده از Redis Sentinel، از redis+sentinel:// به همراه فهرستی از میزبان‌ها که با ویرگول از هم جدا شده‌اند و نام سرویس پس از db در مسیر URL استفاده کنید. مثال:
redis+sentinel://user:pw@host1:1234,host2:2345/0/myredis.
• 2
channel -- نام کانالی که سرور اعلان‌ها را در آن ارسال و دریافت می‌کند. باید در تمام سرورها یکسان باشد.
• 2
write_only -- در صورت تنظیم روی True، تنها برای انتشار رویدادها مقداردهی اولیه می‌شود. مقدار پیش‌فرض False کلاس را برای ارسال و دریافت مقداردهی اولیه می‌کند. یک نمونه فقط-نوشتنی (write-only) می‌تواند به صورت مستقل از سرور برای ارسال به کلاینت‌ها از طریق یک فرآیند خارجی مورد استفاده قرار گیرد.
• 2
logger -- یک ثبت‌کننده وقایع (logger) سفارشی برای ثبت آن. در صورت مشخص نشدن، از logger سرور استفاده می‌شود.
• 2
json -- یک ماژول جایگزین JSON جهت استفاده برای رمزگذاری و رمزگشایی بسته‌ها. ماژول‌های json سفارشی باید توابع dumps و loads را داشته باشند که با نسخه‌های کتابخانه استاندارد سازگار باشند. این تنظیم تنها زمانی اعمال می‌شود که write_only روی True تنظیم شده باشد. در غیر این صورت از ماژول JSON پیکربندی‌شده در سرور استفاده می‌شود.
• 2
redis_options -- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به Redis.from_url() یا Sentinel().
0u
0u
7.0
close_room(room, namespace=None)
حذف تمام شرکت‌کنندگان از یک اتاق.
0u
7.0
connect(eio_sid, namespace)
ثبت اتصال یک کلاینت به یک namespace.
0u
7.0
disconnect(sid, namespace=None, **kwargs)
ثبت قطع ارتباط یک کلاینت از یک namespace.
0u
7.0
emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)
انتشار یک پیام به یک کلاینت واحد، یک اتاق، یا تمامی کلاینت‌های متصل به namespace.
این متد وظیفه بازپخش پیام به تمامی سرورهایی که از طریق صف پیام متصل هستند را بر عهده دارد.
پارامترها همانند پارامترهای موجود در Server.emit() <#socketio.Server.emit> هستند.
0u
7.0
enter_room(sid, namespace, room, eio_sid=None)
افزودن یک کلاینت به یک اتاق.
0u
7.0
get_namespaces()
بازگرداندن یک پیمایش‌پذیر (iterable) شامل نام‌های namespace فعال.
0u
7.0
get_participants(namespace, room)
بازگرداندن یک پیمایش‌پذیر (iterable) شامل شرکت‌کنندگان فعال در یک اتاق.
توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگان متصل به همان سروری را بازمی‌گرداند که متد در آن فراخوانی شده است. در حال حاضر قابلیتی برای گردآوری فهرست کاملی از کاربران در میان چندین سرور وجود ندارد.
0u
7.0
get_rooms(sid, namespace)
بازگرداندن اتاق‌هایی که کلاینت در آن‌ها حضور دارد.
0u
7.0
initialize()
پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کدهای مقداردهی اولیه خود را در اینجا اضافه کنند.
0u
7.0
leave_room(sid, namespace, room)
خارج کردن یک کلاینت از یک اتاق.
0u
7.0
pre_disconnect(sid, namespace)
قرار دادن کلاینت در فهرست در-شرف-قطع ارتباط.
این امکان را فراهم می‌کند که ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع ارتباط حضور داشته باشند، ولی در عین حال مشخص باشد که کلاینت به‌زودی خارج خواهد شد.
0u
7.0
trigger_callback(sid, id, data)
فراخوانی یک کال‌بک (callback) برنامه کاربردی.
0u
0u
0.0
class socketio.KafkaManager(url='kafka://localhost:9092', channel='socketio', write_only=False, logger=None, json=None)
مدیر کلاینت مبتنی بر Kafka.
این کلاس یک پس‌بخش (backend) مبتنی بر Kafka را برای هم‌رسانی رویدادها در میان چندین فرآیند پیاده‌سازی می‌کند.
برای استفاده از یک پس‌بخش Kafka، نمونه Server <#socketio.Server> را به صورت زیر مقداردهی اولیه کنید:
7.0
3.5
url = 'kafka://hostname:port'
server = socketio.Server(client_manager=socketio.KafkaManager(url))
0u
0u
7.0
پارامترها
7.0
• 2
url -- نشانی اینترنتی (URL) اتصال برای سرور Kafka. برای یک ذخیره‌ساز پیش‌فرض Kafka که بر روی همان میزبان اجرا می‌شود، از kafka:// استفاده کنید. برای یک استقرار با دسترسی‌پذیری بالا (high availability) از Kafka، فهرستی شامل تمامی URLهای اتصال موجود در کلاستر خود را ارسال کنید.
• 2
channel -- نام کانال (topic) که سرور اعلان‌ها را در آن ارسال و دریافت می‌کند. باید در تمامی سرورها یکسان باشد.
• 2
write_only -- در صورت تنظیم روی True، تنها برای انتشار رویدادها مقداردهی اولیه می‌شود. مقدار پیش‌فرض False کلاس را برای ارسال و دریافت مقداردهی اولیه می‌کند. یک نمونه فقط-نوشتنی (write-only) می‌تواند به صورت مستقل از سرور برای ارسال به کلاینت‌ها از طریق یک فرآیند خارجی مورد استفاده قرار گیرد..IP • 2
logger -- یک ثبت‌کننده وقایع (logger) سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از ثبت‌کننده وقایع سرور
استفاده می‌شود.
• 2
json -- یک ماژول JSON جایگزین برای استفاده در رمزگذاری و رمزگشایی
بسته‌ها. ماژول‌های سفارشی json باید توابع dumps و loads
سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که write_only
بر روی True تنظیم شده باشد. در غیر این صورت از ماژول JSON پیکربندی‌شده در
سرور استفاده می‌شود.
0u
0u
7.0
close_room(room, namespace=None)
حذف تمام شرکت‌کنندگان از یک اتاق.
0u
7.0
connect(eio_sid, namespace)
ثبت اتصال یک کلاینت به یک namespace.
0u
7.0
disconnect(sid, namespace=None, **kwargs)
ثبت قطع اتصال یک کلاینت از یک namespace.
0u
7.0
emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)
ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمام کلاینت‌های
متصل به namespace.
این متد وظیفه انتشار پیام به تمام سرورهایی
که از طریق صف پیام متصل هستند را بر عهده دارد.
پارامترها مشابه پارامترهای متد Server.emit() <#socketio.Server.emit> هستند.
0u
7.0
enter_room(sid, namespace, room, eio_sid=None)
افزودن یک کلاینت به یک اتاق.
0u
7.0
get_namespaces()
بازگرداندن یک تکرارپذیر (iterable) شامل نام‌های namespace فعال.
0u
7.0
get_participants(namespace, room)
بازگرداندن یک تکرارپذیر شامل شرکت‌کنندگان فعال در یک اتاق.
توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را
بازمی‌گرداند که به سروری که متد در آن فراخوانی شده متصل هستند. در حال حاضر
قابلیتی برای جمع‌آوری فهرست کامل کاربران در چندین سرور وجود ندارد.
0u
7.0
get_rooms(sid, namespace)
بازگرداندن اتاق‌هایی که کلاینت در آن‌ها حضور دارد.
0u
7.0
initialize()
پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند
کد مقداردهی اولیه خود را در اینجا اضافه کنند.
0u
7.0
leave_room(sid, namespace, room)
خارج کردن یک کلاینت از یک اتاق.
0u
7.0
pre_disconnect(sid, namespace)
قرار دادن کلاینت در فهرست در شرف قطع اتصال (to-be-disconnected).
این کار اجازه می‌دهد تا ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع
اتصال (disconnect handler) همچنان در دسترس باشند، اما در عین حال این واقعیت
که کلاینت به‌زودی قطع خواهد شد نیز مشخص باشد.
0u
7.0
trigger_callback(sid, id, data)
فراخوانی یک بازفراخوانی (callback) برنامه.
0u
0u
0.0
class socketio.ZmqManager(url='zmq+tcp://localhost:5555+5556', channel='socketio', write_only=False, logger=None, json=None)
مدیر کلاینت مبتنی بر zmq.
نکته: این پیاده‌سازی zmq در حال حاضر باید به‌صورت آزمایشی در نظر
گرفته شود. در حال حاضر، برای استفاده از zmq به eventlet نیاز است.
این کلاس یک پس‌بخش zmq را برای اشتراک‌گذاری رویدادها میان چندین
پردازه پیاده‌سازی می‌کند. برای استفاده از پس‌بخش zmq، نمونه Server <#socketio.Server> را به‌صورت
زیر مقداردهی اولیه کنید:
7.0
3.5
url = 'zmq+tcp://hostname:port1+port2'
server = socketio.Server(client_manager=socketio.ZmqManager(url))
0u
0u
7.0
پارامترها (Parameters)
7.0
• 2
url -- نشانی اینترنتی (URL) اتصال برای کارگزار پیام zmq
که باید فراهم شده و در حال اجرا باشد.
• 2
channel -- نام کانالی که سرور اعلان‌ها را روی آن ارسال و دریافت
می‌کند. باید در تمام سرورها یکسان باشد.
• 2
write_only -- در صورت تنظیم روی True، تنها برای ارسال رویدادها راه‌اندازی می‌شود.
مقدار پیش‌فرض False کلاس را برای ارسال
و دریافت مقداردهی اولیه می‌کند. یک نمونه فقط‌نوشتنی را می‌توان به‌صورت
مستقل از سرور برای ارسال به کلاینت‌ها از یک
پردازه خارجی استفاده کرد.
• 2
logger -- یک ثبت‌کننده وقایع سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از ثبت‌کننده وقایع
سرور استفاده می‌شود.
• 2
json -- یک ماژول JSON جایگزین برای استفاده در رمزگذاری و رمزگشایی
بسته‌ها. ماژول‌های سفارشی json باید توابع dumps و loads
سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که write_only
بر روی True تنظیم شده باشد. در غیر این صورت از ماژول JSON پیکربندی‌شده در
سرور استفاده می‌شود.
0u
0u
برای کارکرد zmq_manager، یک کارگزار پیام (message broker) zmq باید در حال اجرا باشد.
می‌توانید کارگزار خود را بنویسید یا کارگزار ساده
زیر را تطبیق دهید:
7.0
3.5
import zmq
receiver = zmq.Context().socket(zmq.PULL)
receiver.bind("tcp://*:5555")
publisher = zmq.Context().socket(zmq.PUB)
publisher.bind("tcp://*:5556")
while True:
publisher.send(receiver.recv())
0u
0u
7.0
close_room(room, namespace=None)
حذف تمام شرکت‌کنندگان از یک اتاق.
0u
7.0
connect(eio_sid, namespace)
ثبت اتصال یک کلاینت به یک namespace.
0u
7.0
disconnect(sid, namespace=None, **kwargs)
ثبت قطع اتصال یک کلاینت از یک namespace.
0u
7.0
emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)
ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمام کلاینت‌های
متصل به namespace.
این متد وظیفه انتشار پیام به تمام سرورهایی
که از طریق صف پیام متصل هستند را بر عهده دارد..sp
پارامترها همانند Server.emit() <#socketio.Server.emit> هستند.
0u
7.0
enter_room(sid, namespace, room, eio_sid=None)
افزودن یک کلاینت به یک اتاق.
0u
7.0
get_namespaces()
بازگرداندن یک تکرارپذیر (iterable) شامل نام‌های فضاهای نام فعال.
0u
7.0
get_participants(namespace, room)
بازگرداندن یک تکرارپذیر شامل شرکت‌کنندگان فعال در یک اتاق.
توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را
بازمی‌گرداند که به همان سروری که متد در آن فراخوانی شده متصل هستند. در
حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین
سرور وجود ندارد.
0u
7.0
get_rooms(sid, namespace)
بازگرداندن اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد.
0u
7.0
initialize()
پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند
کد مقداردهی اولیه خود را در اینجا اضافه کنند.
0u
7.0
leave_room(sid, namespace, room)
حذف یک کلاینت از یک اتاق.
0u
7.0
pre_disconnect(sid, namespace)
قراردادن کلاینت در فهرست در انتظار قطع اتصال (to-be-disconnected).
این کار به ساختارهای داده کلاینت اجازه می‌دهد هنگام فراخوانی گرداننده
قطع اتصال (disconnect handler) همچنان حضور داشته باشند، در حالی که همچنان
این واقعیت را تشخیص می‌دهد که کلاینت به‌زودی خارج خواهد شد.
0u
7.0
trigger_callback(sid, id, data)
فراخوانی یک بازخورد (callback) برنامه.
0u
0u
0.0
class socketio.AsyncManager
مدیریت فهرست کلاینت‌ها برای یک سرور asyncio.
7.0
async close_room(room, namespace)
حذف تمام شرکت‌کنندگان از یک اتاق.
نکته: این متد یک کوروتین (coroutine) است.
0u
7.0
async connect(eio_sid, namespace)
ثبت اتصال یک کلاینت به یک فضای نام.
نکته: این متد یک کوروتین است.
0u
7.0
async disconnect(sid, namespace, **kwargs)
قطع اتصال یک کلاینت.
نکته: این متد یک کوروتین است.
0u
7.0
async emit(event, data, namespace, room=None, skip_sid=None, callback=None, to=None, **kwargs)
ارسال (emit) یک پیام به یک کلاینت منفرد، یک اتاق، یا تمامی کلاینت‌های
متصل به فضای نام.
نکته: این متد یک کوروتین است.
0u
7.0
async enter_room(sid, namespace, room, eio_sid=None)
افزودن یک کلاینت به یک اتاق.
نکته: این متد یک کوروتین است.
0u
7.0
get_namespaces()
بازگرداندن یک تکرارپذیر شامل نام‌های فضاهای نام فعال.
0u
7.0
get_participants(namespace, room)
بازگرداندن یک تکرارپذیر شامل شرکت‌کنندگان فعال در یک اتاق.
توجه داشته باشید که در سناریوی چندسروری، این متد تنها شرکت‌کنندگانی را
بازمی‌گرداند که به همان سروری که متد در آن فراخوانی شده متصل هستند. در
حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین
سرور وجود ندارد.
0u
7.0
get_rooms(sid, namespace)
بازگرداندن اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد.
0u
7.0
initialize()
پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند
کد مقداردهی اولیه خود را در اینجا اضافه کنند.
0u
7.0
async leave_room(sid, namespace, room)
حذف یک کلاینت از یک اتاق.
نکته: این متد یک کوروتین است.
0u
7.0
pre_disconnect(sid, namespace)
قراردادن کلاینت در فهرست در انتظار قطع اتصال.
این کار به ساختارهای داده کلاینت اجازه می‌دهد هنگام فراخوانی گرداننده
قطع اتصال همچنان حضور داشته باشند، در حالی که همچنان این واقعیت را
تشخیص می‌دهد که کلاینت به‌زودی خارج خواهد شد.
0u
7.0
async trigger_callback(sid, id, data)
فراخوانی یک بازخورد برنامه.
نکته: این متد یک کوروتین است.
0u
0u
0.0
class socketio.AsyncRedisManager(url='redis://localhost:6379/0', channel='socketio', write_only=False, logger=None, json=None, redis_options=None)
مدیر کلاینت مبتنی بر Redis برای سرورهای asyncio.
این کلاس یک بک‌اند Redis را برای به‌اشتراک‌گذاری رویدادها بین چندین
فرآیند پیاده‌سازی می‌کند.
برای استفاده از یک بک‌اند Redis، نمونه AsyncServer <#socketio.AsyncServer> را به
صورت زیر مقداردهی اولیه کنید:
7.0
3.5
url = 'redis://hostname:port/0'
server = socketio.AsyncServer(
client_manager=socketio.AsyncRedisManager(url))
0u
0u
7.0
پارامترها (Parameters)
7.0
• 2
url -- نشانی وب (URL) اتصال برای سرور Redis. برای یک ذخیره‌ساز
پیش‌فرض Redis که روی همان میزبان اجرا می‌شود، از redis:// استفاده کنید.
برای استفاده از یک اتصال TLS، از rediss:// استفاده کنید. برای استفاده
از Redis Sentinel، از redis+sentinel:// به همراه فهرستی از میزبان‌ها
که با ویرگول از یکدیگر جدا شده‌اند و نام سرویس پس از db در مسیر URL
استفاده کنید. مثال:
redis+sentinel://user:pw@host1:1234,host2:2345/0/myredis.
• 2
channel -- نام کانالی که سرور در آن اعلان‌ها را ارسال و دریافت
می‌کند. باید در تمامی سرورها یکسان باشد.
• 2
write_only -- در صورت تنظیم روی True، تنها برای ارسال (emit)
رویدادها مقداردهی اولیه می‌شود. مقدار پیش‌فرض False کلاس را هم برای
ارسال و هم برای دریافت مقداردهی می‌کند. یک نمونه فقط‌نوشتنی (write-only)
می‌تواند مستقل از سرور برای ارسال به کلاینت‌ها از طریق یک فرآیند خارجی
استفاده شود..IP • 2
logger -- یک logger سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از logger کارساز استفاده می‌شود.
• 2
json -- یک پودمان JSON جایگزین برای رمزگذاری و رمزگشایی بسته‌ها. پودمان‌های سفارشی json باید توابع dumps و loads سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که write_only روی True تنظیم شده باشد. در غیر این صورت، از پودمان JSON پیکربندی‌شده در کارساز استفاده می‌شود.
• 2
redis_options -- آرگومان‌های کلیدواژه‌ای اضافی برای ارسال به Redis.from_url() یا Sentinel().
0u
0u
7.0
async close_room(room, namespace=None)
حذف تمامی شرکت‌کنندگان از یک اتاق.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async connect(eio_sid, namespace)
ثبت اتصال یک کلاینت به یک namespace.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async disconnect(sid, namespace, **kwargs)
قطع اتصال یک کلاینت.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)
ارسال یک پیام به یک کلاینت منفرد، یک اتاق یا تمامی کلاینت‌های متصل به namespace.
این متد وظیفه انتشار پیام به تمامی کارسازهایی که از طریق صف پیام متصل هستند را بر عهده دارد.
پارامترها همانند متد Server.emit() <#socketio.Server.emit> هستند.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async enter_room(sid, namespace, room, eio_sid=None)
افزودن یک کلاینت به یک اتاق.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
get_namespaces()
بازگرداندن یک شیء پیمایش‌پذیر (iterable) با نام‌های namespace فعال.
0u
7.0
get_participants(namespace, room)
بازگرداندن یک شیء پیمایش‌پذیر با شرکت‌کنندگان فعال در یک اتاق.
توجه داشته باشید که در سناریوی چندکارسازی (multi-server) این متد تنها شرکت‌کنندگانی را بازمی‌گرداند که به کارسازی که متد در آن فراخوانی شده متصل هستند. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین کارساز وجود ندارد.
0u
7.0
get_rooms(sid, namespace)
بازگرداندن اتاق‌هایی که یک کلاینت در آن‌ها حضور دارد.
0u
7.0
initialize()
پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد مقداردهی اولیه خود را در اینجا اضافه کنند.
0u
7.0
async leave_room(sid, namespace, room)
حذف یک کلاینت از یک اتاق.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
pre_disconnect(sid, namespace)
قرار دادن کلاینت در فهرست در-انتظار-قطع-اتصال.
این کار اجازه می‌دهد که ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع اتصال حضور داشته باشند، اما همچنان این واقعیت را مشخص می‌کند که کلاینت به‌زودی خارج خواهد شد.
0u
7.0
async trigger_callback(sid, id, data)
فراخوانی یک تابع بازگشتی (callback) برنامه.
نکته: این متد یک هم‌روال (coroutine) است.
0u
0u
0.0
class socketio.AsyncAioPikaManager(url='amqp://guest:guest@localhost:5672//', channel='socketio', write_only=False, logger=None, json=None)
مدیر کلاینتی که از aio_pika برای پیام‌رسانی بین‌فرایندی تحت asyncio استفاده می‌کند.
این کلاس یک پسانه مدیر کلاینت را برای همرسانی رویدادها میان چندین فرایند با استفاده از RabbitMQ پیاده‌سازی می‌کند.
برای استفاده از پسانه aio_pika، نمونه Server <#socketio.Server> را به‌صورت زیر مقداردهی اولیه کنید:
7.0
3.5
url = 'amqp://user:password@hostname:port//'
server = socketio.Server(client_manager=socketio.AsyncAioPikaManager(
url))
0u
0u
7.0
پارامترها (Parameters)
7.0
• 2
url -- نشانی URL اتصال برای صف پیام‌رسانی پسانه. نمونه‌ای از URLهای اتصال 'amqp://guest:guest@localhost:5672//' برای RabbitMQ است.
• 2
channel -- نام کانالی که کارساز اعلان‌ها را روی آن ارسال و دریافت می‌کند. باید در تمام کارسازها یکسان باشد. با این مدیر، نام کانال همان نام exchange در rabbitmq است.
• 2
write_only -- اگر روی True تنظیم شود، تنها برای ارسال (emit) رویدادها مقداردهی می‌شود. مقدار پیش‌فرض False کلاس را برای ارسال و دریافت مقداردهی می‌کند. یک نمونه فقط‌نوشتنی (write-only) می‌تواند مستقل از کارساز برای ارسال پیام به کلاینت‌ها از طریق یک فرایند خارجی استفاده شود.
• 2
logger -- یک logger سفارشی برای ثبت وقایع. در صورت مشخص نشدن، از logger کارساز استفاده می‌شود.
• 2
json -- یک پودمان JSON جایگزین برای رمزگذاری و رمزگشایی بسته‌ها. پودمان‌های سفارشی json باید توابع dumps و loads سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این تنظیم تنها زمانی اعمال می‌شود که write_only روی True تنظیم شده باشد. در غیر این صورت، از پودمان JSON پیکربندی‌شده در کارساز استفاده می‌شود.
0u
0u
7.0
async close_room(room, namespace=None)
حذف تمامی شرکت‌کنندگان از یک اتاق.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async connect(eio_sid, namespace)
ثبت اتصال یک کلاینت به یک namespace.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0
async disconnect(sid, namespace, **kwargs)
قطع اتصال یک کلاینت.
نکته: این متد یک هم‌روال (coroutine) است.
0u
7.0.TP
async emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)
ارسال یک پیام به یک کلاینت منفرد، یک اتاق، یا تمامی کلاینت‌های متصل به namespace.
این متد مدیریت انتشار پیام به تمام کارسازهای متصل از طریق صف پیام (message queue) را بر عهده دارد.
پارامترها مشابه موارد موجود در Server.emit() <#socketio.Server.emit> هستند.
نکته: این متد یک کوروتین (coroutine) است.
0u
7.0
async enter_room(sid, namespace, room, eio_sid=None)
افزودن یک کلاینت به یک اتاق.
نکته: این متد یک کوروتین (coroutine) است.
0u
7.0
get_namespaces()
بازگرداندن یک شیء تکرارپذیر (iterable) شامل نام‌های namespace فعال.
0u
7.0
get_participants(namespace, room)
بازگرداندن یک شیء تکرارپذیر (iterable) شامل شرکت‌کنندگان فعال در یک اتاق.
توجه داشته باشید که در سناریوی چندکارسازی (multi-server)، این متد تنها شرکت‌کنندگان متصل به کارسازی را برمی‌گرداند که متد در آن فراخوانی شده است. در حال حاضر قابلیتی برای جمع‌آوری یک فهرست کامل از کاربران در میان چندین کارساز وجود ندارد.
0u
7.0
get_rooms(sid, namespace)
بازگرداندن اتاق‌هایی که کلاینت در آن‌ها عضو است.
0u
7.0
initialize()
پیش از دریافت نخستین درخواست فراخوانی می‌شود. زیرکلاس‌ها می‌توانند کد مقداردهی اولیه خود را در اینجا قرار دهند.
0u
7.0
async leave_room(sid, namespace, room)
حذف یک کلاینت از یک اتاق.
نکته: این متد یک کوروتین (coroutine) است.
0u
7.0
pre_disconnect(sid, namespace)
قرار دادن کلاینت در فهرست در-حال-قطع-اتصال (to-be-disconnected).
این کار اجازه می‌دهد ساختارهای داده کلاینت هنگام فراخوانی گرداننده قطع ارتباط (disconnect handler) همچنان موجود باشند، در حالی که همچنان این موضوع که کلاینت به‌زودی قطع خواهد شد لحاظ می‌شود.
0u
7.0
async trigger_callback(sid, id, data)
فراخوانی یک کال‌بک (callback) برنامه.
نکته: این متد یک کوروتین (coroutine) است.
0u
0u
0.0
• 2
نمایه <>
• 2
نمایه ماژول <>
• 2
صفحه جستجو <>
0u
"نویسندگان (AUTHORS)"
Miguel Grinberg
"کپی‌رایت و تکثیر (COPYRIGHT)"
2018, Miguel Grinberg

February 7, 2026