site --- قلاب پیکربندی مختص سایت

کد منبع: Lib/site.py

این ماژول در حین راه‌اندازی به‌طور خودکار ایمپورت می‌شود. می‌توان با استفاده از گزینه‌ی -S مفسر، از ایمپورت خودکار جلوگیری کرد.

ایمپورت این ماژول معمولاً مسیرهای مختص سایت را به مسیر جستجوی ماژول اضافه می‌کند و callables، از جمله help()، را به فضای نام توکار می‌افزاید. با این حال، گزینه‌ی راه‌اندازی پایتون -S این را مسدود می‌کند و می‌توان این ماژول را به‌صورت امن، بدون هیچ‌گونه تغییر خودکار در مسیر جستجوی ماژول یا افزودن موارد به توکارها، ایمپورت کرد. برای فعال‌سازی صریح افزودن‌های معمول مختص سایت، تابع main() را فراخوانی کنید.

تغییر یافته در نسخه‌ی 3.3: ایمپورت کردن ماژول، پیش‌تر حتی در صورت استفاده از -S نیز باعث دست‌کاری مسیرها می‌شد.

این کار با ساختن حداکثر چهار پوشه از یک بخش سر و یک بخش دم آغاز می‌شود. برای بخش سر، از sys.prefix و sys.exec_prefix استفاده می‌کند؛ بخش‌های سر خالی نادیده گرفته می‌شوند. برای بخش دم، از رشته خالی و سپس lib/site-packages (در ویندوز) یا lib/pythonX.Y[t]/site-packages (در یونیکس و macOS) استفاده می‌کند. (پسوند اختیاری "t" نشان‌دهنده‌ی free-threaded build است و در صورتی اضافه می‌شود که "t" در ثابت sys.abiflags وجود داشته باشد.) برای هر یک از ترکیب‌های متمایز سر و دم، بررسی می‌کند که آیا آن ترکیب به یک پوشه موجود اشاره دارد یا خیر، و در این صورت، آن را به sys.path اضافه می‌کند و همچنین مسیر تازه اضافه‌شده را برای پرونده‌های پیکربندی بررسی می‌کند.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از پوشه‌ی «site-python» حذف شده است.

تغییر یافته در نسخه‌ی 3.13: در یونیکس، نصب‌های پایتون نخ‌آزاد با پسوند «t» در نام پوشه‌ی مختص نسخه شناسایی می‌شوند، مانند lib/python3.13t/.

تغییر یافته در نسخه‌ی 3.14: site دیگر مسئول به‌روزرسانی sys.prefix و sys.exec_prefix در محیط‌های مجازی نیست. این کار اکنون در حین مقداردهی اولیه مسیر انجام می‌شود. در نتیجه، در محیط‌های مجازی، sys.prefix و sys.exec_prefix دیگر به مقداردهی اولیه site وابسته نیستند و بنابراین تحت تأثیر -S قرار نمی‌گیرند.

هنگام اجرا در یک محیط مجازی، پرونده pyvenv.cfg در sys.prefix از نظر پیکربندی‌های خاص سایت بررسی می‌شود. اگر کلید include-system-site-packages وجود داشته باشد و روی true تنظیم شده باشد (بدون حساسیت به بزرگی و کوچکی حروف)، پیشوندهای سطح سیستم برای site-packages جستجو خواهند شد، در غیر این صورت جستجو نخواهند شد.

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

توجه

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

تغییر یافته در نسخه‌ی 3.13: پرونده‌های .pth اکنون ابتدا با UTF-8 کدگشایی می‌شوند و در صورت شکست، با locale encoding کدگشایی می‌شوند.

برای مثال، فرض کنید 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 کنار گذاشته شده است، زیرا در هیچ‌کدام از پرونده‌های پیکربندی مسیر ذکر نشده است.

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 خود حذف (یا بازنویسی) کنید.

تغییر یافته در نسخه‌ی 3.4: فعال‌سازی rlcompleter و تاریخچه به‌صورت خودکار انجام شد.

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

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.addsitedir(sitedir, known_paths=None)

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

site.getsitepackages(prefixes=None)

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

For each directory given in prefixes (or PREFIXES if prefixes is None), this function will compute its site-packages subdirectory depending on the system environment, and will return a list of full paths, which are not checked for existence.

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

تغییر یافته در نسخه‌ی 3.3: Added the optional prefixes parameter.

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 اگر به دلایل امنیتی یا توسط مدیر غیرفعال شده باشد، و مقداری بزرگ‌تر از ۲ اگر خطایی وجود داشته باشد.

همچنین ملاحظه نمائید