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 مراجعه کنید).

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 تأثیر می‌گذارد.

منسوخ شده از نسخه‌ی 3.15: گزینه‌های خط فرمان -b و -bb منسوخ شده و زمان‌بندی شده‌اند تا در پایتون 3.17 به عملیات بی‌اثر تبدیل شوند. این گزینه‌ها در اصل کمکی برای گذار از پایتون ۲ به ۳ بودند. از پایتون 3.17 به بعد، هیچ BytesWarning برای این موارد ایجاد نخواهد شد؛ به جای آن از یک بررسی‌کننده نوع استفاده کنید.

-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 اضافه نکنید:

همچنین متغیر محیطی 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). این باید یک نام کلاس باشد؛ این مطابقت بررسی می‌کند که آیا دسته‌ی هشدار واقعی پیام، زیرکلاسی از دسته‌ی هشدار مشخص‌شده است یا خیر.

فیلد module با نام ماژول (به‌طور کامل واجد شرایط) مطابقت دارد؛ این تطابق به بزرگی و کوچکی حروف حساس است. اگر با یک اسلش (/) شروع و تمام شود، یک عبارت باقاعده را مشخص می‌کند که ابتدای نام ماژولِ کامل باید با آن مطابقت داشته باشد، در غیر این صورت یک رشته‌ی لفظی را مشخص می‌کند که نام ماژولِ کامل باید با آن برابر باشد.

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

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

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

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

تغییر یافته در نسخه‌ی 3.15: پشتیبانی از عبارت باقاعده برای message و module اضافه شد.

-x¶

از سطر اول منبع بگذرید، که امکان استفاده از فرم‌های غیریونیکس #!cmd را می‌دهد.

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

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

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

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

برخلاف خط مفسر که یک کامنت پایتون است، این سطر سینتکس معتبر پایتون نیست، و گزینه -x برای رد کردن آن لازم است.

-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 map را ببینید.

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

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

  اضافه شده در نسخه‌ی 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=module یا -X presite=module:func یک نقطه‌ی ورود را مشخص می‌کند که باید پیش از اجرای ماژول site و پیش از ایجاد ماژول __main__ اجرا شود. بنابراین، ماژول واردشده __main__ نیست. از این گزینه می‌توان برای اجرای زودهنگام کد در جریان مقداردهی اولیه‌ی پایتون استفاده کرد. برای در دسترس بودن این گزینه، پایتون باید در حالت اشکال‌زدایی ساخته شده باشد. همچنین PYTHON_PRESITE را ببینید.

  تغییر یافته در نسخه‌ی 3.15: همچنین فرمت نقطه‌ی ورودی module:func را بپذیرید.

  اضافه شده در نسخه‌ی 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 pathconfig_warnings=0,1 اگر درست باشد (1) آنگاه مقداردهی اولیه‌ی مسیر جستجوی ماژول sys.path مجاز است هشدارها را در stderr ثبت کند. اگر نادرست باشد (0) این هشدارها را سرکوب کنید. به طور پیش‌فرض روی درست تنظیم شده است. همچنین ببینید PYTHON_PATHCONFIG_WARNINGS.

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

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

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

• -X lazy_imports=all,normal رفتار ایمپورت تنبل را کنترل می‌کند. مقدار all تمام ایمپورت‌ها را به طور پیش‌فرض تنبل می‌کند، و normal (پیش‌فرض) به کلیدواژه lazy در کد منبع احترام می‌گذارد. همچنین ببینید PYTHON_LAZY_IMPORTS.

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

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

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

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

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

1.1.4. کنترل رنگ¶

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

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

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

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

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

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.15: همچنین فرمت نقطه‌ی ورودی module:func را بپذیرید.

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