مشخصات نقاط ورود

نقاط ورود مکانیسمی برای توزیع نصب شده برای تبلیغ مؤلفه هایی است که برای کشف و استفاده از کد دیگر ارائه می شود. مثلا:

توزیع ها می توانند نقاط ورود Console_scripts را مشخص کنند ، هر کدام به یک تابع مراجعه می کنند. هنگامی که PIP (یا یک کنسول دیگر نصب کننده آگاه آگاه) توزیع را نصب می کند ، برای هر نقطه ورودی یک بسته بندی خط فرمان ایجاد می کند.

برنامه ها می توانند از نقاط ورودی برای بارگذاری افزونه ها استفاده کنند. به عنوان مثال،Pygments (یک ابزار برجسته سازی نحو) می تواند از لکسرها و سبک های اضافی از بسته های نصب شده جداگانه استفاده کند. برای اطلاعات بیشتر در مورد این ، به ایجاد و کشف افزونه ها مراجعه کنید.

فرمت پرونده نقطه ورود در ابتدا ساخته شده است تا بسته های ساخته شده با Setuptools را فراهم کند تا ابرداده نقطه ادغام را ارائه دهند که در زمان اجرا با ImportLib. Metadata خوانده می شود. اکنون به عنوان یک مشخصات قابلیت همکاری PYPA تعریف شده است تا بتواند ابزارهای دیگری به غیر از مجموعه هایی برای انتشار Importlib. metadata ایجاد کند. استراتژی های وضوح).

مدل داده¶

از نظر مفهومی ، یک نقطه ورود توسط سه ویژگی مورد نیاز تعریف می شود:

گروهی که یک نقطه ورود به آن تعلق دارد ، نشان می دهد که چه نوع شیئی را ارائه می دهد. به عنوان مثال ، گروه console_scripts برای نقاط ورود به توابع است که می توانند به عنوان یک دستور استفاده شوند ، در حالی که pygments. styles گروهی برای کلاس هایی است که سبک های pygments را تعریف می کنند. مصرف کننده به طور معمول رابط مورد انتظار را تعریف می کند. برای جلوگیری از درگیری ها ، مصرف کنندگان تعریف یک گروه جدید باید از نام هایی که با نام PYPI متعلق به پروژه مصرف کننده شروع می شوند ، استفاده کنند. وادنام گروه ها باید یک یا چند گروه از حروف ، اعداد و زیربناها باشند که توسط نقاط جدا می شوند (Regex ^\ W+(\. \ w+)*$).

این نام این نقطه ورود را در گروه خود مشخص می کند. معنای دقیق این امر به مصرف کننده است. برای اسکریپت های کنسول ، نام نقطه ورود دستور است که برای راه اندازی آن استفاده می شود. در یک توزیع ، نام های نقطه ورود باید منحصر به فرد باشد. اگر توزیع های مختلف به همین نام ارائه دهند ، مصرف کننده تصمیم می گیرد که چگونه چنین درگیری ها را انجام دهد. این نام ممکن است حاوی هر کاراکتر به جز = باشد ، اما نمی تواند با هر شخصیت WhiteSpace شروع یا پایان یابد ، یا با [شروع شود. برای نقاط ورود جدید ، توصیه می شود فقط از حروف ، اعداد ، زیرکرها ، نقاط و خط ها استفاده کنید (Regex [\ w .-]+).

مرجع شی به یک شی پایتون اشاره می کند. یا به شکل importable. module یا importable. module:object. attr است. هر یک از قسمت هایی که با نقاط و کولون مشخص شده اند یک شناسه معتبر پایتون است. در نظر گرفته شده است که به صورت زیر نگاه شود:

برخی از ابزارها این نوع ارجاع شی به خودی خود را «نقطه ورودی» می‌نامند، به دلیل عدم وجود عبارت بهتر، به‌ویژه زمانی که به تابعی برای راه‌اندازی یک برنامه اشاره می‌کند.

همچنین یک ویژگی اختیاری وجود دارد: موارد اضافی مجموعه‌ای از رشته‌ها هستند که ویژگی‌های اختیاری توزیع را که نقطه ورودی را ارائه می‌کنند، شناسایی می‌کنند. اگر این موارد مشخص شده باشند، نقطه ورودی به وابستگی های آن «اضافی» نیاز دارد. به قسمت فوق داده ارائه می دهد-اضافی (چند کاربرد) مراجعه کنید.

استفاده از وسایل اضافی برای یک نقطه ورودی دیگر توصیه نمی شود. مصرف کنندگان باید از تجزیه آنها از توزیع های موجود حمایت کنند، اما ممکن است آنها را نادیده بگیرند. ابزارهای انتشار جدید نیازی به پشتیبانی از مشخص کردن موارد اضافی ندارند. کارکرد مدیریت اضافات به مدل setuptools برای مدیریت بسته‌های «تخم مرغ» مرتبط بود، اما ابزارهای جدیدتر مانند pip و virtualenv از مدل متفاوتی استفاده می‌کنند.

فرمت فایل¶

نقاط ورودی در فایلی به نام enter_points. txt در فهرست *. dist-info توزیع تعریف شده است. این دایرکتوری است که در PEP 376 برای توزیع های نصب شده و در PEP 427 برای چرخ ها توضیح داده شده است. این فایل از رمزگذاری نویسه UTF-8 استفاده می کند.

محتویات فایل در قالب INI هستند، همانطور که توسط ماژول configparser Python خوانده شده است. با این حال، configparser نام‌ها را به‌طور پیش‌فرض به بزرگی و کوچکی حروف حساس نمی‌داند، در حالی که نام‌های نقطه ورودی به حروف بزرگ و کوچک حساس هستند. یک تجزیه کننده پیکربندی حساس به حروف بزرگ و کوچک می تواند به صورت زیر ساخته شود:

فایل نقاط ورودی همیشه باید از = استفاده کند تا نام ها را از مقادیر مشخص کند (در حالی که configparser استفاده از : ) را نیز مجاز می کند.

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

در یک مقدار، خوانندگان باید فاصله‌ها (شامل چندین فاصله متوالی) را قبل یا بعد از دو نقطه، بین مرجع شی و کروشه سمت چپ، بین نام‌های اضافی و براکت‌ها و دو نقطه که آنها را محدود می‌کنند، و بعد از مربع سمت راست بپذیرند و نادیده بگیرند. براکتنحو برای موارد اضافی به طور رسمی به عنوان بخشی از PEP 508 (به عنوان موارد اضافی) و محدودیت هایی در مقادیر مشخص شده در PEP 685 مشخص شده است. برای ابزارهایی که فایل را می نویسند، توصیه می شود فقط یک فاصله بین مرجع شی و براکت مربع سمت چپ درج کنید.

استفاده برای اسکریپت ها¶

دو گروه از نقاط ورود از اهمیت ویژه ای در بسته بندی برخوردار هستند: Console_Scripts و Gui_Scripts. در هر دو گروه ، پس از نصب بسته ، نام نقطه ورود باید به عنوان یک دستور در یک پوسته سیستم قابل استفاده باشد. مرجع شیء به تابعی اشاره می کند که هنگام اجرای این دستور بدون آرگومان فراخوانی می شود. این تابع ممکن است یک عدد صحیح را به عنوان یک کد خروج فرآیند بازگرداند و بازگشت هیچ کدام معادل بازگشت 0 نیست.

به عنوان مثال ، نقطه ورود mycmd = mymod: اصلی می تواند یک فرمان mycmd را برای راه اندازی یک اسکریپت مانند این ایجاد کند:

تفاوت بین Console_scripts و Gui_Scripts فقط بر سیستم های ویندوز تأثیر می گذارد. Console_scripts در یک کنسول اجرایی پیچیده شده است ، بنابراین به یک کنسول وصل می شوند و می توانند از Sys. stdin ، Sys. Stdout و Sys. stderr برای ورودی و خروجی استفاده کنند. GUI_SCRIPTS در یک GUI اجرا می شود ، بنابراین می توان آنها را بدون کنسول شروع کرد ، اما نمی تواند از جریان های استاندارد استفاده کند ، مگر اینکه کد برنامه آنها را هدایت کند. سایر سیستم عامل ها تفاوت یکسانی ندارند.

انتظار می رود ابزارهای نصب برای هر دو Console_scripts و GUI_SCRIPT در فهرست اسکریپت های طرح نصب تنظیم شوند. آنها مسئول قرار دادن این دایرکتوری در متغیر محیط PATH نیستند که تعیین می کند ابزارهای خط فرمان در کجا یافت می شود.

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