.\" Man page generated from reStructuredText
.\" by the Docutils 0.23 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PYTHON-ENGINEIO" "1" "Jul 18, 2026" "" "python-engineio"
.SH "نام (NAME)"
python-engineio \- مستندات python-engineio
.sp
این پروژه کلاینت و سرور Engine.IO مبتنی بر پایتون را پیاده‌سازی می‌کند که می‌توانند به صورت مستقل یا یکپارچه‌شده با انواع فریم‌ورک‌ها و برنامه‌های کاربردی وب پایتون اجرا شوند.
.SH "شروع به کار (GETTING STARTED)"
.SS "Engine.IO چیست؟ (What is Engine.IO?)"
.sp
پروتکل Engine.IO یک پروتکل انتقال سبک‌وزن است که ارتباط بلادرنگ، دوطرفه و مبتنی بر رویداد را میان کلاینت‌ها (معمولاً، هرچند نه همیشه، مرورگرهای وب) و یک سرور فراهم می‌سازد. پیاده‌سازی‌های رسمی مولفه‌های کلاینت و سرور به زبان JavaScript نوشته شده‌اند. این بسته، پیاده‌سازی‌های پایتون هر دو بخش را در گونه‌های استاندارد و \fBasyncio\fP ارائه می‌دهد.
.sp
پروتکل Engine.IO بسیار ساده است. هنگامی که یک اتصال میان کلاینت و سرور برقرار شد، هر یک از طرفین می‌توانند به طرف مقابل \(dqپیام\(dq ارسال کنند. دستگیره‌های رویداد (Event handlers) ارائه‌شده توسط برنامه‌ها در هر دو سمت، هنگام دریافت پیام یا زمانی که اتصالی برقرار یا قطع می‌شود، فراخوانی می‌گردند.
.SS "مثال‌های کلاینت (Client Examples)"
.sp
مثال زیر یک کلاینت ساده پایتون را نشان می‌دهد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import engineio

eio = engineio.Client()

@eio.on(\(aqconnect\(aq)
def on_connect():
    print(\(aqconnection established\(aq)

@eio.on(\(aqmessage\(aq)
def on_message(data):
    print(\(aqmessage received with \(aq, data)
    eio.send({\(aqresponse\(aq: \(aqmy response\(aq})

@eio.on(\(aqdisconnect\(aq)
def on_disconnect():
    print(\(aqdisconnected from server\(aq)

eio.connect(\(aqhttp://localhost:5000\(aq)
eio.wait()
.EE
.UNINDENT
.UNINDENT
.sp
و در اینجا کلاینت مشابهی که با استفاده از کلاینت رسمی جاوااسکریپت Engine.IO نوشته شده است آورده شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
<script src=\(dq/path/to/engine.io.js\(dq></script>
<script>
    var socket = eio(\(aqhttp://localhost:5000\(aq);
    socket.on(\(aqopen\(aq, function() { console.log(\(aqconnection established\(aq); });
    socket.on(\(aqmessage\(aq, function(data) {
        console.log(\(aqmessage received with \(aq + data);
        socket.send({response: \(aqmy response\(aq});
    });
    socket.on(\(aqclose\(aq, function() { console.log(\(aqdisconnected from server\(aq); });
</script>
.EE
.UNINDENT
.UNINDENT.SS ویژگی‌های کلاینت
.INDENT 0.0
.IP \(bu 2
امکان اتصال به دیگر سرورهای سازگار با Engine.IO علاوه بر سرور موجود در این بسته.
.IP \(bu 2
سازگار با Python 3.6+.
.IP \(bu 2
دو نسخه از کلاینت، یکی برای Python استاندارد و دیگری برای \fBasyncio\fP\&.
.IP \(bu 2
استفاده از یک معماری مبتنی بر رویداد پیاده‌سازی‌شده با دکوراتورها که جزئیات پروتکل را پنهان می‌کند.
.IP \(bu 2
پیاده‌سازی روش‌های انتقال HTTP long\-polling و WebSocket.
.UNINDENT
.SS مثال‌های سرور
.sp
برنامه زیر یک مثال پایه است که از سرور ناهمگام Eventlet استفاده می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import engineio
import eventlet

eio = engineio.Server()
app = engineio.WSGIApp(eio, static_files={
    \(aq/\(aq: {\(aqcontent_type\(aq: \(aqtext/html\(aq, \(aqfilename\(aq: \(aqindex.html\(aq}
})

@eio.on(\(aqconnect\(aq)
def connect(sid, environ):
    print(\(dqconnect \(dq, sid)

@eio.on(\(aqmessage\(aq)
def message(sid, data):
    print(\(dqmessage \(dq, data)
    eio.send(sid, \(aqreply\(aq)

@eio.on(\(aqdisconnect\(aq)
def disconnect(sid):
    print(\(aqdisconnect \(aq, sid)

if __name__ == \(aq__main__\(aq:
    eventlet.wsgi.server(eventlet.listen((\(aq\(aq, 5000)), app)
.EE
.UNINDENT
.UNINDENT
.sp
در زیر برنامه‌ای مشابه آمده است که برای asyncio و وب‌سرور Uvicorn نوشته شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import engineio
import uvicorn

eio = engineio.AsyncServer()
app = engineio.ASGIApp(eio, static_files={
    \(aq/\(aq: {\(aqcontent_type\(aq: \(aqtext/html\(aq, \(aqfilename\(aq: \(aqindex.html\(aq}
})

@eio.on(\(aqconnect\(aq)
def connect(sid, environ):
    print(\(dqconnect \(dq, sid)

@eio.on(\(aqmessage\(aq)
async def message(sid, data):
    print(\(dqmessage \(dq, data)
    await eio.send(sid, \(aqreply\(aq)

@eio.on(\(aqdisconnect\(aq)
def disconnect(sid):
    print(\(aqdisconnect \(aq, sid)

if __name__ == \(aq__main__\(aq:
    uvicorn.run(\(aq127.0.0.1\(aq, 5000)
.EE
.UNINDENT
.UNINDENT.SS "ویژگی‌های سرور (Server Features)"
.INDENT 0.0
.IP \(bu 2
می‌تواند علاوه بر کلاینت موجود در این بسته، کلاینت‌های دیگری که با Engine.IO سازگار هستند را بپذیرد.
.IP \(bu 2
سازگار با Python 3.6+.
.IP \(bu 2
دو نسخه از سرور، یکی برای پایتون استاندارد و دیگری برای \fBasyncio\fP\&.
.IP \(bu 2
پشتیبانی از تعداد زیادی کلاینت حتی روی سخت‌افزارهای معمولی به دلیل ناهمگام (asynchronous) بودن.
.IP \(bu 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://\:gevent\:.org>\&.
.IP \(bu 2
امکان یکپارچه‌سازی با برنامه‌های WSGI نوشته‌شده با چارچوب‌هایی نظیر Flask، Django و غیره.
.IP \(bu 2
امکان یکپارچه‌سازی با برنامه‌های \fBasyncio\fP در aiohttp \%<http://\:aiohttp\:.readthedocs\:.io>،
sanic \%<http://\:sanic\:.readthedocs\:.io> و tornado \%<http://\:www\:.tornadoweb\:.org>\&.
.IP \(bu 2
استفاده از معماری مبتنی بر رویداد (event\-based) پیاده‌سازی‌شده با دکوراتورها که جزئیات پروتکل را پنهان می‌کند.
.IP \(bu 2
پیاده‌سازی لایه‌های انتقال HTTP long\-polling و WebSocket.
.IP \(bu 2
پشتیبانی از مرورگرهای XHR2 و XHR به عنوان کلاینت.
.IP \(bu 2
پشتیبانی از پیام‌های متنی و باینری (دودویی).
.IP \(bu 2
پشتیبانی از فشرده‌سازی HTTP با gzip و deflate.
.IP \(bu 2
پاسخ‌های CORS با قابلیت پیکربندی برای جلوگیری از مشکلات منشأ متقاطع (cross\-origin) با مرورگرها.
.UNINDENT
.SH "کلاینت ENGINE.IO (THE ENGINE.IO CLIENT)"
.sp
این بسته شامل دو کلاینت Engine.IO است:
.INDENT 0.0
.IP \(bu 2
کلاس \fBengineio.Client()\fP \%<#\:engineio\:.Client> کلاینتی سازگار با کتابخانه استاندارد پایتون ایجاد می‌کند.
.IP \(bu 2
کلاس \fBengineio.AsyncClient()\fP \%<#\:engineio\:.AsyncClient> کلاینتی سازگار با بسته \fBasyncio\fP ایجاد می‌کند.
.UNINDENT
.sp
متدهای موجود در هر دو کلاینت یکسان هستند، با این تفاوت که در کلاینت \fBasyncio\fP بیشتر متدها به عنوان کوروتین (coroutine) پیاده‌سازی شده‌اند.
.SS "نصب (Installation)"
.sp
برای نصب کلاینت استاندارد پایتون به همراه وابستگی‌های آن، از دستور زیر استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pip install \(dqpython\-engineio[client]\(dq
.EE
.UNINDENT
.UNINDENT
.sp
اگر در عوض قصد استفاده از کلاینت \fBasyncio\fP را دارید، از این دستور استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pip install \(dqpython\-engineio[asyncio_client]\(dq
.EE
.UNINDENT
.UNINDENT
.SS "ایجاد نمونه کلاینت (Creating a Client Instance)"
.sp
برای ساخت یک نمونه از کلاینت Engine.IO، کافی است نمونه‌ای از کلاس کلاینت مناسب را ایجاد کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import engineio

# standard Python
eio = engineio.Client()

# asyncio
eio = engineio.AsyncClient()
.EE
.UNINDENT
.UNINDENT.SS "تعریف گرداننده‌های رویداد (Defining Event Handlers)"
.sp
برای پاسخ به رویدادهای فعال‌شده توسط اتصال یا سرور، توابع گرداننده رویداد باید با استفاده از دکوراتور \fBon\fP تعریف شوند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqconnect\(aq)
def on_connect():
    print(\(aqI\(aqm connected!\(aq)

@eio.on(\(aqmessage\(aq)
def on_message(data):
    print(\(aqI received a message!\(aq)

@eio.on(\(aqdisconnect\(aq)
def on_disconnect(reason):
    print(\(aqI\(aqm disconnected! reason:\(aq, reason)
.EE
.UNINDENT
.UNINDENT
.sp
برای سرور \fBasyncio\fP، گرداننده‌های رویداد می‌توانند توابعی معمولی مانند بالا باشند، یا همچنین می‌توانند کوروتین باشند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqmessage\(aq)
async def on_message(data):
    print(\(aqI received a message!\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
آرگومان داده‌شده به دکوراتور \fBon\fP، نام رویداد است. رویدادهایی که پشتیبانی می‌شوند عبارتند از \fBconnect\fP، \fBmessage\fP و \fBdisconnect\fP\&.
.sp
آرگومان \fBdata\fP ارسال‌شده به گرداننده رویداد \fB\(aqmessage\(aq\fP حاوی داده‌های ویژه‌ی برنامه است که توسط سرور همراه با رویداد ارائه شده است.
.sp
گرداننده \fBdisconnect\fP برای قطع اتصالات آغازشده از سوی کلاینت، قطع اتصالات آغازشده از سوی سرور، یا قطع اتصالات تصادفی (برای مثال به دلیل اختلالات شبکه) فراخوانی می‌شود. آرگومان ارائه‌شده به این گرداننده، دلیل قطع اتصال را مشخص می‌کند. مثال:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqdisconnect\(aq)
def on_disconnect(reason):
    if reason == eio.reason.CLIENT_DISCONNECT:
        print(\(aqclient disconnection\(aq)
    elif reason == eio.reason.SERVER_DISCONNECT:
        print(\(aqthe server kicked me out\(aq)
    else:
        print(f\(aqdisconnect reason: {reason}\(aq)
.EE
.UNINDENT
.UNINDENT
.SS "اتصال به سرور (Connecting to a Server)"
.sp
اتصال به یک سرور با فراخوانی متد \fBconnect()\fP برقرار می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio.connect(\(aqhttp://localhost:5000\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
در مورد کلاینت \fBasyncio\fP، این متد یک کوروتین است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
await eio.connect(\(aqhttp://localhost:5000\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
پس از اتصال، سرور یک شناسه نشست یکتا به کلاینت اختصاص می‌دهد. برنامه می‌تواند این شناسه را در ویژگی \fBsid\fP بیابد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
print(\(aqmy sid is\(aq, eio.sid)
.EE
.UNINDENT
.UNINDENT.SS "ارسال پیام‌ها (Sending Messages)"
.sp
کلاینت می‌تواند با استفاده از متد \fBsend()\fP پیامی را به سرور ارسال کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio.send({\(aqfoo\(aq: \(aqbar\(aq})
.EE
.UNINDENT
.UNINDENT
.sp
یا در مورد \fBasyncio\fP، به صورت یک کوروتین (coroutine):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
await eio.send({\(aqfoo\(aq: \(aqbar\(aq})
.EE
.UNINDENT
.UNINDENT
.sp
تک‌آرگومان ارائه‌شده به این متد، داده‌ای است که به سرور ارسال می‌شود. این داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBdict\fP یا \fBlist\fP\& باشد. داده‌های گنجانده‌شده درون دیکشنری‌ها و لیست‌ها نیز به همین انواع محدود هستند.
.sp
متد \fBsend()\fP می‌تواند درون یک گردانندهٔ رویداد (event handler) در پاسخ به یک رویداد سرور، یا در هر بخش دیگری از برنامه، از جمله در وظایف پس‌زمینه فراخوانی شود.
.SS "قطع اتصال از سرور (Disconnecting from the Server)"
.sp
کلاینت در هر زمان می‌تواند با فراخوانی متد \fBdisconnect()\fP درخواست قطع اتصال از سرور را داشته باشد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio.disconnect()
.EE
.UNINDENT
.UNINDENT
.sp
برای کلاینت \fBasyncio\fP، این فراخوانی یک کوروتین است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
await eio.disconnect()
.EE
.UNINDENT
.UNINDENT
.SS "مدیریت وظایف پس‌زمینه (Managing Background Tasks)"
.sp
هنگامی که اتصال کلاینت به سرور برقرار می‌شود، چند وظیفهٔ پس‌زمینه (background task) برای زنده نگه داشتن اتصال و رسیدگی به رویدادهای دریافتی ایجاد خواهند شد. برنامه‌ای که روی ریسهٔ اصلی (main thread) اجرا می‌شود برای انجام هر کاری آزاد است، چرا که این امر مانع از عملکرد کلاینت Engine.IO نخواهد شد.
.sp
اگر برنامه در ریسهٔ اصلی کاری برای انجام دادن ندارد و تنها می‌خواهد تا زمان پایان اتصال منتظر بماند، می‌تواند متد \fBwait()\fP را فراخوانی کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio.wait()
.EE
.UNINDENT
.UNINDENT
.sp
یا در نسخهٔ \fBasyncio\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
await eio.wait()
.EE
.UNINDENT
.UNINDENT
.sp
جهت سهولت کار با برنامه، یک تابع کمکی برای آغاز یک وظیفهٔ پس‌زمینهٔ سفارشی ارائه شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
def my_background_task(my_argument)
    # do some background work here!
    pass

eio.start_background_task(my_background_task, 123)
.EE
.UNINDENT
.UNINDENT
.sp
آرگومان‌های پاس‌داده‌شده به این متد، تابع پس‌زمینه و هرگونه آرگومان موضعی (positional) یا کلیدواژه‌ای (keyword) هستند که تابع با آن‌ها فراخوانی می‌شود.
.sp
در اینجا نسخهٔ \fBasyncio\fP آورده شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
async def my_background_task(my_argument)
    # do some background work here!
    pass

eio.start_background_task(my_background_task, 123)
.EE
.UNINDENT
.UNINDENT
.sp
توجه داشته باشید که این تابع یک کوروتین نیست، زیرا منتظر پایان کار تابع پس‌زمینه نمی‌ماند، اما تابع پس‌زمینه خود یک کوروتین است.
.sp
متد \fBsleep()\fP دومین تابع کمکی است که به منظور استفادهٔ برنامه‌های دارای وظایف پس‌زمینهٔ اختصاصی فراهم شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio.sleep(2)
.EE
.UNINDENT
.UNINDENT
.sp
یا برای \fBasyncio\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
await eio.sleep(2)
.EE
.UNINDENT
.UNINDENT
.sp
تنها آرگومان پاس‌داده‌شده به این متد، تعداد ثانیه‌های توقف (sleep) است..SS "اشکال‌زدایی و عیب‌یابی (Debugging and Troubleshooting)"
.sp
برای کمک به شما در اشکال‌زدایی مشکلات، کلاینت را می‌توان به گونه‌ای پیکربندی کرد که لاگ‌ها را در ترمینال خروجی دهد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import engineio

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

# asyncio
eio = engineio.AsyncClient(logger=True)
.EE
.UNINDENT
.UNINDENT
.sp
آرگومان \fBlogger\fP رفتار ثبت لاگ را کنترل می‌کند:
.INDENT 0.0
.IP \(bu 2
\fBTrue\fP: خروجی لاگ را در \fBstderr\fP با سطح \fBINFO\fP فعال می‌کند.
.IP \(bu 2
\fBFalse\fP: خروجی لاگ را در \fBstderr\fP با سطح \fBERROR\fP فعال می‌کند. این مقدار پیش‌فرض است.
.IP \(bu 2
یک نمونه از \fBlogging.Logger\fP: از لاگر ارائه‌شده بدون پیکربندی اضافی استفاده می‌کند.
.UNINDENT
.sp
ثبت لاگ می‌تواند به شناسایی علت مشکلات اتصال، قطع ارتباط‌های غیرمنتظره و سایر مسائل کمک کند.
.SH "سرور ENGINE.IO (THE ENGINE.IO SERVER)"
.sp
این بسته شامل دو سرور Engine.IO است:
.INDENT 0.0
.IP \(bu 2
کلاس \fBengineio.Server()\fP \%<#\:engineio\:.Server> سروری سازگار با کتابخانه استاندارد پایتون ایجاد می‌کند.
.IP \(bu 2
کلاس \fBengineio.AsyncServer()\fP \%<#\:engineio\:.AsyncServer> سروری سازگار با بسته \fBasyncio\fP ایجاد می‌کند.
.UNINDENT
.sp
متدهای موجود در هر دو سرور یکسان هستند، با این تفاوت که در سرور \fBasyncio\fP بیشتر متدها به‌صورت هم‌روال (coroutine) پیاده‌سازی شده‌اند.
.SS "نصب (Installation)"
.sp
برای نصب سرور Engine.IO پایتون از دستور زیر استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
pip install \(dqpython\-engineio\(dq
.EE
.UNINDENT
.UNINDENT
.sp
علاوه بر سرور، باید یک چارچوب یا سرور ناهمگام (asynchronous) را برای استفاده در کنار آن انتخاب کنید. فهرست بسته‌های پشتیبانی‌شده در بخش راهبردهای استقرار (Deployment Strategies) پوشش داده شده است.
.SS "ایجاد یک نمونه از سرور (Creating a Server Instance)"
.sp
یک سرور Engine.IO نمونه‌ای از کلاس \fBengineio.Server\fP \%<#\:engineio\:.Server>\& است. این نمونه می‌تواند با قرار گرفتن در کلاس پوشاننده \fBengineio.WSGIApp\fP \%<#\:engineio\:.WSGIApp> به یک برنامه کاربردی استاندارد WSGI تبدیل شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import engineio

# create a Engine.IO server
eio = engineio.Server()

# wrap with a WSGI application
app = engineio.WSGIApp(eio)
.EE
.UNINDENT
.UNINDENT
.sp
برای سرورهای مبتنی بر asyncio، کلاس \fBengineio.AsyncServer\fP \%<#\:engineio\:.AsyncServer> همان قابلیت را اما در قالبی سازگار با هم‌روال‌ها ارائه می‌دهد. در صورت تمایل، کلاس \fBengineio.ASGIApp\fP \%<#\:engineio\:.ASGIApp> می‌تواند سرور را به یک برنامه کاربردی استاندارد ASGI تبدیل کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# create a Engine.IO server
eio = engineio.AsyncServer()

# wrap with ASGI application
app = engineio.ASGIApp(eio)
.EE
.UNINDENT
.UNINDENT
.sp
این دو کلاس پوشاننده همچنین می‌توانند به عنوان میان‌افزار (middleware) عمل کنند و هر ترافیکی را که برای سرور Engine.IO در نظر گرفته نشده است به برنامه کاربردی دیگری هدایت کنند. این قابلیت به سرورهای Engine.IO اجازه می‌دهد تا به‌راحتی با برنامه‌های کاربردی موجود WSGI یا ASGI ادغام شوند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from wsgi import app  # a Flask, Django, etc. application
app = engineio.WSGIApp(eio, app)
.EE
.UNINDENT
.UNINDENT.SS ارائه فایل‌های استاتیک (Serving Static Files)
.sp
سرور Engine.IO را می‌توان طوری پیکربندی کرد که فایل‌های استاتیک را به کلاینت‌ها ارائه دهد. این قابلیت به‌ویژه برای تحویل فایل‌های HTML، CSS و JavaScript به کلاینت‌ها در زمانی که این بسته بدون یک چارچوب وب همراه استفاده می‌شود، بسیار مفید است.
.sp
فایل‌های استاتیک با یک دیکشنری Python پیکربندی می‌شوند که در آن هر جفت کلید/مقدار یک قاعدهٔ نگاشت فایل استاتیک است. در ساده‌ترین حالت، این دیکشنری یک یا چند نشانی URL فایل استاتیک را به عنوان کلید، و فایل‌های متناظر در سرور را به عنوان مقدار در بر دارد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
static_files = {
    \(aq/\(aq: \(aqlatency.html\(aq,
    \(aq/static/engine.io.js\(aq: \(aqstatic/engine.io.js\(aq,
    \(aq/static/style.css\(aq: \(aqstatic/style.css\(aq,
}
.EE
.UNINDENT
.UNINDENT
.sp
با این پیکربندی نمونه، هنگامی که سرور درخواستی برای \fB/\fP (نشانی URL ریشه) دریافت می‌کند، محتوای فایل \fBlatency.html\fP در دایرکتوری جاری را برمی‌گرداند، و نوع محتوا (content type) را بر اساس پسوند فایل تعیین می‌کند که در این حالت \fBtext/html\fP\& خواهد بود.
.sp
فایل‌های دارای پسوندهای \fB\&.html\fP، \fB\&.css\fP، \fB\&.js\fP، \fB\&.json\fP، \fB\&.jpg\fP، \fB\&.png\fP،
\fB\&.gif\fP و \fB\&.txt\fP به صورت خودکار شناسایی شده و نوع محتوای صحیح به آن‌ها اختصاص می‌یابد. برای فایل‌هایی با سایر پسوندها یا بدون پسوند فایل، نوع محتوای \fBapplication/octet\-stream\fP به عنوان پیش‌فرض استفاده می‌شود.
.sp
در صورت تمایل، می‌توان یک نوع محتوای صریح را برای یک فایل استاتیک به صورت زیر مشخص کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
static_files = {
    \(aq/\(aq: {\(aqfilename\(aq: \(aqlatency.html\(aq, \(aqcontent_type\(aq: \(aqtext/plain\(aq},
}
.EE
.UNINDENT
.UNINDENT
.sp
همچنین می‌توان یک دایرکتوری کامل را در یک قاعدهٔ واحد پیکربندی کرد، به‌گونه‌ای که تمامی فایل‌های موجود در آن به عنوان فایل استاتیک ارائه شوند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
static_files = {
    \(aq/static\(aq: \(aq./public\(aq,
}
.EE
.UNINDENT
.UNINDENT
.sp
در این مثال هر فایلی با نشانی URL که با \fB/static\fP آغاز شود، مستقیماً از پوشهٔ \fBpublic\fP در دایرکتوری جاری ارائه خواهد شد؛ بنابراین برای نمونه، نشانی \fB/static/index.html\fP فایل محلی \fB\&./public/index.html\fP و نشانی \fB/static/css/styles.css\fP فایل محلی \fB\&./public/css/styles.css\fP\& را بازمی‌گرداند.
.sp
اگر یک نشانی URL درخواست شود که به \fB/\fP ختم می‌شود، نام فایل پیش‌فرض \fBindex.html\fP به انتهای آن افزوده می‌شود. در مثال پیشین، یک درخواست برای نشانی \fB/static/\fP فایل محلی \fB\&./public/index.html\fP\& را برمی‌گرداند. نام فایل پیش‌فرض برای ارائه در نشانی‌های ختم‌شده به اسلش را می‌توان در دیکشنری فایل‌های استاتیک با یک کلید خالی مشخص کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
static_files = {
    \(aq/static\(aq: \(aq./public\(aq,
    \(aq\(aq: \(aqimage.gif\(aq,
}
.EE
.UNINDENT
.UNINDENT
.sp
با این پیکربندی، درخواستی برای \fB/static/\fP فایل محلی \fB\&./public/image.gif\fP\& را بازمی‌گرداند. در صورت نیاز می‌توان نوع محتوای غیر استاندارد را نیز تعیین نمود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
static_files = {
    \(aq/static\(aq: \(aq./public\(aq,
    \(aq\(aq: {\(aqfilename\(aq: \(aqimage.gif\(aq, \(aqcontent_type\(aq: \(aqtext/plain\(aq},
}
.EE
.UNINDENT
.UNINDENT
.sp
دیکشنری پیکربندی فایل استاتیک به عنوان آرگومان \fBstatic_files\fP به کلاس‌های \fBengineio.WSGIApp\fP یا \fBengineio.ASGIApp\fP ارسال می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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)
.EE
.UNINDENT
.UNINDENT
.sp
اولویت مسیریابی در این دو کلاس به شرح زیر است:
.INDENT 0.0
.IP \(bu 2
نخست، مسیر نسبت به مسیر Engine.IO بررسی می‌شود.
.IP \(bu 2
سپس، در صورت وجود، مسیر با پیکربندی فایل‌های استاتیک تطبیق داده می‌شود.
.IP \(bu 2
اگر مسیر با مسیر Engine.IO یا هیچ فایل استاتیکی مطابقت نداشت، در صورت پیکربندی، کنترل به برنامهٔ ثانویه واگذار می‌شود، در غیر این صورت خطای 404 برگردانده می‌شود.
.UNINDENT
.sp
نکته: ارائه فایل‌های استاتیک فقط برای اهداف توسعه در نظر گرفته شده است و فاقد قابلیت‌های مهمی مانند حافظهٔ پنهان (caching) است. از آن در محیط عملیاتی (production) استفاده نکنید..SS تعریف گرداننده‌های رویداد (Defining Event Handlers)
.sp
برای پاسخ دادن به رویدادهای برانگیخته‌شده توسط اتصال یا کلاینت، توابع گردانندهٔ رویداد باید با استفاده از دکوراتور \fBon\fP تعریف شوند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqconnect\(aq)
def on_connect(sid):
    print(\(aqA client connected!\(aq)

@eio.on(\(aqmessage\(aq)
def on_message(sid, data):
    print(\(aqI received a message!\(aq)

@eio.on(\(aqdisconnect\(aq)
def on_disconnect(sid, reason):
    print(\(aqClient disconnected! reason:\(aq, reason)
.EE
.UNINDENT
.UNINDENT
.sp
برای سرور \fBasyncio\fP، گرداننده‌های رویداد می‌توانند مانند بالا توابعی عادی، یا هم‌روال (coroutine) باشند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqmessage\(aq)
async def on_message(sid, data):
    print(\(aqI received a message!\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
آرگومان داده‌شده به دکوراتور \fBon\fP نام رویداد است. رویدادهایی که پشتیبانی می‌شوند عبارتند از \fBconnect\fP، \fBmessage\fP و \fBdisconnect\fP\&.
.sp
آرگومان \fBsid\fP که به تمام گرداننده‌های رویداد ارسال می‌شود، یک شناسهٔ اتصال برای کلاینت است. تمام رویدادهای یک کلاینت از همان مقدار \fBsid\fP یکسان استفاده خواهند کرد.
.sp
گردانندهٔ \fBconnect\fP مکانی است که سرور می‌تواند در آن احراز هویت را انجام دهد. مقدار بازگردانده‌شده توسط این گرداننده برای تعیین پذیرش یا رد اتصال به کار می‌رود. هنگامی که گرداننده مقداری بازنمی‌گرداند (که معادل بازگرداندن \fBNone\fP است) یا زمانی که \fBTrue\fP برمی‌گرداند، اتصال پذیرفته می‌شود. اگر گرداننده \fBFalse\fP یا هر نوع دادهٔ سازگار با JSON (رشته، عدد صحیح، فهرست یا دیکشنری) برگرداند، اتصال رد می‌شود. یک اتصال ردشده، پاسخی با کد وضعیت 401 برمی‌انگیزد.
.sp
آرگومان \fBdata\fP که به گردانندهٔ رویداد \fB\(aqmessage\(aq\fP فرستاده می‌شود، شامل داده‌های خاص برنامه است که توسط کلاینت به همراه رویداد ارائه شده است.
.sp
گردانندهٔ \fBdisconnect\fP برای قطع ارتباط‌های آغازشده از سوی کلاینت، قطع ارتباط‌های آغازشده از سوی سرور، یا قطع ارتباط‌های اتفاقی مانند مواردی ناشی از اختلالات شبکه فراخوانی می‌شود. آرگومان دومی که به این گرداننده داده می‌شود، دلیل قطع اتصال را فراهم می‌کند. مثال:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqdisconnect\(aq)
def on_disconnect(sid, reason):
    if reason == eio.reason.CLIENT_DISCONNECT:
        print(\(aqthe client went away\(aq)
    elif reason == eio.reason.SERVER_DISCONNECT:
        print(\(aqthe client was kicked out\(aq)
    else:
        print(f\(aqdisconnect reason: {reason}\(aq)
.EE
.UNINDENT
.UNINDENT
.SS ارسال پیام‌ها (Sending Messages)
.sp
سرور می‌تواند با استفاده از متد \fBsend()\fP به هر کلاینتی پیام ارسال کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio.send(sid, {\(aqfoo\(aq: \(aqbar\(aq})
.EE
.UNINDENT
.UNINDENT
.sp
یا در صورت استفاده از \fBasyncio\fP، به صورت یک هم‌روال:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
await eio.send(sid, {\(aqfoo\(aq: \(aqbar\(aq})
.EE
.UNINDENT
.UNINDENT
.sp
نخستین آرگومان داده‌شده به متد، شناسهٔ اتصال کلاینت دریافت‌کننده است. دومین آرگومان، داده‌ای است که به سرور فرستاده می‌شود. این داده می‌تواند از انواع \fBstr\fP، \fBbytes\fP، \fBdict\fP یا \fBlist\fP باشد\&. داده‌های قرارگرفته درون دیکشنری‌ها و فهرست‌ها نیز به همین انواع محدود هستند.
.sp
متد \fBsend()\fP می‌تواند درون یک گردانندهٔ رویداد به عنوان پاسخی به یک رویداد کلاینت، یا در هر بخش دیگری از برنامه، از جمله در وظایف پس‌زمینه فراخوانی شود..SS نشست‌های کاربر (User Sessions)
.sp
سرور می‌تواند اطلاعات وابسته به برنامه را در یک نشست کاربر اختصاص‌یافته به
هر کلاینت متصل نگهداری کند. برنامه‌های کاربردی می‌توانند از نشست کاربر برای
نوشتن هرگونه جزئیات درباره کاربر که باید در طول عمر اتصال حفظ شوند، مانند
نام‌های کاربری یا شناسه‌های کاربری، استفاده کنند.
.sp
متدهای \fBsave_session()\fP و \fBget_session()\fP برای ذخیره و بازیابی
اطلاعات در نشست کاربر استفاده می‌شوند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqconnect\(aq)
def on_connect(sid, environ):
    username = authenticate_user(environ)
    eio.save_session(sid, {\(aqusername\(aq: username})

@eio.on(\(aqmessage\(aq)
def on_message(sid, data):
    session = eio.get_session(sid)
    print(\(aqmessage from \(aq, session[\(aqusername\(aq])
.EE
.UNINDENT
.UNINDENT
.sp
برای سرور \fBasyncio\fP، این متدها به صورت هم‌روال (coroutine) هستند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqconnect\(aq)
async def on_connect(sid, environ):
    username = authenticate_user(environ)
    await eio.save_session(sid, {\(aqusername\(aq: username})

@eio.on(\(aqmessage\(aq)
async def on_message(sid, data):
    session = await eio.get_session(sid)
    print(\(aqmessage from \(aq, session[\(aqusername\(aq])
.EE
.UNINDENT
.UNINDENT
.sp
نشست را همچنین می‌توان با مدیر بافتار \fIsession()\fP دستکاری کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqconnect\(aq)
def on_connect(sid, environ):
    username = authenticate_user(environ)
    with eio.session(sid) as session:
        session[\(aqusername\(aq] = username

@eio.on(\(aqmessage\(aq)
def on_message(sid, data):
    with eio.session(sid) as session:
        print(\(aqmessage from \(aq, session[\(aqusername\(aq])
.EE
.UNINDENT
.UNINDENT
.sp
برای سرور \fBasyncio\fP، از یک مدیر بافتار ناهمگام استفاده می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqconnect\(aq)
def on_connect(sid, environ):
    username = authenticate_user(environ)
    async with eio.session(sid) as session:
        session[\(aqusername\(aq] = username

@eio.on(\(aqmessage\(aq)
def on_message(sid, data):
    async with eio.session(sid) as session:
        print(\(aqmessage from \(aq, session[\(aqusername\(aq])
.EE
.UNINDENT
.UNINDENT
.sp
نکته: محتویات نشست کاربر با قطع اتصال کلاینت از بین می‌رود..SS قطع اتصال کلاینت (Disconnecting a Client)
.sp
سرور در هر زمان می‌تواند با فراخوانی متد \fBdisconnect()\fP و ارسال مقدار \fBsid\fP اختصاص‌یافته به کلاینت، اتصال آن کلاینت را از سرور قطع کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio.disconnect(sid)
.EE
.UNINDENT
.UNINDENT
.sp
برای کلاینت \fBasyncio\fP این یک کوروتین است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
await eio.disconnect(sid)
.EE
.UNINDENT
.UNINDENT
.SS مدیریت وظایف پس‌زمینه (Managing Background Tasks)
.sp
برای راحتی کار برنامه، یک تابع کمکی برای راه‌اندازی یک وظیفهٔ پس‌زمینهٔ سفارشی ارائه شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
def my_background_task(my_argument)
    # do some background work here!
    pass

eio.start_background_task(my_background_task, 123)
.EE
.UNINDENT
.UNINDENT
.sp
آرگومان‌های ارسال‌شده به این متد عبارت‌اند از تابع پس‌زمینه و هرگونه آرگومان موضعی (positional) یا کلیدواژه‌ای (keyword) که تابع باید با آن‌ها فراخوانی شود.
.sp
در اینجا نسخهٔ \fBasyncio\fP آمده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
async def my_background_task(my_argument)
    # do some background work here!
    pass

eio.start_background_task(my_background_task, 123)
.EE
.UNINDENT
.UNINDENT
.sp
توجه داشته باشید که این تابع خود یک کوروتین نیست، زیرا منتظر به پایان رسیدن تابع پس‌زمینه نمی‌ماند، اما تابع پس‌زمینه یک کوروتین است.
.sp
متد \fBsleep()\fP دومین تابع کمکی است که برای راحتی برنامه‌هایی که با وظایف پس‌زمینهٔ اختصاصی خود کار می‌کنند، ارائه شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio.sleep(2)
.EE
.UNINDENT
.UNINDENT
.sp
یا برای \fBasyncio\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
await eio.sleep(2)
.EE
.UNINDENT
.UNINDENT
.sp
تنها آرگومان ارسال‌شده به متد، تعداد ثانیه‌هایی است که باید در حالت تعلیق (sleep) بماند..SS اشکال‌زدایی و عیب‌یابی
.sp
برای کمک به اشکال‌زدایی مشکلات، سرور را می‌توان طوری پیکربندی کرد که لاگ‌ها را در پایانه نمایش دهد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import engineio

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

# asyncio
eio = engineio.AsyncServer(logger=True)
.EE
.UNINDENT
.UNINDENT
.sp
آرگومان \fBlogger\fP رفتار ثبت وقایع را کنترل می‌کند:
.INDENT 0.0
.IP \(bu 2
\fBTrue\fP: خروجی لاگ به \fBstderr\fP را در سطح \fBINFO\fP فعال می‌کند.
.IP \(bu 2
\fBFalse\fP: خروجی لاگ به \fBstderr\fP را در سطح \fBERROR\fP فعال می‌کند. این مقدار پیش‌فرض است.
.IP \(bu 2
یک نمونه از \fBlogging.Logger\fP: از لاگر ارائه‌شده بدون پیکربندی اضافی استفاده می‌کند.
.UNINDENT
.sp
ثبت وقایع می‌تواند به شناسایی علت مشکلات اتصال، پاسخ‌های ۴۰۰، کارایی نامناسب و سایر ایرادها کمک کند.
.SS راهبردهای استقرار
.sp
بخش‌های زیر راهبردهای گوناگون استقرار را برای سرورهای Engine.IO شرح می‌دهند.
.SS سرورهای Uvicorn، Daphne و سایر سرورهای ASGI
.sp
کلاس \fBengineio.ASGIApp\fP یک برنامه سازگار با ASGI است که می‌تواند ترافیک Engine.IO را به یک نمونه \fBengineio.AsyncServer\fP هدایت کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.AsyncServer(async_mode=\(aqasgi\(aq)
app = engineio.ASGIApp(eio)
.EE
.UNINDENT
.UNINDENT
.sp
در صورت تمایل، کلاس \fBengineio.ASGIApp\fP می‌تواند هر ترافیکی را که مربوط به Engine.IO نیست به یک برنامه ASGI دیگر هدایت کند، که این امر امکان استقرار یک برنامه وب استاندارد ASGI و سرور Engine.IO را در قالب یک بسته واحد فراهم می‌سازد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.AsyncServer(async_mode=\(aqasgi\(aq)
app = engineio.ASGIApp(eio, other_app)
.EE
.UNINDENT
.UNINDENT
.sp
نمونه \fBASGIApp\fP یک نمونه کاملاً منطبق با ASGI است که می‌تواند با یک وب‌سرور سازگار با ASGI مستقر شود.
.SS Aiohttp
.sp
کتابخانه aiohttp \%<http://\:aiohttp\:.readthedocs\:.io> چارچوبی مبتنی بر asyncio با پشتیبانی از HTTP و WebSocket فراهم می‌کند.
.sp
نمونه‌های کلاس \fBengineio.AsyncServer\fP در صورت نصب بودن این کتابخانه، به‌طور خودکار از aiohttp برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریح استفاده از آن، گزینه \fBasync_mode\fP را می‌توان در سازنده مشخص کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.AsyncServer(async_mode=\(aqaiohttp\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
سروری که برای aiohttp پیکربندی شده است باید به یک برنامه موجود ضمیمه شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
app = web.Application()
eio.attach(app)
.EE
.UNINDENT
.UNINDENT
.sp
برنامه aiohttp می‌تواند مسیرهای معمولی را تعریف کند که در کنار سرور Engine.IO هم‌زیستی داشته باشند. یک الگوی رایج، افزودن مسیرهایی است که به برنامه سمت کاربر (کلاینت) و فایل‌های ایستای مرتبط با آن پاسخ می‌دهند.
.sp
سپس برنامه aiohttp به شیوه معمول اجرا می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
if __name__ == \(aq__main__\(aq:
    web.run_app(app)
.EE
.UNINDENT
.UNINDENT.SS Tornado
.sp
ابزار Tornado \%<http://\:www\:.tornadoweb\:.org> یک فریم‌ورک وب با پشتیبانی از HTTP و WebSocket است. به لطف یکپارچگی عمیق آن با asyncio، تنها Tornado نسخهٔ ۵ و جدیدتر پشتیبانی می‌شوند.
.sp
در صورت نصب بودن کتابخانه، نمونه‌های کلاس \fBengineio.AsyncServer\fP به‌طور خودکار از tornado برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریحِ استفاده از آن، گزینهٔ \fBasync_mode\fP می‌تواند در سازنده مشخص شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.AsyncServer(async_mode=\(aqtornado\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
سروری که برای tornado پیکربندی شده است باید شامل یک گردانندهٔ درخواست (request handler) برای Engine.IO باشد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
app = tornado.web.Application(
    [
        (r\(dq/engine.io/\(dq, engineio.get_tornado_handler(eio)),
    ],
    # ... other application options
)
.EE
.UNINDENT
.UNINDENT
.sp
برنامهٔ tornado می‌تواند مسیرهای دیگری را نیز تعریف کند که هم‌زمان با سرور Engine.IO وجود داشته باشند. یک الگوی معمول، افزودن مسیرهایی است که یک برنامهٔ کلاینت و هرگونه فایل ایستای مرتبط را ارائه می‌دهند.
.sp
سپس برنامهٔ tornado به روش معمول اجرا می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
app.listen(port)
tornado.ioloop.IOLoop.current().start()
.EE
.UNINDENT
.UNINDENT
.SS Sanic
.sp
نکته: با توجه به برخی تغییرات ناسازگار با گذشته که در نسخه‌های اخیر Sanic اعمال شده است، در حال حاضر توصیه می‌شود که برنامهٔ Sanic در عوض با یکپارچگی ASGI مستقر شود.
.sp
ابزار Sanic \%<http://\:sanic\:.readthedocs\:.io> یک وب‌سرور ناهمگام بسیار کارآمد برای Python است.
.sp
در صورت نصب بودن فریم‌ورک، نمونه‌های کلاس \fBengineio.AsyncServer\fP به‌طور خودکار از Sanic برای عملیات ناهمگام استفاده خواهند کرد. برای درخواست صریحِ استفاده از آن، گزینهٔ \fBasync_mode\fP می‌تواند در سازنده مشخص شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.AsyncServer(async_mode=\(aqsanic\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
سروری که برای Sanic پیکربندی شده است باید به یک برنامهٔ موجود متصل شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
app = Sanic()
eio.attach(app)
.EE
.UNINDENT
.UNINDENT
.sp
برنامهٔ Sanic می‌تواند مسیرهای معمولی را تعریف کند که هم‌زمان با سرور Engine.IO وجود داشته باشند. یک الگوی معمول، افزودن مسیرهایی به این برنامه است که برنامهٔ کلاینت و فایل‌های ایستای مرتبط را ارائه می‌دهند.
.sp
سپس برنامهٔ Sanic به شیوهٔ معمول اجرا می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
if __name__ == \(aq__main__\(aq:
    app.run()
.EE
.UNINDENT
.UNINDENT
.sp
گزارش شده است که پشتیبانی از CORS ارائه‌شده توسط افزونهٔ sanic\-cors \%<https://\:github\:.com/\:ashleysommer/\:sanic-cors> در Sanic با پشتیبانی خود این بسته از این پروتکل ناسازگار است. برای غیرفعال کردن پشتیبانی CORS در این بسته و واگذاری کامل کنترل به Sanic، سرور را به صورت زیر مقداردهی اولیه کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.AsyncServer(async_mode=\(aqsanic\(aq, cors_allowed_origins=[])
.EE
.UNINDENT
.UNINDENT
.sp
در سمت Sanic، علاوه بر هر پیکربندی دیگری که استفاده می‌کنید، باید تنظیم \fICORS_SUPPORTS_CREDENTIALS\fP را نیز فعال کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
app.config[\(aqCORS_SUPPORTS_CREDENTIALS\(aq] = True
.EE
.UNINDENT
.UNINDENT.SS Eventlet
.sp
کتابخانهٔ Eventlet \%<http://\:eventlet\:.net> یک کتابخانهٔ شبکهٔ همروند با کارایی بالا برای Python 2 و 3 است که از هم‌روال‌ها (coroutines) استفاده می‌کند و امکان نوشتن کد به همان سبکی که در توابع مسدودکنندهٔ کتابخانهٔ استاندارد استفاده می‌شود را فراهم می‌سازد. یک سرور Engine.IO مستقرشده با eventlet به روش‌های انتقال long\-polling و WebSocket دسترسی دارد.
.sp
نمونه‌های کلاس \fBengineio.Server\fP در صورت نصب بودن این کتابخانه، به‌طور خودکار از eventlet برای عملیات‌های ناهمگام استفاده خواهند کرد. برای درخواست صریح استفاده از آن، می‌توان گزینهٔ \fBasync_mode\fP را در سازنده (constructor) مشخص کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.Server(async_mode=\(aqeventlet\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
سروری که برای eventlet پیکربندی شده است، با استفاده از \fBengineio.WSGIApp\fP ارائه‌شده، به عنوان یک برنامهٔ WSGI معمولی مستقر می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
app = engineio.WSGIApp(eio)
import eventlet
eventlet.wsgi.server(eventlet.listen((\(aq\(aq, 8000)), app)
.EE
.UNINDENT
.UNINDENT
.SS Eventlet همراه با Gunicorn
.sp
یک راهکار جایگزین برای اجرای سرور WSGI مبتنی بر eventlet مطابق بالا، استفاده از gunicorn \%<gunicorn\:.org> است؛ یک وب‌سرور با امکانات کامل و به زبان پایتون خالص. دستور راه‌اندازی برنامه تحت gunicorn در زیر آورده شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ gunicorn \-k eventlet \-w 1 module:app
.EE
.UNINDENT
.UNINDENT
.sp
به دلیل محدودیت‌های موجود در الگوریتم متعادل‌سازی بار، gunicorn تنها می‌تواند با یک فرآیند worker استفاده شود، بنابراین گزینهٔ \fB\-w 1\fP الزامی است. توجه داشته باشید که یک worker منفرد eventlet می‌تواند تعداد زیادی کلاینت هم‌روند را مدیریت کند.
.sp
محدودیت دیگر هنگام استفاده از gunicorn این است که روش انتقال WebSocket در دسترس نیست، چرا که این روش انتقال نیازمند الحاقاتی به استاندارد WSGI است.
.sp
نکته: کتابخانهٔ Eventlet تابع \fBmonkey_patch()\fP را ارائه می‌دهد که تمامی توابع مسدودکننده در کتابخانهٔ استاندارد را با نسخه‌های ناهمگام معادل جایگزین می‌کند. در حالی که python\-engineio نیازی به monkey patching ندارد، سایر کتابخانه‌ها از جمله درایورهای پایگاه‌داده احتمالاً به آن نیاز خواهند داشت.
.SS Gevent
.sp
کتابخانهٔ Gevent \%<http://\:gevent\:.org> یکی دیگر از چارچوب‌های ناهمگام بر پایهٔ هم‌روال‌ها است که شباهت زیادی به eventlet دارد. یک سرور Engine.IO مستقرشده با gevent به روش‌های انتقال long\-polling و websocket دسترسی دارد.
.sp
نمونه‌های کلاس \fBengineio.Server\fP در صورت نصب بودن این کتابخانه و عدم نصب eventlet، به‌طور خودکار از gevent برای عملیات‌های ناهمگام استفاده خواهند کرد. برای درخواست صریحِ انتخاب gevent، می‌توان گزینهٔ \fBasync_mode\fP را در سازنده مشخص کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.Server(async_mode=\(aqgevent\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
سروری که برای gevent پیکربندی شده است، با استفاده از \fBengineio.WSGIApp\fP ارائه‌شده، به عنوان یک برنامهٔ WSGI معمولی مستقر می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from gevent import pywsgi
app = engineio.WSGIApp(eio)
pywsgi.WSGIServer((\(aq\(aq, 8000), app).serve_forever()
.EE
.UNINDENT
.UNINDENT.SS Gevent همراه با Gunicorn
.sp
یک جایگزین برای اجرای کارساز WSGI مربوط به gevent همانند بالا، استفاده از
gunicorn \%<https://gunicorn.org> است؛ یک وب‌کارساز تمام‌عیار و پایتون خالص (pure Python).
دستور راه‌اندازی برنامه تحت gunicorn در زیر نشان داده شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ gunicorn \-k gevent \-w 1 module:app
.EE
.UNINDENT
.UNINDENT
.sp
همانند eventlet، به دلیل محدودیت‌های موجود در الگوریتم متعادل‌سازی بار (load balancing) آن،
gunicorn تنها می‌تواند با یک فرایند کارگر (worker process) استفاده شود، بنابراین گزینهٔ \fB\-w 1\fP
الزامی است. توجه داشته باشید که یک کارگر gevent منفرد می‌تواند تعداد زیادی کلاینت
هم‌روند را مدیریت کند.
.sp
نکته: Gevent یک تابع \fBmonkey_patch()\fP ارائه می‌دهد که تمامی توابع مسدودکننده (blocking)
در کتابخانهٔ استاندارد را با نسخه‌های معادل غیرهمگام جایگزین می‌کند. اگرچه
python\-engineio نیازی به monkey patching ندارد، اما سایر کتابخانه‌ها مانند درایورهای
پایگاه‌داده احتمالاً به آن نیاز خواهند داشت.
.SS uWSGI
.sp
هنگام استفاده از کارساز uWSGI در ترکیب با gevent، کارساز Engine.IO می‌تواند از
پشتیبانی بومی WebSocket در uWSGI بهره ببرد.
.sp
نمونه‌های کلاس \fBengineio.Server\fP در صورتی که هر دو gevent و uWSGI نصب بوده و
eventlet نصب نباشد، به‌طور خودکار از این گزینه برای عملیات غیرهمگام استفاده خواهند کرد.
برای درخواست صریح این حالت غیرهمگام، می‌توان گزینهٔ \fBasync_mode\fP را در سازنده
(constructor) مشخص کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# gevent with uWSGI
eio = engineio.Server(async_mode=\(aqgevent_uwsgi\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
توضیح کامل پیکربندی و نحوهٔ استفاده از کارساز uWSGI خارج از محدودهٔ این مستندات است.
کارساز uWSGI بسته‌ای نسبتاً پیچیده است که مجموعهٔ بزرگ و جامعی از گزینه‌ها را ارائه
می‌دهد. این بسته برای در دسترس بودن انتقال WebSocket باید همراه با پشتیبانی از
WebSocket و SSL کامپایل شده باشد. به عنوان مقدمه، دستور زیر یک کارساز uWSGI را
برای مثال \fBlatency.py\fP روی درگاه ۵۰۰۰ اجرا می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ uwsgi \-\-http :5000 \-\-gevent 1000 \-\-http\-websockets \-\-master \-\-wsgi\-file latency.py \-\-callable app
.EE
.UNINDENT
.UNINDENT
.SS ریسمان‌های استاندارد (Standard Threads)
.sp
اگرچه از نظر کارایی با eventlet و gevent قابل مقایسه نیست، اما کارساز Engine.IO را
می‌توان برای کار با وب‌کارسازهای چندریسمانی که از ریسمان‌های استاندارد پایتون استفاده
می‌کنند نیز پیکربندی کرد. این یک راه‌اندازی ایده‌آل برای استفاده با کارسازهای توسعه نظیر
Werkzeug \%<http://werkzeug.pocoo.org>\& است.
.sp
نمونه‌های کلاس \fBengineio.Server\fP در صورتی که هیچ‌یک از eventlet یا gevent نصب
نشده باشند، به‌طور خودکار از حالت ریسمان‌بندی استفاده خواهند کرد. برای درخواست صریح
حالت ریسمان‌بندی، می‌توان گزینهٔ \fBasync_mode\fP را در سازنده مشخص کرد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.Server(async_mode=\(aqthreading\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
کارسازی که برای ریسمان‌بندی پیکربندی شده است، همانند یک برنامهٔ وب معمولی و با
استفاده از هر کارساز چندریسمانی منطبق بر WSGI مستقر می‌شود. مثال زیر یک برنامهٔ
Engine.IO را در ترکیب با یک برنامهٔ وب Flask، با استفاده از کارساز توسعهٔ وب Flask
مبتنی بر Werkzeug مستقر می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
eio = engineio.Server(async_mode=\(aqthreading\(aq)
app = Flask(__name__)
app.wsgi_app = engineio.WSGIApp(eio, app.wsgi_app)

# ... Engine.IO and Flask handler functions ...

if __name__ == \(aq__main__\(aq:
    app.run()
.EE
.UNINDENT
.UNINDENT
.sp
مثال زیر نحوهٔ راه‌اندازی یک برنامهٔ Engine.IO را با استفاده از کلاس کارگر چندریسمانی
Gunicorn نشان می‌دهد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ gunicorn \-w 1 \-\-threads 100 module:app
.EE
.UNINDENT
.UNINDENT
.sp
با پیکربندی فوق، کارساز قادر خواهد بود تا ۱۰۰ کلاینت هم‌روند را مدیریت کند.
.sp
هنگام استفاده از ریسمان‌های استاندارد، WebSocket از طریق بستهٔ
simple\-websocket \%<https://github.com/miguelgrinberg/simple-websocket>
پشتیبانی می‌شود که باید به‌طور جداگانه نصب گردد. این بسته یک کارساز چندریسمانی
WebSocket ارائه می‌دهد که با Werkzeug و کارگر ریسمانی Gunicorn سازگار است.
سایر وب‌کارسازهای چندریسمانی پشتیبانی نمی‌شوند و امکان انتقال از طریق WebSocket را
فعال نخواهند کرد..SS "نکات مقیاس‌پذیری (Scalability Notes)"
.sp
پروتکل Engine.IO یک پروتکل با حفظ وضعیت (stateful) است، که مقیاس‌پذیری افقی را دشوارتر می‌کند. برای استقرار یک کلاستر از فرآیندهای Engine.IO که روی یک یا چند سرور میزبانی می‌شوند، شرایط زیر باید برآورده شوند:
.INDENT 0.0
.IP \(bu 2
هر فرآیند سرور Engine.IO باید قادر باشد چندین درخواست را به‌طور هم‌روند مدیریت کند. این امر الزامی است زیرا کلاینت‌های long\-polling دو درخواست را به‌طور موازی ارسال می‌کنند. فرآیندهای worker که در هر لحظه تنها می‌توانند یک درخواست را مدیریت کنند، پشتیبانی نمی‌شوند.
.IP \(bu 2
توازن‌دهنده بار (load balancer) باید به‌گونه‌ای پیکربندی شود که همیشه درخواست‌های یک کلاینت را به همان فرآیند هدایت کند. توازن‌دهنده‌های بار این ویژگی را \fIsticky sessions\fP یا \fIsession affinity\fP می‌نامند.
.UNINDENT
.SS "کنترل‌های مبدأ متقاطع (Cross\-Origin Controls)"
.sp
به دلایل امنیتی، این سرور به‌طور پیش‌فرض از سیاست مبدأ یکسان (same\-origin policy) پیروی می‌کند. از نظر عملی، این به معنای موارد زیر است:
.INDENT 0.0
.IP \(bu 2
اگر یک درخواست ورودی HTTP یا WebSocket شامل هدر \fBOrigin\fP باشد، این هدر باید با scheme و host مربوط به URL اتصال مطابقت داشته باشد. در صورت عدم تطابق، پاسخی با کد وضعیت 400 بازگردانده شده و اتصال رد می‌شود.
.IP \(bu 2
هیچ محدودیتی بر روی درخواست‌های ورودی که شامل هدر \fBOrigin\fP نیستند اعمال نمی‌شود.
.UNINDENT
.sp
در صورت نیاز، گزینه \fBcors_allowed_origins\fP می‌تواند برای مجاز کردن سایر مبدأها استفاده شود. این آرگومان می‌تواند برابر با یک رشته برای تعیین یک مبدأ مجاز واحد، یا یک لیست برای مجاز کردن چندین مبدأ تنظیم شود. مقدار ویژه \fB\(aq*\(aq\fP می‌تواند برای دستور به سرور جهت مجاز کردن همه مبدأها استفاده شود، اما این کار باید با احتیاط انجام گیرد، زیرا می‌تواند سرور را در برابر حملات جعل درخواست میان‌وب‌گاهی (CSRF) آسیب‌پذیر کند.
.SH "مرجع رابط برنامه‌نویسی (API REFERENCE)"
.INDENT 0.0
.TP
.B class engineio.Client(logger=False, json=None, request_timeout=5, http_session=None, ssl_verify=True, handle_sigint=True, websocket_extra_options=None, timestamp_requests=True)
یک کلاینت Engine.IO.
.sp
این کلاس یک کلاینت وب Engine.IO کاملاً منطبق را با پشتیبانی از روش‌های انتقال websocket و long\-polling پیاده‌سازی می‌کند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBlogger\fP \-\- برای فعال‌سازی ثبت وقایع، روی \fBTrue\fP تنظیم کنید یا یک شیء logger را برای استفاده پاس دهید. برای غیرفعال‌سازی ثبت وقایع، روی \fBFalse\fP تنظیم کنید. مقدار پیش‌فرض \fBFalse\fP است. توجه داشته باشید که خطاهای مهلک حتی زمانی که \fBlogger\fP برابر با \fBFalse\fP باشد نیز ثبت می‌شوند.
.IP \(bu 2
\fBjson\fP \-\- یک ماژول JSON جایگزین جهت استفاده برای کدگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی json باید دارای توابع \fBdumps\fP و \fBloads\fP باشند که با نسخه‌های کتابخانه استاندارد سازگار باشند. این یک تنظیم در سطح کل فرآیند است؛ تمام سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON مشابه استفاده کنند.
.IP \(bu 2
\fBrequest_timeout\fP \-\- مدت‌زمان انتظار (مهلت زمانی) برحسب ثانیه برای درخواست‌ها. مقدار پیش‌فرض 5 ثانیه است.
.IP \(bu 2
\fBhttp_session\fP \-\- یک شیء مقداردهی‌شده از \fBrequests.Session\fP برای استفاده هنگام ارسال درخواست‌ها به سرور. در صورتی که نیاز به افزودن گزینه‌های خاص کلاینت مانند سرورهای پراکسی، گواهی‌های SSL، بسته سفارشی CA و غیره دارید، از آن استفاده کنید.
.IP \(bu 2
\fBssl_verify\fP \-\- مقدار \fBTrue\fP برای اعتبارسنجی گواهی‌های SSL، یا \fBFalse\fP برای صرف‌نظر کردن از اعتبارسنجی گواهی SSL، که امکان اتصال به سرورهای دارای گواهی خودامضا را فراهم می‌کند. پیش‌فرض \fBTrue\fP است.
.IP \(bu 2
\fBhandle_sigint\fP \-\- تنظیم روی \fBTrue\fP برای مدیریت خودکار قطع اتصال در صورت ایجاد وقفه در فرآیند، یا روی \fBFalse\fP برای واگذاری مدیریت وقفه به برنامه فراخواننده. مدیریت وقفه تنها زمانی می‌تواند فعال شود که نمونه کلاینت در ریسه اصلی (main thread) ایجاد شده باشد.
.IP \(bu 2
\fBwebsocket_extra_options\fP \-\- دیکشنری حاوی آرگومان‌های کلیدواژه‌ای اضافی که به \fBwebsocket.create_connection()\fP منتقل می‌شوند.
.IP \(bu 2
\fBtimestamp_requests\fP \-\- اگر \fBTrue\fP باشد، یک برچسب زمانی (timestamp) به عنوان راهکاری برای بی‌اثر کردن حافظه پنهان (cache\-busting) به query string درخواست‌های Socket.IO افزوده می‌شود. برای غیرفعال‌سازی روی \fBFalse\fP تنظیم کنید.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B connect(url, headers=None, transports=None, engineio_path=\(aqengine.io\(aq)
اتصال به یک سرور Engine.IO.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBurl\fP \-\- نشانی اینترنتی (URL) سرور Engine.IO. در صورت نیاز سرور، می‌تواند شامل پارامترهای سفارشی query string باشد.
.IP \(bu 2
\fBheaders\fP \-\- یک دیکشنری حاوی هدرهای سفارشی برای ارسال همراه با درخواست اتصال.
.IP \(bu 2
\fBtransports\fP \-\- فهرست روش‌های انتقال مجاز. مقادیر معتبر \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP هستند. در صورت عدم تعیین، ابتدا انتقال polling متصل شده و سپس برای ارتقا به websocket تلاش می‌شود.
.IP \(bu 2
\fBengineio_path\fP \-\- نقطه پایانی (endpoint) که سرور Engine.IO روی آن نصب شده است. مقدار پیش‌فرض برای بیشتر موارد مناسب است.
.UNINDENT
.UNINDENT
.sp
نمونه استفاده:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
eio = engineio.Client()
eio.connect(\(aqhttp://localhost:5000\(aq)
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B wait()
صبر کردن تا زمانی که اتصال با سرور پایان یابد.
.sp
برنامه‌های کلاینت می‌توانند از این تابع برای مسدود کردن ریسه اصلی در طول مدت اتصال استفاده کنند.
.UNINDENT
.INDENT 7.0
.TP
.B send(data)
ارسال یک پیام به سرور.
.INDENT 7.0
.TP
.B پارامترها
\fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع \fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد. در صورت بودن \fBlist\fP یا \fBdict\fP، داده به‌صورت JSON سریال‌سازی خواهد شد.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B disconnect(abort=False, reason=None)
قطع اتصال از سرور.
.INDENT 7.0
.TP
.B پارامترها
\fBabort\fP \-\- در صورت تنظیم روی \fBTrue\fP، منتظر پایان یافتن وظایف پس‌زمینه مرتبط با اتصال نمی‌ماند.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B start_background_task(target, *args, **kwargs)
شروع یک وظیفه پس‌زمینه.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای شروع یک وظیفه پس‌زمینه از آن استفاده کنند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBtarget\fP \-\- تابع هدف برای اجرا.
.IP \(bu 2
\fBargs\fP \-\- آرگومان‌هایی که باید به تابع ارسال شوند.
.IP \(bu 2
\fBkwargs\fP \-\- آرگومان‌های کلیدواژه‌ای که باید به تابع ارسال شوند.
.UNINDENT
.UNINDENT
.sp
این تابع شیئی را بازمی‌گرداند که نشان‌دهنده وظیفه پس‌زمینه است و می‌توان متد \fBjoin()\fP را روی آن فراخوانی کرد تا منتظر تکمیل وظیفه بماند.
.UNINDENT
.INDENT 7.0.TP
.B sleep(seconds=0)
به میزان زمان درخواست‌شده به خواب می‌رود.
.UNINDENT
.INDENT 7.0
.TP
.B create_queue(*args, **kwargs)
یک شیء صف (queue) ایجاد می‌کند.
.UNINDENT
.INDENT 7.0
.TP
.B get_queue_empty_exception()
استثنای خالی بودن صف ناشی از صف‌های ایجادشده توسط متد
\fBcreate_queue()\fP را برمی‌گرداند.
.UNINDENT
.INDENT 7.0
.TP
.B create_event(*args, **kwargs)
یک شیء رویداد (event) ایجاد می‌کند.
.UNINDENT
.INDENT 7.0
.TP
.B on(event, handler=None)
یک گرداننده رویداد (event handler) ثبت می‌کند.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBevent\fP \-\- نام رویداد. می‌تواند \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP یا
\fB\(aqdisconnect\(aq\fP باشد.
.IP \(bu 2
\fBhandler\fP \-\- تابعی که باید برای مدیریت رویداد فراخوانی شود. هنگامی که این پارامتر
مشخص نشود، این متد به عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند.
.UNINDENT
.UNINDENT
.sp
نمونه کاربرد:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
# as a decorator:
@eio.on(\(aqconnect\(aq)
def connect_handler():
    print(\(aqConnection request\(aq)

# as a method:
def message_handler(msg):
    print(\(aqReceived message: \(aq, msg)
    eio.send(\(aqresponse\(aq)
eio.on(\(aqmessage\(aq, message_handler)
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B class reason
دلایل قطع اتصال.
.INDENT 7.0
.TP
.B CLIENT_DISCONNECT = \(aqclient disconnect\(aq
قطع اتصال به درخواست کلاینت.
.UNINDENT
.INDENT 7.0
.TP
.B SERVER_DISCONNECT = \(aqserver disconnect\(aq
قطع اتصال به درخواست سرور.
.UNINDENT
.INDENT 7.0
.TP
.B TRANSPORT_ERROR = \(aqtransport error\(aq
خطای لایه انتقال (transport).
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B transport()
نام روش انتقال در حال استفاده را برمی‌گرداند.
.sp
مقادیر ممکن بازگردانده شده توسط این تابع \fB\(aqpolling\(aq\fP و
\fB\(aqwebsocket\(aq\fP هستند.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class engineio.AsyncClient(logger=False, json=None, request_timeout=5, http_session=None, ssl_verify=True, handle_sigint=True, websocket_extra_options=None, timestamp_requests=True)
یک کلاینت Engine.IO برای asyncio.
.sp
این کلاس یک وب‌کلاینت کاملاً منطبق با Engine.IO پیاده‌سازی می‌کند که از روش‌های انتقال websocket و long\-polling پشتیبانی کرده و با چارچوب asyncio در Python 3.5 یا جدیدتر سازگار است.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBlogger\fP \-\- برای فعال‌سازی ثبت وقایع روی \fBTrue\fP تنظیم شود یا یک شیء logger برای استفاده ارسال گردد. برای غیرفعال‌سازی ثبت وقایع روی \fBFalse\fP تنظیم شود. مقدار پیش‌فرض
\fBFalse\fP است. توجه داشته باشید که خطاهای مهلک حتی در صورت \fBFalse\fP بودن
\fBlogger\fP نیز ثبت می‌شوند.
.IP \(bu 2
\fBjson\fP \-\- یک ماژول JSON جایگزین برای استفاده در انکود و دکود بسته‌ها. ماژول‌های سفارشی json باید دارای توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانه استاندارد باشند. این یک تنظیم در سطح کل فرآیند (process\-wide) است و همه سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON یکسان استفاده کنند.
.IP \(bu 2
\fBrequest_timeout\fP \-\- مهلت زمانی درخواست‌ها بر حسب ثانیه. مقدار پیش‌فرض
5 ثانیه است.
.IP \(bu 2
\fBhttp_session\fP \-\- یک شیء مقداردهی‌شده از \fBaiohttp.ClientSession\fP برای استفاده هنگام ارسال درخواست‌ها به سرور. در صورتی که نیاز به افزودن گزینه‌های خاص کلاینت مانند سرورهای پروکسی، گواهی‌های SSL، بسته سفارشی CA و غیره دارید از آن استفاده کنید.
.IP \(bu 2
\fBssl_verify\fP \-\- مقدار \fBTrue\fP برای بررسی گواهی‌های SSL، یا \fBFalse\fP برای نادیده گرفتن اعتبارسنجی گواهی SSL و برقراری ارتباط با سرورهای دارای گواهی خودامضا (self\-signed). مقدار پیش‌فرض \fBTrue\fP است.
.IP \(bu 2
\fBhandle_sigint\fP \-\- برای مدیریت خودکار قطع اتصال هنگام وقفه در فرآیند روی \fBTrue\fP تنظیم شود، یا روی \fBFalse\fP قرار گیرد تا مدیریت وقفه به برنامه فراخواننده واگذار گردد. مدیریت وقفه تنها زمانی می‌تواند فعال شود که نمونه کلاینت در ریسه اصلی (main thread) ایجاد شده باشد.
.IP \(bu 2
\fBwebsocket_extra_options\fP \-\- دیکشنری حاوی آرگومان‌های کلیدواژه‌ای اضافی ارسال‌شده به
\fBaiohttp.ws_connect()\fP\&.
.IP \(bu 2
\fBtimestamp_requests\fP \-\- در صورت تنظیم روی \fBTrue\fP یک برچسب زمانی به رشته پرس‌وجوی (query string) درخواست‌های Socket.IO به عنوان روشی برای جلوگیری از کش شدن (cache\-busting) اضافه می‌شود. برای غیرفعال‌سازی روی \fBFalse\fP تنظیم کنید.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B async connect(url, headers=None, transports=None, engineio_path=\(aqengine.io\(aq)
اتصال به یک سرور Engine.IO.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBurl\fP \-\- آدرس اینترنتی (URL) سرور Engine.IO. در صورت نیاز سرور می‌تواند شامل پارامترهای سفارشی رشته پرس‌وجو باشد.
.IP \(bu 2
\fBheaders\fP \-\- دیکشنری حاوی سرآیندهای سفارشی برای ارسال همراه با درخواست اتصال.
.IP \(bu 2
\fBtransports\fP \-\- فهرست روش‌های انتقال مجاز. روش‌های انتقال معتبر عبارتند از \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP\&. در صورت مشخص نشدن، ابتدا انتقال polling متصل می‌شود و سپس برای ارتقا به websocket تلاش می‌گردد.
.IP \(bu 2
\fBengineio_path\fP \-\- نقطه پایانی (endpoint) جایی که سرور Engine.IO نصب شده است. مقدار پیش‌فرض برای بیشتر موارد مناسب است.
.UNINDENT
.UNINDENT
.sp
توجه: این متد یک هم‌روال (coroutine) است.
.sp
نمونه کاربرد:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
eio = engineio.Client()
await eio.connect(\(aqhttp://localhost:5000\(aq)
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B async wait()
تا زمان پایان یافتن اتصال با سرور منتظر می‌ماند..sp
برنامه‌های کلاینت می‌توانند از این تابع برای مسدود کردن نخ اصلی
در طول حیات اتصال استفاده کنند.
.sp
نکته: این متد یک کوروتین است.
.UNINDENT
.INDENT 7.0
.TP
.B async send(data)
ارسال یک پیام به سرور.
.INDENT 7.0
.TP
.B پارامترها
\fBdata\fP \-\- داده برای ارسال به سرور. داده می‌تواند از نوع
\fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد\&. اگر یک \fBlist\fP
یا \fBdict\fP باشد، داده به‌صورت JSON سریال‌سازی خواهد شد.
.UNINDENT
.sp
نکته: این متد یک کوروتین است.
.UNINDENT
.INDENT 7.0
.TP
.B async disconnect(abort=False, reason=None)
قطع اتصال از سرور.
.INDENT 7.0
.TP
.B پارامترها
\fBabort\fP \-\- اگر روی \fBTrue\fP تنظیم شود، منتظر پایان یافتن وظایف
پس‌زمینهٔ مرتبط با اتصال نمی‌ماند.
.UNINDENT
.sp
نکته: این متد یک کوروتین است.
.UNINDENT
.INDENT 7.0
.TP
.B start_background_task(target, *args, **kwargs)
شروع یک وظیفهٔ پس‌زمینه.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای شروع یک
وظیفهٔ پس‌زمینه از آن استفاده کنند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBtarget\fP \-\- تابع هدف برای اجرا.
.IP \(bu 2
\fBargs\fP \-\- آرگومان‌ها برای ارسال به تابع.
.IP \(bu 2
\fBkwargs\fP \-\- آرگومان‌های کلیدواژه‌ای برای ارسال به تابع.
.UNINDENT
.UNINDENT
.sp
مقدار بازگشتی یک شیء \fBasyncio.Task\fP است.
.UNINDENT
.INDENT 7.0
.TP
.B async sleep(seconds=0)
توقف موقت به میزان زمان درخواستی.
.sp
نکته: این متد یک کوروتین است.
.UNINDENT
.INDENT 7.0
.TP
.B create_queue(*args, **kwargs)
ایجاد یک شیء صف.
.UNINDENT
.INDENT 7.0
.TP
.B get_queue_empty_exception()
استثنای خالی بودن صف که توسط صف‌های ساخته‌شده با متد
\fBcreate_queue()\fP برانگیخته می‌شود را بازمی‌گرداند.
.UNINDENT
.INDENT 7.0
.TP
.B create_event()
ایجاد یک شیء رویداد.
.UNINDENT
.INDENT 7.0
.TP
.B on(event, handler=None)
ثبت یک گردانندهٔ رویداد.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBevent\fP \-\- نام رویداد. می‌تواند \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP یا
\fB\(aqdisconnect\(aq\fP باشد\&.
.IP \(bu 2
\fBhandler\fP \-\- تابعی که باید برای رسیدگی به رویداد فراخوانی
شود. اگر این پارامتر مشخص نشود، متد به عنوان یک دکوراتور
برای تابع گرداننده عمل می‌کند.
.UNINDENT
.UNINDENT
.sp
مثال استفاده:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
# as a decorator:
@eio.on(\(aqconnect\(aq)
def connect_handler():
    print(\(aqConnection request\(aq)

# as a method:
def message_handler(msg):
    print(\(aqReceived message: \(aq, msg)
    eio.send(\(aqresponse\(aq)
eio.on(\(aqmessage\(aq, message_handler)
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B class reason
دلایل قطع اتصال.
.INDENT 7.0
.TP
.B CLIENT_DISCONNECT = \(aqclient disconnect\(aq
قطع اتصال آغازشده از سوی کلاینت.
.UNINDENT
.INDENT 7.0
.TP
.B SERVER_DISCONNECT = \(aqserver disconnect\(aq
قطع اتصال آغازشده از سوی سرور.
.UNINDENT
.INDENT 7.0
.TP
.B TRANSPORT_ERROR = \(aqtransport error\(aq
خطای انتقال (transport).
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B transport()
نام لایهٔ انتقال در حال استفاده را بازمی‌گرداند.
.sp
مقدارهای احتمالی بازگردانده‌شده توسط این تابع \fB\(aqpolling\(aq\fP و
\fB\(aqwebsocket\(aq\fP هستند\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class engineio.Server(async_mode=None, ping_interval=25, ping_timeout=20, max_http_buffer_size=1000000, allow_upgrades=True, http_compression=True, compression_threshold=1024, cookie=None, cors_allowed_origins=None, cors_credentials=True, logger=False, json=None, async_handlers=True, monitor_clients=None, transports=None, **kwargs)
یک سرور Engine.IO.
.sp
این کلاس یک وب‌سرور کاملاً سازگار با Engine.IO همراه با پشتیبانی
از روش‌های انتقال websocket و long\-polling را پیاده‌سازی می‌کند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBasync_mode\fP \-\- مدل ناهمگام مورد استفاده. برای شرح
گزینه‌های موجود، بخش Deployment را در مستندات ببینید.
حالت‌های ناهمگام معتبر عبارتند از \(dqthreading\(dq،
\(dqeventlet\(dq، \(dqgevent\(dq و \(dqgevent_uwsgi\(dq. اگر این
آرگومان مشخص نشود، ابتدا \(dqeventlet\(dq امتحان می‌شود، سپس
\(dqgevent_uwsgi\(dq، سپس \(dqgevent\(dq و در نهایت \(dqthreading\(dq.
نخستین حالت ناهمگامی که تمام وابستگی‌های آن نصب شده
باشد انتخاب خواهد شد.
.IP \(bu 2
\fBping_interval\fP \-\- بازهٔ زمانی برحسب ثانیه که در آن سرور به کلاینت
پینگ می‌فرستد. مقدار پیش‌فرض 25 ثانیه است. برای کنترل پیشرفته‌تر،
می‌توان یک تاپل دو عنصری تعیین کرد که در آن عدد اول بازهٔ پینگ
و عدد دوم یک مهلت اضافه (grace period) اعمال‌شده توسط سرور است.
.IP \(bu 2
\fBping_timeout\fP \-\- مدت زمانی برحسب ثانیه که کلاینت پیش از قطع اتصال،
منتظر پاسخ سرور می‌ماند. مقدار پیش‌فرض 20 ثانیه است.
.IP \(bu 2
\fBmax_http_buffer_size\fP \-\- حداکثر اندازهٔ پذیرفته‌شده برای پیام‌های
ورودی. مقدار پیش‌فرض 1,000,000 بایت است. به‌رغم نام آن،
مقدار تنظیم‌شده در این آرگومان برای اتصال‌های HTTP long\-polling
و WebSocket اعمال می‌شود..IP \(bu 2
\fBallow_upgrades\fP \-\- تعیین اینکه ارتقای انتقال (transport) مجاز باشد یا خیر. مقدار
پیش‌فرض \fBTrue\fP است\&.
.IP \(bu 2
\fBhttp_compression\fP \-\- تعیین اینکه آیا بسته‌ها هنگام استفاده از انتقال
polling فشرده‌سازی شوند یا خیر. مقدار پیش‌فرض \fBTrue\fP است\&.
.IP \(bu 2
\fBcompression_threshold\fP \-\- پیام‌ها تنها زمانی فشرده‌سازی می‌شوند که اندازه بایتی آن‌ها
بزرگ‌تر از این مقدار باشد. مقدار پیش‌فرض
1024 بایت است.
.IP \(bu 2
\fBcookie\fP \-\- اگر روی یک رشته تنظیم شود، نام کوکی HTTP خواهد بود که
سرور حاوی شناسه نشست (session id) کلاینت به کلاینت بازمی‌گرداند.
اگر روی یک دیکشنری تنظیم شود، کلید \fB\(aqname\(aq\fP
شامل نام کوکی است و سایر کلیدها مشخصه‌های کوکی را تعریف می‌کنند،
که مقدار هر مشخصه می‌تواند یک رشته، یک شیء فراخوانی‌پذیر بدون آرگومان
یا یک مقدار بولی باشد. اگر روی \fBNone\fP (پیش‌فرض) تنظیم شود،
هیچ کوکی‌ای به کلاینت ارسال نمی‌شود.
.IP \(bu 2
\fBcors_allowed_origins\fP \-\- مبدا (origin) یا فهرستی از مبداهایی که مجاز به
اتصال به این سرور هستند. به‌طور پیش‌فرض تنها همان مبدا (same origin)
مجاز است. این آرگومان را روی
\fB\(aq*\(aq\fP یا \fB[\(aq*\(aq]\fP تنظیم کنید تا همه مبداها مجاز شوند، یا
روی \fB[]\fP قرار دهید تا مدیریت CORS غیرفعال شود.
.IP \(bu 2
\fBcors_credentials\fP \-\- تعیین اینکه آیا اطلاعات اعتبارسنجی (کوکی‌ها، احراز هویت)
در درخواست‌ها به این سرور مجاز هستند یا خیر. مقدار پیش‌فرض
\fBTrue\fP است\&.
.IP \(bu 2
\fBlogger\fP \-\- برای فعال‌سازی ثبت وقایع، روی \fBTrue\fP تنظیم کنید یا یک شیء ثبت‌کننده (logger)
ارسال نمایید. برای غیرفعال‌سازی ثبت وقایع، روی \fBFalse\fP تنظیم کنید\&. مقدار پیش‌فرض
\fBFalse\fP است\&. توجه داشته باشید که خطاهای مهلک حتی زمانی که
\fBlogger\fP برابر با \fBFalse\fP باشد نیز ثبت می‌شوند\&.
.IP \(bu 2
\fBjson\fP \-\- یک ماژول JSON جایگزین برای کدگذاری و رمزگشایی
بسته‌ها. ماژول‌های سفارشی JSON باید توابع \fBdumps\fP و \fBloads\fP
سازگار با نسخه‌های کتابخانه استاندارد داشته باشند. این یک تنظیم در سطح
فرایند است؛ تمام سرورها و کلاینت‌های نمونه‌سازی‌شده باید از همان ماژول JSON استفاده کنند.
.IP \(bu 2
\fBasync_handlers\fP \-\- اگر روی \fBTrue\fP تنظیم شود، گرداننده‌های رویداد پیام در
رشته‌های غیرانسدادی اجرا می‌شوند. برای اجرای همگام گرداننده‌ها،
روی \fBFalse\fP تنظیم کنید\&. مقدار پیش‌فرض \fBTrue\fP است\&.
.IP \(bu 2
\fBmonitor_clients\fP \-\- اگر روی \fBTrue\fP تنظیم شود، یک وظیفه پس‌زمینه اطمینان حاصل
می‌کند که کلاینت‌های غیرفعال بسته شوند. برای غیرفعال‌سازی وظیفه نظارت، آن را
روی \fBFalse\fP قرار دهید (توصیه نمی‌شود). مقدار
پیش‌فرض \fBTrue\fP است\&.
.IP \(bu 2
\fBtransports\fP \-\- فهرست انتقال‌های مجاز. انتقال‌های معتبر
شامل \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP هستند\&. پیش‌فرض
\fB[\(aqpolling\(aq, \(aqwebsocket\(aq]\fP است\&.
.IP \(bu 2
\fBkwargs\fP \-\- برای توسعه‌های آینده رزرو شده است؛ هرگونه پارامتر اضافی
ارائه‌شده به عنوان آرگومان کلیدواژه‌ای، بدون اعلام نادیده گرفته می‌شود.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B send(sid, data)
ارسال یک پیام به یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBsid\fP \-\- شناسه نشست (session id) کلاینت گیرنده.
.IP \(bu 2
\fBdata\fP \-\- داده‌هایی که باید به کلاینت ارسال شوند. داده می‌تواند از نوع
\fBstr\fP، \fBbytes\fP، \fBlist\fP یا \fBdict\fP باشد\&. اگر از نوع \fBlist\fP
یا \fBdict\fP باشد، داده‌ها به صورت JSON سریال‌سازی خواهند شد.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B send_packet(sid, pkt)
ارسال یک بسته خام (raw packet) به یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBsid\fP \-\- شناسه نشست (session id) کلاینت گیرنده.
.IP \(bu 2
\fBpkt\fP \-\- بسته‌ای که باید به کلاینت ارسال شود.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B get_session(sid)
بازگرداندن نشست کاربر برای یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
\fBsid\fP \-\- شناسه نشست (session id) کلاینت.
.UNINDENT
.sp
مقدار بازگشتی یک دیکشنری است. حفظ تغییرات ایجادشده در این
دیکشنری تضمین نمی‌شود، مگر اینکه \fBsave_session()\fP فراخوانی شود، یا از
مدیر زمینه (context manager) \fBsession\fP استفاده گردد.
.UNINDENT
.INDENT 7.0
.TP
.B save_session(sid, session)
ذخیره نشست کاربر برای یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBsid\fP \-\- شناسه نشست (session id) کلاینت.
.IP \(bu 2
\fBsession\fP \-\- دیکشنری نشست.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B session(sid)
بازگرداندن نشست کاربر برای یک کلاینت با نحو مدیر زمینه (context manager).
.INDENT 7.0
.TP
.B پارامترها (Parameters)
\fBsid\fP \-\- شناسه نشست (session id) کلاینت.
.UNINDENT
.sp
این یک مدیر زمینه است که دیکشنری نشست کاربر را برای
کلاینت بازمی‌گرداند. هرگونه تغییری که درون بلوک مدیر زمینه در این
دیکشنری ایجاد شود، در نشست ذخیره خواهد شد. نمونه استفاده:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqconnect\(aq)
def on_connect(sid, environ):
    username = authenticate_user(environ)
    if not username:
        return False
    with eio.session(sid) as session:
        session[\(aqusername\(aq] = username

@eio.on(\(aqmessage\(aq)
def on_message(sid, msg):
    with eio.session(sid) as session:
        print(\(aqreceived message from \(aq, session[\(aqusername\(aq])
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B disconnect(sid=None)
قطع اتصال یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
\fBsid\fP \-\- شناسه نشست (session id) کلاینتی که باید بسته شود. اگر این پارامتر
مشخص نشود، تمام کلاینت‌ها بسته می‌شوند.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B handle_request(environ, start_response)
مدیریت یک درخواست HTTP از طرف کلاینت.
.sp
این نقطه ورود برنامه Engine.IO است که از رابط مشابه برنامه WSGI
استفاده می‌کند. در کاربرد معمول، این تابع توسط نمونه \fBMiddleware\fP \%<#\:engineio\:.Middleware>
فراخوانی می‌شود، اما در صورت عدم استفاده از میان‌افزار می‌توان آن را
به‌طور مستقیم نیز فراخوانی کرد.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBenviron\fP \-\- محیط WSGI.
.IP \(bu 2
\fBstart_response\fP \-\- تابع \fBstart_response\fP در WSGI.
.UNINDENT
.UNINDENT.sp
این تابع بدنه پاسخ HTTP را برای تحویل به کلاینت به صورت دنباله‌ای از بایت‌ها برمی‌گرداند.
.UNINDENT
.INDENT 7.0
.TP
.B shutdown()
متوقف کردن وظایف پس‌زمینه Socket.IO.
.sp
این متد فعالیت‌های پس‌زمینه‌ای را که توسط سرور Socket.IO آغاز شده‌اند متوقف می‌کند. این متد باید پیش از خاموش کردن وب‌سرور فراخوانی شود.
.UNINDENT
.INDENT 7.0
.TP
.B start_background_task(target, *args, **kwargs)
شروع یک وظیفه پس‌زمینه با استفاده از مدل ناهمگام مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند از آن برای شروع یک وظیفه پس‌زمینه با استفاده از روش سازگار با حالت ناهمگام انتخاب‌شده استفاده کنند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBtarget\fP \-\- تابع مقصد برای اجرا.
.IP \(bu 2
\fBargs\fP \-\- آرگومان‌هایی که باید به تابع فرستاده شوند.
.IP \(bu 2
\fBkwargs\fP \-\- آرگومان‌های کلیدواژه‌ای که باید به تابع فرستاده شوند.
.UNINDENT
.UNINDENT
.sp
این تابع شیئی را برمی‌گرداند که نشان‌دهنده وظیفه پس‌زمینه است و می‌توان متد \fBjoin()\fP را روی آن فراخوانی کرد تا منتظر تکمیل وظیفه بماند.
.UNINDENT
.INDENT 7.0
.TP
.B sleep(seconds=0)
خوابیدن به میزان زمان درخواستی با استفاده از مدل ناهمگام مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای به خواب بردن یک وظیفه بدون نگرانی از به‌کارگیری فراخوانی صحیح برای حالت ناهمگام انتخاب‌شده، از آن استفاده کنند.
.UNINDENT
.INDENT 7.0
.TP
.B create_event(*args, **kwargs)
ایجاد یک شیء رویداد با استفاده از مدل ناهمگام مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای ایجاد یک رویداد بدون نگرانی از به‌کارگیری فراخوانی صحیح برای حالت ناهمگام انتخاب‌شده، از آن استفاده کنند.
.UNINDENT
.INDENT 7.0
.TP
.B create_queue(*args, **kwargs)
ایجاد یک شیء صف با استفاده از مدل ناهمگام مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای ایجاد یک صف بدون نگرانی از به‌کارگیری فراخوانی صحیح برای حالت ناهمگام انتخاب‌شده، از آن استفاده کنند.
.UNINDENT
.INDENT 7.0
.TP
.B generate_id()
تولید یک شناسه نشست یکتا.
.UNINDENT
.INDENT 7.0
.TP
.B get_queue_empty_exception()
برگرداندن استثنای خالی بودن صف برای مدل ناهمگام مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای کار با یک صف بدون نگرانی از به‌کارگیری فراخوانی صحیح برای حالت ناهمگام انتخاب‌شده، از آن استفاده کنند.
.UNINDENT
.INDENT 7.0
.TP
.B on(event, handler=None)
ثبت یک گرداننده رویداد.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBevent\fP \-\- نام رویداد. می‌تواند \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP یا
\fB\(aqdisconnect\(aq\fP\& باشد.
.IP \(bu 2
\fBhandler\fP \-\- تابعی که باید برای مدیریت رویداد فراخوانی شود. هنگامی که این پارامتر داده نشود، متد به عنوان یک دکوراتور برای تابع گرداننده عمل می‌کند.
.UNINDENT
.UNINDENT
.sp
نمونه کاربرد:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
# as a decorator:
@eio.on(\(aqconnect\(aq)
def connect_handler(sid, environ):
    print(\(aqConnection request\(aq)
    if environ[\(aqREMOTE_ADDR\(aq] in blacklisted:
        return False  # reject

# as a method:
def message_handler(sid, msg):
    print(\(aqReceived message: \(aq, msg)
    eio.send(sid, \(aqresponse\(aq)
eio.on(\(aqmessage\(aq, message_handler)
.EE
.UNINDENT
.UNINDENT
.sp
تابع گرداننده، \fBsid\fP (شناسه نشست) کلاینت را به عنوان آرگومان نخست دریافت می‌کند. گرداننده رویداد \fB\(aqconnect\(aq\fP محیط WSGI را به عنوان آرگومان دوم دریافت کرده و می‌تواند برای رد اتصال، \fBFalse\fP برگرداند. گرداننده \fB\(aqmessage\(aq\fP محموله پیام را به عنوان آرگومان دوم دریافت می‌کند. گرداننده \fB\(aqdisconnect\(aq\fP آرگومان دوم نمی‌پذیرد.
.UNINDENT
.INDENT 7.0
.TP
.B class reason
دلایل قطع اتصال.
.INDENT 7.0
.TP
.B CLIENT_DISCONNECT = \(aqclient disconnect\(aq
قطع اتصال آغاز شده از سوی کلاینت.
.UNINDENT
.INDENT 7.0
.TP
.B PING_TIMEOUT = \(aqping timeout\(aq
پایان مهلت پینگ.
.UNINDENT
.INDENT 7.0
.TP
.B SERVER_DISCONNECT = \(aqserver disconnect\(aq
قطع اتصال آغاز شده از سوی سرور.
.UNINDENT
.INDENT 7.0
.TP
.B TRANSPORT_CLOSE = \(aqtransport close\(aq
بسته‌شدن لایه انتقال.
.UNINDENT
.INDENT 7.0
.TP
.B TRANSPORT_ERROR = \(aqtransport error\(aq
خطای لایه انتقال.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B transport(sid)
برگرداندن نام روش انتقال استفاده‌شده توسط کلاینت.
.sp
دو مقدار ممکن بازگردانده شده توسط این تابع \fB\(aqpolling\(aq\fP
و \fB\(aqwebsocket\(aq\fP\& هستند.
.INDENT 7.0
.TP
.B پارامترها
\fBsid\fP \-\- نشست کلاینت.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class engineio.AsyncServer(async_mode=None, ping_interval=25, ping_timeout=20, max_http_buffer_size=1000000, allow_upgrades=True, http_compression=True, compression_threshold=1024, cookie=None, cors_allowed_origins=None, cors_credentials=True, logger=False, json=None, async_handlers=True, monitor_clients=None, transports=None, **kwargs)
یک سرور Engine.IO برای asyncio.
.sp
این کلاس یک وب‌سرور Engine.IO کاملاً منطبق را با پشتیبانی از روش‌های انتقال websocket و long\-polling پیاده‌سازی می‌کند که با چارچوب asyncio در Python 3.5 یا جدیدتر سازگار است.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0.IP \(bu 2
\fBasync_mode\fP \-\- مدل ناهمگام (asynchronous) مورد استفاده. برای توضیحی از گزینه‌های موجود، بخش Deployment را در مستندات ببینید. حالت‌های ناهمگام معتبر عبارتند از \(dqaiohttp\(dq،‏ \(dqsanic\(dq،‏ \(dqtornado\(dq و \(dqasgi\(dq. اگر این آرگومان مشخص نشود، ابتدا \(dqaiohttp\(dq، سپس \(dqsanic\(dq، بعد \(dqtornado\(dq و در نهایت \(dqasgi\(dq آزمایش می‌شوند. نخستین حالت ناهمگامی که تمامی وابستگی‌های آن نصب باشد انتخاب خواهد شد.
.IP \(bu 2
\fBping_interval\fP \-\- بازهٔ زمانی برحسب ثانیه که سرور کلاینت را پینگ می‌کند. مقدار پیش‌فرض ۲۵ ثانیه است. برای کنترل پیشرفته‌تر، می‌توان یک تاپل دو عضوی تعیین کرد که در آن عدد اول بازهٔ پینگ و عدد دوم یک مهلت ارفاقی (grace period) اضافه‌شده توسط سرور است.
.IP \(bu 2
\fBping_timeout\fP \-\- مدت زمانی برحسب ثانیه که کلاینت پیش از قطع اتصال، منتظر پاسخ سرور می‌ماند. مقدار پیش‌فرض ۲۰ ثانیه است.
.IP \(bu 2
\fBmax_http_buffer_size\fP \-\- حداکثر اندازهٔ مجاز برای پیام‌های ورودی. مقدار پیش‌فرض ۱٬۰۰۰٬۰۰۰ بایت است. علی‌رغم نام آن، مقدار تعیین‌شده در این آرگومان هم برای اتصال‌های HTTP long\-polling و هم برای WebSocket اعمال می‌شود.
.IP \(bu 2
\fBallow_upgrades\fP \-\- مجاز بودن یا نبودن ارتقای ترابری (transport upgrade).
.IP \(bu 2
\fBhttp_compression\fP \-\- فشرده‌سازی بسته‌ها هنگام استفاده از ترابری polling.
.IP \(bu 2
\fBcompression_threshold\fP \-\- پیام‌ها تنها زمانی فشرده می‌شوند که اندازهٔ بایتی آن‌ها بزرگ‌تر از این مقدار باشد.
.IP \(bu 2
\fBcookie\fP \-\- اگر روی یک رشته تنظیم شود، نام کوکی HTTP خواهد بود که سرور حاوی شناسهٔ نشست (session id) کلاینت به آن بازمی‌گرداند. اگر روی یک دیکشنری تنظیم شود، کلید \fB\(aqname\(aq\fP حاوی نام کوکی است و سایر کلیدها ویژگی‌های کوکی را تعریف می‌کنند؛ مقدار هر ویژگی می‌تواند یک رشته، یک شیء فراخوانی‌پذیر (callable) بدون آرگومان، یا یک مقدار بولی (boolean) باشد. در صورت تنظیم روی \fBNone\fP (پیش‌فرض)، هیچ کوکی‌ای به کلاینت فرستاده نمی‌شود.
.IP \(bu 2
\fBcors_allowed_origins\fP \-\- مبدأ (origin) یا فهرستی از مبداهایی که مجاز به اتصال به این سرور هستند. به‌طور پیش‌فرض تنها مبدأ یکسان (same origin) مجاز است. برای مجاز کردن تمامی مبدأها، این آرگومان را روی \fB\(aq*\(aq\fP یا \fB[\(aq*\(aq]\fP تنظیم کنید، یا برای غیرفعال کردن مدیریت CORS، آن را روی \fB[]\fP بگذارید.
.IP \(bu 2
\fBcors_credentials\fP \-\- مجاز بودن یا نبودن اطلاعات اعتباری (کوکی‌ها، احراز هویت) در درخواست‌ها به این سرور.
.IP \(bu 2
\fBlogger\fP \-\- برای فعال‌سازی ثبت وقایع، آن را روی \fBTrue\fP تنظیم کنید یا یک شیء ثبت وقایع (logger) پاس دهید. برای غیرفعال‌سازی ثبت وقایع، آن را روی \fBFalse\fP قرار دهید\&. توجه داشته باشید که خطاهای مهلک حتی زمانی که \fBlogger\fP برابر \fBFalse\fP باشد نیز ثبت می‌شوند\&.
.IP \(bu 2
\fBjson\fP \-\- یک ماژول جایگزین JSON برای رمزگذاری و رمزگشایی بسته‌ها. ماژول‌های سفارشی JSON باید دارای توابع \fBdumps\fP و \fBloads\fP سازگار با نسخه‌های کتابخانهٔ استاندارد باشند. این یک تنظیم در سطح کل فرآیند (process\-wide) است؛ تمام سرورها و کلاینت‌های نمونه‌سازی‌شده باید از یک ماژول JSON یکسان استفاده کنند.
.IP \(bu 2
\fBasync_handlers\fP \-\- اگر روی \fBTrue\fP تنظیم شود، گرداننده‌های رویداد پیام در ریسمان‌های (threads) غیرمسدودکننده اجرا می‌شوند. برای اجرای همگام گرداننده‌ها، آن را روی \fBFalse\fP تنظیم کنید\&. مقدار پیش‌فرض \fBTrue\fP است\&.
.IP \(bu 2
\fBmonitor_clients\fP \-\- اگر روی \fBTrue\fP تنظیم شود، یک وظیفه در پس‌زمینه تضمین می‌کند که کلاینت‌های غیرفعال بسته شوند. برای غیرفعال کردن وظیفهٔ پایش (توصیه نمی‌شود)، آن را روی \fBFalse\fP تنظیم کنید. مقدار پیش‌فرض \fBTrue\fP است\&.
.IP \(bu 2
\fBtransports\fP \-\- فهرست ترابری‌های مجاز. ترابری‌های معتبر شامل \fB\(aqpolling\(aq\fP و \fB\(aqwebsocket\(aq\fP هستند\&. مقدار پیش‌فرض \fB[\(aqpolling\(aq, \(aqwebsocket\(aq]\fP است\&.
.IP \(bu 2
\fBkwargs\fP \-\- برای توسعه‌های آینده رزرو شده است؛ هرگونه پارامتر اضافی ارائه‌شده به‌صورت آرگومان‌های کلیدواژه‌ای نادیده گرفته خواهد شد.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B attach(app, engineio_path=\(aqengine.io\(aq)
متصل کردن سرور Engine.IO به یک برنامه (application).
.UNINDENT
.INDENT 7.0
.TP
.B async send(sid, data)
ارسال یک پیام به یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBsid\fP \-\- شناسهٔ نشست (session id) کلاینت گیرنده.
.IP \(bu 2
\fBdata\fP \-\- داده برای ارسال به کلاینت. داده می‌تواند از نوع \fBstr\fP،‏ \fBbytes\fP،‏ \fBlist\fP یا \fBdict\fP باشد\&. اگر از نوع \fBlist\fP یا \fBdict\fP باشد، داده به‌صورت JSON سریال‌سازی خواهد شد.
.UNINDENT
.UNINDENT
.sp
نکته: این متد یک هم‌روال (coroutine) است.
.UNINDENT
.INDENT 7.0
.TP
.B async send_packet(sid, pkt)
ارسال یک بستهٔ خام (raw packet) به یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBsid\fP \-\- شناسهٔ نشست (session id) کلاینت گیرنده.
.IP \(bu 2
\fBpkt\fP \-\- بسته‌ای که باید به کلاینت فرستاده شود.
.UNINDENT
.UNINDENT
.sp
نکته: این متد یک هم‌روال (coroutine) است.
.UNINDENT
.INDENT 7.0
.TP
.B async get_session(sid)
بازگرداندن نشست کاربری برای یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
\fBsid\fP \-\- شناسهٔ نشست (session id) کلاینت.
.UNINDENT
.sp
مقدار بازگشتی یک دیکشنری است. حفظ تغییرات اعمال‌شده روی این دیکشنری تضمین نمی‌شود. اگر می‌خواهید نشست کاربری را تغییر دهید، در عوض از مدیر زمینهٔ (context manager) \fBsession\fP استفاده کنید.
.UNINDENT
.INDENT 7.0
.TP
.B async save_session(sid, session)
ذخیرهٔ نشست کاربری برای یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBsid\fP \-\- شناسهٔ نشست (session id) کلاینت.
.IP \(bu 2
\fBsession\fP \-\- دیکشنری نشست.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B session(sid)
بازگرداندن نشست کاربری برای یک کلاینت با نحو (syntax) مدیر زمینه (context manager).
.INDENT 7.0
.TP
.B پارامترها (Parameters)
\fBsid\fP \-\- شناسهٔ نشست (session id) کلاینت.
.UNINDENT
.sp
این یک مدیر زمینه (context manager) است که دیکشنری نشست کاربری را برای کلاینت بازمی‌گرداند. هرگونه تغییری که درون بلوک مدیر زمینه در این دیکشنری ایجاد شود، مجدداً در نشست ذخیره خواهد شد. مثال کاربرد:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
@eio.on(\(aqconnect\(aq)
def on_connect(sid, environ):
    username = authenticate_user(environ)
    if not username:
        return False
    with eio.session(sid) as session:
        session[\(aqusername\(aq] = username

@eio.on(\(aqmessage\(aq)
def on_message(sid, msg):
    async with eio.session(sid) as session:
        print(\(aqreceived message from \(aq, session[\(aqusername\(aq])
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0.TP
.B async disconnect(sid=None)
قطع اتصال یک کلاینت.
.INDENT 7.0
.TP
.B پارامترها
\fBsid\fP \-\- شناسه نشست (session id) کلاینت برای بستن اتصال. اگر این پارامتر
ارائه نشود، اتصال تمام کلاینت‌ها بسته می‌شود.
.UNINDENT
.sp
نکته: این متد یک کوروتین (coroutine) است.
.UNINDENT
.INDENT 7.0
.TP
.B async handle_request(*args, **kwargs)
مدیریت یک درخواست HTTP از طرف کلاینت.
.sp
این نقطه ورود برنامه Engine.IO است. این تابع
پاسخ HTTP را جهت تحویل به کلاینت بازمی‌گرداند.
.sp
نکته: این متد یک کوروتین (coroutine) است.
.UNINDENT
.INDENT 7.0
.TP
.B async shutdown()
توقف وظایف پس‌زمینه Socket.IO.
.sp
این متد فعالیت‌های پس‌زمینه‌ای را که توسط سرور Socket.IO
آغاز شده‌اند متوقف می‌کند. این متد باید پیش از خاموش کردن وب‌سرور فراخوانی شود.
.UNINDENT
.INDENT 7.0
.TP
.B start_background_task(target, *args, **kwargs)
شروع یک وظیفه پس‌زمینه با استفاده از مدل ناهمگام (async) مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای شروع یک
وظیفه پس‌زمینه با روشی سازگار با حالت async انتخاب‌شده
از آن استفاده کنند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBtarget\fP \-\- تابع هدف برای اجرا.
.IP \(bu 2
\fBargs\fP \-\- آرگومان‌ها برای ارسال به تابع.
.IP \(bu 2
\fBkwargs\fP \-\- آرگومان‌های کلیدواژه‌ای برای ارسال به تابع.
.UNINDENT
.UNINDENT
.sp
مقدار بازگشتی یک شیء \fBasyncio.Task\fP است.
.UNINDENT
.INDENT 7.0
.TP
.B async sleep(seconds=0)
توقف اجرا (خواب) به مدت زمان درخواست‌شده با استفاده از مدل ناهمگام (async)
مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند از آن برای به خواب بردن یک وظیفه
بدون نگرانی از به‌کارگیری فراخوانی صحیح برای حالت async
انتخاب‌شده استفاده کنند.
.sp
نکته: این متد یک کوروتین (coroutine) است.
.UNINDENT
.INDENT 7.0
.TP
.B create_queue(*args, **kwargs)
ایجاد یک شیء صف (queue) با استفاده از مدل ناهمگام (async) مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای ایجاد یک صف
بدون نگرانی از به‌کارگیری فراخوانی صحیح در حالت async انتخاب‌شده
از آن استفاده کنند. برای حالت‌های async مبتنی بر asyncio، این متد یک نمونه از
\fBasyncio.Queue\fP\& را برمی‌گرداند.
.UNINDENT
.INDENT 7.0
.TP
.B get_queue_empty_exception()
برگرداندن استثنای خالی بودن صف برای مدل ناهمگام (async) مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای کار با یک
صف بدون نگرانی از به‌کارگیری فراخوانی صحیح در حالت async
انتخاب‌شده از آن استفاده کنند. برای حالت‌های async مبتنی بر asyncio، این متد
یک نمونه از \fBasyncio.QueueEmpty\fP\& را برمی‌گرداند.
.UNINDENT
.INDENT 7.0
.TP
.B create_event(*args, **kwargs)
ایجاد یک شیء رویداد (event) با استفاده از مدل ناهمگام (async) مناسب.
.sp
این یک تابع کمکی است که برنامه‌ها می‌توانند برای ایجاد یک
رویداد بدون نگرانی از به‌کارگیری فراخوانی صحیح در حالت async
انتخاب‌شده از آن استفاده کنند. برای حالت‌های async مبتنی بر asyncio، این متد
یک نمونه از \fBasyncio.Event\fP\& را برمی‌گرداند.
.UNINDENT
.INDENT 7.0
.TP
.B generate_id()
تولید یک شناسه نشست (session id) یکتا.
.UNINDENT
.INDENT 7.0
.TP
.B on(event, handler=None)
ثبت یک گرداننده رویداد (event handler).
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBevent\fP \-\- نام رویداد. می‌تواند \fB\(aqconnect\(aq\fP، \fB\(aqmessage\(aq\fP یا
\fB\(aqdisconnect\(aq\fP باشد.
.IP \(bu 2
\fBhandler\fP \-\- تابعی که باید برای مدیریت رویداد فراخوانی شود.
هنگامی که این پارامتر ارائه نشود، این متد به‌عنوان یک دکوراتور
برای تابع گرداننده عمل می‌کند.
.UNINDENT
.UNINDENT
.sp
نمونه کاربرد:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
# as a decorator:
@eio.on(\(aqconnect\(aq)
def connect_handler(sid, environ):
    print(\(aqConnection request\(aq)
    if environ[\(aqREMOTE_ADDR\(aq] in blacklisted:
        return False  # reject

# as a method:
def message_handler(sid, msg):
    print(\(aqReceived message: \(aq, msg)
    eio.send(sid, \(aqresponse\(aq)
eio.on(\(aqmessage\(aq, message_handler)
.EE
.UNINDENT
.UNINDENT
.sp
تابع گرداننده، \fBsid\fP (شناسه نشست) کلاینت را به‌عنوان
آرگومان نخست دریافت می‌کند. گرداننده رویداد \fB\(aqconnect\(aq\fP محیط
WSGI را به‌عنوان آرگومان دوم دریافت می‌کند و می‌تواند با بازگرداندن \fBFalse\fP
اتصال را رد کند. گرداننده \fB\(aqmessage\(aq\fP بار داده پیام
را به‌عنوان آرگومان دوم دریافت می‌کند. گرداننده \fB\(aqdisconnect\(aq\fP
آرگومان دوم نمی‌پذیرد.
.UNINDENT
.INDENT 7.0
.TP
.B class reason
دلیل‌های قطع اتصال.
.INDENT 7.0
.TP
.B CLIENT_DISCONNECT = \(aqclient disconnect\(aq
قطع اتصال آغازشده توسط کلاینت.
.UNINDENT
.INDENT 7.0
.TP
.B PING_TIMEOUT = \(aqping timeout\(aq
پایان مهلت زمانی پینگ (Ping timeout).
.UNINDENT
.INDENT 7.0
.TP
.B SERVER_DISCONNECT = \(aqserver disconnect\(aq
قطع اتصال آغازشده توسط سرور.
.UNINDENT
.INDENT 7.0
.TP
.B TRANSPORT_CLOSE = \(aqtransport close\(aq
بسته شدن لایه انتقال (Transport close).
.UNINDENT
.INDENT 7.0
.TP
.B TRANSPORT_ERROR = \(aqtransport error\(aq
خطای لایه انتقال (Transport error).
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B transport(sid)
برگرداندن نام سازوکار انتقال (transport) استفاده‌شده توسط کلاینت..sp
دو مقدار ممکنی که توسط این تابع بازگردانده می‌شوند \fB\(aqpolling\(aq\fP
و \fB\(aqwebsocket\(aq\fP هستند\&.
.INDENT 7.0
.TP
.B پارامترها
\fBsid\fP \-\- نشستِ کلاینت.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class engineio.WSGIApp(engineio_app, wsgi_app=None, static_files=None, engineio_path=\(aqengine.io\(aq)
میان‌افزار برنامه WSGI برای Engine.IO.
.sp
این میان‌افزار ترافیک را به یک برنامه Engine.IO هدایت می‌کند. همچنین می‌تواند
فهرستی از فایل‌های ایستا را به کلاینت ارائه دهد، یا ترافیک غیرمرتبط
HTTP را به یک برنامه WSGI دیگر بازپخش کند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBengineio_app\fP \-\- سرور Engine.IO. باید نمونه‌ای از کلاس
\fBengineio.Server\fP باشد.
.IP \(bu 2
\fBwsgi_app\fP \-\- برنامه WSGI که سایر ترافیک‌ها را دریافت می‌کند.
.IP \(bu 2
\fBstatic_files\fP \-\- یک دیکشنری شامل قواعد نگاشت فایل‌های ایستا. برای جزئیات
درباره این آرگومان مستندات را ببینید.
.IP \(bu 2
\fBengineio_path\fP \-\- نقطه پایانی (endpoint) که برنامه Engine.IO باید در آن
نصب شود. مقدار پیش‌فرض برای اکثر موارد مناسب
است.
.UNINDENT
.UNINDENT
.sp
مثال استفاده:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
import engineio
import eventlet

eio = engineio.Server()
app = engineio.WSGIApp(eio, static_files={
    \(aq/\(aq: {\(aqcontent_type\(aq: \(aqtext/html\(aq, \(aqfilename\(aq: \(aqindex.html\(aq},
    \(aq/index.html\(aq: {\(aqcontent_type\(aq: \(aqtext/html\(aq,
                    \(aqfilename\(aq: \(aqindex.html\(aq},
})
eventlet.wsgi.server(eventlet.listen((\(aq\(aq, 8000)), app)
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class engineio.ASGIApp(engineio_server, other_asgi_app=None, static_files=None, engineio_path=\(aqengine.io\(aq, on_startup=None, on_shutdown=None)
میان‌افزار برنامه ASGI برای Engine.IO.
.sp
این میان‌افزار ترافیک را به یک برنامه Engine.IO هدایت می‌کند. همچنین می‌تواند
فهرستی از فایل‌های ایستا را به کلاینت ارائه دهد، یا ترافیک غیرمرتبط
HTTP را به یک برنامه ASGI دیگر بازپخش کند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBengineio_server\fP \-\- سرور Engine.IO. باید نمونه‌ای از کلاس
\fBengineio.AsyncServer\fP باشد.
.IP \(bu 2
\fBstatic_files\fP \-\- یک دیکشنری شامل قواعد نگاشت فایل‌های ایستا. برای جزئیات
درباره این آرگومان مستندات را ببینید.
.IP \(bu 2
\fBother_asgi_app\fP \-\- یک برنامه ASGI جداگانه که تمام ترافیک‌های دیگر را دریافت می‌کند.
.IP \(bu 2
\fBengineio_path\fP \-\- نقطه پایانی (endpoint) که برنامه Engine.IO باید در آن
نصب شود. مقدار پیش‌فرض برای اکثر موارد مناسب است.
با مقدار \fBNone\fP، تمام ترافیک ورودی به سرور Engine.IO هدایت می‌شود،
با این فرض که مسیریابی در صورت نیاز توسط لایه متفاوتی انجام
می‌گیرد. هنگامی که این گزینه روی \fBNone\fP تنظیم شود،
\fBstatic_files\fP و \fBother_asgi_app\fP نادیده گرفته
می‌شوند.
.IP \(bu 2
\fBon_startup\fP \-\- تابعی که هنگام راه‌اندازی برنامه فراخوانی می‌شود؛ می‌تواند
یک coroutine باشد
.IP \(bu 2
\fBon_shutdown\fP \-\- تابعی که هنگام خاموش شدن برنامه فراخوانی می‌شود؛ می‌تواند
یک coroutine باشد
.UNINDENT
.UNINDENT
.sp
مثال استفاده:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
import engineio
import uvicorn

eio = engineio.AsyncServer()
app = engineio.ASGIApp(eio, static_files={
    \(aq/\(aq: {\(aqcontent_type\(aq: \(aqtext/html\(aq, \(aqfilename\(aq: \(aqindex.html\(aq},
    \(aq/index.html\(aq: {\(aqcontent_type\(aq: \(aqtext/html\(aq,
                    \(aqfilename\(aq: \(aqindex.html\(aq},
})
uvicorn.run(app, \(aq127.0.0.1\(aq, 5000)
.EE
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B async not_found(receive, send)
بازگرداندن خطای 404 Not Found به کلاینت.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class engineio.Middleware(engineio_app, wsgi_app=None, engineio_path=\(aqengine.io\(aq)
نام این کلاس به \fBWSGIApp\fP تغییر یافته و اکنون منسوخ شده است.
.UNINDENT
.INDENT 0.0
.IP \(bu 2
نمایه \%<>
.IP \(bu 2
نمایه ماژول \%<>
.IP \(bu 2
صفحه جستجو \%<>
.UNINDENT.SH "نویسنده (AUTHOR)"
Miguel Grinberg
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
2018, Miguel Grinberg
.\" End of generated man page.