مقداردهی اولیهی مسیر جستجوی ماژول sys.path¶
مسیر جستجوی ماژول هنگام شروع پایتون مقداردهی اولیه میشود. این مسیر جستجوی ماژول در sys.path قابل دسترسی است.
اولین ورودی در مسیر جستجوی ماژول، پوشه حاوی اسکریپت ورودی است، اگر چنین اسکریپتی وجود داشته باشد. در غیر این صورت، اولین ورودی پوشه جاری است؛ این حالت هنگام اجرای پوسته تعاملی، یک فرمان -c یا ماژول -m رخ میدهد.
متغیر محیطی PYTHONPATH اغلب برای افزودن پوشهها به مسیر جستجو استفاده میشود. اگر این متغیر محیطی یافت شود، محتویات آن به مسیر جستجوی ماژول افزوده میشوند.
توجه
PYTHONPATH بر تمام نسخهها/محیطهای نصبشدهی پایتون تأثیر خواهد گذاشت. در تنظیم این متغیر در پروفایل پوسته یا متغیرهای محیطی سراسری احتیاط کنید. ماژول site همانطور که در ادامه ذکر شده است، روشهای ظریفتری ارائه میدهد.
آیتمهای بعدی که اضافه میشوند، پوشههایی هستند که ماژولهای استاندارد پایتون و همچنین هر ماژول توسعهای (extension modules) را که این ماژولها به آن وابستهاند، شامل میشوند. ماژولهای توسعهای، پروندههای .pyd در ویندوز و پروندههای .so در سایر سکوها هستند. پوشهی حاوی ماژولهای پایتون مستقل از سکو، prefix نامیده میشود. پوشهی حاوی ماژولهای توسعهای، exec_prefix نامیده میشود.
از متغیر محیطی PYTHONHOME میشود برای تنظیم محلهای prefix و exec_prefix استفاده کرد. در غیر این صورت، این پوشهها با استفاده از پرونده اجرایی پایتون بهعنوان نقطه آغاز و سپس با جستوجوی پروندهها و پوشههای «نشانه» مختلف پیدا میشوند. توجه داشته باشید که هرگونه پیوند نمادینی دنبال میشود، بنابراین مکان واقعی پرونده اجرایی پایتون بهعنوان نقطه آغاز جستوجو استفاده میشود. مکان پرونده اجرایی پایتون home نامیده میشود.
پس از تعیین home، پوشهی prefix ابتدا با جستجو برای pythonmajorversionminorversion.zip (python311.zip) یافت میشود. در ویندوز، بایگانی zip در home جستجو میشود و در یونیکس انتظار میرود بایگانی در lib قرار داشته باشد. توجه داشته باشید که محل مورد انتظار برای بایگانی zip حتی اگر بایگانی وجود نداشته باشد، به مسیر جستجوی ماژول افزوده میشود. اگر هیچ بایگانیای یافت نشد، پایتون در ویندوز جستجو برای یافتن prefix را با جستجوی Lib\os.py ادامه میدهد. پایتون در یونیکس به دنبال lib/pythonmajorversion.minorversion/os.py (lib/python3.11/os.py) میگردد. در ویندوز prefix و exec_prefix یکسان هستند، اما در سایر پلتفرمها lib/pythonmajorversion.minorversion/lib-dynload (lib/python3.11/lib-dynload) جستجو میشود و بهعنوان مبنایی برای exec_prefix استفاده میشود. در برخی پلتفرمها ممکن است lib برابر با lib64 یا مقدار دیگری باشد؛ sys.platlibdir و PYTHONPLATLIBDIR را ببینید.
پس از یافت شدن، prefix و exec_prefix بهترتیب در sys.base_prefix و sys.base_exec_prefix در دسترس هستند.
اگر PYTHONHOME تنظیمنشده باشد و یک پرونده pyvenv.cfg در کنار پرونده اجرایی اصلی یا در پوشهی والد آن پیدا شود، sys.prefix و sys.exec_prefix به پوشهی حاوی pyvenv.cfg تنظیم میشوند؛ در غیر این صورت، آنها بهترتیب به همان مقدار sys.base_prefix و sys.base_exec_prefix تنظیم میشوند. این توسط محیطهای مجازی استفاده میشود.
در نهایت، ماژول site پردازش میشود و پوشههای site-packages به مسیر جستجوی ماژول افزوده میشوند. یک روش رایج برای سفارشیسازی مسیر جستجو، ایجاد ماژولهای sitecustomize یا usercustomize است، همانطور که در مستندات ماژول site توضیح داده شده است.
توجه
برخی گزینههای خط فرمان ممکن است بر محاسبات مسیر تأثیر بیشتری بگذارند. برای جزئیات بیشتر، -E، -I، -s و -S را ببینید.
تغییر یافته در نسخهی 3.14: sys.prefix و sys.exec_prefix اکنون در حین مقداردهی اولیهی مسیر به پوشهی حاوی pyvenv.cfg تنظیم میشوند. این کار پیشتر توسط site انجام میشد، بنابراین تحت تأثیر -S قرار میگرفت.
محیطهای مجازی¶
محیطهای مجازی یک پرونده pyvenv.cfg را در پیشوند خود قرار میدهند، که باعث میشود sys.prefix و sys.exec_prefix به جای نصب پایه، به آنها اشاره کنند.
مقادیر prefix و exec_prefix مربوط به نصب پایه، در sys.base_prefix و sys.base_exec_prefix در دسترس هستند.
علاوه بر استفاده بهعنوان نشانگری برای شناسایی محیطهای مجازی، میتوان از pyvenv.cfg همچنین برای پیکربندی مقداردهی اولیه site استفاده کرد. لطفاً به مستندات محیطهای مجازی مربوط به site مراجعه کنید.
توجه
PYTHONHOME بر شناسایی pyvenv.cfg مقدم است.
توجه
روشهای دیگری نیز برای پیادهسازی «محیطهای مجازی» وجود دارد؛ این مستندات به پیادهسازیهایی اشاره میکند که بر پایهی سازوکار pyvenv.cfg هستند، مانند venv. بیشتر پیادهسازیهای محیط مجازی از مدلی پیروی میکنند که venv تعیین کرده است، اما ممکن است پیادهسازیهای غیرمتعارفی وجود داشته باشند که از آن منحرف شوند.
پروندههای _pth¶
برای لغو کامل sys.path، یک پرونده ._pth با همان نام کتابخانهی اشتراکی یا پرونده اجرایی (python._pth یا python311._pth) ایجاد کنید. مسیر کتابخانهی اشتراکی همیشه در ویندوز شناختهشده است، اما ممکن است در سایر پلتفرمها در دسترس نباشد. در پرونده ._pth، یک خط برای هر مسیر جهت افزودن به sys.path مشخص کنید. پرونده مبتنی بر نام کتابخانهی اشتراکی، پرونده مبتنی بر پرونده اجرایی را لغو میکند، که این امکان را فراهم میکند تا در صورت تمایل، مسیرها برای هر برنامهای که رانتایم را بارگذاری میکند محدود شوند.
هنگامی که پرونده وجود دارد، تمام متغیرهای رجیستری و محیطی نادیده گرفته میشوند، حالت ایزوله فعال میشود، و site ایمپورت نمیشود مگر اینکه یک خط در پرونده import site را مشخص کند. مسیرهای خالی و سطرهایی که با # شروع میشوند نادیده گرفته میشوند. هر مسیر میتواند مطلق یا نسبی نسبت به محل پرونده باشد. دستورهای ایمپورت بهجز برای site مجاز نیستند، و نمیتوان کد دلخواهی را مشخص کرد.
توجه داشته باشید که پروندههای .pth (بدون زیرخط آغازین) زمانی بهطور عادی توسط ماژول site پردازش میشوند که import site مشخص شده باشد.
پایتون تعبیهشده¶
اگر پایتون درون یک برنامه کاربردی دیگر تعبیهشده باشد، میتوان از Py_InitializeFromConfig() و ساختار PyConfig برای راهاندازی پایتون استفاده کرد. جزئیات مربوط به مسیر در پیکربندی مسیر پایتون شرح داده شدهاند.
همچنین ملاحظه نمائید
یافتن ماژولها برای یادداشتهای تفصیلی ویندوز.
استفاده از پایتون در پلتفرمهای یونیکس برای جزئیات یونیکس.