پروتکل سرور را تایپ کنید

پروتکل نوع سرور (TSP) یک پروتکل JSON-RPC برای درخواست از یک سرور نوع برای داده های تجزیه و تحلیل پایتون است. یک نوع سرور حالت تحلیل نوع را برای یک فضای کاری حفظ می کند و به درخواست های نسخه پروتکل، عکس های فوری، مسیرهای جستجوی پایتون، وضوح واردات و پرس و جوهای نوع (انواع محاسبه شده، اعلام شده و مورد انتظار) پاسخ می دهد.

پروتکل از شکل‌ها و قراردادهای داده پروتکل زبان سرور (LSP) استفاده می‌کند، مانند موقعیت و محدوده، و URI‌ها را به‌عنوان رشته‌ها به همان شیوه LSP نشان می‌دهد. روش های TSP از پیشوند typeServer/ استفاده می کنند.

مصنوعات پروتکل در این پوشه تعاریف معتبر هستند:

TSP از رشته های نسخه معنایی برای بررسی سازگاری مشتری/سرور استفاده می کند. در حالی که پروتکل در خط 0.x است، تغییرات جزئی نسخه ممکن است شکسته شود. تغییرات نسخه پچ در همان خط جزئی سازگار با قبل باقی می مانند.

یک کلاینت یک نوع سرور را راه اندازی می کند و با استفاده از انتقالی که سرور پشتیبانی می کند، مانند stdio یا Node IPC، از طریق اتصال اصلی JSON-RPC با آن ارتباط برقرار می کند. هنگام استفاده از stdio، stdout باید برای پیام های پروتکل JSON-RPC رزرو شود.

از یک نوع سرور انتظار می رود که فضای کاری و وضعیت سند کافی برای پاسخ به درخواست های TSP که پشتیبانی می کند را دریافت کند. کلاینت‌ها معمولا از مقداردهی اولیه LSP و همگام‌سازی اسناد برای این حالت استفاده می‌کنند، سپس درخواست‌های typeServer/* را روی همان اتصال JSON-RPC ارسال می‌کنند.

TSP همچنین از اتصالات فقط خواندنی اضافی اختیاری پشتیبانی می کند. اتصال اصلی همچنان اتصال اصلی است و دارای مقداردهی اولیه، وضعیت فضای کاری، همگام‌سازی اسناد، اعلان‌های تغییر وضعیت و کنترل اتصال است. اتصالات اضافی تنها پس از مذاکره مشتری و سرور در هنگام تنظیم اولیه باز می شوند.

حالت اتصال چندگانه یک ویژگی عملکرد اختیاری است. این به یک کلاینت اجازه می‌دهد تا کانال‌های محلی اضافی را برای درخواست‌های TSP فقط خواندنی به همان نوع سرور باز کند، در حالی که اتصال اصلی همچنان مالک وضعیت فضای کاری قابل تغییر است.

کلاینت‌ها باید از حالت چند اتصالی فقط زمانی استفاده کنند که بتوانند از کارهای هم‌زمان فقط خواندنی بهره ببرند، مانند جستارهای نوع با حجم بالا یا کارگران پس‌زمینه که نباید اتصال اصلی JSON-RPC را مسدود کنند. یک سرور همچنان باید در حالت تک اتصال به درستی کار کند. برای صحت پروتکل نباید به پشتیبانی چند اتصالی نیاز باشد.

پشتیبانی چند اتصالی از طریق درخواست اولیه اولیه LSP و پاسخ مورد مذاکره قرار می گیرد. سرویس گیرنده ای که می تواند کانال های TSP اضافی را باز کند، انواع حمل و نقل پشتیبانی شده را تحت capabilities.experimental.typeServerMultiConnection تبلیغ می کند:

سروری که می‌تواند کانال‌های TSP اضافی را ارائه کند، همان شکل قابلیت را در نتیجه اولیه برمی‌گرداند:

حالت اتصال چندگانه تنها زمانی فعال می شود که هر دو طرف typeServerMultiConnection را تبلیغ کنند و دو لیست پشتیبانی شده حمل و نقل حداقل یک حمل و نقل مشترک داشته باشند. اگر هر یک از طرفین قابلیت را حذف کند، یا اگر حمل و نقل مشترک وجود نداشته باشد، جلسه یک اتصال باقی می ماند و کلاینت نباید typeServer/connection را ارسال کند.

نوع حمل و نقل داخلی پشتیبانی شده در حال حاضر برای اتصالات اضافی ipc است. این مذاکره جدا از اتصال اصلی است که می تواند از stdio یا Node IPC استفاده کند.

پس از شروع اولیه و مذاکره انتقال، مشتری با ارسال typeServer/connection در اتصال اصلی، یک کانال اضافی باز می کند:

برای ipc، آرایه args نقطه پایانی یا نقاط پایانی را که سرور باید به آنها متصل شود، مشخص می کند. سرور باید درخواست را تأیید کند، فورا به نقطه پایانی ارائه شده متصل شود و نتیجه را با موفقیت بازگرداند: درست زمانی که درخواست را می‌پذیرد. اگر سرور نتواند کانال را باز کند، باید موفقیت را بازگرداند: false و در صورت مفید بودن برای گزارش ها، پیام کوتاهی را شامل شود.

زمانی که مکانیسم IPC پلتفرم از آن پشتیبانی می‌کند، انتظار می‌رود نقطه پایانی ipc یک جریان JSON-RPC تمام دوبلکس را ارائه دهد. در آن صورت، args حاوی یک رشته نقطه پایانی است:

اگر مکانیسم IPC پلت فرم فقط نقاط پایانی یک طرفه را نشان دهد، args شامل دو رشته نقطه پایانی است. نام نقطه پایانی از دیدگاه نوع سرور است: اولین نقطه پایانی جریان ورودی سرور و نقطه پایانی دوم جریان خروجی سرور است.

کلاینت یک کانال اضافی را با ارسال typeServer/connection روی اتصال اصلی با همان نوع انتقال و هویت نقطه پایانی می بندد:

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

درخواست بسته باید از همان شکل args استفاده کند که کانال را باز کرد: یک نقطه پایانی برای یک جریان IPC تمام دوبلکس، یا همان جفت نقطه پایانی ورودی/خروجی برای یک جریان IPC تقسیم‌شده.

اتصال اصلی مالک تمام ترافیک تغییر وضعیت است. موارد زیر باید فقط در اتصال اصلی باقی بمانند:

اتصالات اضافی فقط TSP و فقط خواندنی هستند. آنها ممکن است برای درخواست هایی استفاده شوند که حالت سرور را تغییر نمی دهند و نتایج آنها برای عکس فوری ارائه شده توسط مشتری معتبر است.

پیام های TSP مجاز در یک اتصال اضافی به نسخه TSP مذاکره شده متصل می شوند. اگر سروری از نسخه TSP پشتیبانی می کند و پشتیبانی چند اتصالی را برای آن جلسه تبلیغ می کند، باید از هر پیام TSP اضافی اتصال تعریف شده برای آن نسخه پشتیبانی کند.

جدول زیر نسخه TSP را فهرست می کند که ابتدا به هر پیام اجازه اتصال اضافی را می دهد:

سرورها باید ترافیک LSP، اعلان‌های تغییر وضعیت، نوع سرور/اتصال و هر پیام TSP را که برای نسخه مذاکره‌شده TSP مجاز نیست، در صورت دریافت اتصال اضافی، رد کنند.

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

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

اگر یک نوع سرور مکان های منبع را در رمزگذاری دیگری ذخیره می کند، باید مکان ها را در مرز پروتکل تبدیل کند. تبدیل نادرست می تواند باعث شود مشتری اطلاعات گره نحوی اشتباه را درخواست کند.

درخواست های نوع پرس و جو (typServer/getComputedType، typeServer/getDeclaredType، typeServer/getExpectedType) یک ساختار منبع را با یک arg که یک گره یا یک اعلان است شناسایی می کند. گره یک URI به اضافه یک محدوده منبع است. یک اعلان توضیح می دهد که یک نماد کجا و چگونه تعریف می شود و یا یک اعلان معمولی است که توسط یک گره AST منبع پشتیبانی می شود، یا یک اعلان ترکیبی است که توسط جستجوگر نوع ایجاد می شود و هیچ گره منبعی ندارد.

InvalidHandle -1 است و نشان دهنده یک دسته نامعتبر یا در دسترس نیست. کلاینت ها و سرورها باید آن را به عنوان یک مقدار نگهبان در نظر بگیرند، نه به عنوان یک شناسه شی معتبر.

نتایج نوع، اشیاء برچسب‌گذاری‌شده با JSON هستند. هر نوع شامل یک تفکیک کننده است که به مشتری می گوید چگونه بقیه شی را تفسیر کند. این پروتکل از انواع داخلی، انواع اعلام شده، توابع، کلاس‌ها، اتحادیه‌ها، ماژول‌ها، متغیرهای نوع، مجموعه‌های اضافه بار، انواع سنتز شده و مراجع نوع پشتیبانی می‌کند.

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

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

پروتکل فعلی عمدا کوچک است. پارامترهای دقیق و اشکال نتیجه در مصنوعات پروتکل تعریف شده است. جدول زیر هر پیام TSP را با جهت و شکل محموله آن فهرست می کند.

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

سه درخواست نوع پرس و جو بر اساس نوع گزارش آنها برای همان گره یا اعلان متفاوت است:

خطاها باید شامل جزئیات پیام کافی برای ورود به سیستم مشتری برای شناسایی درخواست ناموفق باشند، اما نباید اسرار محلی یا حالت فقط اجرا را فاش کنند.

یک سرور نوع سازگار باید این رفتارها را تأیید کند:

آخرین به‌روزرسانی محتوا با Pylance 2026.4.1 هماهنگ شد.