PYTHON-ENGINEIO(1) python-engineio PYTHON-ENGINEIO(1)

python-engineio - مستندات python-engineio

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

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

پروتکل Engine.IO بسیار ساده است. هنگامی که یک اتصال میان کلاینت و سرور برقرار شد، هر یک از طرفین می‌توانند به طرف مقابل "پیام" ارسال کنند. دستگیره‌های رویداد (Event handlers) ارائه‌شده توسط برنامه‌ها در هر دو سمت، هنگام دریافت پیام یا زمانی که اتصالی برقرار یا قطع می‌شود، فراخوانی می‌گردند.

مثال زیر یک کلاینت ساده پایتون را نشان می‌دهد:

import engineio
eio = engineio.Client()
@eio.on('connect')
def on_connect():
    print('connection established')
@eio.on('message')
def on_message(data):
    print('message received with ', data)
    eio.send({'response': 'my response'})
@eio.on('disconnect')
def on_disconnect():
    print('disconnected from server')
eio.connect('http://localhost:5000')
eio.wait()

و در اینجا کلاینت مشابهی که با استفاده از کلاینت رسمی جاوااسکریپت Engine.IO نوشته شده است آورده شده است:

<script src="/path/to/engine.io.js"></script>
<script>
    var socket = eio('http://localhost:5000');
    socket.on('open', function() { console.log('connection established'); });
    socket.on('message', function(data) {
        console.log('message received with ' + data);
        socket.send({response: 'my response'});
    });
    socket.on('close', function() { console.log('disconnected from server'); });
</script>
  • امکان اتصال به دیگر سرورهای سازگار با Engine.IO علاوه بر سرور موجود در این بسته.
  • سازگار با Python 3.6+.
  • دو نسخه از کلاینت، یکی برای Python استاندارد و دیگری برای asyncio.
  • استفاده از یک معماری مبتنی بر رویداد پیاده‌سازی‌شده با دکوراتورها که جزئیات پروتکل را پنهان می‌کند.
  • پیاده‌سازی روش‌های انتقال HTTP long-polling و WebSocket.

برنامه زیر یک مثال پایه است که از سرور ناهمگام Eventlet استفاده می‌کند:

import engineio
import eventlet
eio = engineio.Server()
app = engineio.WSGIApp(eio, static_files={
    '/': {'content_type': 'text/html', 'filename': 'index.html'}
})
@eio.on('connect')
def connect(sid, environ):
    print("connect ", sid)
@eio.on('message')
def message(sid, data):
    print("message ", data)
    eio.send(sid, 'reply')
@eio.on('disconnect')
def disconnect(sid):
    print('disconnect ', sid)
if __name__ == '__main__':
    eventlet.wsgi.server(eventlet.listen(('', 5000)), app)

در زیر برنامه‌ای مشابه آمده است که برای asyncio و وب‌سرور Uvicorn نوشته شده است:

import engineio
import uvicorn
eio = engineio.AsyncServer()
app = engineio.ASGIApp(eio, static_files={
    '/': {'content_type': 'text/html', 'filename': 'index.html'}
})
@eio.on('connect')
def connect(sid, environ):
    print("connect ", sid)
@eio.on('message')
async def message(sid, data):
    print("message ", data)
    await eio.send(sid, 'reply')
@eio.on('disconnect')
def disconnect(sid):
    print('disconnect ', sid)
if __name__ == '__main__':
    uvicorn.run('127.0.0.1', 5000)
  • می‌تواند علاوه بر کلاینت موجود در این بسته، کلاینت‌های دیگری که با Engine.IO سازگار هستند را بپذیرد.
  • سازگار با Python 3.6+.
  • دو نسخه از سرور، یکی برای پایتون استاندارد و دیگری برای asyncio.
  • پشتیبانی از تعداد زیادی کلاینت حتی روی سخت‌افزارهای معمولی به دلیل ناهمگام (asynchronous) بودن.
  • امکان میزبانی روی هر وب‌سرور 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://gevent.org.
  • امکان یکپارچه‌سازی با برنامه‌های WSGI نوشته‌شده با چارچوب‌هایی نظیر Flask، Django و غیره.
  • امکان یکپارچه‌سازی با برنامه‌های asyncio در aiohttp http://aiohttp.readthedocs.io، sanic http://sanic.readthedocs.io و tornado http://www.tornadoweb.org.
  • استفاده از معماری مبتنی بر رویداد (event-based) پیاده‌سازی‌شده با دکوراتورها که جزئیات پروتکل را پنهان می‌کند.
  • پیاده‌سازی لایه‌های انتقال HTTP long-polling و WebSocket.
  • پشتیبانی از مرورگرهای XHR2 و XHR به عنوان کلاینت.
  • پشتیبانی از پیام‌های متنی و باینری (دودویی).
  • پشتیبانی از فشرده‌سازی HTTP با gzip و deflate.
  • پاسخ‌های CORS با قابلیت پیکربندی برای جلوگیری از مشکلات منشأ متقاطع (cross-origin) با مرورگرها.

این بسته شامل دو کلاینت Engine.IO است:

  • کلاس engineio.Client() <#engineio.Client> کلاینتی سازگار با کتابخانه استاندارد پایتون ایجاد می‌کند.
  • کلاس engineio.AsyncClient() <#engineio.AsyncClient> کلاینتی سازگار با بسته asyncio ایجاد می‌کند.

متدهای موجود در هر دو کلاینت یکسان هستند، با این تفاوت که در کلاینت asyncio بیشتر متدها به عنوان کوروتین (coroutine) پیاده‌سازی شده‌اند.

برای نصب کلاینت استاندارد پایتون به همراه وابستگی‌های آن، از دستور زیر استفاده کنید:

pip install "python-engineio[client]"

اگر در عوض قصد استفاده از کلاینت asyncio را دارید، از این دستور استفاده کنید:

pip install "python-engineio[asyncio_client]"

برای ساخت یک نمونه از کلاینت Engine.IO، کافی است نمونه‌ای از کلاس کلاینت مناسب را ایجاد کنید:

import engineio
# standard Python
eio = engineio.Client()
# asyncio
eio = engineio.AsyncClient()

برای پاسخ به رویدادهای فعال‌شده توسط اتصال یا سرور، توابع گرداننده رویداد باید با استفاده از دکوراتور on تعریف شوند:

@eio.on('connect')
def on_connect():
    print('I'm connected!')
@eio.on('message')
def on_message(data):
    print('I received a message!')
@eio.on('disconnect')
def on_disconnect(reason):
    print('I'm disconnected! reason:', reason)

برای سرور asyncio، گرداننده‌های رویداد می‌توانند توابعی معمولی مانند بالا باشند، یا همچنین می‌توانند کوروتین باشند:

@eio.on('message')
async def on_message(data):
    print('I received a message!')

آرگومان داده‌شده به دکوراتور on، نام رویداد است. رویدادهایی که پشتیبانی می‌شوند عبارتند از connect، message و disconnect.

آرگومان data ارسال‌شده به گرداننده رویداد 'message' حاوی داده‌های ویژه‌ی برنامه است که توسط سرور همراه با رویداد ارائه شده است.

گرداننده disconnect برای قطع اتصالات آغازشده از سوی کلاینت، قطع اتصالات آغازشده از سوی سرور، یا قطع اتصالات تصادفی (برای مثال به دلیل اختلالات شبکه) فراخوانی می‌شود. آرگومان ارائه‌شده به این گرداننده، دلیل قطع اتصال را مشخص می‌کند. مثال:

@eio.on('disconnect')
def on_disconnect(reason):
    if reason == eio.reason.CLIENT_DISCONNECT:
        print('client disconnection')
    elif reason == eio.reason.SERVER_DISCONNECT:
        print('the server kicked me out')
    else:
        print(f'disconnect reason: {reason}')

اتصال به یک سرور با فراخوانی متد connect() برقرار می‌شود:

eio.connect('http://localhost:5000')

در مورد کلاینت asyncio، این متد یک کوروتین است:

await eio.connect('http://localhost:5000')

پس از اتصال، سرور یک شناسه نشست یکتا به کلاینت اختصاص می‌دهد. برنامه می‌تواند این شناسه را در ویژگی sid بیابد:

print('my sid is', eio.sid)

کلاینت می‌تواند با استفاده از متد send() پیامی را به سرور ارسال کند:

eio.send({'foo': 'bar'})

یا در مورد asyncio، به صورت یک کوروتین (coroutine):

await eio.send({'foo': 'bar'})

تک‌آرگومان ارائه‌شده به این متد، داده‌ای است که به سرور ارسال می‌شود. این داده می‌تواند از نوع str، bytes، dict یا list باشد. داده‌های گنجانده‌شده درون دیکشنری‌ها و لیست‌ها نیز به همین انواع محدود هستند.

متد send() می‌تواند درون یک گردانندهٔ رویداد (event handler) در پاسخ به یک رویداد سرور، یا در هر بخش دیگری از برنامه، از جمله در وظایف پس‌زمینه فراخوانی شود.

کلاینت در هر زمان می‌تواند با فراخوانی متد disconnect() درخواست قطع اتصال از سرور را داشته باشد:

eio.disconnect()

برای کلاینت asyncio، این فراخوانی یک کوروتین است:

await eio.disconnect()

هنگامی که اتصال کلاینت به سرور برقرار می‌شود، چند وظیفهٔ پس‌زمینه (background task) برای زنده نگه داشتن اتصال و رسیدگی به رویدادهای دریافتی ایجاد خواهند شد. برنامه‌ای که روی ریسهٔ اصلی (main thread) اجرا می‌شود برای انجام هر کاری آزاد است، چرا که این امر مانع از عملکرد کلاینت Engine.IO نخواهد شد.

اگر برنامه در ریسهٔ اصلی کاری برای انجام دادن ندارد و تنها می‌خواهد تا زمان پایان اتصال منتظر بماند، می‌تواند متد wait() را فراخوانی کند:

eio.wait()

یا در نسخهٔ asyncio:

await eio.wait()

جهت سهولت کار با برنامه، یک تابع کمکی برای آغاز یک وظیفهٔ پس‌زمینهٔ سفارشی ارائه شده است:

def my_background_task(my_argument)
    # do some background work here!
    pass
eio.start_background_task(my_background_task, 123)

آرگومان‌های پاس‌داده‌شده به این متد، تابع پس‌زمینه و هرگونه آرگومان موضعی (positional) یا کلیدواژه‌ای (keyword) هستند که تابع با آن‌ها فراخوانی می‌شود.

در اینجا نسخهٔ asyncio آورده شده است:

async def my_background_task(my_argument)
    # do some background work here!
    pass
eio.start_background_task(my_background_task, 123)

توجه داشته باشید که این تابع یک کوروتین نیست، زیرا منتظر پایان کار تابع پس‌زمینه نمی‌ماند، اما تابع پس‌زمینه خود یک کوروتین است.

متد sleep() دومین تابع کمکی است که به منظور استفادهٔ برنامه‌های دارای وظایف پس‌زمینهٔ اختصاصی فراهم شده است:

eio.sleep(2)

یا برای asyncio:

await eio.sleep(2)

تنها آرگومان پاس‌داده‌شده به این متد، تعداد ثانیه‌های توقف (sleep) است..SS "اشکال‌زدایی و عیب‌یابی (Debugging and Troubleshooting)"

برای کمک به شما در اشکال‌زدایی مشکلات، کلاینت را می‌توان به گونه‌ای پیکربندی کرد که لاگ‌ها را در ترمینال خروجی دهد:

import engineio
# standard Python
eio = engineio.Client(logger=True)
# asyncio
eio = engineio.AsyncClient(logger=True)

آرگومان logger رفتار ثبت لاگ را کنترل می‌کند:

  • True: خروجی لاگ را در stderr با سطح INFO فعال می‌کند.
  • False: خروجی لاگ را در stderr با سطح ERROR فعال می‌کند. این مقدار پیش‌فرض است.
  • یک نمونه از logging.Logger: از لاگر ارائه‌شده بدون پیکربندی اضافی استفاده می‌کند.

ثبت لاگ می‌تواند به شناسایی علت مشکلات اتصال، قطع ارتباط‌های غیرمنتظره و سایر مسائل کمک کند.

این بسته شامل دو سرور Engine.IO است:

  • کلاس engineio.Server() <#engineio.Server> سروری سازگار با کتابخانه استاندارد پایتون ایجاد می‌کند.
  • کلاس engineio.AsyncServer() <#engineio.AsyncServer> سروری سازگار با بسته asyncio ایجاد می‌کند.

متدهای موجود در هر دو سرور یکسان هستند، با این تفاوت که در سرور asyncio بیشتر متدها به‌صورت هم‌روال (coroutine) پیاده‌سازی شده‌اند.

برای نصب سرور Engine.IO پایتون از دستور زیر استفاده کنید:

pip install "python-engineio"

علاوه بر سرور، باید یک چارچوب یا سرور ناهمگام (asynchronous) را برای استفاده در کنار آن انتخاب کنید. فهرست بسته‌های پشتیبانی‌شده در بخش راهبردهای استقرار (Deployment Strategies) پوشش داده شده است.

یک سرور Engine.IO نمونه‌ای از کلاس engineio.Server <#engineio.Server> است. این نمونه می‌تواند با قرار گرفتن در کلاس پوشاننده engineio.WSGIApp <#engineio.WSGIApp> به یک برنامه کاربردی استاندارد WSGI تبدیل شود:

import engineio
# create a Engine.IO server
eio = engineio.Server()
# wrap with a WSGI application
app = engineio.WSGIApp(eio)

برای سرورهای مبتنی بر asyncio، کلاس engineio.AsyncServer <#engineio.AsyncServer> همان قابلیت را اما در قالبی سازگار با هم‌روال‌ها ارائه می‌دهد. در صورت تمایل، کلاس engineio.ASGIApp <#engineio.ASGIApp> می‌تواند سرور را به یک برنامه کاربردی استاندارد ASGI تبدیل کند:

# create a Engine.IO server
eio = engineio.AsyncServer()
# wrap with ASGI application
app = engineio.ASGIApp(eio)

این دو کلاس پوشاننده همچنین می‌توانند به عنوان میان‌افزار (middleware) عمل کنند و هر ترافیکی را که برای سرور Engine.IO در نظر گرفته نشده است به برنامه کاربردی دیگری هدایت کنند. این قابلیت به سرورهای Engine.IO اجازه می‌دهد تا به‌راحتی با برنامه‌های کاربردی موجود WSGI یا ASGI ادغام شوند:

from wsgi import app  # a Flask, Django, etc. application
app = engineio.WSGIApp(eio, app)

سرور Engine.IO را می‌توان طوری پیکربندی کرد که فایل‌های استاتیک را به کلاینت‌ها ارائه دهد. این قابلیت به‌ویژه برای تحویل فایل‌های HTML، CSS و JavaScript به کلاینت‌ها در زمانی که این بسته بدون یک چارچوب وب همراه استفاده می‌شود، بسیار مفید است.

فایل‌های استاتیک با یک دیکشنری Python پیکربندی می‌شوند که در آن هر جفت کلید/مقدار یک قاعدهٔ نگاشت فایل استاتیک است. در ساده‌ترین حالت، این دیکشنری یک یا چند نشانی URL فایل استاتیک را به عنوان کلید، و فایل‌های متناظر در سرور را به عنوان مقدار در بر دارد:

static_files = {
    '/': 'latency.html',
    '/static/engine.io.js': 'static/engine.io.js',
    '/static/style.css': 'static/style.css',
}

با این پیکربندی نمونه، هنگامی که سرور درخواستی برای / (نشانی URL ریشه) دریافت می‌کند، محتوای فایل latency.html در دایرکتوری جاری را برمی‌گرداند، و نوع محتوا (content type) را بر اساس پسوند فایل تعیین می‌کند که در این حالت text/html خواهد بود.

فایل‌های دارای پسوندهای .html، .css، .js، .json، .jpg، .png، .gif و .txt به صورت خودکار شناسایی شده و نوع محتوای صحیح به آن‌ها اختصاص می‌یابد. برای فایل‌هایی با سایر پسوندها یا بدون پسوند فایل، نوع محتوای application/octet-stream به عنوان پیش‌فرض استفاده می‌شود.

در صورت تمایل، می‌توان یک نوع محتوای صریح را برای یک فایل استاتیک به صورت زیر مشخص کرد:

static_files = {
    '/': {'filename': 'latency.html', 'content_type': 'text/plain'},
}

همچنین می‌توان یک دایرکتوری کامل را در یک قاعدهٔ واحد پیکربندی کرد، به‌گونه‌ای که تمامی فایل‌های موجود در آن به عنوان فایل استاتیک ارائه شوند:

static_files = {
    '/static': './public',
}

در این مثال هر فایلی با نشانی URL که با /static آغاز شود، مستقیماً از پوشهٔ public در دایرکتوری جاری ارائه خواهد شد؛ بنابراین برای نمونه، نشانی /static/index.html فایل محلی ./public/index.html و نشانی /static/css/styles.css فایل محلی ./public/css/styles.css را بازمی‌گرداند.

اگر یک نشانی URL درخواست شود که به / ختم می‌شود، نام فایل پیش‌فرض index.html به انتهای آن افزوده می‌شود. در مثال پیشین، یک درخواست برای نشانی /static/ فایل محلی ./public/index.html را برمی‌گرداند. نام فایل پیش‌فرض برای ارائه در نشانی‌های ختم‌شده به اسلش را می‌توان در دیکشنری فایل‌های استاتیک با یک کلید خالی مشخص کرد:

static_files = {
    '/static': './public',
    '': 'image.gif',
}

با این پیکربندی، درخواستی برای /static/ فایل محلی ./public/image.gif را بازمی‌گرداند. در صورت نیاز می‌توان نوع محتوای غیر استاندارد را نیز تعیین نمود:

static_files = {
    '/static': './public',
    '': {'filename': 'image.gif', 'content_type': 'text/plain'},
}

دیکشنری پیکربندی فایل استاتیک به عنوان آرگومان static_files به کلاس‌های engineio.WSGIApp یا engineio.ASGIApp ارسال می‌شود:

# for standard WSGI applications
eio = engineio.Server()
app = engineio.WSGIApp(eio, static_files=static_files)
# for asyncio-based ASGI applications
eio = engineio.AsyncServer()
app = engineio.ASGIApp(eio, static_files=static_files)

اولویت مسیریابی در این دو کلاس به شرح زیر است:

  • نخست، مسیر نسبت به مسیر Engine.IO بررسی می‌شود.
  • سپس، در صورت وجود، مسیر با پیکربندی فایل‌های استاتیک تطبیق داده می‌شود.
  • اگر مسیر با مسیر Engine.IO یا هیچ فایل استاتیکی مطابقت نداشت، در صورت پیکربندی، کنترل به برنامهٔ ثانویه واگذار می‌شود، در غیر این صورت خطای 404 برگردانده می‌شود.

نکته: ارائه فایل‌های استاتیک فقط برای اهداف توسعه در نظر گرفته شده است و فاقد قابلیت‌های مهمی مانند حافظهٔ پنهان (caching) است. از آن در محیط عملیاتی (production) استفاده نکنید..SS تعریف گرداننده‌های رویداد (Defining Event Handlers)

برای پاسخ دادن به رویدادهای برانگیخته‌شده توسط اتصال یا کلاینت، توابع گردانندهٔ رویداد باید با استفاده از دکوراتور on تعریف شوند:

@eio.on('connect')
def on_connect(sid):
    print('A client connected!')
@eio.on('message')
def on_message(sid, data):
    print('I received a message!')
@eio.on('disconnect')
def on_disconnect(sid, reason):
    print('Client disconnected! reason:', reason)

برای سرور asyncio، گرداننده‌های رویداد می‌توانند مانند بالا توابعی عادی، یا هم‌روال (coroutine) باشند:

@eio.on('message')
async def on_message(sid, data):
    print('I received a message!')

آرگومان داده‌شده به دکوراتور on نام رویداد است. رویدادهایی که پشتیبانی می‌شوند عبارتند از connect، message و disconnect.

آرگومان sid که به تمام گرداننده‌های رویداد ارسال می‌شود، یک شناسهٔ اتصال برای کلاینت است. تمام رویدادهای یک کلاینت از همان مقدار sid یکسان استفاده خواهند کرد.

گردانندهٔ connect مکانی است که سرور می‌تواند در آن احراز هویت را انجام دهد. مقدار بازگردانده‌شده توسط این گرداننده برای تعیین پذیرش یا رد اتصال به کار می‌رود. هنگامی که گرداننده مقداری بازنمی‌گرداند (که معادل بازگرداندن None است) یا زمانی که True برمی‌گرداند، اتصال پذیرفته می‌شود. اگر گرداننده False یا هر نوع دادهٔ سازگار با JSON (رشته، عدد صحیح، فهرست یا دیکشنری) برگرداند، اتصال رد می‌شود. یک اتصال ردشده، پاسخی با کد وضعیت 401 برمی‌انگیزد.

آرگومان data که به گردانندهٔ رویداد 'message' فرستاده می‌شود، شامل داده‌های خاص برنامه است که توسط کلاینت به همراه رویداد ارائه شده است.

گردانندهٔ disconnect برای قطع ارتباط‌های آغازشده از سوی کلاینت، قطع ارتباط‌های آغازشده از سوی سرور، یا قطع ارتباط‌های اتفاقی مانند مواردی ناشی از اختلالات شبکه فراخوانی می‌شود. آرگومان دومی که به این گرداننده داده می‌شود، دلیل قطع اتصال را فراهم می‌کند. مثال:

@eio.on('disconnect')
def on_disconnect(sid, reason):
    if reason == eio.reason.CLIENT_DISCONNECT:
        print('the client went away')
    elif reason == eio.reason.SERVER_DISCONNECT:
        print('the client was kicked out')
    else:
        print(f'disconnect reason: {reason}')

سرور می‌تواند با استفاده از متد send() به هر کلاینتی پیام ارسال کند:

eio.send(sid, {'foo': 'bar'})

یا در صورت استفاده از asyncio، به صورت یک هم‌روال:

await eio.send(sid, {'foo': 'bar'})

نخستین آرگومان داده‌شده به متد، شناسهٔ اتصال کلاینت دریافت‌کننده است. دومین آرگومان، داده‌ای است که به سرور فرستاده می‌شود. این داده می‌تواند از انواع str، bytes، dict یا list باشد. داده‌های قرارگرفته درون دیکشنری‌ها و فهرست‌ها نیز به همین انواع محدود هستند.

متد send() می‌تواند درون یک گردانندهٔ رویداد به عنوان پاسخی به یک رویداد کلاینت، یا در هر بخش دیگری از برنامه، از جمله در وظایف پس‌زمینه فراخوانی شود..SS نشست‌های کاربر (User Sessions)

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

متدهای save_session() و get_session() برای ذخیره و بازیابی اطلاعات در نشست کاربر استفاده می‌شوند:

@eio.on('connect')
def on_connect(sid, environ):
    username = authenticate_user(environ)
    eio.save_session(sid, {'username': username})
@eio.on('message')
def on_message(sid, data):
    session = eio.get_session(sid)
    print('message from ', session['username'])

برای سرور asyncio، این متدها به صورت هم‌روال (coroutine) هستند:

@eio.on('connect')
async def on_connect(sid, environ):
    username = authenticate_user(environ)
    await eio.save_session(sid, {'username': username})
@eio.on('message')
async def on_message(sid, data):
    session = await eio.get_session(sid)
    print('message from ', session['username'])

نشست را همچنین می‌توان با مدیر بافتار session() دستکاری کرد:

@eio.on('connect')
def on_connect(sid, environ):
    username = authenticate_user(environ)
    with eio.session(sid) as session:
        session['username'] = username
@eio.on('message')
def on_message(sid, data):
    with eio.session(sid) as session:
        print('message from ', session['username'])

برای سرور asyncio، از یک مدیر بافتار ناهمگام استفاده می‌شود:

@eio.on('connect')
def on_connect(sid, environ):
    username = authenticate_user(environ)
    async with eio.session(sid) as session:
        session['username'] = username
@eio.on('message')
def on_message(sid, data):
    async with eio.session(sid) as session:
        print('message from ', session['username'])

نکته: محتویات نشست کاربر با قطع اتصال کلاینت از بین می‌رود..SS قطع اتصال کلاینت (Disconnecting a Client)

سرور در هر زمان می‌تواند با فراخوانی متد disconnect() و ارسال مقدار sid اختصاص‌یافته به کلاینت، اتصال آن کلاینت را از سرور قطع کند:

eio.disconnect(sid)

برای کلاینت asyncio این یک کوروتین است:

await eio.disconnect(sid)

برای راحتی کار برنامه، یک تابع کمکی برای راه‌اندازی یک وظیفهٔ پس‌زمینهٔ سفارشی ارائه شده است:

def my_background_task(my_argument)
    # do some background work here!
    pass
eio.start_background_task(my_background_task, 123)

آرگومان‌های ارسال‌شده به این متد عبارت‌اند از تابع پس‌زمینه و هرگونه آرگومان موضعی (positional) یا کلیدواژه‌ای (keyword) که تابع باید با آن‌ها فراخوانی شود.

در اینجا نسخهٔ asyncio آمده است:

async def my_background_task(my_argument)
    # do some background work here!
    pass
eio.start_background_task(my_background_task, 123)

توجه داشته باشید که این تابع خود یک کوروتین نیست، زیرا منتظر به پایان رسیدن تابع پس‌زمینه نمی‌ماند، اما تابع پس‌زمینه یک کوروتین است.

متد sleep() دومین تابع کمکی است که برای راحتی برنامه‌هایی که با وظایف پس‌زمینهٔ اختصاصی خود کار می‌کنند، ارائه شده است:

eio.sleep(2)

یا برای asyncio:

await eio.sleep(2)

تنها آرگومان ارسال‌شده به متد، تعداد ثانیه‌هایی است که باید در حالت تعلیق (sleep) بماند..SS اشکال‌زدایی و عیب‌یابی

برای کمک به اشکال‌زدایی مشکلات، سرور را می‌توان طوری پیکربندی کرد که لاگ‌ها را در پایانه نمایش دهد:

import engineio
# standard Python
eio = engineio.Server(logger=True)
# asyncio
eio = engineio.AsyncServer(logger=True)

آرگومان logger رفتار ثبت وقایع را کنترل می‌کند:

  • True: خروجی لاگ به stderr را در سطح INFO فعال می‌کند.
  • False: خروجی لاگ به stderr را در سطح ERROR فعال می‌کند. این مقدار پیش‌فرض است.
  • یک نمونه از logging.Logger: از لاگر ارائه‌شده بدون پیکربندی اضافی استفاده می‌کند.

ثبت وقایع می‌تواند به شناسایی علت مشکلات اتصال، پاسخ‌های ۴۰۰، کارایی نامناسب و سایر ایرادها کمک کند.

بخش‌های زیر راهبردهای گوناگون استقرار را برای سرورهای Engine.IO شرح می‌دهند.

کلاس engineio.ASGIApp یک برنامه سازگار با ASGI است که می‌تواند ترافیک Engine.IO را به یک نمونه engineio.AsyncServer هدایت کند:

eio = engineio.AsyncServer(async_mode='asgi')
app = engineio.ASGIApp(eio)

در صورت تمایل، کلاس engineio.ASGIApp می‌تواند هر ترافیکی را که مربوط به Engine.IO نیست به یک برنامه ASGI دیگر هدایت کند، که این امر امکان استقرار یک برنامه وب استاندارد ASGI و سرور Engine.IO را در قالب یک بسته واحد فراهم می‌سازد:

eio = engineio.AsyncServer(async_mode='asgi')
app = engineio.ASGIApp(eio, other_app)

نمونه ASGIApp یک نمونه کاملاً منطبق با ASGI است که می‌تواند با یک وب‌سرور سازگار با ASGI مستقر شود.

کتابخانه aiohttp http://aiohttp.readthedocs.io چارچوبی مبتنی بر asyncio با پشتیبانی از HTTP و WebSocket فراهم می‌کند.

نمونه‌های کلاس engineio.AsyncServer در صورت نصب بودن این کتابخانه، به‌طور خودکار از aiohttp برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریح استفاده از آن، گزینه async_mode را می‌توان در سازنده مشخص کرد:

eio = engineio.AsyncServer(async_mode='aiohttp')

سروری که برای aiohttp پیکربندی شده است باید به یک برنامه موجود ضمیمه شود:

app = web.Application()
eio.attach(app)

برنامه aiohttp می‌تواند مسیرهای معمولی را تعریف کند که در کنار سرور Engine.IO هم‌زیستی داشته باشند. یک الگوی رایج، افزودن مسیرهایی است که به برنامه سمت کاربر (کلاینت) و فایل‌های ایستای مرتبط با آن پاسخ می‌دهند.

سپس برنامه aiohttp به شیوه معمول اجرا می‌شود:

if __name__ == '__main__':
    web.run_app(app)

ابزار Tornado http://www.tornadoweb.org یک فریم‌ورک وب با پشتیبانی از HTTP و WebSocket است. به لطف یکپارچگی عمیق آن با asyncio، تنها Tornado نسخهٔ ۵ و جدیدتر پشتیبانی می‌شوند.

در صورت نصب بودن کتابخانه، نمونه‌های کلاس engineio.AsyncServer به‌طور خودکار از tornado برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریحِ استفاده از آن، گزینهٔ async_mode می‌تواند در سازنده مشخص شود:

eio = engineio.AsyncServer(async_mode='tornado')

سروری که برای tornado پیکربندی شده است باید شامل یک گردانندهٔ درخواست (request handler) برای Engine.IO باشد:

app = tornado.web.Application(
    [
        (r"/engine.io/", engineio.get_tornado_handler(eio)),
    ],
    # ... other application options
)

برنامهٔ tornado می‌تواند مسیرهای دیگری را نیز تعریف کند که هم‌زمان با سرور Engine.IO وجود داشته باشند. یک الگوی معمول، افزودن مسیرهایی است که یک برنامهٔ کلاینت و هرگونه فایل ایستای مرتبط را ارائه می‌دهند.

سپس برنامهٔ tornado به روش معمول اجرا می‌شود:

app.listen(port)
tornado.ioloop.IOLoop.current().start()

نکته: با توجه به برخی تغییرات ناسازگار با گذشته که در نسخه‌های اخیر Sanic اعمال شده است، در حال حاضر توصیه می‌شود که برنامهٔ Sanic در عوض با یکپارچگی ASGI مستقر شود.

ابزار Sanic http://sanic.readthedocs.io یک وب‌سرور ناهمگام بسیار کارآمد برای Python است.

در صورت نصب بودن فریم‌ورک، نمونه‌های کلاس engineio.AsyncServer به‌طور خودکار از Sanic برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریحِ استفاده از آن، گزینهٔ async_mode می‌تواند در سازنده مشخص شود:

eio = engineio.AsyncServer(async_mode='sanic')

سروری که برای Sanic پیکربندی شده است باید به یک برنامهٔ موجود متصل شود:

app = Sanic()
eio.attach(app)

برنامهٔ Sanic می‌تواند مسیرهای معمولی را تعریف کند که هم‌زمان با سرور Engine.IO وجود داشته باشند. یک الگوی معمول، افزودن مسیرهایی به این برنامه است که برنامهٔ کلاینت و فایل‌های ایستای مرتبط را ارائه می‌دهند.

سپس برنامهٔ Sanic به شیوهٔ معمول اجرا می‌شود:

if __name__ == '__main__':
    app.run()

گزارش شده است که پشتیبانی از CORS ارائه‌شده توسط افزونهٔ sanic-cors https://github.com/ashleysommer/sanic-cors در Sanic با پشتیبانی خود این بسته از این پروتکل ناسازگار است. برای غیرفعال کردن پشتیبانی CORS در این بسته و واگذاری کامل کنترل به Sanic، سرور را به صورت زیر مقداردهی اولیه کنید:

eio = engineio.AsyncServer(async_mode='sanic', cors_allowed_origins=[])

در سمت Sanic، علاوه بر هر پیکربندی دیگری که استفاده می‌کنید، باید تنظیم CORS_SUPPORTS_CREDENTIALS را نیز فعال کنید:

app.config['CORS_SUPPORTS_CREDENTIALS'] = True

کتابخانهٔ Eventlet http://eventlet.net یک کتابخانهٔ شبکهٔ همروند با کارایی بالا برای Python 2 و 3 است که از هم‌روال‌ها (coroutines) استفاده می‌کند و امکان نوشتن کد به همان سبکی که در توابع مسدودکنندهٔ کتابخانهٔ استاندارد استفاده می‌شود را فراهم می‌سازد. یک سرور Engine.IO مستقرشده با eventlet به روش‌های انتقال long-polling و WebSocket دسترسی دارد.

نمونه‌های کلاس engineio.Server در صورت نصب بودن این کتابخانه، به‌طور خودکار از eventlet برای عملیات‌های ناهمگام استفاده خواهند کرد. برای درخواست صریح استفاده از آن، می‌توان گزینهٔ async_mode را در سازنده (constructor) مشخص کرد:

eio = engineio.Server(async_mode='eventlet')

سروری که برای eventlet پیکربندی شده است، با استفاده از engineio.WSGIApp ارائه‌شده، به عنوان یک برنامهٔ WSGI معمولی مستقر می‌شود:

app = engineio.WSGIApp(eio)
import eventlet
eventlet.wsgi.server(eventlet.listen(('', 8000)), app)

یک راهکار جایگزین برای اجرای سرور WSGI مبتنی بر eventlet مطابق بالا، استفاده از gunicorn <gunicorn.org> است؛ یک وب‌سرور با امکانات کامل و به زبان پایتون خالص. دستور راه‌اندازی برنامه تحت gunicorn در زیر آورده شده است:

$ gunicorn -k eventlet -w 1 module:app

به دلیل محدودیت‌های موجود در الگوریتم متعادل‌سازی بار، gunicorn تنها می‌تواند با یک فرآیند worker استفاده شود، بنابراین گزینهٔ -w 1 الزامی است. توجه داشته باشید که یک worker منفرد eventlet می‌تواند تعداد زیادی کلاینت هم‌روند را مدیریت کند.

محدودیت دیگر هنگام استفاده از gunicorn این است که روش انتقال WebSocket در دسترس نیست، چرا که این روش انتقال نیازمند الحاقاتی به استاندارد WSGI است.

نکته: کتابخانهٔ Eventlet تابع monkey_patch() را ارائه می‌دهد که تمامی توابع مسدودکننده در کتابخانهٔ استاندارد را با نسخه‌های ناهمگام معادل جایگزین می‌کند. در حالی که python-engineio نیازی به monkey patching ندارد، سایر کتابخانه‌ها از جمله درایورهای پایگاه‌داده احتمالاً به آن نیاز خواهند داشت.

کتابخانهٔ Gevent http://gevent.org یکی دیگر از چارچوب‌های ناهمگام بر پایهٔ هم‌روال‌ها است که شباهت زیادی به eventlet دارد. یک سرور Engine.IO مستقرشده با gevent به روش‌های انتقال long-polling و websocket دسترسی دارد.

نمونه‌های کلاس engineio.Server در صورت نصب بودن این کتابخانه و عدم نصب eventlet، به‌طور خودکار از gevent برای عملیات‌های ناهمگام استفاده خواهند کرد. برای درخواست صریحِ انتخاب gevent، می‌توان گزینهٔ async_mode را در سازنده مشخص کرد:

eio = engineio.Server(async_mode='gevent')

سروری که برای gevent پیکربندی شده است، با استفاده از engineio.WSGIApp ارائه‌شده، به عنوان یک برنامهٔ WSGI معمولی مستقر می‌شود:

from gevent import pywsgi
app = engineio.WSGIApp(eio)
pywsgi.WSGIServer(('', 8000), app).serve_forever()

یک جایگزین برای اجرای کارساز WSGI مربوط به gevent همانند بالا، استفاده از gunicorn https://gunicorn.org است؛ یک وب‌کارساز تمام‌عیار و پایتون خالص (pure Python). دستور راه‌اندازی برنامه تحت gunicorn در زیر نشان داده شده است:

$ gunicorn -k gevent -w 1 module:app

همانند eventlet، به دلیل محدودیت‌های موجود در الگوریتم متعادل‌سازی بار (load balancing) آن، gunicorn تنها می‌تواند با یک فرایند کارگر (worker process) استفاده شود، بنابراین گزینهٔ -w 1 الزامی است. توجه داشته باشید که یک کارگر gevent منفرد می‌تواند تعداد زیادی کلاینت هم‌روند را مدیریت کند.

نکته: Gevent یک تابع monkey_patch() ارائه می‌دهد که تمامی توابع مسدودکننده (blocking) در کتابخانهٔ استاندارد را با نسخه‌های معادل غیرهمگام جایگزین می‌کند. اگرچه python-engineio نیازی به monkey patching ندارد، اما سایر کتابخانه‌ها مانند درایورهای پایگاه‌داده احتمالاً به آن نیاز خواهند داشت.

هنگام استفاده از کارساز uWSGI در ترکیب با gevent، کارساز Engine.IO می‌تواند از پشتیبانی بومی WebSocket در uWSGI بهره ببرد.

نمونه‌های کلاس engineio.Server در صورتی که هر دو gevent و uWSGI نصب بوده و eventlet نصب نباشد، به‌طور خودکار از این گزینه برای عملیات غیرهمگام استفاده خواهند کرد. برای درخواست صریح این حالت غیرهمگام، می‌توان گزینهٔ async_mode را در سازنده (constructor) مشخص کرد:

# gevent with uWSGI
eio = engineio.Server(async_mode='gevent_uwsgi')

توضیح کامل پیکربندی و نحوهٔ استفاده از کارساز uWSGI خارج از محدودهٔ این مستندات است. کارساز uWSGI بسته‌ای نسبتاً پیچیده است که مجموعهٔ بزرگ و جامعی از گزینه‌ها را ارائه می‌دهد. این بسته برای در دسترس بودن انتقال WebSocket باید همراه با پشتیبانی از WebSocket و SSL کامپایل شده باشد. به عنوان مقدمه، دستور زیر یک کارساز uWSGI را برای مثال latency.py روی درگاه ۵۰۰۰ اجرا می‌کند:

$ uwsgi --http :5000 --gevent 1000 --http-websockets --master --wsgi-file latency.py --callable app

اگرچه از نظر کارایی با eventlet و gevent قابل مقایسه نیست، اما کارساز Engine.IO را می‌توان برای کار با وب‌کارسازهای چندریسمانی که از ریسمان‌های استاندارد پایتون استفاده می‌کنند نیز پیکربندی کرد. این یک راه‌اندازی ایده‌آل برای استفاده با کارسازهای توسعه نظیر Werkzeug http://werkzeug.pocoo.org است.

نمونه‌های کلاس engineio.Server در صورتی که هیچ‌یک از eventlet یا gevent نصب نشده باشند، به‌طور خودکار از حالت ریسمان‌بندی استفاده خواهند کرد. برای درخواست صریح حالت ریسمان‌بندی، می‌توان گزینهٔ async_mode را در سازنده مشخص کرد:

eio = engineio.Server(async_mode='threading')

کارسازی که برای ریسمان‌بندی پیکربندی شده است، همانند یک برنامهٔ وب معمولی و با استفاده از هر کارساز چندریسمانی منطبق بر WSGI مستقر می‌شود. مثال زیر یک برنامهٔ Engine.IO را در ترکیب با یک برنامهٔ وب Flask، با استفاده از کارساز توسعهٔ وب Flask مبتنی بر Werkzeug مستقر می‌کند:

eio = engineio.Server(async_mode='threading')
app = Flask(__name__)
app.wsgi_app = engineio.WSGIApp(eio, app.wsgi_app)
# ... Engine.IO and Flask handler functions ...
if __name__ == '__main__':
    app.run()

مثال زیر نحوهٔ راه‌اندازی یک برنامهٔ Engine.IO را با استفاده از کلاس کارگر چندریسمانی Gunicorn نشان می‌دهد:

$ gunicorn -w 1 --threads 100 module:app

با پیکربندی فوق، کارساز قادر خواهد بود تا ۱۰۰ کلاینت هم‌روند را مدیریت کند.

هنگام استفاده از ریسمان‌های استاندارد، WebSocket از طریق بستهٔ simple-websocket https://github.com/miguelgrinberg/simple-websocket پشتیبانی می‌شود که باید به‌طور جداگانه نصب گردد. این بسته یک کارساز چندریسمانی WebSocket ارائه می‌دهد که با Werkzeug و کارگر ریسمانی Gunicorn سازگار است. سایر وب‌کارسازهای چندریسمانی پشتیبانی نمی‌شوند و امکان انتقال از طریق WebSocket را فعال نخواهند کرد..SS "نکات مقیاس‌پذیری (Scalability Notes)"

پروتکل Engine.IO یک پروتکل با حفظ وضعیت (stateful) است، که مقیاس‌پذیری افقی را دشوارتر می‌کند. برای استقرار یک کلاستر از فرآیندهای Engine.IO که روی یک یا چند سرور میزبانی می‌شوند، شرایط زیر باید برآورده شوند:

  • هر فرآیند سرور Engine.IO باید قادر باشد چندین درخواست را به‌طور هم‌روند مدیریت کند. این امر الزامی است زیرا کلاینت‌های long-polling دو درخواست را به‌طور موازی ارسال می‌کنند. فرآیندهای worker که در هر لحظه تنها می‌توانند یک درخواست را مدیریت کنند، پشتیبانی نمی‌شوند.
  • توازن‌دهنده بار (load balancer) باید به‌گونه‌ای پیکربندی شود که همیشه درخواست‌های یک کلاینت را به همان فرآیند هدایت کند. توازن‌دهنده‌های بار این ویژگی را sticky sessions یا session affinity می‌نامند.

به دلایل امنیتی، این سرور به‌طور پیش‌فرض از سیاست مبدأ یکسان (same-origin policy) پیروی می‌کند. از نظر عملی، این به معنای موارد زیر است:

  • اگر یک درخواست ورودی HTTP یا WebSocket شامل هدر Origin باشد، این هدر باید با scheme و host مربوط به URL اتصال مطابقت داشته باشد. در صورت عدم تطابق، پاسخی با کد وضعیت 400 بازگردانده شده و اتصال رد می‌شود.
  • هیچ محدودیتی بر روی درخواست‌های ورودی که شامل هدر Origin نیستند اعمال نمی‌شود.

در صورت نیاز، گزینه cors_allowed_origins می‌تواند برای مجاز کردن سایر مبدأها استفاده شود. این آرگومان می‌تواند برابر با یک رشته برای تعیین یک مبدأ مجاز واحد، یا یک لیست برای مجاز کردن چندین مبدأ تنظیم شود. مقدار ویژه '*' می‌تواند برای دستور به سرور جهت مجاز کردن همه مبدأها استفاده شود، اما این کار باید با احتیاط انجام گیرد، زیرا می‌تواند سرور را در برابر حملات جعل درخواست میان‌وب‌گاهی (CSRF) آسیب‌پذیر کند.

یک کلاینت Engine.IO.

این کلاس یک کلاینت وب Engine.IO کاملاً منطبق را با پشتیبانی از روش‌های انتقال websocket و long-polling پیاده‌سازی می‌کند.

پارامترها
  • logger -- برای فعال‌سازی ثبت وقایع، روی True تنظیم کنید یا یک شیء logger را برای استفاده پاس دهید. برای غیرفعال‌سازی ثبت وقایع، روی False تنظیم کنید. مقدار پیش‌فرض False است. توجه داشته باشید که خطاهای مهلک حتی زمانی که logger برابر با False باشد نیز ثبت می‌شوند.
  • json -- یک ماژول JSON جایگزین جهت استفاده برای کدگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید دارای توابع dumps و loads باشند که با نسخه‌های کتابخانه استاندارد سازگار باشند. این یک تنظیم در سطح کل فرآیند است؛ تمام سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON مشابه استفاده کنند.
  • request_timeout -- مدت‌زمان انتظار (مهلت زمانی) برحسب ثانیه برای درخواست‌ها. مقدار پیش‌فرض 5 ثانیه است.
  • http_session -- یک شیء مقداردهی‌شده از requests.Session برای استفاده هنگام ارسال درخواست‌ها به سرور. در صورتی که نیاز به افزودن گزینه‌های خاص کلاینت مانند سرورهای پراکسی، گواهی‌های SSL، بسته سفارشی CA و غیره دارید، از آن استفاده کنید.
  • ssl_verify -- مقدار True برای اعتبارسنجی گواهی‌های SSL، یا False برای صرف‌نظر کردن از اعتبارسنجی گواهی SSL، که امکان اتصال به سرورهای دارای گواهی خودامضا را فراهم می‌کند. پیش‌فرض True است.
  • handle_sigint -- تنظیم روی True برای مدیریت خودکار قطع اتصال در صورت ایجاد وقفه در فرآیند، یا روی False برای واگذاری مدیریت وقفه به برنامه فراخواننده. مدیریت وقفه تنها زمانی می‌تواند فعال شود که نمونه کلاینت در ریسه اصلی (main thread) ایجاد شده باشد.
  • websocket_extra_options -- دیکشنری حاوی آرگومان‌های کلیدواژه‌ای اضافی که به websocket.create_connection() منتقل می‌شوند.
  • timestamp_requests -- اگر True باشد، یک برچسب زمانی (timestamp) به عنوان راهکاری برای بی‌اثر کردن حافظه پنهان (cache-busting) به query string درخواست‌های Socket.IO افزوده می‌شود. برای غیرفعال‌سازی روی False تنظیم کنید.
اتصال به یک سرور Engine.IO.
پارامترها
  • url -- نشانی اینترنتی (URL) سرور Engine.IO. در صورت نیاز سرور، می‌تواند شامل پارامترهای سفارشی query string باشد.
  • headers -- یک دیکشنری حاوی هدرهای سفارشی برای ارسال همراه با درخواست اتصال.
  • transports -- فهرست روش‌های انتقال مجاز. مقادیر معتبر 'polling' و 'websocket' هستند. در صورت عدم تعیین، ابتدا انتقال polling متصل شده و سپس برای ارتقا به websocket تلاش می‌شود.
  • engineio_path -- نقطه پایانی (endpoint) که سرور Engine.IO روی آن نصب شده است. مقدار پیش‌فرض برای بیشتر موارد مناسب است.

نمونه استفاده:

eio = engineio.Client()
eio.connect('http://localhost:5000')
صبر کردن تا زمانی که اتصال با سرور پایان یابد.

برنامه‌های کلاینت می‌توانند از این تابع برای مسدود کردن ریسه اصلی در طول مدت اتصال استفاده کنند.

ارسال یک پیام به سرور.
پارامترها
data -- داده برای ارسال به سرور. داده می‌تواند از نوع str، bytes، list یا dict باشد. در صورت بودن list یا dict، داده به‌صورت JSON سریال‌سازی خواهد شد.
قطع اتصال از سرور.
پارامترها
abort -- در صورت تنظیم روی True، منتظر پایان یافتن وظایف پس‌زمینه مرتبط با اتصال نمی‌ماند.
شروع یک وظیفه پس‌زمینه.

این یک تابع کمکی است که برنامه‌ها می‌توانند برای شروع یک وظیفه پس‌زمینه از آن استفاده کنند.

پارامترها
  • target -- تابع هدف برای اجرا.
  • args -- آرگومان‌هایی که باید به تابع ارسال شوند.
  • kwargs -- آرگومان‌های کلیدواژه‌ای که باید به تابع ارسال شوند.

این تابع شیئی را بازمی‌گرداند که نشان‌دهنده وظیفه پس‌زمینه است و می‌توان متد join() را روی آن فراخوانی کرد تا منتظر تکمیل وظیفه بماند.

sleep(seconds=0) به میزان زمان درخواست‌شده به خواب می‌رود.
یک شیء صف (queue) ایجاد می‌کند.
استثنای خالی بودن صف ناشی از صف‌های ایجادشده توسط متد create_queue() را برمی‌گرداند.
یک شیء رویداد (event) ایجاد می‌کند.
یک گرداننده رویداد (event handler) ثبت می‌کند.
پارامترها (Parameters)
  • event -- نام رویداد. می‌تواند 'connect'، 'message' یا 'disconnect' باشد.
  • handler -- تابعی که باید برای مدیریت رویداد فراخوانی شود. هنگامی که این پارامتر مشخص نشود، این متد به عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند.

نمونه کاربرد:

# as a decorator:
@eio.on('connect')
def connect_handler():
    print('Connection request')
# as a method:
def message_handler(msg):
    print('Received message: ', msg)
    eio.send('response')
eio.on('message', message_handler)
دلایل قطع اتصال.
قطع اتصال به درخواست کلاینت.
قطع اتصال به درخواست سرور.
خطای لایه انتقال (transport).
نام روش انتقال در حال استفاده را برمی‌گرداند.

مقادیر ممکن بازگردانده شده توسط این تابع 'polling' و 'websocket' هستند.

یک کلاینت Engine.IO برای asyncio.

این کلاس یک وب‌کلاینت کاملاً منطبق با Engine.IO پیاده‌سازی می‌کند که از روش‌های انتقال websocket و long-polling پشتیبانی کرده و با چارچوب asyncio در Python 3.5 یا جدیدتر سازگار است.

پارامترها (Parameters)
  • logger -- برای فعال‌سازی ثبت وقایع روی True تنظیم شود یا یک شیء logger برای استفاده ارسال گردد. برای غیرفعال‌سازی ثبت وقایع روی False تنظیم شود. مقدار پیش‌فرض False است. توجه داشته باشید که خطاهای مهلک حتی در صورت False بودن logger نیز ثبت می‌شوند.
  • json -- یک ماژول JSON جایگزین برای استفاده در انکود و دکود بسته‌ها. ماژول‌های سفارشی json باید دارای توابع dumps و loads سازگار با نسخه‌های کتابخانه استاندارد باشند. این یک تنظیم در سطح کل فرآیند (process-wide) است و همه سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON یکسان استفاده کنند.
  • request_timeout -- مهلت زمانی درخواست‌ها بر حسب ثانیه. مقدار پیش‌فرض 5 ثانیه است.
  • http_session -- یک شیء مقداردهی‌شده از aiohttp.ClientSession برای استفاده هنگام ارسال درخواست‌ها به سرور. در صورتی که نیاز به افزودن گزینه‌های خاص کلاینت مانند سرورهای پروکسی، گواهی‌های SSL، بسته سفارشی CA و غیره دارید از آن استفاده کنید.
  • ssl_verify -- مقدار True برای بررسی گواهی‌های SSL، یا False برای نادیده گرفتن اعتبارسنجی گواهی SSL و برقراری ارتباط با سرورهای دارای گواهی خودامضا (self-signed). مقدار پیش‌فرض True است.
  • handle_sigint -- برای مدیریت خودکار قطع اتصال هنگام وقفه در فرآیند روی True تنظیم شود، یا روی False قرار گیرد تا مدیریت وقفه به برنامه فراخواننده واگذار گردد. مدیریت وقفه تنها زمانی می‌تواند فعال شود که نمونه کلاینت در ریسه اصلی (main thread) ایجاد شده باشد.
  • websocket_extra_options -- دیکشنری حاوی آرگومان‌های کلیدواژه‌ای اضافی ارسال‌شده به aiohttp.ws_connect().
  • timestamp_requests -- در صورت تنظیم روی True یک برچسب زمانی به رشته پرس‌وجوی (query string) درخواست‌های Socket.IO به عنوان روشی برای جلوگیری از کش شدن (cache-busting) اضافه می‌شود. برای غیرفعال‌سازی روی False تنظیم کنید.
اتصال به یک سرور Engine.IO.
پارامترها (Parameters)
  • url -- آدرس اینترنتی (URL) سرور Engine.IO. در صورت نیاز سرور می‌تواند شامل پارامترهای سفارشی رشته پرس‌وجو باشد.
  • headers -- دیکشنری حاوی سرآیندهای سفارشی برای ارسال همراه با درخواست اتصال.
  • transports -- فهرست روش‌های انتقال مجاز. روش‌های انتقال معتبر عبارتند از 'polling' و 'websocket'. در صورت مشخص نشدن، ابتدا انتقال polling متصل می‌شود و سپس برای ارتقا به websocket تلاش می‌گردد.
  • engineio_path -- نقطه پایانی (endpoint) جایی که سرور Engine.IO نصب شده است. مقدار پیش‌فرض برای بیشتر موارد مناسب است.

توجه: این متد یک هم‌روال (coroutine) است.

نمونه کاربرد:

eio = engineio.Client()
await eio.connect('http://localhost:5000')
تا زمان پایان یافتن اتصال با سرور منتظر می‌ماند..sp برنامه‌های کلاینت می‌توانند از این تابع برای مسدود کردن نخ اصلی در طول حیات اتصال استفاده کنند.

نکته: این متد یک کوروتین است.

ارسال یک پیام به سرور.
پارامترها
data -- داده برای ارسال به سرور. داده می‌تواند از نوع str، bytes، list یا dict باشد. اگر یک list یا dict باشد، داده به‌صورت JSON سریال‌سازی خواهد شد.

نکته: این متد یک کوروتین است.

قطع اتصال از سرور.
پارامترها
abort -- اگر روی True تنظیم شود، منتظر پایان یافتن وظایف پس‌زمینهٔ مرتبط با اتصال نمی‌ماند.

نکته: این متد یک کوروتین است.

شروع یک وظیفهٔ پس‌زمینه.

این یک تابع کمکی است که برنامه‌ها می‌توانند برای شروع یک وظیفهٔ پس‌زمینه از آن استفاده کنند.

پارامترها
  • target -- تابع هدف برای اجرا.
  • args -- آرگومان‌ها برای ارسال به تابع.
  • kwargs -- آرگومان‌های کلیدواژه‌ای برای ارسال به تابع.

مقدار بازگشتی یک شیء asyncio.Task است.

توقف موقت به میزان زمان درخواستی.

نکته: این متد یک کوروتین است.

ایجاد یک شیء صف.
استثنای خالی بودن صف که توسط صف‌های ساخته‌شده با متد create_queue() برانگیخته می‌شود را بازمی‌گرداند.
ایجاد یک شیء رویداد.
ثبت یک گردانندهٔ رویداد.
پارامترها
  • event -- نام رویداد. می‌تواند 'connect'، 'message' یا 'disconnect' باشد.
  • handler -- تابعی که باید برای رسیدگی به رویداد فراخوانی شود. اگر این پارامتر مشخص نشود، متد به عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند.

مثال استفاده:

# as a decorator:
@eio.on('connect')
def connect_handler():
    print('Connection request')
# as a method:
def message_handler(msg):
    print('Received message: ', msg)
    eio.send('response')
eio.on('message', message_handler)
دلایل قطع اتصال.
قطع اتصال آغازشده از سوی کلاینت.
قطع اتصال آغازشده از سوی سرور.
خطای انتقال (transport).
نام لایهٔ انتقال در حال استفاده را بازمی‌گرداند.

مقدارهای احتمالی بازگردانده‌شده توسط این تابع 'polling' و 'websocket' هستند.

یک سرور Engine.IO.

این کلاس یک وب‌سرور کاملاً سازگار با Engine.IO همراه با پشتیبانی از روش‌های انتقال websocket و long-polling را پیاده‌سازی می‌کند.

پارامترها
  • async_mode -- مدل ناهمگام مورد استفاده. برای شرح گزینه‌های موجود، بخش Deployment را در مستندات ببینید. حالت‌های ناهمگام معتبر عبارتند از "threading"، "eventlet"، "gevent" و "gevent_uwsgi". اگر این آرگومان مشخص نشود، ابتدا "eventlet" امتحان می‌شود، سپس "gevent_uwsgi"، سپس "gevent" و در نهایت "threading". نخستین حالت ناهمگامی که تمام وابستگی‌های آن نصب شده باشد انتخاب خواهد شد.
  • ping_interval -- بازهٔ زمانی برحسب ثانیه که در آن سرور به کلاینت پینگ می‌فرستد. مقدار پیش‌فرض 25 ثانیه است. برای کنترل پیشرفته‌تر، می‌توان یک تاپل دو عنصری تعیین کرد که در آن عدد اول بازهٔ پینگ و عدد دوم یک مهلت اضافه (grace period) اعمال‌شده توسط سرور است.
  • ping_timeout -- مدت زمانی برحسب ثانیه که کلاینت پیش از قطع اتصال، منتظر پاسخ سرور می‌ماند. مقدار پیش‌فرض 20 ثانیه است.
  • max_http_buffer_size -- حداکثر اندازهٔ پذیرفته‌شده برای پیام‌های ورودی. مقدار پیش‌فرض 1,000,000 بایت است. به‌رغم نام آن، مقدار تنظیم‌شده در این آرگومان برای اتصال‌های HTTP long-polling و WebSocket اعمال می‌شود..IP • 2 allow_upgrades -- تعیین اینکه ارتقای انتقال (transport) مجاز باشد یا خیر. مقدار پیش‌فرض True است.
  • http_compression -- تعیین اینکه آیا بسته‌ها هنگام استفاده از انتقال polling فشرده‌سازی شوند یا خیر. مقدار پیش‌فرض True است.
  • compression_threshold -- پیام‌ها تنها زمانی فشرده‌سازی می‌شوند که اندازه بایتی آن‌ها بزرگ‌تر از این مقدار باشد. مقدار پیش‌فرض 1024 بایت است.
  • cookie -- اگر روی یک رشته تنظیم شود، نام کوکی HTTP خواهد بود که سرور حاوی شناسه نشست (session id) کلاینت به کلاینت بازمی‌گرداند. اگر روی یک دیکشنری تنظیم شود، کلید 'name' شامل نام کوکی است و سایر کلیدها مشخصه‌های کوکی را تعریف می‌کنند، که مقدار هر مشخصه می‌تواند یک رشته، یک شیء فراخوانی‌پذیر بدون آرگومان یا یک مقدار بولی باشد. اگر روی None (پیش‌فرض) تنظیم شود، هیچ کوکی‌ای به کلاینت ارسال نمی‌شود.
  • cors_allowed_origins -- مبدا (origin) یا فهرستی از مبداهایی که مجاز به اتصال به این سرور هستند. به‌طور پیش‌فرض تنها همان مبدا (same origin) مجاز است. این آرگومان را روی '*' یا ['*'] تنظیم کنید تا همه مبداها مجاز شوند، یا روی [] قرار دهید تا مدیریت CORS غیرفعال شود.
  • cors_credentials -- تعیین اینکه آیا اطلاعات اعتبارسنجی (کوکی‌ها، احراز هویت) در درخواست‌ها به این سرور مجاز هستند یا خیر. مقدار پیش‌فرض True است.
  • logger -- برای فعال‌سازی ثبت وقایع، روی True تنظیم کنید یا یک شیء ثبت‌کننده (logger) ارسال نمایید. برای غیرفعال‌سازی ثبت وقایع، روی False تنظیم کنید. مقدار پیش‌فرض False است. توجه داشته باشید که خطاهای مهلک حتی زمانی که logger برابر با False باشد نیز ثبت می‌شوند.
  • json -- یک ماژول JSON جایگزین برای کدگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی JSON باید توابع dumps و loads سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این یک تنظیم در سطح فرایند است؛ تمام سرورها و کلاینت‌های نمونه‌سازی‌شده باید از همان ماژول JSON استفاده کنند.
  • async_handlers -- اگر روی True تنظیم شود، گرداننده‌های رویداد پیام در رشته‌های غیرانسدادی اجرا می‌شوند. برای اجرای همگام گرداننده‌ها، روی False تنظیم کنید. مقدار پیش‌فرض True است.
  • monitor_clients -- اگر روی True تنظیم شود، یک وظیفه پس‌زمینه اطمینان حاصل می‌کند که کلاینت‌های غیرفعال بسته شوند. برای غیرفعال‌سازی وظیفه نظارت، آن را روی False قرار دهید (توصیه نمی‌شود). مقدار پیش‌فرض True است.
  • transports -- فهرست انتقال‌های مجاز. انتقال‌های معتبر شامل 'polling' و 'websocket' هستند. پیش‌فرض ['polling', 'websocket'] است.
  • kwargs -- برای توسعه‌های آینده رزرو شده است؛ هرگونه پارامتر اضافی ارائه‌شده به عنوان آرگومان کلیدواژه‌ای، بدون اعلام نادیده گرفته می‌شود.
ارسال یک پیام به یک کلاینت.
پارامترها (Parameters)
  • sid -- شناسه نشست (session id) کلاینت گیرنده.
  • data -- داده‌هایی که باید به کلاینت ارسال شوند. داده می‌تواند از نوع str، bytes، list یا dict باشد. اگر از نوع list یا dict باشد، داده‌ها به صورت JSON سریال‌سازی خواهند شد.
ارسال یک بسته خام (raw packet) به یک کلاینت.
پارامترها (Parameters)
  • sid -- شناسه نشست (session id) کلاینت گیرنده.
  • pkt -- بسته‌ای که باید به کلاینت ارسال شود.
بازگرداندن نشست کاربر برای یک کلاینت.
پارامترها (Parameters)
sid -- شناسه نشست (session id) کلاینت.

مقدار بازگشتی یک دیکشنری است. حفظ تغییرات ایجادشده در این دیکشنری تضمین نمی‌شود، مگر اینکه save_session() فراخوانی شود، یا از مدیر زمینه (context manager) session استفاده گردد.

ذخیره نشست کاربر برای یک کلاینت.
پارامترها (Parameters)
  • sid -- شناسه نشست (session id) کلاینت.
  • session -- دیکشنری نشست.
بازگرداندن نشست کاربر برای یک کلاینت با نحو مدیر زمینه (context manager).
پارامترها (Parameters)
sid -- شناسه نشست (session id) کلاینت.

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

@eio.on('connect')
def on_connect(sid, environ):
    username = authenticate_user(environ)
    if not username:
        return False
    with eio.session(sid) as session:
        session['username'] = username
@eio.on('message')
def on_message(sid, msg):
    with eio.session(sid) as session:
        print('received message from ', session['username'])
قطع اتصال یک کلاینت.
پارامترها (Parameters)
sid -- شناسه نشست (session id) کلاینتی که باید بسته شود. اگر این پارامتر مشخص نشود، تمام کلاینت‌ها بسته می‌شوند.
مدیریت یک درخواست HTTP از طرف کلاینت.

این نقطه ورود برنامه Engine.IO است که از رابط مشابه برنامه WSGI استفاده می‌کند. در کاربرد معمول، این تابع توسط نمونه Middleware <#engineio.Middleware> فراخوانی می‌شود، اما در صورت عدم استفاده از میان‌افزار می‌توان آن را به‌طور مستقیم نیز فراخوانی کرد.

پارامترها (Parameters)
  • environ -- محیط WSGI.
  • start_response -- تابع start_response در WSGI.
این تابع بدنه پاسخ HTTP را برای تحویل به کلاینت به صورت دنباله‌ای از بایت‌ها برمی‌گرداند.
متوقف کردن وظایف پس‌زمینه Socket.IO.

این متد فعالیت‌های پس‌زمینه‌ای را که توسط سرور Socket.IO آغاز شده‌اند متوقف می‌کند. این متد باید پیش از خاموش کردن وب‌سرور فراخوانی شود.

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

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

پارامترها
  • target -- تابع مقصد برای اجرا.
  • args -- آرگومان‌هایی که باید به تابع فرستاده شوند.
  • kwargs -- آرگومان‌های کلیدواژه‌ای که باید به تابع فرستاده شوند.

این تابع شیئی را برمی‌گرداند که نشان‌دهنده وظیفه پس‌زمینه است و می‌توان متد join() را روی آن فراخوانی کرد تا منتظر تکمیل وظیفه بماند.

خوابیدن به میزان زمان درخواستی با استفاده از مدل ناهمگام مناسب.

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

ایجاد یک شیء رویداد با استفاده از مدل ناهمگام مناسب.

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

ایجاد یک شیء صف با استفاده از مدل ناهمگام مناسب.

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

تولید یک شناسه نشست یکتا.
برگرداندن استثنای خالی بودن صف برای مدل ناهمگام مناسب.

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

ثبت یک گرداننده رویداد.
پارامترها
  • event -- نام رویداد. می‌تواند 'connect'، 'message' یا 'disconnect' باشد.
  • handler -- تابعی که باید برای مدیریت رویداد فراخوانی شود. هنگامی که این پارامتر داده نشود، متد به عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند.

نمونه کاربرد:

# as a decorator:
@eio.on('connect')
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)
    eio.send(sid, 'response')
eio.on('message', message_handler)

تابع گرداننده، sid (شناسه نشست) کلاینت را به عنوان آرگومان نخست دریافت می‌کند. گرداننده رویداد 'connect' محیط WSGI را به عنوان آرگومان دوم دریافت کرده و می‌تواند برای رد اتصال، False برگرداند. گرداننده 'message' محموله پیام را به عنوان آرگومان دوم دریافت می‌کند. گرداننده 'disconnect' آرگومان دوم نمی‌پذیرد.

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

دو مقدار ممکن بازگردانده شده توسط این تابع 'polling' و 'websocket' هستند.

پارامترها
sid -- نشست کلاینت.
یک سرور Engine.IO برای asyncio.

این کلاس یک وب‌سرور Engine.IO کاملاً منطبق را با پشتیبانی از روش‌های انتقال websocket و long-polling پیاده‌سازی می‌کند که با چارچوب asyncio در Python 3.5 یا جدیدتر سازگار است.

پارامترها
async_mode -- مدل ناهمگام (asynchronous) مورد استفاده. برای توضیحی از گزینه‌های موجود، بخش Deployment را در مستندات ببینید. حالت‌های ناهمگام معتبر عبارتند از "aiohttp"،‏ "sanic"،‏ "tornado" و "asgi". اگر این آرگومان مشخص نشود، ابتدا "aiohttp"، سپس "sanic"، بعد "tornado" و در نهایت "asgi" آزمایش می‌شوند. نخستین حالت ناهمگامی که تمامی وابستگی‌های آن نصب باشد انتخاب خواهد شد.
  • ping_interval -- بازهٔ زمانی برحسب ثانیه که سرور کلاینت را پینگ می‌کند. مقدار پیش‌فرض ۲۵ ثانیه است. برای کنترل پیشرفته‌تر، می‌توان یک تاپل دو عضوی تعیین کرد که در آن عدد اول بازهٔ پینگ و عدد دوم یک مهلت ارفاقی (grace period) اضافه‌شده توسط سرور است.
  • ping_timeout -- مدت زمانی برحسب ثانیه که کلاینت پیش از قطع اتصال، منتظر پاسخ سرور می‌ماند. مقدار پیش‌فرض ۲۰ ثانیه است.
  • max_http_buffer_size -- حداکثر اندازهٔ مجاز برای پیام‌های ورودی. مقدار پیش‌فرض ۱٬۰۰۰٬۰۰۰ بایت است. علی‌رغم نام آن، مقدار تعیین‌شده در این آرگومان هم برای اتصال‌های HTTP long-polling و هم برای WebSocket اعمال می‌شود.
  • allow_upgrades -- مجاز بودن یا نبودن ارتقای ترابری (transport upgrade).
  • http_compression -- فشرده‌سازی بسته‌ها هنگام استفاده از ترابری polling.
  • compression_threshold -- پیام‌ها تنها زمانی فشرده می‌شوند که اندازهٔ بایتی آن‌ها بزرگ‌تر از این مقدار باشد.
  • cookie -- اگر روی یک رشته تنظیم شود، نام کوکی HTTP خواهد بود که سرور حاوی شناسهٔ نشست (session id) کلاینت به آن بازمی‌گرداند. اگر روی یک دیکشنری تنظیم شود، کلید 'name' حاوی نام کوکی است و سایر کلیدها ویژگی‌های کوکی را تعریف می‌کنند؛ مقدار هر ویژگی می‌تواند یک رشته، یک شیء فراخوانی‌پذیر (callable) بدون آرگومان، یا یک مقدار بولی (boolean) باشد. در صورت تنظیم روی None (پیش‌فرض)، هیچ کوکی‌ای به کلاینت فرستاده نمی‌شود.
  • cors_allowed_origins -- مبدأ (origin) یا فهرستی از مبداهایی که مجاز به اتصال به این سرور هستند. به‌طور پیش‌فرض تنها مبدأ یکسان (same origin) مجاز است. برای مجاز کردن تمامی مبدأها، این آرگومان را روی '*' یا ['*'] تنظیم کنید، یا برای غیرفعال کردن مدیریت CORS، آن را روی [] بگذارید.
  • cors_credentials -- مجاز بودن یا نبودن اطلاعات اعتباری (کوکی‌ها، احراز هویت) در درخواست‌ها به این سرور.
  • logger -- برای فعال‌سازی ثبت وقایع، آن را روی True تنظیم کنید یا یک شیء ثبت وقایع (logger) پاس دهید. برای غیرفعال‌سازی ثبت وقایع، آن را روی False قرار دهید. توجه داشته باشید که خطاهای مهلک حتی زمانی که logger برابر False باشد نیز ثبت می‌شوند.
  • json -- یک ماژول جایگزین JSON برای رمزگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی JSON باید دارای توابع dumps و loads سازگار با نسخه‌های کتابخانهٔ استاندارد باشند. این یک تنظیم در سطح کل فرآیند (process-wide) است؛ تمام سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON یکسان استفاده کنند.
  • async_handlers -- اگر روی True تنظیم شود، گرداننده‌های رویداد پیام در ریسمان‌های (threads) غیرمسدودکننده اجرا می‌شوند. برای اجرای همگام گرداننده‌ها، آن را روی False تنظیم کنید. مقدار پیش‌فرض True است.
  • monitor_clients -- اگر روی True تنظیم شود، یک وظیفه در پس‌زمینه تضمین می‌کند که کلاینت‌های غیرفعال بسته شوند. برای غیرفعال کردن وظیفهٔ پایش (توصیه نمی‌شود)، آن را روی False تنظیم کنید. مقدار پیش‌فرض True است.
  • transports -- فهرست ترابری‌های مجاز. ترابری‌های معتبر شامل 'polling' و 'websocket' هستند. مقدار پیش‌فرض ['polling', 'websocket'] است.
  • kwargs -- برای توسعه‌های آینده رزرو شده است؛ هرگونه پارامتر اضافی ارائه‌شده به‌صورت آرگومان‌های کلیدواژه‌ای نادیده گرفته خواهد شد.
متصل کردن سرور Engine.IO به یک برنامه (application).
ارسال یک پیام به یک کلاینت.
پارامترها (Parameters)
  • sid -- شناسهٔ نشست (session id) کلاینت گیرنده.
  • data -- داده برای ارسال به کلاینت. داده می‌تواند از نوع str،‏ bytes،‏ list یا dict باشد. اگر از نوع list یا dict باشد، داده به‌صورت JSON سریال‌سازی خواهد شد.

نکته: این متد یک هم‌روال (coroutine) است.

ارسال یک بستهٔ خام (raw packet) به یک کلاینت.
پارامترها (Parameters)
  • sid -- شناسهٔ نشست (session id) کلاینت گیرنده.
  • pkt -- بسته‌ای که باید به کلاینت فرستاده شود.

نکته: این متد یک هم‌روال (coroutine) است.

بازگرداندن نشست کاربری برای یک کلاینت.
پارامترها (Parameters)
sid -- شناسهٔ نشست (session id) کلاینت.

مقدار بازگشتی یک دیکشنری است. حفظ تغییرات اعمال‌شده روی این دیکشنری تضمین نمی‌شود. اگر می‌خواهید نشست کاربری را تغییر دهید، در عوض از مدیر زمینهٔ (context manager) session استفاده کنید.

ذخیرهٔ نشست کاربری برای یک کلاینت.
پارامترها (Parameters)
  • sid -- شناسهٔ نشست (session id) کلاینت.
  • session -- دیکشنری نشست.
بازگرداندن نشست کاربری برای یک کلاینت با نحو (syntax) مدیر زمینه (context manager).
پارامترها (Parameters)
sid -- شناسهٔ نشست (session id) کلاینت.

این یک مدیر زمینه (context manager) است که دیکشنری نشست کاربری را برای کلاینت بازمی‌گرداند. هرگونه تغییری که درون بلوک مدیر زمینه در این دیکشنری ایجاد شود، مجدداً در نشست ذخیره خواهد شد. مثال کاربرد:

@eio.on('connect')
def on_connect(sid, environ):
    username = authenticate_user(environ)
    if not username:
        return False
    with eio.session(sid) as session:
        session['username'] = username
@eio.on('message')
def on_message(sid, msg):
    async with eio.session(sid) as session:
        print('received message from ', session['username'])
async disconnect(sid=None) قطع اتصال یک کلاینت.
پارامترها
sid -- شناسه نشست (session id) کلاینت برای بستن اتصال. اگر این پارامتر ارائه نشود، اتصال تمام کلاینت‌ها بسته می‌شود.

نکته: این متد یک کوروتین (coroutine) است.

مدیریت یک درخواست HTTP از طرف کلاینت.

این نقطه ورود برنامه Engine.IO است. این تابع پاسخ HTTP را جهت تحویل به کلاینت بازمی‌گرداند.

نکته: این متد یک کوروتین (coroutine) است.

توقف وظایف پس‌زمینه Socket.IO.

این متد فعالیت‌های پس‌زمینه‌ای را که توسط سرور Socket.IO آغاز شده‌اند متوقف می‌کند. این متد باید پیش از خاموش کردن وب‌سرور فراخوانی شود.

شروع یک وظیفه پس‌زمینه با استفاده از مدل ناهمگام (async) مناسب.

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

پارامترها
  • target -- تابع هدف برای اجرا.
  • args -- آرگومان‌ها برای ارسال به تابع.
  • kwargs -- آرگومان‌های کلیدواژه‌ای برای ارسال به تابع.

مقدار بازگشتی یک شیء asyncio.Task است.

توقف اجرا (خواب) به مدت زمان درخواست‌شده با استفاده از مدل ناهمگام (async) مناسب.

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

نکته: این متد یک کوروتین (coroutine) است.

ایجاد یک شیء صف (queue) با استفاده از مدل ناهمگام (async) مناسب.

این یک تابع کمکی است که برنامه‌ها می‌توانند برای ایجاد یک صف بدون نگرانی از به‌کارگیری فراخوانی صحیح در حالت async انتخاب‌شده از آن استفاده کنند. برای حالت‌های async مبتنی بر asyncio، این متد یک نمونه از asyncio.Queue را برمی‌گرداند.

برگرداندن استثنای خالی بودن صف برای مدل ناهمگام (async) مناسب.

این یک تابع کمکی است که برنامه‌ها می‌توانند برای کار با یک صف بدون نگرانی از به‌کارگیری فراخوانی صحیح در حالت async انتخاب‌شده از آن استفاده کنند. برای حالت‌های async مبتنی بر asyncio، این متد یک نمونه از asyncio.QueueEmpty را برمی‌گرداند.

ایجاد یک شیء رویداد (event) با استفاده از مدل ناهمگام (async) مناسب.

این یک تابع کمکی است که برنامه‌ها می‌توانند برای ایجاد یک رویداد بدون نگرانی از به‌کارگیری فراخوانی صحیح در حالت async انتخاب‌شده از آن استفاده کنند. برای حالت‌های async مبتنی بر asyncio، این متد یک نمونه از asyncio.Event را برمی‌گرداند.

تولید یک شناسه نشست (session id) یکتا.
ثبت یک گرداننده رویداد (event handler).
پارامترها
  • event -- نام رویداد. می‌تواند 'connect'، 'message' یا 'disconnect' باشد.
  • handler -- تابعی که باید برای مدیریت رویداد فراخوانی شود. هنگامی که این پارامتر ارائه نشود، این متد به‌عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند.

نمونه کاربرد:

# as a decorator:
@eio.on('connect')
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)
    eio.send(sid, 'response')
eio.on('message', message_handler)

تابع گرداننده، sid (شناسه نشست) کلاینت را به‌عنوان آرگومان نخست دریافت می‌کند. گرداننده رویداد 'connect' محیط WSGI را به‌عنوان آرگومان دوم دریافت می‌کند و می‌تواند با بازگرداندن False اتصال را رد کند. گرداننده 'message' بار داده پیام را به‌عنوان آرگومان دوم دریافت می‌کند. گرداننده 'disconnect' آرگومان دوم نمی‌پذیرد.

دلیل‌های قطع اتصال.
قطع اتصال آغازشده توسط کلاینت.
پایان مهلت زمانی پینگ (Ping timeout).
قطع اتصال آغازشده توسط سرور.
بسته شدن لایه انتقال (Transport close).
خطای لایه انتقال (Transport error).
برگرداندن نام سازوکار انتقال (transport) استفاده‌شده توسط کلاینت..sp دو مقدار ممکنی که توسط این تابع بازگردانده می‌شوند 'polling' و 'websocket' هستند.
پارامترها
sid -- نشستِ کلاینت.
میان‌افزار برنامه WSGI برای Engine.IO.

این میان‌افزار ترافیک را به یک برنامه Engine.IO هدایت می‌کند. همچنین می‌تواند فهرستی از فایل‌های ایستا را به کلاینت ارائه دهد، یا ترافیک غیرمرتبط HTTP را به یک برنامه WSGI دیگر بازپخش کند.

پارامترها
  • engineio_app -- سرور Engine.IO. باید نمونه‌ای از کلاس engineio.Server باشد.
  • wsgi_app -- برنامه WSGI که سایر ترافیک‌ها را دریافت می‌کند.
  • static_files -- یک دیکشنری شامل قواعد نگاشت فایل‌های ایستا. برای جزئیات درباره این آرگومان مستندات را ببینید.
  • engineio_path -- نقطه پایانی (endpoint) که برنامه Engine.IO باید در آن نصب شود. مقدار پیش‌فرض برای اکثر موارد مناسب است.

مثال استفاده:

import engineio
import eventlet
eio = engineio.Server()
app = engineio.WSGIApp(eio, static_files={
    '/': {'content_type': 'text/html', 'filename': 'index.html'},
    '/index.html': {'content_type': 'text/html',
                    'filename': 'index.html'},
})
eventlet.wsgi.server(eventlet.listen(('', 8000)), app)
میان‌افزار برنامه ASGI برای Engine.IO.

این میان‌افزار ترافیک را به یک برنامه Engine.IO هدایت می‌کند. همچنین می‌تواند فهرستی از فایل‌های ایستا را به کلاینت ارائه دهد، یا ترافیک غیرمرتبط HTTP را به یک برنامه ASGI دیگر بازپخش کند.

پارامترها
  • engineio_server -- سرور Engine.IO. باید نمونه‌ای از کلاس engineio.AsyncServer باشد.
  • static_files -- یک دیکشنری شامل قواعد نگاشت فایل‌های ایستا. برای جزئیات درباره این آرگومان مستندات را ببینید.
  • other_asgi_app -- یک برنامه ASGI جداگانه که تمام ترافیک‌های دیگر را دریافت می‌کند.
  • engineio_path -- نقطه پایانی (endpoint) که برنامه Engine.IO باید در آن نصب شود. مقدار پیش‌فرض برای اکثر موارد مناسب است. با مقدار None، تمام ترافیک ورودی به سرور Engine.IO هدایت می‌شود، با این فرض که مسیریابی در صورت نیاز توسط لایه متفاوتی انجام می‌گیرد. هنگامی که این گزینه روی None تنظیم شود، static_files و other_asgi_app نادیده گرفته می‌شوند.
  • on_startup -- تابعی که هنگام راه‌اندازی برنامه فراخوانی می‌شود؛ می‌تواند یک coroutine باشد
  • on_shutdown -- تابعی که هنگام خاموش شدن برنامه فراخوانی می‌شود؛ می‌تواند یک coroutine باشد

مثال استفاده:

import engineio
import uvicorn
eio = engineio.AsyncServer()
app = engineio.ASGIApp(eio, static_files={
    '/': {'content_type': 'text/html', 'filename': 'index.html'},
    '/index.html': {'content_type': 'text/html',
                    'filename': 'index.html'},
})
uvicorn.run(app, '127.0.0.1', 5000)
بازگرداندن خطای 404 Not Found به کلاینت.
نام این کلاس به WSGIApp تغییر یافته و اکنون منسوخ شده است.
  • نمایه <>
  • نمایه ماژول <>
  • صفحه جستجو <> Miguel Grinberg

2018, Miguel Grinberg

July 18, 2026