1. خط فرمان و محیط

مفسر سی‌پایتون خط فرمان و محیط را برای تنظیمات مختلف پویش می‌کند.

طرح‌واره‌های خط فرمان پیاده‌سازی‌های دیگر ممکن است متفاوت باشند. برای منابع بیشتر به پیاده‌سازی‌های جایگزین مراجعه کنید.

1.1. خط فرمان

هنگام فراخوانی پایتون، می‌توانید هر یک از این گزینه‌ها را مشخص کنید:

python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]

رایج‌ترین مورد استفاده، البته، فراخوانی ساده‌ی یک اسکریپت است:

python myscript.py

1.1.1. گزینه‌های رابط

رابط مفسر شبیه پوسته یونیکس است، اما چندین روش فراخوانی اضافی ارائه می‌دهد:

• وقتی با ورودی استاندارد متصل به یک دستگاه tty فراخوانی شود، برای دریافت دستورها اعلان نمایش می‌دهد و آن‌ها را اجرا می‌کند تا زمانی که یک EOF (نویسه‌ی پایان پرونده؛ می‌توانید آن را با Ctrl-D در یونیکس یا Ctrl-Z, Enter در ویندوز ایجاد کنید) خوانده شود. برای اطلاعات بیشتر درباره‌ی حالت تعاملی، به حالت تعاملی مراجعه کنید.

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

• هنگامی که با آرگومان نام یک پوشه فراخوانی شود، اسکریپتی با نام مناسب را از آن پوشه می‌خواند و اجرا می‌کند.

• هنگامی که با -c command فراخوانی شود، دستور(های) پایتونِ داده‌شده به‌عنوان command را اجرا می‌کند. در اینجا command می‌تواند شامل چندین دستور باشد که با سطرهای جدید از هم جدا شده‌اند. فضای سفیدِ ابتدای سطر در دستورهای پایتون معنادار است!

• وقتی با -m module-name فراخوانی شود، ماژول داده‌شده با استفاده از سازوکار استاندارد ایمپورت یافته می‌شود و به‌عنوان یک اسکریپت اجرا می‌شود.

در حالت غیرتعاملی، کل ورودی پیش از اجرا شدن تجزیه می‌شود.

یک گزینه‌ی رابط، فهرست گزینه‌هایی را که توسط مفسر مصرف می‌شوند، پایان می‌دهد؛ تمام آرگومان‌های متوالی در sys.argv قرار می‌گیرند -- توجه داشته باشید که اولین عنصر، زیرنویس صفر (sys.argv[0])، رشته‌ای است که منبع برنامه را بازتاب می‌دهد.

-c <command>

کد پایتون موجود در command را اجرا می‌کند. command می‌تواند یک یا چند دستور باشد که با سطرهای جدید از هم جدا شده‌اند و مانند کد ماژول معمولی، فضای سفید ابتدای سطر در آن معنادار است.

اگر این گزینه داده شود، نخستین المان sys.argv برابر "-c" خواهد بود و پوشه جاری به ابتدای sys.path افزوده می‌شود (که این اجازه را می‌دهد ماژول‌های موجود در آن پوشه به‌عنوان ماژول‌های سطح بالا ایمپورت شوند).

رویداد حسابرسی cpython.run_command را با آرگومان command ایجاد می‌کند.

تغییر یافته در نسخه‌ی 3.14: تورفتگی command پیش از اجرا به‌طور خودکار حذف می‌شود.

-m <module-name>

ماژول را با استفاده از سازوکار ایمپورت استاندارد بیابید و محتویات آن را به عنوان ماژول __main__ اجرا کنید.

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

نام‌های بسته (از جمله بسته‌های فضای نام) نیز مجاز هستند. هنگامی که به جای یک ماژول معمولی، نام یک بسته ارائه شود، مفسر <pkg>.__main__ را به عنوان ماژول اصلی اجرا می‌کند. این رفتار عمداً مشابه نحوه‌ی برخورد با پوشه‌ها و پرونده‌های zip است که به عنوان آرگومان اسکریپت به مفسر داده می‌شوند.

توجه

این گزینه را نمی‌توان برای ماژول‌های توکار و ماژول‌های توسعه‌ای نوشته‌شده به زبان C به کار برد، زیرا آن‌ها پرونده‌های ماژول پایتون ندارند. با این حال، این گزینه همچنان برای ماژول‌های پیش‌کامپایل‌شده قابل استفاده است، حتی اگر پرونده منبع اصلی در دسترس نباشد.

اگر این گزینه داده شود، عنصر اول sys.argv مسیر کامل پرونده ماژول خواهد بود (در حین یافتن پرونده ماژول، عنصر اول روی "-m" تنظیم خواهد شد). همانند گزینه -c، پوشه جاری به ابتدای sys.path افزوده خواهد شد.

می‌توان از گزینه‌ی -I برای اجرای اسکریپت در حالت ایزوله استفاده کرد؛ حالتی که در آن sys.path نه پوشه‌ی جاری و نه پوشه‌ی site-packages کاربر را در بر می‌گیرد. تمام متغیرهای محیطی PYTHON* نیز نادیده گرفته می‌شوند.

بسیاری از ماژول‌های کتابخانه استاندارد کدی دارند که هنگام اجرای آن‌ها به‌عنوان اسکریپت فراخوانی می‌شود. نمونه‌ای از این موارد، ماژول timeit است:

python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details

یک رویداد حسابرسی cpython.run_module را با آرگومان module-name ایجاد می‌کند.

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

runpy.run_module()

کارکرد معادلی که مستقیماً در دسترس کد پایتون است

PEP 338 -- اجرای ماژول‌ها به‌صورت اسکریپت

تغییر یافته در نسخه‌ی 3.1: نام بسته را برای اجرای یک زیرماژول __main__ ارائه کنید.

تغییر یافته در نسخه‌ی 3.4: بسته‌های فضای نام نیز پشتیبانی می‌شوند

-

فرمان‌ها از ورودی استاندارد (sys.stdin) خوانده می‌شوند. اگر ورودی استاندارد یک پایانه باشد، گزینه‌ی -i به‌طور ضمنی در نظر گرفته می‌شود.

اگر این گزینه داده شود، عنصر نخستِ sys.argv برابر "-" خواهد بود و پوشه‌ی جاری به ابتدای sys.path اضافه می‌شود.

رویداد حسابرسی cpython.run_stdin را بدون هیچ آرگومانی ایجاد می‌کند.

<script>

کد پایتون موجود در script را اجرا می‌کند، که باید مسیری در سامانه فایل‌بندی (مطلق یا نسبی) باشد و به یک پرونده پایتون، یک پوشه‌ی حاوی پرونده __main__.py، یا یک پرونده zip حاوی پرونده __main__.py اشاره کند.

اگر این گزینه داده شود، اولین عنصر sys.argv نام اسکریپت، همان‌طور که در خط فرمان داده شده است، خواهد بود.

اگر نام اسکریپت مستقیماً به یک پرونده پایتون اشاره کند، پوشه‌ی حاوی آن پرونده به ابتدای sys.path افزوده می‌شود و آن پرونده به‌عنوان ماژول __main__ اجرا می‌شود.

اگر نام اسکریپت به یک پوشه یا پرونده zip اشاره کند، نام اسکریپت به ابتدای sys.path اضافه می‌شود و پرونده __main__.py در آن مکان به‌عنوان ماژول __main__ اجرا می‌شود.

می‌توان از گزینه‌ی -I برای اجرای اسکریپت در حالت ایزوله استفاده کرد؛ حالتی که در آن sys.path نه پوشه‌ی اسکریپت و نه پوشه‌ی site-packages کاربر را در بر می‌گیرد. تمام متغیرهای محیطی PYTHON* نیز نادیده گرفته می‌شوند.

رویداد حسابرسی cpython.run_file را با آرگومان filename ایجاد می‌کند.

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

runpy.run_path()

کارکرد معادلی که مستقیماً در دسترس کد پایتون است

اگر هیچ گزینه‌ی رابطی داده نشود، -i به‌طور ضمنی در نظر گرفته می‌شود، sys.argv[0] یک رشته‌ی خالی ("") است و پوشه‌ی جاری به ابتدای sys.path افزوده می‌شود. همچنین، تکمیل با کلید Tab و ویرایش تاریخچه، در صورت در دسترس بودن در پلتفرم شما، به‌طور خودکار فعال می‌شوند (به پیکربندی Readline مراجعه کنید).

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

فراخوانی مفسر

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

1.1.2. گزینه‌های عمومی

-?

-h

--help

چاپ توضیح کوتاهی از تمام گزینه‌های خط فرمان و متغیرهای محیطی متناظر و خروج.

--help-env

چاپ توضیح کوتاهی درباره‌ی متغیرهای محیطی مخصوص پایتون و خارج شدن.

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

--help-xoptions

توضیحی از گزینه‌های -X مخصوص پیاده‌سازی را چاپ می‌کند و خارج می‌شود.

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

--help-all

اطلاعات کامل استفاده را چاپ می‌کند و خارج می‌شود.

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

-V

--version

شماره نسخه پایتون را چاپ کرده و خارج می‌شود. نمونه‌ای از خروجی می‌تواند به این صورت باشد:

Python 3.8.0b2+

وقتی دو بار داده شود، اطلاعات بیشتری درباره‌ی ساخت چاپ می‌کند، مانند:

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

اضافه شده در نسخه‌ی 3.6: گزینه‌ی -VV.

1.1.3. گزینه‌های متفرقه

-b

هنگام تبدیل bytes یا bytearray به str بدون مشخص کردن کدگذاری، یا مقایسه‌ی bytes یا bytearray با str یا bytes با int، هشدار صادر می‌کند. وقتی این گزینه دو بار داده شود (-bb) خطا صادر می‌کند.

تغییر یافته در نسخه‌ی 3.5: همچنین بر مقایسه‌های bytes با int تأثیر می‌گذارد.

-B

در صورت داده شدن، پایتون هنگام ایمپورت ماژول‌های منبع تلاش نمی‌کند پرونده‌های .pyc را بنویسد. همچنین PYTHONDONTWRITEBYTECODE را ببینید.

--check-hash-based-pycs default|always|never

رفتار اعتبارسنجی پرونده‌های .pyc مبتنی بر هش را کنترل می‌کند. به بی‌اعتبارسازی بایت‌کد نهان‌شده مراجعه کنید. هنگامی که روی default تنظیم شود، پرونده‌های نهانگاه بایت‌کد مبتنی بر هش، اعم از بررسی‌شده و بررسی‌نشده، مطابق معناشناسی پیش‌فرض خود اعتبارسنجی می‌شوند. هنگامی که روی always تنظیم شود، همه‌ی پرونده‌های .pyc مبتنی بر هش، چه بررسی‌شده و چه بررسی‌نشده، در برابر پرونده منبع متناظر خود اعتبارسنجی می‌شوند. هنگامی که روی never تنظیم شود، پرونده‌های .pyc مبتنی بر هش در برابر پرونده‌های منبع متناظر خود اعتبارسنجی نمی‌شوند.

معناشناسی پرونده‌های .pyc مبتنی بر مهر زمانی، تحت تأثیر این گزینه قرار نمی‌گیرد.

-d

فعال کردن خروجی اشکال‌زدایی پارسر (فقط برای متخصصان). همچنین متغیر محیطی PYTHONDEBUG را ببینید.

این گزینه نیازمند نسخه‌ی اشکال‌زدایی پایتون است؛ در غیر این صورت نادیده گرفته می‌شود.

-E

همه متغیرهای محیطی PYTHON* که ممکن است تنظیم شده باشند را نادیده بگیرید، مانند PYTHONPATH و PYTHONHOME.

همچنین گزینه‌های -P و -I (ایزوله) را ببینید.

-i

ورود به حالت تعاملی پس از اجرا.

استفاده از گزینه‌ی -i در هر یک از شرایط زیر موجب ورود به حالت تعاملی می‌شود:

• وقتی یک اسکریپت به‌عنوان آرگومان اول گذرانده می‌شود

• هنگامی که از گزینه‌ی -c استفاده می‌شود

• هنگامی که از گزینه‌ی -m استفاده می‌شود

حالت تعاملی حتی زمانی که sys.stdin به نظر نمی‌رسد پایانه باشد، آغاز می‌شود. پرونده‌ی PYTHONSTARTUP خوانده نمی‌شود.

این می‌تواند برای بازرسی متغیرهای سراسری یا ردگیری پشته هنگامی که یک اسکریپت استثنا ایجاد می‌کند، مفید باشد. همچنین PYTHONINSPECT را ببینید.

-I

پایتون را در حالت ایزوله اجرا می‌کند. این کار همچنین شامل گزینه‌های -E، -P و -s است.

در حالت ایزوله، sys.path نه پوشه‌ی اسکریپت را در بر می‌گیرد و نه پوشه‌ی site-packages کاربر را. همچنین تمام متغیرهای محیطی PYTHON* نادیده گرفته می‌شوند. ممکن است محدودیت‌های بیشتری برای جلوگیری از تزریق کد مخرب توسط کاربر اعمال شود.

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

-O

دستورهای ادعا (assert) و هر کدی که مشروط به مقدار __debug__ باشد را حذف می‌کند. نام پرونده‌های کامپایل‌شده (bytecode) را با افزودن .opt-1 پیش از پسوند .pyc تغییر می‌دهد (به PEP 488 مراجعه کنید). همچنین PYTHONOPTIMIZE را ببینید.

تغییر یافته در نسخه‌ی 3.5: نام پرونده‌های .pyc را مطابق PEP 488 تغییر دهید.

-OO

همان کار -O را انجام می‌دهد و همچنین رشته‌های مستند را دور می‌ریزد. نام پرونده‌های کامپایل‌شده (بایت‌کد) را با افزودن .opt-2 پیش از پسوند .pyc تغییر می‌دهد (ببینید PEP 488).

تغییر یافته در نسخه‌ی 3.5: نام پرونده‌های .pyc را مطابق PEP 488 تغییر دهید.

-P

مسیر بالقوه ناامنی را به ابتدای sys.path اضافه نکنید:

• خط فرمان python -m module: پوشه‌ی کاری جاری را به ابتدا اضافه نکنید.

• خط فرمان python script.py: پوشه‌ی اسکریپت به ابتدا افزوده نشود. اگر اسکریپت پیوند نمادین باشد، پیوندهای نمادین حل شوند.

• سطرهای فرمان python -c code و python (REPL): رشته‌ی خالی را که به معنای پوشه کاری جاری است، در ابتدا قرار ندهید.

همچنین متغیر محیطی PYTHONSAFEPATH و گزینه‌های -E و -I (ایزوله) را ببینید.

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

-q

پیام‌های حق نشر و نسخه را حتی در حالت تعاملی نمایش ندهید.

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

-R

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

در نسخه‌های قبلی پایتون، این گزینه تصادفی‌سازی هش را فعال می‌کند، به‌طوری که مقادیر __hash__() اشیاء str و bytes با یک مقدار تصادفی غیرقابل پیش‌بینی «نمک‌گذاری» می‌شوند. اگرچه این مقادیر درون یک فرایند پایتون ثابت باقی می‌مانند، اما بین فراخوانی‌های مکرر پایتون قابل پیش‌بینی نیستند.

تصادفی‌سازی هش در نظر گرفته شده است تا در برابر انکار سرویس (denial-of-service) محافظت فراهم کند؛ انکار سرویسی که توسط ورودی‌های به‌دقت انتخاب‌شده‌ای ایجاد می‌شود که از عملکرد بدترین حالت ساخت یک dict، یعنی پیچیدگی O(n²)، سوءاستفاده می‌کنند. برای جزئیات به https://ocert.org/advisories/ocert-2011-003.html مراجعه کنید.

PYTHONHASHSEED به شما اجازه می‌دهد مقدار ثابتی برای بذر هشِ مخفی تعیین کنید.

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

تغییر یافته در نسخه‌ی 3.7: این گزینه دیگر نادیده گرفته نمی‌شود.

-s

پوشه site-packages کاربر را به sys.path اضافه نکنید.

همچنین PYTHONNOUSERSITE را ببینید.

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

PEP 370 -- پوشه site-packages به ازای هر کاربر

-S

ایمپورت ماژول site و دستکاری‌های وابسته به site در sys.path که این ایمپورت در پی دارد را غیرفعال می‌کند. همچنین اگر site بعداً به‌طور صریح ایمپورت شود، این دستکاری‌ها را نیز غیرفعال می‌کند (اگر می‌خواهید این دستکاری‌ها انجام شوند، site.main() را فراخوانی کنید).

-u

جریان‌های stdout و stderr را مجبور می‌کند بدون بافر باشند. این گزینه هیچ تأثیری بر جریان stdin ندارد.

همچنین PYTHONUNBUFFERED را ببینید.

تغییر یافته در نسخه‌ی 3.7: لایه متنی جریان‌های stdout و stderr اکنون بدون بافر است.

-v

هر بار که یک ماژول راه‌اندازی می‌شود، پیامی چاپ می‌کند که نشان می‌دهد از کدام مکان (نام پرونده یا ماژول توکار) بارگذاری شده است. هنگامی که دو بار داده شود (-vv)، برای هر پرونده‌ای که هنگام جستجوی یک ماژول بررسی می‌شود، پیامی چاپ می‌کند. همچنین اطلاعاتی درباره پاک‌سازی ماژول‌ها هنگام خاتمه ارائه می‌دهد.

تغییر یافته در نسخه‌ی 3.10: ماژول site مسیرهای مخصوص سایت و پرونده‌های .pth در حال پردازش را گزارش می‌دهد.

همچنین PYTHONVERBOSE را ببینید.

-W arg

کنترل هشدار. سازوکار هشدار پایتون به‌طور پیش‌فرض پیام‌های هشدار را در sys.stderr چاپ می‌کند.

ساده‌ترین تنظیمات، یک اکشن خاص را بدون قید و شرط به تمام هشدارهایی که توسط یک فرایند منتشر می‌شوند اعمال می‌کنند (حتی هشدارهایی که در غیر این صورت به‌طور پیش‌فرض نادیده گرفته می‌شوند):

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wall      # Same as -Walways
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

نام‌های اکشن را می‌توان به هر اندازه که مایل باشید مختصر کرد و مفسر آن‌ها را به نام اکشن مناسب حل می‌کند. برای مثال، -Wi همان -Wignore است.

شکل کامل آرگومان به این صورت است:

action:message:category:module:lineno

فیلدهای خالی با همه‌ی مقادیر مطابقت دارند؛ فیلدهای خالی انتهایی را می‌توان حذف کرد. برای مثال، -W ignore::DeprecationWarning همه‌ی هشدارهای DeprecationWarning را نادیده می‌گیرد.

فیلد اکشن همان‌طور است که در بالا توضیح داده شد، اما فقط بر هشدارهایی اعمال می‌شود که با فیلدهای باقی‌مانده مطابقت داشته باشند.

فیلد message باید با تمام پیام هشدار تطبیق داشته باشد؛ این تطبیق بدون حساسیت به بزرگی و کوچکی حروف است.

فیلد category با دسته‌ی هشدار مطابقت دارد (مثلاً DeprecationWarning). این باید یک نام کلاس باشد؛ این مطابقت بررسی می‌کند که آیا دسته‌ی هشدار واقعی پیام، زیرکلاسی از دسته‌ی هشدار مشخص‌شده است یا خیر.

فیلد ماژول با نام (کامل) ماژول تطبیق می‌کند؛ این تطبیق به بزرگی و کوچکی حروف حساس است.

فیلد lineno با شماره سطر تطبیق می‌کند، که در آن صفر با همه شماره سطرها تطبیق می‌کند و بنابراین معادل شماره سطر ذکرنشده است.

می‌توان چندین گزینه‌ی -W داد؛ وقتی یک هشدار با بیش از یک گزینه مطابقت داشته باشد، اکشن مربوط به آخرین گزینه‌ی مطابق انجام می‌شود. گزینه‌های نامعتبر -W نادیده گرفته می‌شوند (هرچند، هنگام صدور اولین هشدار، پیام هشداری درباره‌ی گزینه‌های نامعتبر چاپ می‌شود).

هشدارها همچنین می‌توانند با استفاده از متغیر محیطی PYTHONWARNINGS و از درون یک برنامه‌ی پایتون با استفاده از ماژول warnings کنترل شوند. برای مثال، می‌توان از تابع warnings.filterwarnings() برای به‌کارگیری یک عبارت باقاعده روی پیام هشدار استفاده کرد.

برای جزئیات بیشتر به فیلتر هشدارها و توصیف پالایه‌های هشدار مراجعه کنید.

-x

Skip the first line of the source, allowing use of non-Unix forms of #!cmd.

This can be used to turn a Python script into a Windows batch file. Similarly to adding a shebang line and setting the executable bit on Unix, the extension of the Python script can be changed to .bat and the following line can be added at the start of the script:

@py -x "%~f0" %* & exit /b

Or, to specify the path to the Python interpreter explicitly:

@"C:\Path\to\python.exe" -x "%~f0" %* & exit /b

Unlike a shebang line which is a Python comment, this line is not valid Python syntax, and the -x option is needed to skip it.

-X

برای گزینه‌های مختلف مخصوص پیاده‌سازی رزرو شده است. سی‌پایتون در حال حاضر مقادیر ممکن زیر را تعریف می‌کند:

• -X faulthandler برای فعال‌سازی faulthandler. همچنین PYTHONFAULTHANDLER را ببینید.

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

• -X showrefcount برای خروجی گرفتن از شمارش ارجاع کل و تعداد بلوک‌های حافظه‌ی استفاده‌شده هنگام پایان برنامه یا پس از هر دستور در مفسر تعاملی. این گزینه فقط در نسخه‌های اشکال‌زدایی (debug builds) کار می‌کند.

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

• -X tracemalloc برای شروع ردگیری تخصیص‌های حافظه پایتون با استفاده از ماژول tracemalloc. به‌طور پیش‌فرض، تنها جدیدترین فریم در ردیابی یک ردگیری ذخیره می‌شود. برای شروع ردگیری با محدودیت ردیابی برابر با NFRAME فریم، از -X tracemalloc=NFRAME استفاده کنید. برای اطلاعات بیشتر به tracemalloc.start() و PYTHONTRACEMALLOC مراجعه کنید.

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

• -X int_max_str_digits محدودیت طول تبدیل رشته‌ی عدد صحیح را پیکربندی می‌کند. همچنین PYTHONINTMAXSTRDIGITS را ببینید.

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

• -X importtime برای نمایش اینکه هر ایمپورت چقدر زمان می‌برد. این گزینه نام ماژول، زمان تجمعی (شامل ایمپورت‌های تودرتو) و زمان خود (بدون احتساب ایمپورت‌های تودرتو) را نشان می‌دهد. توجه داشته باشید که خروجی آن ممکن است در برنامه‌های چندنخی به هم بریزد. کاربرد معمول آن python -X importtime -c 'import asyncio' است.

  -X importtime=2 خروجی اضافی را فعال می‌کند که نشان می‌دهد چه زمانی یک ماژول ایمپورت‌شده از قبل بارگذاری شده است. در چنین مواردی، رشته‌ی cached در هر دو ستون زمان چاپ خواهد شد.

  همچنین ببینید PYTHONPROFILEIMPORTTIME.

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

  تغییر یافته در نسخه‌ی 3.14: -X importtime=2 افزوده شد تا ایمپورت‌های ماژول‌های بارگذاری‌شده نیز ردگیری شوند، و مقادیری غیر از 1 و 2 برای استفاده در آینده رزرو شدند.

• -X dev: فعال کردن حالت توسعه پایتون که بررسی‌های اضافی ران‌تایم را معرفی می‌کند؛ این بررسی‌ها برای فعال‌سازی به‌صورت پیش‌فرض بیش از حد پرهزینه هستند. همچنین PYTHONDEVMODE را ببینید.

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

• -X utf8 حالت UTF-8 پایتون را فعال می‌کند. -X utf8=0 به‌طور صریح حالت UTF-8 پایتون را غیرفعال می‌کند (حتی زمانی که در غیر این صورت به‌طور خودکار فعال می‌شد). همچنین PYTHONUTF8 را ببینید.

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

• -X pycache_prefix=PATH امکان نوشتن پرونده‌های .pyc را به جای درخت کد، در یک درخت موازی که در پوشه‌ی داده‌شده ریشه دارد فراهم می‌کند. همچنین PYTHONPYCACHEPREFIX را ببینید.

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

• -X warn_default_encoding هنگامی که کدگذاری پیش‌فرض وابسته به locale برای باز کردن پرونده‌ها استفاده شود، EncodingWarning صادر می‌کند. همچنین PYTHONWARNDEFAULTENCODING را ببینید.

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

• -X no_debug_ranges درج جدول‌هایی را که اطلاعات مکان اضافی (سطر پایان، آفست ستون شروع و آفست ستون پایان) را به هر دستورالعمل در اشیای کد نگاشت می‌کنند، غیرفعال می‌کند. این هم زمانی مفید است که اشیای کد و پرونده‌های pyc کوچک‌تر مطلوب باشند و هم برای حذف نشانگرهای بصری مکان اضافی هنگامی که مفسر ردگیری پشته را نمایش می‌دهد. همچنین PYTHONNODEBUGRANGES را ببینید.

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

• -X frozen_modules تعیین می‌کند که آیا ماژول‌های فریزشده توسط سازوکار ایمپورت نادیده گرفته شوند یا خیر. مقدار on به این معنا است که آن‌ها ایمپورت می‌شوند و off به این معنا است که نادیده گرفته می‌شوند. اگر این یک پایتون نصب‌شده باشد (حالت معمول)، مقدار پیش‌فرض on است. اگر در حال توسعه باشد (اجرا از درخت سورس)، مقدار پیش‌فرض off است. توجه داشته باشید که ماژول‌های فریزشده importlib_bootstrap و importlib_bootstrap_external همیشه استفاده می‌شوند، حتی اگر این پرچم روی off تنظیم‌شده باشد. همچنین PYTHON_FROZEN_MODULES را ببینید.

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

• گزینه -X perf پشتیبانی از پروفایل‌گیر perf لینوکس را فعال می‌کند. هنگامی که این گزینه ارائه شود، پروفایل‌گیر perf قادر خواهد بود فراخوانی‌های پایتون را گزارش کند. این گزینه تنها روی برخی پلتفرم‌ها در دسترس است و اگر روی سیستم فعلی پشتیبانی نشود، هیچ کاری انجام نمی‌دهد. مقدار پیش‌فرض "off" است. همچنین PYTHONPERFSUPPORT و پشتیبانی پایتون از پروفایل‌گیر perf لینوکس را ببینید.

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

• گزینه‌ی -X perf_jit پشتیبانی از پروفایل‌گیر perf لینوکس را همراه با پشتیبانی DWARF فعال می‌کند. هنگامی که این گزینه ارائه شود، پروفایل‌گیر perf می‌تواند فراخوانی‌های پایتون را با استفاده از اطلاعات DWARF گزارش کند. این گزینه تنها روی برخی پلتفرم‌ها در دسترس است و اگر در سیستم فعلی پشتیبانی نشده باشد، هیچ کاری انجام نمی‌دهد. مقدار پیش‌فرض «off» است. همچنین PYTHON_PERF_JIT_SUPPORT و پشتیبانی پایتون از پروفایل‌گیر perf لینوکس را ببینید.

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

• -X disable_remote_debug پشتیبانی از اشکال‌زدایی از راه دور را که در PEP 768 شرح داده شده است، غیرفعال می‌کند. این شامل هم قابلیت زمان‌بندی کد برای اجرا در فرایندی دیگر و هم قابلیت دریافت کد برای اجرا در فرایند جاری است.

  این گزینه تنها در برخی پلتفرم‌ها در دسترس است و اگر در سیستم فعلی پشتیبانی نشود، هیچ کاری انجام نمی‌دهد. همچنین PYTHON_DISABLE_REMOTE_DEBUG و PEP 768 را ببینید.

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

• -X cpu_count=n os.cpu_count()، os.process_cpu_count() و multiprocessing.cpu_count() را بازنویسی می‌کند. n باید بزرگ‌تر یا مساوی ۱ باشد. این گزینه ممکن است برای کاربرانی که نیاز به محدود کردن منابع CPU یک سیستم کانتینری دارند، مفید باشد. همچنین PYTHON_CPU_COUNT را ببینید. اگر n برابر default باشد، هیچ‌چیز بازنویسی نمی‌شود.

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

• -X presite=package.module ماژولی را مشخص می‌کند که باید پیش از اجرای ماژول site و پیش از وجود داشتن ماژول __main__ ایمپورت شود. بنابراین، ماژول ایمپورت‌شده __main__ نیست. از این می‌توان برای اجرای کد در ابتدای راه‌اندازی پایتون استفاده کرد. پایتون باید در حالت اشکال‌زدایی ساخته شده باشد تا این گزینه وجود داشته باشد. همچنین PYTHON_PRESITE را ببینید.

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

• -X gil=0,1 قفل مفسر سراسری (GIL) را به‌ترتیب مجبور به غیرفعال یا فعال شدن می‌کند. تنظیم به 0 تنها در ساخت‌های پیکربندی‌شده با --disable-gil در دسترس است. همچنین PYTHON_GIL و سی‌پایتون نخ‌آزاد را ببینید.

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

• -X thread_inherit_context=0,1 باعث می‌شود Thread به‌طور پیش‌فرض هنگام آغاز، از رونوشتی از زمینه‌ی فراخواننده‌ی Thread.start() استفاده کند. در غیر این صورت، نخ‌ها با زمینه‌ی خالی آغاز می‌شوند. اگر تنظیم نشده باشد، مقدار این گزینه به‌طور پیش‌فرض در ساخت‌های نخ‌آزاد 1 و در غیر این صورت 0 است. همچنین PYTHON_THREAD_INHERIT_CONTEXT را ببینید.

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

• -X context_aware_warnings=0,1 باعث می‌شود مدیر زمینه warnings.catch_warnings برای ذخیره وضعیت فیلتر هشدارها از یک ContextVar استفاده کند. اگر تنظیم نشده باشد، مقدار این گزینه در ساخت‌های نخ‌آزاد به‌طور پیش‌فرض 1 و در غیر این صورت 0 است. همچنین PYTHON_CONTEXT_AWARE_WARNINGS را ببینید.

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

• -X tlbc=0,1 در ساخت‌هایی که با --disable-gil پیکربندی شده‌اند، بایت‌کد نخ‌محلی را فعال (1، پیش‌فرض) یا غیرفعال (0) می‌کند. در صورت غیرفعال بودن، مفسر تخصص‌ساز (specializing interpreter) نیز غیرفعال می‌شود. همچنین ببینید: PYTHON_TLBC.

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

این گزینه همچنین امکان ارسال مقادیر دلخواه و بازیابی آن‌ها از طریق دیکشنری sys._xoptions را فراهم می‌کند.

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

تغییر یافته در نسخه‌ی 3.9: گزینه‌ی -X showalloccount حذف شد.

تغییر یافته در نسخه‌ی 3.10: گزینه‌ی -X oldparser حذف شد.

حذف شده در نسخه‌ی 3.14: -J دیگر برای استفاده توسط Jython رزرو نشده است و اکنون معنای خاصی ندارد.

1.1.4. کنترل رنگ

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

تنظیم متغیر محیطی TERM روی dumb رنگ را غیرفعال می‌کند.

اگر متغیر محیطی FORCE_COLOR تنظیم شده باشد، رنگ صرف‌نظر از مقدار TERM فعال خواهد شد. این ویژگی در سیستم‌های یکپارچه‌سازی مستمر (CI) که پایانه نیستند، اما همچنان می‌توانند دنباله‌های گریز ANSI را نمایش دهند، مفید است.

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

همه‌ی این متغیرهای محیطی همچنین توسط ابزارهای دیگر برای کنترل خروجی رنگی استفاده می‌شوند. برای کنترل خروجی رنگی فقط در مفسر پایتون، می‌توان از متغیر محیطی PYTHON_COLORS استفاده کرد. این متغیر بر NO_COLOR تقدم دارد که آن نیز به نوبه‌ی خود بر FORCE_COLOR تقدم دارد.

1.2. متغیرهای محیطی

این متغیرهای محیطی بر رفتار پایتون تأثیر می‌گذارند و پیش از سوییچ‌های خط فرمان (به‌جز -E و -I) پردازش می‌شوند. متعارف است که در صورت وجود تعارض، سوییچ‌های خط فرمان بر متغیرهای محیطی اولویت داشته باشند.

PYTHONHOME

مکان کتابخانه‌های استاندارد پایتون را تغییر می‌دهد. به‌طور پیش‌فرض، کتابخانه‌ها در prefix/lib/pythonversion و exec_prefix/lib/pythonversion جستجو می‌شوند که در آن‌ها prefix و exec_prefix پوشه‌هایی وابسته به نصب هستند و مقدار پیش‌فرض هر دو /usr/local است.

وقتی PYTHONHOME روی یک پوشه‌ی تنها تنظیم شود، مقدار آن جایگزین هر دو prefix و exec_prefix می‌شود. برای تعیین مقادیر متفاوت برای این دو، PYTHONHOME را روی prefix:exec_prefix تنظیم کنید.

PYTHONPATH

مسیر جستجوی پیش‌فرض برای پرونده‌های ماژول را گسترش می‌دهد. قالب آن همان قالب PATH در پوسته است: یک یا چند مسیرنام پوشه که با os.pathsep از هم جدا شده‌اند (مثلاً دونقطه در یونیکس یا نقطه‌ویرگول در ویندوز). پوشه‌های ناموجود بی‌سروصدا نادیده گرفته می‌شوند.

علاوه بر پوشه‌های معمولی، ورودی‌های منفرد PYTHONPATH ممکن است به پرونده‌های zip حاوی ماژول‌های خالص پایتون (چه به شکل کد منبع و چه کامپایل‌شده) اشاره کنند. ماژول‌های توسعه‌ای را نمی‌توان از پرونده‌های zip ایمپورت کرد.

مسیر جستجوی پیش‌فرض وابسته به نصب است، اما به‌طور کلی با prefix/lib/pythonversion آغاز می‌شود (به PYTHONHOME در بالا مراجعه کنید). این مسیر همیشه به PYTHONPATH الحاق می‌شود.

همان‌طور که در بالا در بخش گزینه‌های رابط توضیح داده شد، یک پوشه‌ی اضافی در مسیر جستجو، پیش از PYTHONPATH درج خواهد شد. مسیر جستجو را می‌توان از درون یک برنامه‌ی پایتون، به‌صورت متغیر sys.path، دستکاری کرد.

PYTHONSAFEPATH

اگر این مقدار به یک رشته‌ی غیرخالی تنظیم شده باشد، مسیری که به‌طور بالقوه ناامن است به ابتدای sys.path اضافه نمی‌شود: برای جزئیات به گزینه‌ی -P مراجعه کنید.

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

PYTHONPLATLIBDIR

اگر این روی یک رشته‌ی غیرخالی تنظیم شده باشد، مقدار sys.platlibdir را بازنویسی می‌کند.

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

PYTHONSTARTUP

اگر این نام یک پرونده‌ی خوانا باشد، دستورهای پایتون آن پرونده پیش از نمایش نخستین اعلان در حالت تعاملی اجرا می‌شوند. این پرونده در همان فضای نامی که دستورهای تعاملی در آن اجرا می‌شوند اجرا می‌شود تا بتوان از اشیایی که در آن تعریف یا ایمپورت شده‌اند، بدون نیاز به نام کامل در نشست تعاملی استفاده کرد. همچنین می‌توانید اعلان‌های sys.ps1 و sys.ps2 و قلاب sys.__interactivehook__ را در این پرونده تغییر دهید.

هنگامی که در زمان راه‌اندازی فراخوانی می‌شود، رویداد حسابرسی cpython.run_startup را با نام پرونده به عنوان آرگومان ایجاد می‌کند.

PYTHONOPTIMIZE

اگر این به یک رشته‌ی غیرخالی تنظیم شود، معادل مشخص کردن گزینه‌ی -O است. اگر به یک عدد صحیح تنظیم شود، معادل مشخص کردن گزینه‌ی -O به دفعات متعدد است.

PYTHONBREAKPOINT

اگر این تنظیم شده باشد، نام یک فراخوانی‌پذیر را با استفاده از نمادگذاری مسیر نقطه‌ای (dotted-path) مشخص می‌کند. ماژول حاوی فراخوانی‌پذیر ایمپورت خواهد شد و سپس فراخوانی‌پذیر توسط پیاده‌سازی پیش‌فرض sys.breakpointhook() اجرا خواهد شد که خود آن توسط breakpoint() توکار فراخوانی می‌شود. اگر تنظیم نشده باشد یا روی رشته خالی تنظیم شده باشد، معادل مقدار "pdb.set_trace" است. تنظیم این روی رشته "0" باعث می‌شود پیاده‌سازی پیش‌فرض sys.breakpointhook() هیچ کاری انجام ندهد و بلافاصله بازگردد.

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

PYTHONDEBUG

اگر این به یک رشته‌ی غیرخالی تنظیم شود، معادل تعیین گزینه‌ی -d است. اگر به یک عدد صحیح تنظیم شود، معادل این است که -d چندین بار تعیین شده باشد.

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

PYTHONINSPECT

اگر این به یک رشته‌ی غیرخالی تنظیم شده باشد، معادل تعیین گزینه‌ی -i است.

این متغیر را همچنین می‌توان با کد پایتون از طریق os.environ تغییر داد تا حالت بازرسی (inspect mode) هنگام خاتمه برنامه به‌اجبار فعال شود.

رویداد حسابرسی cpython.run_stdin را بدون هیچ آرگومانی ایجاد می‌کند.

تغییر یافته در نسخه‌ی 3.12.5: (همچنین 3.11.10، 3.10.15، 3.9.20 و 3.8.20) رویدادهای حسابرسی را منتشر می‌کند.

تغییر یافته در نسخه‌ی 3.13: در صورت امکان از PyREPL استفاده می‌کند، که در این صورت PYTHONSTARTUP نیز اجرا می‌شود. رویدادهای حسابرسی منتشر می‌کند.

PYTHONUNBUFFERED

اگر این روی رشته‌ای غیرخالی تنظیم شود، معادل مشخص کردن گزینه‌ی -u است.

PYTHONVERBOSE

اگر این روی یک رشته‌ی غیرخالی تنظیم شود، معادل مشخص کردن گزینه‌ی -v است. اگر روی یک عدد صحیح تنظیم شود، معادل مشخص کردن -v به دفعات متعدد است.

PYTHONCASEOK

اگر این تنظیم شده باشد، پایتون در دستورات import بزرگی و کوچکی حروف را نادیده می‌گیرد. این تنها در ویندوز و macOS کار می‌کند.

PYTHONDONTWRITEBYTECODE

اگر این به یک رشته‌ی غیرخالی تنظیم شود، پایتون هنگام ایمپورت ماژول‌های منبع تلاش نمی‌کند پرونده‌های .pyc را بنویسد. این معادل تعیین گزینه‌ی -B است.

PYTHONPYCACHEPREFIX

اگر این تنظیم شده باشد، پایتون پرونده‌های .pyc را به جای پوشه‌های __pycache__ درون درخت منبع، در یک درخت پوشه‌ی آینه‌ای در این مسیر می‌نویسد. این کار معادل تعیین گزینه‌ی -X pycache_prefix=PATH است.

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

PYTHONHASHSEED

اگر این متغیر تنظیم نشده باشد یا روی random تنظیم شده باشد، از یک مقدار تصادفی برای بذر دادن به هش‌های شیءهای str و bytes استفاده می‌شود.

اگر PYTHONHASHSEED به یک مقدار عدد صحیح تنظیم شده باشد، از آن به‌عنوان یک بذر ثابت برای تولید hash() نوع‌هایی که مشمول تصادفی‌سازی هش هستند، استفاده می‌شود.

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

عدد صحیح باید عددی در مبنای ده و در بازه‌ی [0,4294967295] باشد. تعیین مقدار 0، تصادفی‌سازی هش را غیرفعال می‌کند.

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

PYTHONINTMAXSTRDIGITS

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

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

PYTHONIOENCODING

اگر این پیش از اجرای مفسر تنظیم شود، کدگذاری استفاده‌شده برای stdin/stdout/stderr را نادیده می‌گیرد، با سینتکس encodingname:errorhandler. هر دو بخش encodingname و :errorhandler اختیاری هستند و همان معنایی را دارند که در str.encode() دارند.

برای stderr، بخش :errorhandler نادیده گرفته می‌شود؛ هندلر همیشه 'backslashreplace' خواهد بود.

تغییر یافته در نسخه‌ی 3.4: بخش encodingname اکنون اختیاری است.

تغییر یافته در نسخه‌ی 3.6: در ویندوز، کدگذاری تعیین‌شده توسط این متغیر برای بافرهای کنسول تعاملی نادیده گرفته می‌شود، مگر اینکه PYTHONLEGACYWINDOWSSTDIO نیز تعیین‌شده باشد. پرونده‌ها و پایپ‌هایی که از طریق جریان‌های استاندارد تغییر مسیر داده‌شده‌اند، تأثیر نمی‌پذیرند.

PYTHONNOUSERSITE

اگر این تنظیم شده باشد، پایتون پوشه‌ی site-packages کاربر را به sys.path اضافه نمی‌کند.

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

PEP 370 -- پوشه site-packages به ازای هر کاربر

PYTHONUSERBASE

پوشه‌ی پایه‌ی کاربر را تعریف می‌کند که برای محاسبه‌ی مسیر پوشه‌ی site-packages کاربر و مسیر‌های نصب برای python -m pip install --user استفاده می‌شود.

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

PEP 370 -- پوشه site-packages به ازای هر کاربر

PYTHONEXECUTABLE

اگر این متغیر محیطی تنظیم شده باشد، sys.argv[0] به‌جای مقداری که از ران‌تایم C به دست می‌آید، به مقدار آن تنظیم می‌شود. فقط روی macOS کار می‌کند.

PYTHONWARNINGS

این معادل گزینه‌ی -W است. اگر به یک رشته‌ی جداشده با کاما تنظیم شود، معادل مشخص کردن -W به دفعات متعدد است، به‌طوری که فیلترهای انتهای فهرست بر فیلترهای ابتدای فهرست اولویت دارند.

ساده‌ترین تنظیمات، یک اکشن خاص را بدون قید و شرط به تمام هشدارهایی که توسط یک فرایند منتشر می‌شوند اعمال می‌کنند (حتی هشدارهایی که در غیر این صورت به‌طور پیش‌فرض نادیده گرفته می‌شوند):

PYTHONWARNINGS=default  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
PYTHONWARNINGS=all      # Same as PYTHONWARNINGS=always
PYTHONWARNINGS=module   # Warn once per calling module
PYTHONWARNINGS=once     # Warn once per Python process
PYTHONWARNINGS=ignore   # Never warn

برای جزئیات بیشتر به فیلتر هشدارها و توصیف پالایه‌های هشدار مراجعه کنید.

PYTHONFAULTHANDLER

اگر این متغیر محیطی به یک رشته‌ی غیرخالی تنظیم شده باشد، faulthandler.enable() در زمان راه‌اندازی فراخوانی می‌شود: یک هندلر برای سیگنال‌های SIGSEGV، SIGFPE، SIGABRT، SIGBUS و SIGILL نصب می‌کند تا ردگیری پایتون برون‌ریزی شود. این کار معادل گزینه‌ی -X faulthandler است.

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

PYTHONTRACEMALLOC

اگر این متغیر محیطی به یک رشته‌ی غیرخالی تنظیم شده باشد، ردگیری تخصیص‌های حافظه‌ی پایتون با استفاده از ماژول tracemalloc آغاز می‌شود. مقدار این متغیر، حداکثر تعداد فریم‌های ذخیره‌شده در ردگیریِ یک ردیابی است. برای مثال، PYTHONTRACEMALLOC=1 فقط جدیدترین فریم را ذخیره می‌کند. برای اطلاعات بیشتر، تابع tracemalloc.start() را ببینید. این کار معادل تنظیم گزینه‌ی -X tracemalloc است.

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

PYTHONPROFILEIMPORTTIME

اگر این متغیر محیطی روی 1 تنظیم شود، پایتون نشان می‌دهد که هر ایمپورت چقدر طول می‌کشد. اگر روی 2 تنظیم شود، پایتون خروجی مربوط به ماژول‌های ایمپورت‌شده‌ای را که از قبل بارگذاری شده‌اند نیز در بر می‌گیرد. این کار معادل تنظیم گزینه‌ی -X importtime است.

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

تغییر یافته در نسخه‌ی 3.14: افزوده شد PYTHONPROFILEIMPORTTIME=2 تا ایمپورت‌های ماژول‌های بارگذاری‌شده نیز ردگیری شوند.

PYTHONASYNCIODEBUG

اگر این متغیر محیطی روی یک رشته‌ی غیرخالی تنظیم شده باشد، حالت اشکال‌زدایی ماژول asyncio را فعال کنید.

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

PYTHONMALLOC

تنظیم تخصیص‌دهنده‌های حافظه پایتون و/یا نصب قلاب‌های اشکال‌زدایی.

خانواده‌ی تخصیص‌دهنده‌های حافظه‌ی مورد استفاده‌ی پایتون را تنظیم می‌کند:

• default: استفاده از تخصیص‌دهنده‌های حافظه پیش‌فرض.

• malloc: استفاده از تابع malloc() کتابخانه C برای همه دامنه‌ها (PYMEM_DOMAIN_RAW، PYMEM_DOMAIN_MEM، PYMEM_DOMAIN_OBJ).

• pymalloc: از تخصیص‌دهنده‌ی pymalloc برای حوزه‌های PYMEM_DOMAIN_MEM و PYMEM_DOMAIN_OBJ استفاده کنید و از تابع malloc() برای حوزه‌ی PYMEM_DOMAIN_RAW استفاده کنید.

• mimalloc: از تخصیص‌دهنده‌ی mimalloc برای دامنه‌های PYMEM_DOMAIN_MEM و PYMEM_DOMAIN_OBJ استفاده کنید و از تابع malloc() برای دامنه‌ی PYMEM_DOMAIN_RAW استفاده کنید.

نصب قلاب‌های اشکال‌زدایی:

• debug: نصب قلاب‌های اشکال‌زدایی روی تخصیص‌دهنده‌های پیش‌فرض حافظه.

• malloc_debug: مانند malloc است، اما قلاب‌های اشکال‌زدایی را نیز نصب می‌کند.

• pymalloc_debug: همان pymalloc است، اما قلاب‌های اشکال‌زدایی را نیز نصب می‌کند.

• mimalloc_debug: مانند mimalloc است، اما قلاب‌های اشکال‌زدایی را نیز نصب می‌کند.

توجه

در ساخت‌ نخ‌آزاد، مقادیر malloc، malloc_debug، pymalloc و pymalloc_debug پشتیبانی نمی‌شوند. فقط default، debug، mimalloc و mimalloc_debug پذیرفته می‌شوند.

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

تغییر یافته در نسخه‌ی 3.7: تخصیص‌دهنده "default" افزوده شد.

PYTHONMALLOCSTATS

اگر روی یک رشته‌ی غیرخالی تنظیم شود، پایتون هر بار که یک آرنا‌ی شیء (object arena) جدید ایجاد می‌شود و هنگام خاموش شدن، آمار تخصیص‌دهنده‌ی حافظه‌ی pymalloc یا تخصیص‌دهنده‌ی حافظه‌ی mimalloc (هر کدام که در حال استفاده است) را چاپ می‌کند.

اگر متغیر محیطی PYTHONMALLOC برای اجبار به استفاده از تخصیص‌دهنده malloc() کتابخانه C به کار رود، یا اگر پایتون بدون پشتیبانی از هر دو pymalloc و mimalloc پیکربندی شده باشد، این متغیر نادیده گرفته می‌شود.

تغییر یافته در نسخه‌ی 3.6: اکنون می‌توان از این متغیر روی پایتون کامپایل‌شده در حالت انتشار نیز استفاده کرد. اکنون اگر روی رشته‌ی خالی تنظیم شود، هیچ اثری نخواهد داشت.

PYTHONLEGACYWINDOWSFSENCODING

اگر روی رشته‌ای غیرخالی تنظیم شود، حالت پیش‌فرض filesystem encoding and error handler به‌ترتیب به مقادیر پیش از 3.6 خود یعنی 'mbcs' و 'replace' بازمی‌گردد. در غیر این صورت، پیش‌فرض‌های جدید 'utf-8' و 'surrogatepass' استفاده می‌شوند.

همچنین می‌توان این را در زمان اجرا با sys._enablelegacywindowsfsencoding() فعال کرد.

دسترس‌پذیری: Windows.

اضافه شده در نسخه‌ی 3.6: برای جزئیات بیشتر به PEP 529 مراجعه کنید.

PYTHONLEGACYWINDOWSSTDIO

اگر روی رشته‌ای غیر‌خالی تنظیم شود، از خواننده و نویسنده‌ی جدید کنسول استفاده نمی‌شود. این بدان معناست که نویسه‌های یونیکد بر اساس صفحه‌ی کد فعال کنسول کدگذاری می‌شوند، نه با استفاده از utf-8.

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

دسترس‌پذیری: Windows.

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

PYTHONCOERCECLOCALE

اگر روی مقدار 0 تنظیم شود، باعث می‌شود برنامه اصلی خط فرمان پایتون از تبدیل اجباری localeهای قدیمی C و POSIX مبتنی بر اسکی به جایگزین توانمندتری مبتنی بر UTF-8 صرف‌نظر کند.

اگر این متغیر تنظیم نشده باشد (یا روی مقداری غیر از 0 تنظیم شده باشد)، متغیر محیطی بازنویسی locale با نام LC_ALL نیز تنظیم نشده باشد، و locale فعلی گزارش‌شده برای دسته‌ی LC_CTYPE یا locale پیش‌فرض C باشد یا locale POSIX که صریحاً مبتنی بر اسکی است، آنگاه رابط خط فرمان پایتون پیش از بارگذاری ران‌تایم مفسر تلاش می‌کند locale‌های زیر را به ترتیب فهرست‌شده برای دسته‌ی LC_CTYPE پیکربندی کند:

• C.UTF-8

• C.utf8

• UTF-8

اگر تنظیم یکی از این دسته‌های locale با موفقیت انجام شود، متغیر محیطی LC_CTYPE نیز پیش از مقداردهی اولیه‌ی ران‌تایم پایتون، به‌طور متناسب در محیط فرایند فعلی تنظیم خواهد شد. این تضمین می‌کند که تنظیم به‌روزرسانی‌شده، علاوه بر اینکه توسط خودِ مفسر و دیگر کامپوننت‌های آگاه از locale که در همان فرایند اجرا می‌شوند (مانند کتابخانه‌ی GNU readline) دیده می‌شود، در زیرفرایندها (صرف‌نظر از اینکه آن فرایندها در حال اجرای مفسر پایتون هستند یا خیر) و همچنین در عملیاتی که به‌جای locale فعلی C از محیط استعلام می‌کنند (مانند تابع locale.getdefaultlocale() خودِ پایتون) نیز دیده خواهد شد.

پیکربندی یکی از این locale‌ها (چه به‌طور صریح و چه از طریق تبدیل ضمنی locale ذکرشده در بالا) به‌طور خودکار هندلر خطای surrogateescape را برای sys.stdin و sys.stdout فعال می‌کند (sys.stderr مانند هر locale دیگری همچنان از backslashreplace استفاده می‌کند). این رفتار مدیریت جریان را می‌توان، همان‌طور که معمول است، با استفاده از PYTHONIOENCODING بازنویسی کرد.

برای مقاصد اشکال‌زدایی، تنظیم PYTHONCOERCECLOCALE=warn باعث می‌شود پایتون در صورتی که اجبار locale فعال شود، یا در صورتی که locale‌ای که باید موجب اجبار می‌شد، هنوز هنگام راه‌اندازی ران‌تایم پایتون فعال باشد، پیام‌های هشدار را در stderr منتشر کند.

همچنین توجه داشته باشید که حتی وقتی تغییر اجباری locale (locale coercion) غیرفعال باشد، یا وقتی نتواند locale هدف مناسبی بیابد، PYTHONUTF8 همچنان به‌صورت پیش‌فرض در locale‌های قدیمی مبتنی بر اسکی فعال می‌شود. برای وادار کردن مفسر به استفاده از ASCII به‌جای UTF-8 در رابط‌های سیستمی، باید هر دو ویژگی غیرفعال شوند.

دسترس‌پذیری: Unix.

اضافه شده در نسخه‌ی 3.7: برای جزئیات بیشتر به PEP 538 مراجعه کنید.

PYTHONDEVMODE

اگر این متغیر محیطی به یک رشته‌ی غیرخالی تنظیم شود، حالت توسعه پایتون فعال می‌شود که بررسی‌های اضافی زمان اجرا را معرفی می‌کند؛ بررسی‌هایی که به دلیل پرهزینه بودن، به‌طور پیش‌فرض فعال نمی‌شوند. این کار معادل تنظیم گزینه‌ی -X dev است.

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

PYTHONUTF8

اگر روی 1 تنظیم شود، حالت UTF-8 پایتون را فعال می‌کند.

اگر روی 0 تنظیم شود، حالت UTF-8 پایتون غیرفعال می‌شود.

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

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

PYTHONWARNDEFAULTENCODING

اگر این متغیر محیطی به یک رشته‌ی غیرخالی تنظیم شده باشد، هنگامی که کدگذاری پیش‌فرض مخصوص locale استفاده می‌شود، EncodingWarning صادر می‌شود.

برای جزئیات به فعال‌سازی اختیاری هشدار کدگذاری (EncodingWarning) مراجعه کنید.

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

PYTHONNODEBUGRANGES

اگر این متغیر تنظیم شده باشد، گنجاندن جدول‌هایی را غیرفعال می‌کند که اطلاعات مکان اضافی (سطر پایانی، آفست ستون آغازین و آفست ستون پایانی) را به هر دستورالعمل در اشیاء کد نگاشت می‌کنند. این مورد زمانی مفید است که اشیاء کد و پرونده‌های pyc کوچک‌تر مطلوب باشند، و همچنین برای سرکوب نشانگرهای بصری مکان اضافی هنگامی که مفسر ردگیری‌ها را نمایش می‌دهد.

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

PYTHONPERFSUPPORT

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

اگر روی 0 تنظیم شود، پشتیبانی از پروفایل‌گیر perf لینوکس را غیرفعال می‌کند.

همچنین گزینه‌ی خط فرمان -X perf و پشتیبانی پایتون از پروفایل‌گیر perf لینوکس را ببینید.

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

PYTHON_PERF_JIT_SUPPORT

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

اگر روی 0 تنظیم شود، پشتیبانی از پروفایل‌گیر perf لینوکس را غیرفعال می‌کند.

همچنین گزینه‌ی خط فرمان -X perf_jit و پشتیبانی پایتون از پروفایل‌گیر perf لینوکس را ببینید.

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

PYTHON_DISABLE_REMOTE_DEBUG

اگر این متغیر به رشته‌ای غیرخالی تنظیم شده باشد، قابلیت اشکال‌زدایی از راه دورِ توصیف‌شده در PEP 768 را غیرفعال می‌کند. این شامل هر دو کارکرد زمان‌بندی کد برای اجرا در فرایندی دیگر و کارکرد دریافت کد برای اجرا در فرایند جاری است.

همچنین گزینه‌ی خط فرمان -X disable_remote_debug را ببینید.

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

PYTHON_CPU_COUNT

اگر این متغیر روی یک عدد صحیح مثبت تنظیم‌شده باشد، مقادیر بازگشتی os.cpu_count() و os.process_cpu_count() را بازنویسی می‌کند.

همچنین گزینه‌ی خط فرمان -X cpu_count را ببینید.

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

PYTHON_FROZEN_MODULES

اگر این متغیر روی on یا off تنظیم شده باشد، تعیین می‌کند که آیا ماژول‌های فریزشده توسط سازوکار ایمپورت نادیده گرفته شوند یا خیر. مقدار on به این معنی است که آن‌ها ایمپورت می‌شوند و off به این معنی است که نادیده گرفته می‌شوند. مقدار پیش‌فرض برای ساخت‌های غیردیباگ (حالت معمول) on و برای ساخت‌های دیباگ off است. توجه داشته باشید که ماژول‌های فریزشده importlib_bootstrap و importlib_bootstrap_external همیشه استفاده می‌شوند، حتی اگر این پرچم روی off تنظیم شده باشد.

همچنین گزینه‌ی خط فرمان -X frozen_modules را ببینید.

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

PYTHON_COLORS

اگر این متغیر روی 1 تنظیم شود، مفسر انواع مختلفی از خروجی را رنگ‌آمیزی می‌کند. تنظیم آن روی 0 این رفتار را غیرفعال می‌کند. همچنین ببینید کنترل رنگ.

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

PYTHON_BASIC_REPL

اگر این متغیر به هر مقداری تنظیم شده باشد، مفسر تلاش نخواهد کرد REPL مبتنی بر پایتون را که به readline نیاز دارد بارگذاری کند، و در عوض از REPL سنتی مبتنی بر پارسر استفاده خواهد کرد.

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

PYTHON_HISTORY

از این متغیر محیطی می‌توان برای تعیین مکان پرونده .python_history استفاده کرد (به‌طور پیش‌فرض، این پرونده .python_history در پوشه خانگی کاربر است).

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

PYTHON_GIL

اگر این متغیر روی 1 تنظیم شود، قفل مفسر سراسری (GIL) به‌اجبار فعال خواهد شد. تنظیم آن روی 0 قفل مفسر سراسری را به‌اجبار غیرفعال می‌کند (نیازمند آن است که پایتون با گزینه‌ی ساخت --disable-gil پیکربندی‌شده باشد).

همچنین گزینه‌ی خط فرمان -X gil را ببینید که نسبت به این متغیر اولویت دارد، و سی‌پایتون نخ‌آزاد.

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

PYTHON_THREAD_INHERIT_CONTEXT

اگر این متغیر روی 1 تنظیم شده باشد، Thread به‌طور پیش‌فرض هنگام شروع، از رونوشتی از زمینه‌ی فراخواننده‌ی Thread.start() استفاده خواهد کرد. در غیر این صورت، نخ‌های جدید با زمینه‌ی خالی شروع خواهند شد. اگر این متغیر تنظیم نشده باشد، مقدار پیش‌فرض آن در ساخت‌های نخ‌آزاد 1 و در غیر این صورت 0 خواهد بود. همچنین گزینه‌ی -X thread_inherit_context را ببینید.

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

PYTHON_CONTEXT_AWARE_WARNINGS

اگر روی 1 تنظیم شده باشد، مدیر زمینه‌ی warnings.catch_warnings برای ذخیره‌سازی وضعیت فیلتر هشدارها از یک ContextVar استفاده خواهد کرد. اگر تنظیم نشده باشد، مقدار پیش‌فرض این متغیر در ساخت‌های نخ‌آزاد 1 و در غیر این صورت 0 است. به -X context_aware_warnings مراجعه کنید.

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

PYTHON_JIT

در ساخت‌هایی (builds) که کامپایل در لحظه (JIT) به‌صورت آزمایشی در دسترس است، این متغیر می‌تواند JIT را هنگام راه‌اندازی مفسر به‌اجبار غیرفعال (0) یا فعال (1) کند.

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

PYTHON_TLBC

اگر روی 1 تنظیم شود، بایت‌کد نخ‌محلی فعال می‌شود. اگر روی 0 تنظیم شود، بایت‌کد نخ‌محلی و مفسر ویژه‌ساز (specializing interpreter) غیرفعال می‌شوند. تنها در ساخت‌هایی که با --disable-gil پیکربندی شده‌اند اعمال می‌شود.

همچنین گزینه‌ی خط فرمان -X tlbc را ببینید.

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

1.2.1. متغیرهای حالت اشکال‌زدایی

PYTHONDUMPREFS

در صورت تنظیم، پایتون پس از خاموش کردن مفسر، اشیاء و شمارش ارجاعِ همچنان زنده را برون‌ریزی می‌کند.

نیازمند پایتونی است که با گزینه‌ی ساخت --with-trace-refs پیکربندی‌شده باشد.

PYTHONDUMPREFSFILE

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

نیازمند پایتونی است که با گزینه‌ی ساخت --with-trace-refs پیکربندی‌شده باشد.

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

PYTHON_PRESITE

اگر این متغیر به یک ماژول تنظیم شده باشد، آن ماژول در اوایل چرخه حیات مفسر ایمپورت می‌شود؛ پیش از آنکه ماژول site اجرا شود و پیش از آنکه ماژول __main__ ایجاد شود. بنابراین، ماژول ایمپورت‌شده به عنوان __main__ در نظر گرفته نمی‌شود.

از این می‌توان برای اجرای کد در مراحل اولیه‌ی راه‌اندازی پایتون استفاده کرد.

برای ایمپورت کردن یک زیرماژول، مانند دستور ایمپورت، از package.module به‌عنوان مقدار استفاده کنید.

همچنین گزینه‌ی خط فرمان -X presite را ببینید که بر این متغیر اولویت دارد.

نیازمند پایتونی است که با گزینه‌ی ساخت --with-pydebug پیکربندی‌شده باشد.

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