پسوندهای مسیر (پرونده‌های .pth)¶

پرونده‌ی name.pth حاوی آیتم‌های اضافی (هر سطر یک مورد) است که به sys.path اضافه می‌شوند. آیتم‌هایی که نام پوشه‌های ناموجود را دارند هرگز به sys.path اضافه نمی‌شوند و هیچ بررسی انجام نمی‌شود که آیا آیتم به یک پوشه اشاره دارد یا یک پرونده. هیچ آیتمی بیش از یک بار به sys.path اضافه نمی‌شود. سطرهای خالی و سطرهایی که با # شروع می‌شوند نادیده گرفته می‌شوند.

به‌منظور سازگاری عقبگرد، سطرهایی که با import (به‌دنبال آن فاصله یا تب) شروع می‌شوند، با exec() اجرا می‌شوند.

نقاط ورودی راه‌اندازی (پرونده‌های .start)¶

یک پرونده‌ی نقطه‌ی شروع راه‌اندازی، پرونده‌ای است که نام آن به شکل name.start است و در یکی از پوشه‌های site-packages که در بالا توضیح داده شد قرار دارد. هر پرونده نقاط شروعی را مشخص می‌کند که باید در طول راه‌اندازی مفسر فراخوانی شوند، و این کار با استفاده از نحو pkg.mod:callable که توسط pkgutil.resolve_name() درک می‌شود، انجام می‌گیرد.

هر سطر غیرخالی که با # شروع نمی‌شود باید شامل یک ارجاع نقطه‌ی ورود به شکل pkg.mod:callable باشد. دو نقطه و بخش فراخوانی‌پذیر الزامی هستند. هر فراخوانی‌پذیر بدون هیچ آرگومان فراخوانی می‌شود و هر مقدار بازگشتی دور انداخته می‌شود.

پرونده‌های .start پس از اعمال تمام پسوندهای مسیر .pth روی sys.path پردازش می‌شوند و تضمین می‌کنند که مسیرها پیش از اجرای هرگونه کد راه‌اندازی در دسترس هستند.

برخلاف پسوندهای sys.path از پرونده‌های .pth، نقاط ورودی تکراری حذف‌تکرار نمی‌شوند — اگر یک نقطه‌ی ورودی بیش از یک بار ظاهر شود، بیش از یک بار فراخوانی خواهد شد.

اگر استثنایی در طول حل یا فراخوانی یک نقطه‌ی ورود رخ دهد، یک ردگیری در sys.stderr چاپ می‌شود و پردازش با نقاط ورود باقی‌مانده ادامه می‌یابد.

پرونده‌های .start باید با کدگذاری UTF-8 رمزگذاری شوند.

PEP 829 مشخصات اصلی این ویژگی‌ها را تعریف کرده است.

نمونه‌های پرونده‌ی راه‌اندازی¶

برای مثال، فرض کنید sys.prefix و sys.exec_prefix روی /usr/local تنظیم شده باشند. کتابخانه‌ی پایتون X.Y سپس در /usr/local/lib/pythonX.Y نصب می‌شود. فرض کنید این مسیر دارای یک زیرپوشه به نام /usr/local/lib/pythonX.Y/site-packages با سه زیرپوشه به نام‌های foo، bar و spam، و دو پرونده‌ی پیکربندی مسیر به نام‌های foo.pth و bar.pth باشد. فرض کنید foo.pth شامل موارد زیر باشد:

# foo package configuration

foo
bar
bletch

و bar.pth شامل موارد زیر است:

# bar package configuration

bar

سپس پوشه‌های مختص نسخه زیر به sys.path اضافه می‌شوند، به این ترتیب:

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

توجه داشته باشید که bletch کنار گذاشته شده است، زیرا وجود ندارد؛ پوشه‌ی bar پیش از پوشه‌ی foo قرار می‌گیرد، زیرا bar.pth از نظر الفبایی پیش از foo.pth می‌آید؛ و spam کنار گذاشته شده است، زیرا در هیچ‌کدام از پرونده‌های پیکربندی مسیر ذکر نشده است.

فرض کنید پرونده‌ی foo.start دیگری نیز وجود دارد که شامل موارد زیر است:

# foo package startup code

foo.submod:initialize

اکنون، پس از اینکه sys.path مطابق بالا گسترش یافت و پیش از اینکه پایتون کنترل را به کد کاربر واگذار کند، ماژول foo.submod ایمپورت شده و تابع initialize() از آن ماژول فراخوانی می‌شود.

مهاجرت از سطرهای import در پرونده‌های .pth به پرونده‌های .start¶

اگر بسته‌ی شما در حال حاضر یک پرونده‌ی name.pth ارائه می‌دهد، می‌توانید تمام سطرهای گسترش sys.path را دست‌نخورده نگه دارید. فقط سطرهای import نیاز به مهاجرت دارند.

برای مهاجرت، یک شیء فراخوانی‌پذیر (بدون هیچ آرگومان) درون یک ماژول قابل‌ایمپورت در بسته‌ی خود ایجاد کنید. به آن به عنوان یک نقطه‌ی ورودی pkg.mod:callable در یک پرونده‌ی name.start متناظر ارجاع دهید. هر چیزی را که در سطر import شما پس از نقطه‌ویرگول اول قرار دارد، به تابع callable() منتقل کنید.

اگر بسته‌ی شما باید هم با نسخه‌های قدیمی‌تر پایتون که از PEP 829 پشتیبانی نمی‌کنند و هم با نسخه‌های جدیدتر که پشتیبانی می‌کنند سازگار بماند، سطرهای import را در پرونده‌ی name.pth خود تغییر دهید تا از شکل زیر استفاده کنند:

import pkg.mod; pkg.mod.callable()

نسخه‌های قدیمی‌تر پایتون این سطرهای import را اجرا خواهند کرد، در حالی که نسخه‌های جدیدتر پایتون آن‌ها را به نفع پرونده‌ی name.start نادیده خواهند گرفت. پس از دوره‌ی گذار، تمام سطرهای import را از پرونده‌های .pth خود حذف کنید.

sitecustomize¶

پس از این دستکاری‌های مسیر، تلاش می‌شود ماژولی به نام sitecustomize ایمپورت شود که می‌تواند سفارشی‌سازی‌های دلخواه و مختص سایت را انجام دهد. این ماژول معمولاً توسط مدیر سیستم در پوشه‌ی site-packages ایجاد می‌شود. اگر این ایمپورت با ImportError یا استثنایی از زیرکلاس‌های آن ناموفق باشد و ویژگی name آن استثنا برابر 'sitecustomize' باشد، به‌صورت خاموش نادیده گرفته می‌شود. اگر پایتون بدون در دسترس بودن جریان‌های خروجی شروع شود، مانند pythonw.exe در ویندوز (که به‌طور پیش‌فرض برای راه‌اندازی IDLE استفاده می‌شود)، هرگونه تلاش برای خروجی از sitecustomize نادیده گرفته می‌شود. هر استثنای دیگری باعث شکستی خاموش و شاید مرموز در فرایند می‌شود.

usercustomize¶

پس از این، اگر ENABLE_USER_SITE درست باشد، تلاش می‌شود ماژولی به نام usercustomize، که می‌تواند سفارشی‌سازی‌های دلخواه و مختص کاربر را انجام دهد، ایمپورت شود. این پرونده قرار است در پوشه‌ی site-packages کاربر (در زیر ببینید) ایجاد شود؛ این پوشه بخشی از sys.path است، مگر آنکه با -s غیرفعال شده باشد. اگر این ایمپورت با استثنای ImportError یا استثنایی از زیرکلاس آن شکست بخورد و ویژگی name آن استثنا برابر 'usercustomize' باشد، به‌صورت خاموش نادیده گرفته می‌شود.

توجه داشته باشید که در برخی سیستم‌های غیر Unix، sys.prefix و sys.exec_prefix خالی هستند و دستکاری‌های مسیر نادیده گرفته می‌شوند؛ با این حال، همچنان تلاش برای ایمپورت sitecustomize و usercustomize انجام می‌شود.

پیکربندی Readline¶

در سیستم‌هایی که از readline پشتیبانی می‌کنند، اگر پایتون در حالت تعاملی و بدون گزینه -S شروع شده باشد، این ماژول همچنین ماژول rlcompleter را نیز ایمپورت و پیکربندی می‌کند. رفتار پیش‌فرض، فعال‌سازی تکمیل با کلید Tab و استفاده از ~/.python_history به‌عنوان پرونده ذخیره تاریخچه است. برای غیرفعال‌سازی آن، ویژگی sys.__interactivehook__ را در ماژول sitecustomize یا usercustomize خود یا پرونده PYTHONSTARTUP خود حذف (یا بازنویسی) کنید.

محتویات ماژول¶

site.PREFIXES¶

فهرستی از پیشوندها برای پوشه‌های site-packages.

site.ENABLE_USER_SITE¶

پرچمی که وضعیت پوشه‌ی site-packages کاربر را نشان می‌دهد. True یعنی این پوشه فعال است و به sys.path افزوده شده است. False یعنی به درخواست کاربر (با -s یا PYTHONNOUSERSITE) غیرفعال شده است. None یعنی به دلایل امنیتی (عدم تطابق شناسه‌ی کاربر یا گروه با شناسه‌ی مؤثر) یا توسط مدیر غیرفعال شده است.

site.USER_SITE¶

مسیر site-packages کاربر برای پایتون در حال اجرا. اگر getusersitepackages() هنوز فراخوانی نشده باشد، ممکن است None باشد. مقدار پیش‌فرض برای UNIX و ساخت‌های غیرچارچوب macOS برابر با ~/.local/lib/pythonX.Y[t]/site-packages، برای ساخت‌های چارچوب macOS برابر با ~/Library/Python/X.Y/lib/python/site-packages، و در ویندوز %APPDATA%\Python\PythonXY\site-packages است. نویسه اختیاری «t» نشان‌دهنده ساخت نخ‌آزاداست. این پوشه یک پوشه سایت (site directory) است، به این معنا که پرونده‌های .pth درون آن پردازش خواهند شد.

site.USER_BASE¶

مسیر پوشه‌ی پایه برای site-packages کاربر. اگر getuserbase() هنوز فراخوانی نشده باشد، ممکن است None باشد. مقدار پیش‌فرض برای ساخت‌های غیرچارچوبی در UNIX و macOS برابر ~/.local، برای ساخت‌های چارچوبی در macOS برابر ~/Library/Python/X.Y، و برای Windows برابر %APPDATA%\Python است. این مقدار برای محاسبه‌ی پوشه‌های نصب اسکریپت‌ها، پرونده‌های داده، ماژول‌های پایتون و غیره برای طرح‌واره نصب کاربر استفاده می‌شود. همچنین PYTHONUSERBASE را ببینید.

site.main()¶

همه‌ی پوشه‌های استانداردِ خاصِ سایت را به مسیر جستجوی ماژول اضافه می‌کند. این تابع به‌صورت خودکار هنگامی که این ماژول ایمپورت می‌شود فراخوانی می‌شود، مگر اینکه مفسر پایتون با پرچم -S راه‌اندازی شده باشد.

تغییر یافته در نسخه‌ی 3.3: این تابع پیش‌تر به‌طور غیرشرطی فراخوانی می‌شد.

site.makepath(*paths)¶

مسیرها (paths) را با تابع os.path.join() به هم متصل کنید، تلاش کنید نتیجه را با تابع os.path.abspath() به مسیر مطلق تبدیل کنید، و یک تاپل ۲تایی شامل مسیر مطلق و فرم نرمال‌شده‌ی بزرگ/کوچک‌نمایی حروف آن را که توسط تابع os.path.normcase() تولید شده است، برگردانید. اگر تابع os.path.abspath() خطای OSError را ایجاد کند، مسیر متصل‌شده بدون تغییر برای مرحله‌ی نرمال‌سازی بزرگ/کوچک‌نمایی استفاده می‌شود.

عنصر دوم تاپل بازگردانده‌شده، فرمی است که در سرتاسر ماژول site برای مقایسه‌ی مسیرها در سیستم پرونده‌ی حساس به بزرگی و کوچکی حروف استفاده می‌شود، و همان چیزی است که مجموعه‌های known_paths را پر می‌کند تا از ورود‌ی‌های تکراری sys.path در APIهای مختلف درون این ماژول جلوگیری کند.

class site.StartupState(known_paths=None)¶

نمونه‌های این کلاس، داده‌های پیکربندی راه‌اندازی مفسر را از یک یا چند دایرکتوری سایت انباشته می‌کنند. آن‌ها رابط ترجیحی برای پردازش دسته‌ای پرونده‌های .pth و .start در چندین دایرکتوری سایت هستند، به‌طوری‌که هر پسوند sys.path قبل از اجرای هرگونه کد راه‌اندازی قابل‌مشاهده باشد.

آرگومان اختیاری known_paths مجموعه‌ای از مسیرهای نرمال‌شده از نظر بزرگی و کوچکی حروف است (که می‌توانند توسط تابع makepath() تولید شوند) و برای جلوگیری از ورود‌ی‌های تکراری sys.path استفاده می‌شود. هنگامی که مقدار None باشد (پیش‌فرض)، مجموعه از sys.path فعلی ساخته می‌شود. تابع main() به طور ضمنی از نمونه‌ای از این کلاس استفاده می‌کند.

کاربرد معمولی:

state = site.StartupState()
for sitedir in site_dirs:
    state.addsitedir(sitedir)
state.process()

اضافه شده در نسخه‌ی 3.15.

addsitedir(sitedir)¶

پرونده‌های .pth و .start را در sitedir بخوانید و پسوندهای sys.path آن‌ها، خطوط import منسوخ پرونده‌های .pth و نقاط ورود .start را در این وضعیت ثبت کنید. داده‌های ثبت‌شده تا زمانی که process() فراخوانی نشود، اعمال نمی‌شوند.

addusersitepackages()¶

در صورت فعال بودن و وجود داشتن، پوشه‌ی site-packages مخصوص کاربر را اضافه کنید. داده‌های راه‌اندازی پوشه برای پردازش بعدی توسط process() جمع‌آوری می‌شوند.

addsitepackages(prefixes=None)¶

پوشه‌های سراسری site-packages، که از prefixes یا از PREFIXES سراسری زمانی که prefixes برابر با None است محاسبه می‌شوند را اضافه کنید. داده‌های راه‌اندازی هر پوشه برای پردازش بعدی توسط process() انباشته می‌شوند.

process()¶

وضعیت انباشته‌شده را ابتدا با افزودن پسوندهای مسج به sys.path، سپس اجرای نقاط ورود پرونده‌ی .start و سطرهای import پرونده‌ی .pth (منسوخ‌شده) اعمال کنید.

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

site.addsitedir(sitedir, known_paths=None)¶

یک پوشه را به sys.path اضافه کنید و پرونده‌های .pth و .start یافت‌شده در آن پوشه را تجزیه (parse) کنید. معمولاً در sitecustomize یا usercustomize استفاده می‌شود (به بالا مراجعه کنید).

آرگومان known_paths مجموعه‌ای اختیاری از مسیرهای نرمال‌شده از نظر بزرگی و کوچکی حروف است که برای جلوگیری از ورودهای تکراری sys.path استفاده می‌شود. وقتی None باشد (پیش‌فرض)، این مجموعه از sys.path فعلی ساخته می‌شود.

برای پردازش دسته‌ای در چندین پوشه‌ی site، یک StartupState به طور صریح بسازید و StartupState.addsitedir() را روی آن فراخوانی کنید؛ این کار پردازش .pth و .start را تا زمان یک فراخوانی منفرد StartupState.process() به تأخیر می‌اندازد و تضمین می‌کند که هر پسوند sys.path قبل از اجرای هرگونه کد راه‌اندازی قابل مشاهده باشد.

تغییر یافته در نسخه‌ی 3.15: همچنین پرونده‌های .start را پردازش می‌کند. نگاه کنید به نقاط ورودی راه‌اندازی (پرونده‌های .start).

site.getsitepackages(prefixes=None)¶

فهرستی شامل تمام پوشه‌های site-packages سراسری را برمی‌گرداند.

برای هر پوشه داده‌شده در prefixes (یا PREFIXES اگر prefixes برابر None باشد)، این تابع زیرپوشه‌ی site-packages آن را بر اساس محیط سیستم محاسبه می‌کند، و یک فهرست از مسیرهای کامل برمی‌گرداند که برای وجود بررسی نمی‌شوند.

اضافه شده در نسخه‌ی 3.2.

تغییر یافته در نسخه‌ی 3.3: پارامتر اختیاری prefixes اضافه شد.

site.getuserbase()¶

مسیر پوشه‌ی پایه‌ی کاربر، USER_BASE را برمی‌گرداند. اگر هنوز مقداردهی اولیه نشده باشد، این تابع آن را نیز با رعایت PYTHONUSERBASE تنظیم می‌کند.

اضافه شده در نسخه‌ی 3.2.

site.getusersitepackages()¶

مسیر پوشه‌ی site-packages اختصاصی کاربر، USER_SITE را برمی‌گرداند. اگر هنوز مقداردهی اولیه نشده باشد، این تابع آن را نیز با رعایت USER_BASE تنظیم می‌کند. برای تشخیص اینکه آیا site-packages اختصاصی کاربر به sys.path اضافه شده است یا خیر، باید از ENABLE_USER_SITE استفاده شود.

اضافه شده در نسخه‌ی 3.2.

رابط خط فرمان¶

ماژول site همچنین راهی برای دریافت پوشه‌های کاربر از خط فرمان فراهم می‌کند:

$ python -m site --user-site
/home/user/.local/lib/python3.11/site-packages

اگر بدون آرگومان فراخوانی شود، محتوای sys.path را در خروجی استاندارد چاپ می‌کند، پس از آن مقدار USER_BASE و اینکه آیا آن پوشه وجود دارد یا خیر، سپس همین مورد برای USER_SITE، و در نهایت مقدار ENABLE_USER_SITE را چاپ می‌کند.

--user-base¶

مسیر پوشه‌ی پایه‌ی کاربر را چاپ می‌کند.

--user-site¶

مسیر پوشه‌ی site-packages کاربر را چاپ می‌کند.

اگر هر دو گزینه داده شده باشد، پایه کاربر (user base) و سایت کاربر (user site)، همیشه با همین ترتیب، چاپ می‌شوند و با os.pathsep جدا می‌شوند.

اگر گزینه‌ای داده شود، اسکریپت با یکی از این مقدارها خارج می‌شود: 0 اگر پوشه site-packages کاربر فعال باشد، 1 اگر توسط کاربر غیرفعال شده باشد، 2 اگر به دلایل امنیتی یا توسط مدیر غیرفعال شده باشد، و مقداری بزرگ‌تر از ۲ اگر خطایی وجود داشته باشد.