sys --- پارامترها و توابع مختص سیستم¶

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

sys.abi_info¶

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

شیءای حاوی اطلاعات درباره‌ی رابط دودویی کاربردی (ABI) مفسر در حال اجرای پایتون. این شیء باید شامل اطلاعاتی باشد که روی رابط دودویی کاربردی سی‌پایتون (CPython ABI) به انحایی تأثیر می‌گذارند که نیازمند ساخت (build) خاصی از مفسرِ انتخاب‌شده از میان انواعِ توانمندِ همزیست روی یک ماشین واحد است. برای مثال، سیستم‌عامل پایه (لینوکس یا ویندوز) را رمزگذاری نمی‌کند، اما اندازه‌ی اشاره‌گر را شامل می‌شود زیرا برخی سیستم‌ها از هر دو ساخت ۳۲ بیتی و ۶۴ بیتی پشتیبانی می‌کنند. مدخل‌های موجود در تمام سکوها یکسان هستند؛ برای مثال pointer_size حتی روی معماری‌های فقط ۶۴ بیتی نیز در دسترس است.

ویژگی‌های زیر در دسترس هستند:

abi_info.pointer_bits¶

عرض اشاره‌گرها بر حسب بیت، به شکل یک عدد صحیح، معادل 8 * sizeof(void *). معمولاً این مقدار 32 یا 64 است.

abi_info.free_threaded¶

یک مقدار بولی که نشان می‌دهد آیا مفسر با پشتیبانی از نخ‌بندی آزاد ساخته شده است یا خیر. این مورد بازتاب‌دهنده‌ی حضور گزینه‌ی configure به شکل --disable-gil (در یونیکس) یا تنظیم ویژگی DisableGil (در ویندوز) است.

abi_info.debug¶

یک مقدار بولی که نشان می‌دهد آیا مفسر در حالت رفع اشکال ساخته شده است یا خیر. این مورد بازتاب‌دهنده‌ی حضور گزینه‌ی configure به شکل --with-pydebug (در یونیکس) یا پیکربندی Debug (در ویندوز) است.

abi_info.byteorder¶

رشته‌ای که ترتیب بایت بومی (native byte order)، یعنی 'big' یا 'little' را مشخص می‌کند. این ویژگی همانند ویژگی byteorder است.

sys.abiflags¶

در سیستم‌های POSIX که پایتون با اسکریپت استاندارد configure ساخته شده است، این شامل پرچم‌های ABI می‌شود، همان‌طور که در PEP 3149 مشخص شده است.

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

تغییر یافته در نسخه‌ی 3.8: پرچم‌های پیش‌فرض به یک رشته خالی تبدیل شدند (پرچم m برای pymalloc حذف شده است).

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

sys.addaudithook(hook)¶

hook فراخوانی‌پذیر را به فهرست قلاب‌های حسابرسی فعال برای (زیر)مفسر جاری می‌افزاید.

هنگامی که یک رویداد حسابرسی از طریق تابع sys.audit() پرتاب می‌شود، هر قلاب به ترتیبی که اضافه‌شده است، با نام رویداد و تاپل آرگومان‌ها فراخوانی می‌شود. قلاب‌های بومی اضافه‌شده توسط PySys_AddAuditHook() ابتدا فراخوانی می‌شوند و پس از آن‌ها، قلاب‌های اضافه‌شده در (زیر)مفسر جاری فراخوانی می‌شوند. سپس قلاب‌ها می‌توانند رویداد را ثبت کنند، استثنایی را برای لغو عملیات پرتاب کنند، یا فرایند را به‌طور کامل خاتمه دهند.

توجه داشته باشید که قلاب‌های حسابرسی (audit hooks) عمدتاً برای جمع‌آوری اطلاعات درباره اعمال داخلی یا اعمالی که به‌طریق دیگر قابل مشاهده نیستند، چه از سوی پایتون و چه از سوی کتابخانه‌های نوشته‌شده با پایتون، به کار می‌روند. آن‌ها برای پیاده‌سازی یک «سندباکس» مناسب نیستند. به‌ویژه، کد مخرب می‌تواند به‌سادگی قلاب‌های اضافه‌شده با این تابع را غیرفعال یا دور بزند. دست‌کم، هر قلاب حساس از نظر امنیتی باید پیش از مقداردهی اولیه ران‌تایم با استفاده از C API یعنی PySys_AddAuditHook() اضافه شود، و هر ماژولی که امکان تغییر دلخواه حافظه را فراهم می‌کند (مانند ctypes) باید به‌طور کامل حذف شود یا به‌دقت پایش شود.

فراخوانی sys.addaudithook() به‌خودی‌خود یک رویداد حسابرسی به نام sys.addaudithook را بدون آرگومان پرتاب می‌کند. اگر هر یک از قلاب‌های موجود استثنایی مشتق‌شده از RuntimeError را پرتاب کنند، قلاب جدید اضافه نخواهد شد و استثنا مهار خواهد شد. در نتیجه، فراخوانندگان نمی‌توانند فرض کنند که قلاب آن‌ها اضافه شده است، مگر اینکه همه قلاب‌های موجود را کنترل کنند.

برای همه‌ی رویدادهای پرتاب‌شده از سوی CPython، جدول رویدادهای حسابرسی و برای بحث طراحی اصلی، PEP 578 را ببینید.

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

تغییر یافته در نسخه‌ی 3.8.1: استثناهایی که از Exception مشتق شده‌اند، اما از RuntimeError مشتق نشده‌اند، دیگر سرکوب نمی‌شوند.

هنگامی که ردگیری فعال شده باشد (به settrace() مراجعه کنید)، قلاب‌های پایتون (hooks) تنها در صورتی ردگیری می‌شوند که شیء فراخوانی‌پذیر دارای یک عضو __cantrace__ باشد که روی یک مقدار درست تنظیم شده باشد. در غیر این صورت، توابع ردگیری از قلاب می‌گذرند.

sys.argv¶

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

برای حلقه زدن روی ورودی استاندارد، یا فهرست پرونده‌های داده‌شده در خط فرمان، ماژول fileinput را ببینید.

همچنین sys.orig_argv را ببینید.

نکته

در یونیکس، آرگومان‌های خط فرمان به‌صورت بایت از سوی سیستم‌عامل منتقل می‌شوند. پایتون آن‌ها را با کدگذاری سامانه فایل‌بندی و هندلر خطای "surrogateescape" کدگشایی می‌کند. وقتی به بایت‌های اصلی نیاز دارید، می‌توانید آن‌ها را با [os.fsencode(arg) for arg in sys.argv] دریافت کنید.

sys.audit(event, *args)¶

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

برای مثال، یک رویداد حسابرسی os.chdir نام دارد. این رویداد یک آرگومان به نام path دارد که شامل پوشه کاری جدید درخواست‌شده خواهد بود.

sys.audit() قلاب‌های حسابرسی موجود را فراخوانی می‌کند، نام رویداد و آرگومان‌ها را به آن‌ها منتقل می‌کند و نخستین استثنای پرتاب‌شده از سوی هر یک از قلاب‌ها را دوباره پرتاب می‌کند. به‌طور کلی، اگر استثنایی پرتاب شد، نباید آن را مدیریت کرد و فرایند باید تا حد ممکن به‌سرعت خاتمه یابد. این امکان را به پیاده‌سازی‌های قلاب می‌دهد تا تصمیم بگیرند چگونه به رویدادهای خاص پاسخ دهند: آن‌ها می‌توانند صرفاً رویداد را ثبت کنند یا عملیات را با پرتاب یک استثنا متوقف کنند.

قلاب‌ها (hooks) با استفاده از توابع sys.addaudithook() یا PySys_AddAuditHook() افزوده می‌شوند.

معادل بومی این تابع PySys_Audit() است. در صورت امکان، استفاده از تابع بومی ترجیح دارد.

برای مشاهده همه رویدادهای پرتاب‌شده توسط CPython، به جدول رویدادهای حسابرسی مراجعه کنید.

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

sys.base_exec_prefix¶

معادل exec_prefix است، اما به نصب پایه‌ی پایتون اشاره دارد.

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

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

sys.base_prefix¶

معادل prefix است، اما به نصب پایه‌ی پایتون اشاره می‌کند.

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

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

sys.byteorder¶

نشانگری از ترتیب بایت بومی. این نشانگر در سکوهای بزرگ‌اندیان (big-endian، بایت با بیشترین اهمیت در ابتدا) دارای مقدار 'big' و در سکوهای کوچک‌اندیان (little-endian، بایت با کمترین اهمیت در ابتدا) دارای مقدار 'little' خواهد بود.

sys.builtin_module_names¶

تاپلی از رشته‌ها که شامل نام تمام ماژول‌های کامپایل‌شده در این مفسر پایتون است. (این اطلاعات به هیچ روش دیگری در دسترس نیست --- modules.keys() فقط ماژول‌های ایمپورت‌شده را فهرست می‌کند.)

همچنین فهرست sys.stdlib_module_names را ببینید.

sys.call_tracing(func, args)¶

func(*args) را، در حالی که ردگیری فعال است، فراخوانی می‌کند. وضعیت ردگیری ذخیره می‌شود و پس از آن بازیابی می‌شود. این برای فراخوانی از یک اشکال‌زدا از یک نقطه بازرسی (checkpoint) در نظر گرفته شده است، تا بتوان کد دیگری را به‌صورت بازگشتی اشکال‌زدایی یا پروفایل (profile) کرد.

ردگیری هنگام فراخوانی تابع ردگیری تنظیم‌شده توسط settrace() یا setprofile()، معلق می‌شود تا از بازگشت بی‌نهایت جلوگیری شود. call_tracing() بازگشت صریح تابع ردگیری را فعال می‌کند.

sys.copyright¶

رشته‌ای شامل حق نشر مربوط به مفسر پایتون.

sys._clear_type_cache()¶

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

این تابع باید تنها برای اهداف داخلی و تخصصی استفاده شود.

منسوخ شده از نسخه‌ی 3.13: به‌جای آن از تابع عمومی‌تر _clear_internal_caches() استفاده کنید.

sys._clear_internal_caches()¶

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

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

sys._current_frames()¶

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

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

این تابع باید تنها برای اهداف داخلی و تخصصی استفاده شود.

یک رویداد حسابرسی sys._current_frames را بدون آرگومان پرتاب می‌کند.

sys._current_exceptions()¶

یک دیکشنری برمی‌گرداند که شناسه‌ی هر نخ را به بالاترین استثنای فعال در آن نخ در زمان فراخوانی تابع نگاشت می‌کند. اگر نخی در حال حاضر در حال مدیریت یک استثنا نباشد، در دیکشنری نتیجه گنجانده نمی‌شود.

این بیشترین کاربرد را در پروفایل‌گیری آماری دارد.

این تابع باید تنها برای اهداف داخلی و تخصصی استفاده شود.

یک رویداد حسابرسی sys._current_exceptions را بدون آرگومان پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.12: هر مقدار در دیکشنری اکنون یک نمونه استثنای واحد است، نه یک ۳-تایی (3-tuple) مانند آنچه از sys.exc_info() برگردانده می‌شود.

sys.breakpointhook()¶

این تابع قلاب توسط breakpoint() توکار فراخوانی می‌شود. به‌طور پیش‌فرض، شما را در اشکال‌زدا pdb قرار می‌دهد، اما می‌توان آن را روی هر تابع دیگری تنظیم کرد تا بتوانید انتخاب کنید کدام اشکال‌زدا استفاده می‌شود.

امضای این تابع به آنچه فراخوانی می‌کند وابسته است. برای مثال، اتصال پیش‌فرض (مثلاً pdb.set_trace()) هیچ آرگومانی نمی‌پذیرد، اما ممکن است آن را به تابعی مقید کنید که آرگومان‌های اضافی (جایگاهی و/یا کلیدواژه‌ای) می‌پذیرد. تابع توکار breakpoint()، *args و **kws خود را مستقیماً منتقل می‌کند. هر چه breakpointhooks() برگرداند، از breakpoint() برگردانده می‌شود.

پیاده‌سازی پیش‌فرض ابتدا متغیر محیطی PYTHONBREAKPOINT را بررسی می‌کند. اگر این متغیر روی "0" تنظیم شده باشد، این تابع بلافاصله برمی‌گردد؛ یعنی یک عملیات بی‌اثر (no-op) است. اگر متغیر محیطی تنظیم نشده باشد، یا روی رشته خالی تنظیم شده باشد، pdb.set_trace() فراخوانی می‌شود. در غیر این صورت، این متغیر باید با استفاده از نام‌گذاری ایمپورت نقطه‌دار پایتون، نام تابعی را برای اجرا مشخص کند؛ برای مثال package.subpackage.module.function. در این حالت، package.subpackage.module ایمپورت می‌شود و ماژول حاصل باید یک شیء قابل فراخوانی به نام function() داشته باشد. این تابع اجرا می‌شود، در حالی که *args و **kws به آن ارسال می‌شوند، و هر چه function() برگرداند، sys.breakpointhook() همان را به تابع توکار breakpoint() برمی‌گرداند.

توجه داشته باشید که اگر هنگام ایمپورت شیء فراخوانی‌پذیر مشخص‌شده توسط PYTHONBREAKPOINT مشکلی پیش بیاید، یک RuntimeWarning گزارش داده می‌شود و نقطه توقف نادیده گرفته می‌شود.

همچنین توجه داشته باشید که اگر sys.breakpointhook() به‌صورت برنامه‌ای بازنویسی شود، به PYTHONBREAKPOINT مراجعه نمی‌شود.

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

sys._debugmallocstats()¶

اطلاعات سطح پایین را درباره وضعیت تخصیص‌دهنده حافظه CPython در stderr چاپ می‌کند.

اگر پایتون در حالت اشکال‌زدایی ساخته‌شده باشد (configure --with-pydebug option)، همچنین برخی بررسی‌های پرهزینه‌ی سازگاری درونی را نیز انجام می‌دهد.

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

این تابع مختص CPython است. قالب دقیق خروجی در اینجا تعریف نشده است و ممکن است تغییر کند.

sys.dllhandle¶

عدد صحیحی که دسته DLL پایتون را مشخص می‌کند.

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

sys.displayhook(value)¶

اگر value None نباشد، این تابع repr(value) را در sys.stdout چاپ می‌کند و value را در builtins._ ذخیره می‌کند. اگر repr(value) با هندلر خطای sys.stdout.errors (که احتمالاً 'strict' است) به sys.stdout.encoding قابل کدگذاری نباشد، آن را با هندلر خطای 'backslashreplace' به sys.stdout.encoding کدگذاری می‌کند.

sys.displayhook برای نتیجه‌ی ارزیابی یک عبارت واردشده در یک نشست تعاملی پایتون فراخوانی می‌شود. نمایش این مقادیر را می‌توان با انتساب تابع یک‌آرگومانی دیگری به sys.displayhook سفارشی کرد.

شبه‌کد:

def displayhook(value):
    if value is None:
        return
    # Set '_' to None to avoid recursion
    builtins._ = None
    text = repr(value)
    try:
        sys.stdout.write(text)
    except UnicodeEncodeError:
        bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
        if hasattr(sys.stdout, 'buffer'):
            sys.stdout.buffer.write(bytes)
        else:
            text = bytes.decode(sys.stdout.encoding, 'strict')
            sys.stdout.write(text)
    sys.stdout.write("\n")
    builtins._ = value

تغییر یافته در نسخه‌ی 3.2: برای UnicodeEncodeError از هندلر خطای 'backslashreplace' استفاده کنید.

sys.dont_write_bytecode¶

اگر این مقدار درست باشد، پایتون تلاشی برای نوشتن پرونده‌های .pyc هنگام ایمپورت ماژول‌های منبع نمی‌کند. این مقدار در ابتدا بسته به گزینه خط فرمان -B و متغیر محیطی PYTHONDONTWRITEBYTECODE روی True یا False تنظیم می‌شود، اما می‌توانید خودتان آن را برای کنترل تولید پرونده‌های بایت‌کد تنظیم کنید.

sys._emscripten_info¶

یک named tuple حاوی اطلاعات درباره محیط سکوی wasm32-emscripten. این named tuple موقتی است و ممکن است در آینده تغییر کند.

_emscripten_info.emscripten_version¶

نسخه Emscripten به‌صورت تاپلی از اعداد صحیح (اصلی، فرعی، میکرو)، برای مثال (3, 1, 8).

_emscripten_info.runtime¶

رشته‌ی ران‌تایم، مثلاً عامل کاربری مرورگر، 'Node.js v14.18.2'، یا 'UNKNOWN'.

_emscripten_info.pthreads¶

True اگر پایتون با پشتیبانی از pthreads در Emscripten کامپایل‌شده باشد.

_emscripten_info.shared_memory¶

True اگر پایتون با پشتیبانی از حافظه‌ی مشترک کامپایل شده باشد.

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

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

sys.pycache_prefix¶

اگر این مقدار تنظیم شده باشد (None نباشد)، پایتون پرونده‌های .pyc نهانگاه بایت‌کد را در یک درخت پوشه‌ای موازی که ریشه‌ی آن این پوشه است می‌نویسد (و آن‌ها را از همان می‌خواند)، نه از پوشه‌های __pycache__ در درخت کد منبع. هر پوشه‌ی __pycache__ در درخت کد منبع نادیده گرفته خواهد شد و پرونده‌های .pyc جدید درون پیشوند pycache نوشته می‌شوند. بنابراین اگر از compileall به‌عنوان یک مرحله‌ی پیش از ساخت استفاده می‌کنید، باید اطمینان حاصل کنید که آن را با همان پیشوند pycache (در صورت وجود) اجرا می‌کنید که در ران‌تایم استفاده خواهید کرد.

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

این مقدار در ابتدا بر اساس مقدار گزینه خط فرمان -X pycache_prefix=PATH یا متغیر محیطی PYTHONPYCACHEPREFIX تنظیم می‌شود (خط فرمان اولویت دارد). اگر هیچ‌کدام تنظیم نشده باشند، None است.

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

sys.excepthook(type, value, traceback)¶

این تابع یک ردگیری پشته و استثنای داده‌شده را در sys.stderr چاپ می‌کند.

هنگامی که استثنایی غیر از SystemExit پرتاب شود و گرفته نشود، مفسر sys.excepthook را با سه آرگومان فراخوانی می‌کند: کلاس استثنا، نمونه استثنا، و یک شیء ردگیری پشته. در یک نشست تعاملی، این اتفاق درست پیش از بازگشت کنترل به اعلان خط فرمان رخ می‌دهد؛ در یک برنامه پایتون، این اتفاق درست پیش از خروج برنامه رخ می‌دهد. مدیریت چنین استثناهای سطح‌بالایی را می‌توان با انتساب تابع دیگری با سه آرگومان به sys.excepthook سفارشی‌سازی کرد.

هنگامی که استثنای گرفته‌نشده‌ای رخ دهد، یک رویداد حسابرسی sys.excepthook با آرگومان‌های hook، type، value، traceback پرتاب می‌شود. اگر هیچ قلابی تنظیم نشده باشد، ممکن است hook برابر None باشد. اگر هر قلابی استثنایی مشتق‌شده از RuntimeError پرتاب کند، فراخوانی آن قلاب سرکوب خواهد شد. در غیر این صورت، استثنای قلاب حسابرسی به‌عنوان غیرقابل‌پرتاب گزارش خواهد شد و sys.excepthook فراخوانی خواهد شد.

همچنین ببینید

تابع sys.unraisablehook() استثناهای غیرقابل‌پرتاب را مدیریت می‌کند و تابع threading.excepthook() استثنای پرتاب‌شده توسط threading.Thread.run() را مدیریت می‌کند.

sys.__breakpointhook__¶

sys.__displayhook__¶

sys.__excepthook__¶

sys.__unraisablehook__¶

این اشیاء شامل مقادیر اصلی breakpointhook، displayhook، excepthook و unraisablehook در آغاز برنامه هستند. آن‌ها ذخیره می‌شوند تا breakpointhook، displayhook، excepthook و unraisablehook در صورتی که احیاناً با اشیای خراب یا جایگزین جایگزین شده باشند، بازگردانی شوند.

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

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

sys.exception()¶

این تابع، هنگامی که در حین اجرای یک مدیر استثنا فراخوانی شود (مانند یک بند except یا except*)، نمونه‌ی استثنای گرفته‌شده توسط این مدیر را برمی‌گرداند. هنگامی که هندلرهای استثنا در یکدیگر تودرتو شده باشند، تنها استثنای مدیریت‌شده توسط داخلی‌ترین مدیر قابل دسترسی است.

اگر هیچ هندلر استثنایی در حال اجرا نباشد، این تابع None را بازمی‌گرداند.

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

sys.exc_info()¶

این تابع بازنمایی به سبک قدیمی استثنای مدیریت‌شده را برمی‌گرداند. اگر یک استثنا e در حال حاضر مدیریت شده باشد (به‌طوری که exception() مقدار e را برمی‌گرداند)، exc_info() تاپل (type(e), e, e.__traceback__) را برمی‌گرداند. یعنی تاپلی شامل نوع استثنا (یک زیرکلاس از BaseException)، خود استثنا، و یک شیء ردگیری پشته که معمولاً پشته فراخوانی را در نقطه‌ای که استثنا آخرین بار در آن رخ داده است در بر می‌گیرد.

اگر هیچ استثنایی در هیچ نقطه‌ای از پشته مدیریت نشود، این تابع یک تاپل شامل سه مقدار None برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.11: فیلدهای type و traceback اکنون از value (نمونه استثنا) به دست می‌آیند، بنابراین هنگامی که یک استثنا در حین مدیریت تغییر داده می‌شود، تغییرات در نتایج فراخوانی‌های بعدی exc_info() منعکس می‌شوند.

sys.exec_prefix¶

رشته‌ای که پیشوند پوشه‌ی مختص سایت را مشخص می‌کند؛ جایی که پرونده‌های پایتون وابسته به پلتفرم در آن نصب می‌شوند؛ به‌طور پیش‌فرض، این مقدار نیز '/usr/local' است. این مقدار را می‌توان در زمان ساخت با آرگومان --exec-prefix اسکریپت configure تنظیم کرد. به‌طور مشخص، همه‌ی پرونده‌های پیکربندی (مانند پرونده‌ی سرآیند pyconfig.h) در پوشه‌ی exec_prefix/lib/pythonX.Y/config نصب می‌شوند و ماژول‌های کتابخانه‌ی اشتراکی در exec_prefix/lib/pythonX.Y/lib-dynload نصب می‌شوند، که در آن X.Y شماره‌ی نسخه‌ی پایتون است، برای مثال 3.2.

نکته

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

تغییر یافته در نسخه‌ی 3.14: هنگام اجرا در یک محیط مجازی، prefix و exec_prefix اکنون به‌جای site توسط راه‌اندازی مسیر به پیشوند محیط مجازی تنظیم می‌شوند. این بدان معناست که prefix و exec_prefix همیشه به محیط مجازی اشاره می‌کنند، حتی زمانی که site غیرفعال باشد (-S).

sys.executable¶

رشته‌ای که مسیر مطلق دودویی اجرایی مفسر پایتون را در سیستم‌هایی که این موضوع در آن‌ها معنا دارد، نشان می‌دهد. اگر پایتون قادر به دریافت مسیر واقعی پرونده اجرایی خود نباشد، sys.executable یک رشته خالی یا None خواهد بود.

sys.exit([arg])¶

یک استثنای SystemExit را پرتاب می‌کند، که قصد خروج از مفسر را نشان می‌دهد.

آرگومان اختیاری arg می‌تواند یک عدد صحیح باشد که وضعیت خروج را مشخص می‌کند (پیش‌فرض آن صفر است)، یا شیءای از نوع دیگر. اگر عدد صحیح باشد، صفر از سوی پوسته‌ها و امثال آن «خاتمه‌ی موفق» و هر مقدار ناصفر «خاتمه‌ی غیرعادی» تلقی می‌شود. در بیشتر سیستم‌ها، این مقدار باید در محدوده‌ی ۰ تا ۱۲۷ باشد؛ در غیر این صورت نتایج تعریف‌نشده‌ای تولید می‌شود. برخی سیستم‌ها برای اختصاص معانی خاص به کدهای خروج خاص قراردادی دارند، اما این قراردادها عموماً چندان توسعه‌یافته نیستند؛ برنامه‌های یونیکس معمولاً از ۲ برای خطاهای سینتکس خط فرمان و از ۱ برای تمام انواع دیگر خطاها استفاده می‌کنند. اگر شیءای از نوع دیگر ارسال شود، None معادل ارسال صفر است و هر شیء دیگری در stderr چاپ می‌شود و به کد خروج ۱ منجر می‌شود. به‌ویژه، sys.exit("some error message") راهی سریع برای خروج از برنامه هنگام وقوع خطا است.

از آنجا که exit() در نهایت «فقط» یک استثنا ایجاد می‌کند، فرایند را تنها زمانی متوقف می‌کند که از نخ اصلی فراخوانی شود و استثنا رهگیری نشود. کنش‌های پاکسازی مشخص‌شده توسط بندهای finally از دستورات try محترم شمرده می‌شوند و امکان رهگیری تلاش برای خروج در سطح بیرونی‌تر وجود دارد.

تغییر یافته در نسخه‌ی 3.6: اگر در پاک‌سازی، پس از آنکه مفسر پایتون SystemExit را گرفته باشد، خطایی رخ دهد (مانند خطا در تخلیه‌ی داده‌های بافری‌شده در جریان‌های استاندارد)، وضعیت خروج به ۱۲۰ تغییر می‌یابد.

sys.flags¶

named tuple flags وضعیت پرچم‌های خط فرمان را نشان می‌دهد. پرچم‌ها باید تنها با نام و نه با اندیس مورد دسترسی قرار گیرند. ویژگی‌ها فقط‌خواندنی هستند.

flags.debug¶	-d
flags.inspect¶	-i
flags.interactive¶	-i
flags.isolated¶	-I
flags.optimize¶	-O یا -OO
flags.dont_write_bytecode¶	-B
flags.no_user_site¶	-s
flags.no_site¶	-S
flags.ignore_environment¶	-E
flags.verbose¶	-v
flags.bytes_warning¶	-b
flags.quiet¶	-q
flags.hash_randomization¶	-R
flags.dev_mode¶	-X dev (حالت توسعه پایتون)
flags.utf8_mode¶	-X utf8
flags.safe_path¶	-P
flags.int_max_str_digits¶	-X int_max_str_digits (محدودیت طول تبدیل عدد صحیح به رشته)
flags.warn_default_encoding¶	-X warn_default_encoding
flags.gil¶	-X gil و PYTHON_GIL
flags.thread_inherit_context¶	-X thread_inherit_context و PYTHON_THREAD_INHERIT_CONTEXT
flags.context_aware_warnings¶	-X context_aware_warnings و PYTHON_CONTEXT_AWARE_WARNINGS
flags.lazy_imports¶	-X lazy_imports and PYTHON_LAZY_IMPORTS (1 for all, -1 otherwise; not changed by set_lazy_imports())

تغییر یافته در نسخه‌ی 3.2: ویژگی quiet برای پرچم جدید -q افزوده شد.

اضافه شده در نسخه‌ی 3.2.3: ویژگی hash_randomization.

تغییر یافته در نسخه‌ی 3.3: ویژگی منسوخ division_warning حذف شد.

تغییر یافته در نسخه‌ی 3.4: ویژگی isolated برای پرچم isolated در -I افزوده شد.

تغییر یافته در نسخه‌ی 3.7: ویژگی dev_mode برای حالت توسعه پایتون جدید و ویژگی utf8_mode برای پرچم utf8 جدید -X افزوده شدند.

تغییر یافته در نسخه‌ی 3.10: ویژگی warn_default_encoding برای پرچم -X warn_default_encoding افزوده شد.

تغییر یافته در نسخه‌ی 3.11: ویژگی safe_path برای گزینه‌ی -P افزوده شد.

تغییر یافته در نسخه‌ی 3.11: ویژگی int_max_str_digits اضافه شد.

تغییر یافته در نسخه‌ی 3.13: ویژگی gil افزوده شد.

تغییر یافته در نسخه‌ی 3.14: ویژگی thread_inherit_context افزوده شد.

تغییر یافته در نسخه‌ی 3.14: ویژگی context_aware_warnings افزوده شد.

تغییر یافته در نسخه‌ی 3.15: ویژگی gil افزوده شد.

sys.float_info¶

یک تاپل نام‌دار (named tuple) حاوی اطلاعاتی درباره نوع float است. این شامل اطلاعات سطح پایین درباره دقت و نمایش داخلی است. مقادیر با ثابت‌های مختلف ممیز شناور تعریف‌شده در پرونده‌ی سرآیند استاندارد float.h برای زبان برنامه‌نویسی C مطابقت دارند؛ برای جزئیات، بخش ۵.۲.۴.۲.۲ از استاندارد ISO/IEC C سال ۱۹۹۹ [C99]، «مشخصات انواع ممیز شناور» را ببینید.

ویژگی‌های named tuple float_info¶

ویژگی	ماکروی float.h	توضیح
float_info.epsilon¶	DBL_EPSILON	تفاوت میان 1.0 و کمترین مقدار بزرگ‌تر از 1.0 که به‌صورت یک عدد اعشاری قابل‌نمایش است. همچنین ببینید math.ulp().
float_info.dig¶	DBL_DIG	حداکثر تعداد ارقام اعشاری که می‌توانند به‌صورت امانت‌دارانه در یک شناور بازنمایی شوند؛ در ادامه ببینید.
float_info.mant_dig¶	DBL_MANT_DIG	دقت عدد اعشاری: تعداد ارقام مبنای radix در بخش معنادار (significand) یک عدد اعشاری.
float_info.max¶	DBL_MAX	بیشترین عدد اعشاری مثبت متناهی قابل نمایش.
float_info.max_exp¶	DBL_MAX_EXP	بزرگ‌ترین عدد صحیح e به‌طوری که radix**(e-1) یک عدد اعشاری متناهی قابل‌نمایش باشد.
float_info.max_10_exp¶	DBL_MAX_10_EXP	بزرگ‌ترین عدد صحیح e که 10**e در بازه‌ی اعداد اعشاری متناهی قابل‌نمایش باشد.
float_info.min¶	DBL_MIN	کمینه عدد اعشاری مثبت نرمال‌شده قابل بازنمایی. برای به دست آوردن کوچک‌ترین شناور مثبت غیرنرمال (denormalized) قابل نمایش از math.ulp(0.0) استفاده کنید.
float_info.min_exp¶	DBL_MIN_EXP	کمترین عدد صحیح e به‌طوری‌که radix**(e-1) یک شناور نرمال‌شده باشد.
float_info.min_10_exp¶	DBL_MIN_10_EXP	کمترین عدد صحیح e به‌طوری که 10**e یک شناور نرمال‌شده باشد.
float_info.radix¶	FLT_RADIX	مبنای نمایش توان.
float_info.rounds¶	FLT_ROUNDS	عدد صحیحی که حالت گرد کردن برای محاسبات ممیز شناور را نشان می‌دهد. این مقدار، مقدار ماکروی سیستمی FLT_ROUNDS را در زمان راه‌اندازی مفسر منعکس می‌کند: -1: غیرقابل تعیین 0: به سمت صفر 1: به نزدیک‌ترین 2: به سمت بی‌نهایت مثبت 3: به سمت بی‌نهایت منفی همه‌ی مقادیر دیگر FLT_ROUNDS نشان‌دهنده‌ی رفتار گرد کردن تعریف‌شده توسط پیاده‌سازی هستند.

ویژگی sys.float_info.dig به توضیح بیشتری نیاز دارد. اگر s هر رشته‌ای باشد که یک عدد اعشاری را با حداکثر sys.float_info.dig رقم معنادار نشان می‌دهد، آنگاه تبدیل s به یک عدد اعشاری و سپس تبدیل دوباره‌ی آن به رشته، رشته‌ای را بازیابی خواهد کرد که همان مقدار اعشاری را نشان می‌دهد:

>>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979'    # decimal string with 15 significant digits
>>> format(float(s), '.15g')  # convert to float and back -> same value
'3.14159265358979'

اما برای رشته‌هایی که بیش از sys.float_info.dig رقم معنادار دارند، این همیشه درست نیست:

>>> s = '9876543211234567'    # 16 significant digits is too many!
>>> format(float(s), '.16g')  # conversion changes value
'9876543211234568'

sys.float_repr_style¶

رشته‌ای که نشان می‌دهد تابع repr() برای اعداد اعشاری چگونه رفتار می‌کند. اگر رشته مقدار 'short' داشته باشد، آنگاه برای یک عدد اعشاری متناهی x، repr(x) تلاش می‌کند رشته‌ای کوتاه با این ویژگی تولید کند که float(repr(x)) == x. این رفتار معمول در پایتون 3.1 و نسخه‌های بعدی است. در غیر این صورت، float_repr_style مقدار 'legacy' دارد و repr(x) همان‌گونه رفتار می‌کند که در نسخه‌های پایتون پیش از 3.1 رفتار می‌کرد.

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

sys.getallocatedblocks()¶

تعداد بلوک‌های حافظه‌ای را که در حال حاضر توسط مفسر تخصیص داده شده‌اند، صرف‌نظر از اندازه‌شان، برمی‌گرداند. این تابع عمدتاً برای پیگیری و اشکال‌زدایی نشت حافظه مفید است. به دلیل نهانگاه‌های داخلی مفسر، نتیجه می‌تواند از یک فراخوانی به فراخوانی دیگر متفاوت باشد؛ ممکن است لازم باشد _clear_internal_caches() و gc.collect() را فراخوانی کنید تا نتایج قابل‌پیش‌بینی‌تری به دست آورید.

اگر یک ساخت یا پیاده‌سازی پایتون نتواند به‌طور معقول این اطلاعات را محاسبه کند، getallocatedblocks() مجاز است در عوض 0 برگرداند.

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

sys.getunicodeinternedsize()¶

تعداد اشیای یونیکدی را که درونی‌سازی‌شده هستند برمی‌گرداند.

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

sys.getandroidapilevel()¶

سطح API زمان ساخت اندروید را به‌عنوان یک عدد صحیح برمی‌گرداند. این مقدار نشان‌دهنده‌ی حداقل نسخه‌ی اندرویدی است که این ساخت پایتون می‌تواند روی آن اجرا شود. برای اطلاعات نسخه‌ی ران‌تایم، platform.android_ver() را ببینید.

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

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

sys.getdefaultencoding()¶

'utf-8' را برمی‌گرداند. این نام کدگذاری پیش‌فرض رشته است که در متدهایی مانند str.encode() استفاده می‌شود.

sys.getdlopenflags()¶

مقدار فعلی پرچم‌های استفاده‌شده برای فراخوانی‌های dlopen() را برمی‌گرداند. نام‌های نمادین مقادیر پرچم‌ها را می‌توان در ماژول os یافت (ثابت‌های RTLD_xxx، مثلاً os.RTLD_LAZY).

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

sys.getfilesystemencoding()¶

کدگذاری سامانه فایل‌بندی را دریافت کنید: کدگذاری‌ای که همراه با هندلر خطای سامانه فایل‌بندی برای تبدیل بین نام پرونده‌های یونیکدی و نام پرونده‌های بایتی استفاده می‌شود. هندلر خطای سامانه فایل‌بندی از getfilesystemencodeerrors() بازگردانده می‌شود.

برای بیشترین سازگاری، باید در همه موارد برای نام پرونده‌ها از str استفاده شود، هرچند نمایش نام پرونده‌ها به‌صورت bytes نیز پشتیبانی می‌شود. توابعی که نام پرونده‌ها را می‌پذیرند یا بازمی‌گردانند باید از str یا bytes پشتیبانی کنند و آن‌ها را به‌صورت داخلی به نمایش ترجیحی سیستم تبدیل کنند.

باید از os.fsencode() و os.fsdecode() استفاده شود تا اطمینان حاصل شود که کدگذاری و حالت خطاهای صحیح به کار می‌روند.

کدگذاری و هندلر خطای سامانه فایل‌بندی در هنگام راه‌اندازی پایتون توسط تابع PyConfig_Read() پیکربندی می‌شوند: اعضای filesystem_encoding و filesystem_errors از PyConfig را ببینید.

تغییر یافته در نسخه‌ی 3.2: نتیجه‌ی getfilesystemencoding() دیگر نمی‌تواند None باشد.

تغییر یافته در نسخه‌ی 3.6: دیگر تضمین نمی‌شود که ویندوز 'mbcs' را برگرداند. برای اطلاعات بیشتر PEP 529 و _enablelegacywindowsfsencoding() را ببینید.

تغییر یافته در نسخه‌ی 3.7: اگر حالت UTF-8 پایتون فعال باشد، 'utf-8' را برمی‌گرداند.

sys.getfilesystemencodeerrors()¶

دریافت هندلر خطای سامانه فایل‌بندی: هندلر خطایی که همراه با کدگذاری سامانه فایل‌بندی برای تبدیل بین نام پرونده‌های یونیکدی و نام پرونده‌های بایتی استفاده می‌شود. کدگذاری سامانه فایل‌بندی از getfilesystemencoding() بازگردانده می‌شود.

باید از os.fsencode() و os.fsdecode() استفاده شود تا اطمینان حاصل شود که کدگذاری و حالت خطاهای صحیح به کار می‌روند.

کدگذاری و هندلر خطای سامانه فایل‌بندی در هنگام راه‌اندازی پایتون توسط تابع PyConfig_Read() پیکربندی می‌شوند: اعضای filesystem_encoding و filesystem_errors از PyConfig را ببینید.

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

sys.get_int_max_str_digits()¶

مقدار فعلی محدودیت طول تبدیل عدد صحیح به رشته را برمی‌گرداند. همچنین set_int_max_str_digits() را ببینید.

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

sys.get_lazy_imports()¶

حالت فعلی ایمپورت‌های تنبل (lazy imports) را به شکل یک رشته برمی‌گرداند.

• "normal": فقط ایمپورت‌هایی که صراحتاً با کلیدواژه‌ی lazy مشخص شده‌اند، تنبل هستند

• "all": تمام ایمپورت‌های سطح بالا به طور بالقوه تنبل هستند

همچنین نگاه کنید به set_lazy_imports() و PEP 810.

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

sys.get_lazy_imports_filter()¶

تابع فیلتر فعلی ایمپورت‌های تنبل را برمی‌گرداند، یا اگر هیچ فیلتری تنظیم نشده باشد، None را برمی‌گرداند.

تابع فیلتر برای هر ایمپورتِ به طور بالقوه تنبلی فراخوانی می‌شود تا مشخص شود که آیا واقعاً باید تنبل باشد یا خیر. برای جزئیات درباره‌ی امضای تابع فیلتر به set_lazy_imports_filter() مراجعه کنید.

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

sys.getrefcount(object)¶

تعداد ارجاع به object را برمی‌گرداند. تعداد برگردانده‌شده معمولاً یکی بیشتر از مقداری است که ممکن است انتظار داشته باشید، زیرا ارجاع (موقت) به‌عنوان آرگومان به getrefcount() را شامل می‌شود.

توجه داشته باشید که مقدار برگردانده‌شده ممکن است در عمل تعداد ارجاع‌های نگهداری‌شده به شیء را نشان ندهد. برای مثال، برخی از شیء‌ها نامیرا هستند و شمارش ارجاع‌ها (refcount) بسیار بالایی دارند که تعداد واقعی ارجاع‌ها را نشان نمی‌دهد. در نتیجه، به دقیق بودن مقدار برگردانده‌شده، مگر برای مقدار ۰ یا ۱، اتکا نکنید.

اشیاء نامیرا با تعداد ارجاع زیاد را می‌توان از طریق _is_immortal() شناسایی کرد.

تغییر یافته در نسخه‌ی 3.12: اشیاء نامیرا دارای شمارش ارجاع (refcount) بسیار بزرگی هستند که با تعداد واقعی ارجاع‌ها به شیء مطابقت ندارد.

sys.getrecursionlimit()¶

مقدار فعلی محدودیت بازگشت، یعنی حداکثر عمق پشته مفسر پایتون را برمی‌گرداند. این محدودیت از سرریز پشته C و از کار افتادن پایتون در اثر بازگشت بی‌پایان جلوگیری می‌کند. می‌توان آن را با setrecursionlimit() تنظیم کرد.

sys.getsizeof(object[, default])¶

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

تنها مصرف حافظه‌ای که مستقیماً به شیء نسبت داده می‌شود، محاسبه می‌شود، نه مصرف حافظه‌ی اشیایی که به آن‌ها ارجاع می‌دهد.

اگر داده شود، چنانچه شیء وسیله‌ای برای بازیابی اندازه فراهم نکند، default برگردانده می‌شود. در غیر این صورت یک TypeError پرتاب می‌شود.

getsizeof() متد __sizeof__ شیء را فراخوانی می‌کند و اگر شیء توسط زباله‌رو مدیریت شود، سربار اضافی زباله‌رو را اضافه می‌کند.

برای دیدن نمونه‌ای از استفاده‌ی بازگشتی از getsizeof() جهت یافتن اندازه‌ی ظرف‌ها و تمام محتوای آن‌ها، recursive sizeof recipe را ببینید.

sys.getswitchinterval()¶

بازه‌ی تعویض نخ مفسر را بر حسب ثانیه برمی‌گرداند؛ setswitchinterval() را ببینید.

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

sys._getframe([depth])¶

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

یک رویداد حسابرسی sys._getframe را با آرگومان frame پرتاب می‌کند.

این تابع باید تنها برای اهداف داخلی و تخصصی استفاده شود. وجود آن در تمام پیاده‌سازی‌های پایتون تضمین نمی‌شود.

sys._getframemodulename([depth])¶

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

یک رویداد حسابرسی sys._getframemodulename را با آرگومان depth پرتاب می‌کند.

این تابع باید تنها برای اهداف داخلی و تخصصی استفاده شود. وجود آن در تمام پیاده‌سازی‌های پایتون تضمین نمی‌شود.

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

sys.getobjects(limit[, type])¶

این تابع تنها در صورتی وجود دارد که CPython با استفاده از گزینه‌ی تخصصی configure --with-trace-refs ساخته شده باشد. این تابع فقط برای اشکال‌زدایی مسائل مربوط به زباله‌روبی در نظر گرفته شده است.

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

استفاده از اشیای موجود در فهرست ایمن نیست. به‌طور مشخص، نتیجه شامل اشیای تمام مفسرهایی خواهد بود که وضعیت تخصیص‌دهنده‌ی اشیای خود را به اشتراک می‌گذارند (یعنی مفسرهایی که با PyInterpreterConfig.use_main_obmalloc تنظیم‌شده روی ۱ یا با استفاده از Py_NewInterpreter() ایجادشده‌اند، و نیز مفسر اصلی). ترکیب اشیای مفسرهای مختلف ممکن است منجر به فروپاشی یا سایر رفتارهای غیرمنتظره شود.

این تابع باید تنها برای اهداف تخصصی استفاده شود. وجود آن در تمام پیاده‌سازی‌های پایتون تضمین نمی‌شود.

تغییر یافته در نسخه‌ی 3.14: نتیجه ممکن است شامل اشیایی از مفسرهای دیگر باشد.

sys.getprofile()¶

تابع پروفایل‌گیر (profiler) تنظیم‌شده توسط setprofile() را دریافت کنید.

sys.gettrace()¶

تابع ردگیری تنظیم‌شده توسط settrace() را دریافت کنید.

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

sys.getwindowsversion()¶

یک تاپل نام‌دار (named tuple) را برمی‌گرداند که نسخه ویندوز در حال اجرا را توصیف می‌کند. عناصر نام‌دار عبارت‌اند از major، minor، build، platform، service_pack، service_pack_minor، service_pack_major، suite_mask، product_type و platform_version. service_pack شامل یک رشته است، platform_version یک تاپل ۳-تایی است و همه‌ی مقادیر دیگر عدد صحیح هستند. کامپوننت‌ها را نیز می‌توان از طریق نام دسترسی داشت، بنابراین sys.getwindowsversion()[0] معادل sys.getwindowsversion().major است. برای سازگاری با نسخه‌های پیشین، تنها ۵ عنصر نخست از طریق اندیس‌دهی قابل بازیابی هستند.

platform برابر با 2 (VER_PLATFORM_WIN32_NT) خواهد بود.

product_type می‌تواند یکی از مقادیر زیر باشد:

ثابت	معنی
1 (VER_NT_WORKSTATION)	این سیستم یک ایستگاه کاری است.
2 (VER_NT_DOMAIN_CONTROLLER)	این سیستم یک کنترل‌کننده دامنه است.
3 (VER_NT_SERVER)	این سیستم یک سرور است، اما کنترل‌کننده دامنه نیست.

این تابع، پوششی برای تابع Win32 GetVersionEx() است؛ برای اطلاعات بیشتر درباره این فیلدها، به مستندات مایکروسافت درباره OSVERSIONINFOEX() مراجعه کنید.

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

نکته

platform_version نسخه را از kernel32.dll استخراج می‌کند که ممکن است نسخه‌ای متفاوت از نسخه سیستم‌عامل داشته باشد. لطفاً برای به‌دست آوردن نسخه دقیق سیستم‌عامل از ماژول platform استفاده کنید.

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

تغییر یافته در نسخه‌ی 3.2: به یک تاپل نام‌دار (named tuple) تغییر یافت و service_pack_minor، service_pack_major، suite_mask و product_type به آن افزوده شدند.

تغییر یافته در نسخه‌ی 3.6: platform_version اضافه شد

sys.get_asyncgen_hooks()¶

یک شیء asyncgen_hooks برمی‌گرداند، که شبیه به یک namedtuple به شکل (firstiter, finalizer) است و در آن firstiter و finalizer انتظار می‌رود یا None باشند یا توابعی که یک asynchronous generator iterator را به‌عنوان آرگومان می‌پذیرند و برای زمان‌بندی نهایی‌سازی یک تولیدگر ناهمگام توسط یک حلقه رویداد استفاده می‌شوند.

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

نکته

این تابع به‌صورت آزمایشی افزوده شده است (برای جزئیات، PEP 411 را ببینید.)

sys.get_coroutine_origin_tracking_depth()¶

عمق فعلی پیگیری مبدأ هم‌روال را، که توسط set_coroutine_origin_tracking_depth() تنظیم شده است، دریافت کنید.

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

نکته

این تابع به‌صورت موقت افزوده شده است (برای جزئیات PEP 411 را ببینید). از آن فقط برای اهداف اشکال‌زدایی استفاده کنید.

sys.hash_info¶

یک named tuple که پارامترهای پیاده‌سازی هش عددی را ارائه می‌دهد. برای جزئیات بیشتر درباره‌ی هش انواع عددی، درهم‌سازی انواع عددی را ببینید.

hash_info.width¶

عرض بر حسب بیت برای مقادیر هش

hash_info.modulus¶

پیمانه اول P که برای طرح‌واره هش عددی استفاده می‌شود

hash_info.inf¶

مقدار هش بازگشت‌داده‌شده برای بی‌نهایت مثبت

hash_info.nan¶

(این ویژگی دیگر استفاده نمی‌شود)

hash_info.imag¶

ضریب استفاده‌شده برای بخش موهومی یک عدد مختلط

hash_info.algorithm¶

نام الگوریتم هش برای str، bytes و memoryview

hash_info.hash_bits¶

اندازه‌ی خروجی داخلی الگوریتم هش

hash_info.seed_bits¶

اندازه‌ی کلید دانه (seed key) الگوریتم هش

hash_info.cutoff¶

آستانه برای بهینه‌سازی DJBX33A برای رشته‌های کوچک در بازه‌ی [1, cutoff).

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

تغییر یافته در نسخه‌ی 3.4: algorithm، hash_bits، seed_bits و cutoff افزوده شدند.

sys.hexversion¶

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

if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...

این hexversion نامیده می‌شود، زیرا تنها زمانی واقعاً معنادار به نظر می‌رسد که به‌عنوان نتیجه‌ی ارسال آن به تابع توکار hex() مشاهده شود. برای کدگذاری انسان‌پسندترِ همین اطلاعات می‌توان از named tuple sys.version_info استفاده کرد.

جزئیات بیشتر در مورد hexversion را می‌توان در نسخه‌گذاری API و ABI یافت.

sys.implementation¶

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

name شناسه‌ی پیاده‌سازی است، برای مثال 'cpython'. رشته‌ی واقعی توسط پیاده‌سازی پایتون تعریف می‌شود، اما تضمین می‌شود که با حروف کوچک باشد.

version یک تاپل نام‌دار (named tuple) است، با همان قالب sys.version_info. این، نسخه‌ی پیاده‌سازی پایتون را نشان می‌دهد. این معنایی متمایز از نسخه‌ی مشخص زبان پایتون دارد که مفسر در حال اجرا با آن مطابقت دارد و sys.version_info آن را نشان می‌دهد. برای مثال، برای PyPy 1.8 ممکن است sys.implementation.version برابر sys.version_info(1, 8, 0, 'final', 0) باشد، در حالی که sys.version_info برابر sys.version_info(2, 7, 2, 'final', 0) خواهد بود. برای CPython، این دو مقدار یکسانی دارند، زیرا این پیاده‌سازی مرجع است.

hexversion نسخه‌ی پیاده‌سازی در قالب مبنای شانزده است، مانند sys.hexversion.

cache_tag برچسبی است که سازوکار ایمپورت آن را در نام پرونده‌های ماژول‌های نهان‌شده به کار می‌برد. طبق قرارداد، این برچسب ترکیبی از نام و نسخه پیاده‌سازی است، مانند 'cpython-33'. با این حال، یک پیاده‌سازی پایتون ممکن است در صورت مناسب بودن از مقدار دیگری استفاده کند. اگر cache_tag روی None تنظیم شود، نشان می‌دهد که نهان‌سازی ماژول باید غیرفعال شود.

supports_isolated_interpreters یک مقدار بولی است که نشان می‌دهد آیا این پیاده‌سازی از چندین مفسر جداشده پشتیبانی می‌کند یا خیر. این مقدار برای CPython در بیشتر سکوها True است. سکوهای دارای این پشتیبانی، ماژول سطح پایین _interpreters را پیاده‌سازی می‌کنند.

همچنین ببینید

PEP 684، PEP 734 و concurrent.interpreters.

sys.implementation ممکن است شامل ویژگی‌های اضافی مختص پیاده‌سازی پایتون باشد. این ویژگی‌های غیراستاندارد باید با یک زیرخط شروع شوند و در اینجا توصیف نشده‌اند. صرف‌نظر از محتوای آن، sys.implementation در طول اجرای مفسر، و نه بین نسخه‌های پیاده‌سازی، تغییر نخواهد کرد. (البته ممکن است بین نسخه‌های زبان پایتون تغییر کند.) برای اطلاعات بیشتر PEP 421 را ببینید.

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

تغییر یافته در نسخه‌ی 3.14: فیلد supports_isolated_interpreters افزوده شد.

نکته

افزودن ویژگی‌های الزامی جدید باید از طریق فرایند عادی PEP انجام شود. برای اطلاعات بیشتر PEP 421 را ببینید.

sys.int_info¶

یک named tuple که حاوی اطلاعاتی درباره بازنمایی داخلی پایتون از اعداد صحیح است. ویژگی‌ها فقط‌خواندنی هستند.

int_info.bits_per_digit¶

تعداد بیت‌هایی که در هر رقم نگه داشته می‌شود. اعداد صحیح پایتون به‌صورت داخلی در مبنای 2**int_info.bits_per_digit ذخیره می‌شوند.

int_info.sizeof_digit¶

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

int_info.default_max_str_digits¶

مقدار پیش‌فرض برای sys.get_int_max_str_digits() هنگامی که به‌گونه‌ای دیگر به‌صورت صریح پیکربندی نشده باشد.

int_info.str_digits_check_threshold¶

کمترین مقدار غیرصفر برای sys.set_int_max_str_digits()، PYTHONINTMAXSTRDIGITS، یا -X int_max_str_digits.

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

تغییر یافته در نسخه‌ی 3.11: default_max_str_digits و str_digits_check_threshold افزوده شدند.

sys.__interactivehook__¶

هنگامی که این ویژگی وجود داشته باشد، مقدار آن به‌طور خودکار (بدون آرگومان) در زمان راه‌اندازی مفسر در حالت تعاملی فراخوانی می‌شود. این کار پس از خوانده شدن پرونده PYTHONSTARTUP انجام می‌شود، تا بتوانید این قلاب را آنجا تنظیم کنید. ماژول site این را تنظیم می‌کند.

هنگامی که قلاب در راه‌اندازی فراخوانی می‌شود، یک رویداد حسابرسی cpython.run_interactivehook را با شیء قلاب به‌عنوان آرگومان پرتاب می‌کند.

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

sys.intern(string)¶

string را در جدول رشته‌های «درونی‌سازی‌شده» وارد می‌کند و رشته‌ی درونی‌سازی‌شده را برمی‌گرداند — که خود string یا یک کپی از آن است. درونی‌سازی رشته‌ها برای افزایش اندک کارایی در جستجوی دیکشنری مفید است — اگر کلیدهای یک دیکشنری درونی‌سازی‌شده باشند و کلید مورد جستجو نیز درونی‌سازی‌شده باشد، مقایسه‌های کلید (پس از هش‌شدن) می‌توانند به‌جای مقایسه‌ی رشته‌ای، با مقایسه‌ی اشاره‌گر انجام شوند. به‌طور معمول، نام‌های استفاده‌شده در برنامه‌های پایتون به‌طور خودکار اینترن می‌شوند و دیکشنری‌های مورد استفاده برای نگه‌داری ویژگی‌های ماژول، کلاس یا نمونه، کلیدهای درونی‌سازی‌شده دارند.

رشته‌های internشده نامیرا نیستند؛ برای بهره‌مندی از آن، باید ارجاعی به مقدار بازگشتی intern() را نگه‌دارید.

sys._is_gil_enabled()¶

اگر GIL فعال باشد، True و اگر غیرفعال باشد، False را برمی‌گرداند.

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

تضمینی برای وجود آن در همه پیاده‌سازی‌های پایتون وجود ندارد.

sys.is_finalizing()¶

اگر مفسر اصلی پایتون در حال خاموش شدن باشد، True را برمی‌گرداند. در غیر این صورت False را برمی‌گرداند.

همچنین استثنا PythonFinalizationError را ببینید.

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

sys._jit¶

ابزارهایی برای مشاهده‌ی کامپایل در لحظه (just-in-time compilation).

کامپایل JIT (JIT compilation) یک جزئیات پیاده‌سازی آزمایشی در CPython است. تضمینی وجود ندارد که sys._jit در تمام پیاده‌سازی‌ها، نسخه‌ها یا پیکربندی‌های ساخت پایتون وجود داشته باشد یا رفتار یکسانی داشته باشد.

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

_jit.is_available()¶

اگر پرونده اجرایی پایتون جاری از کامپایل JIT پشتیبانی کند، True را برمی‌گرداند و در غیر این صورت False را برمی‌گرداند. این موضوع را می‌توان با ساخت CPython با گزینه‌ی --experimental-jit در ویندوز و گزینه‌ی --enable-experimental-jit در همه‌ی پلتفرم‌های دیگر کنترل کرد.

_jit.is_enabled()¶

اگر کامپایل JIT برای فرآیند پایتون جاری فعال باشد، True را برمی‌گرداند (که مستلزم برقراری sys._jit.is_available() است) و در غیر این صورت False را برمی‌گرداند. اگر کامپایل JIT در دسترس باشد، می‌توان این وضعیت را با تنظیم متغیر محیطی PYTHON_JIT بر روی 0 (غیرفعال) یا 1 (فعال) در زمان راه‌اندازی مفسر کنترل کرد.

_jit.is_active()¶

اگر بالاترین فریم پایتون هم‌اکنون در حال اجرای کد JIT باشد، True برمی‌گرداند (به این معنا که sys._jit.is_enabled() نیز برقرار است) و در غیر این صورت False برمی‌گرداند.

نکته

این تابع برای آزمون و اشکال‌زدایی خود JIT در نظر گرفته شده است. باید از استفاده از آن برای هر هدف دیگری پرهیز شود.

نکته

به دلیل ماهیت کامپایلرهای JIT مبتنی بر ردگیری (tracing JIT compilers)، فراخوانی‌های مکرر این تابع ممکن است نتایج غافلگیرکننده‌ای بدهند. برای مثال، انشعاب بر اساس مقدار بازگشتی آن احتمالاً به رفتار غیرمنتظره‌ای منجر می‌شود (اگر این کار باعث ورود به کد JIT یا خروج از آن شود):

>>> for warmup in range(BIG_NUMBER):
...     # This line is "hot", and is eventually JIT-compiled:
...     if sys._jit.is_active():
...         # This line is "cold", and is run in the interpreter:
...         assert sys._jit.is_active()
...
Traceback (most recent call last):
  File "<stdin>", line 5, in <module>
    assert sys._jit.is_active()
           ~~~~~~~~~~~~~~~~~~^^
AssertionError

sys.last_exc¶

این متغیر همیشه تعریف‌شده نیست؛ هنگامی که یک استثنا مدیریت نشود و مفسر یک پیام خطا و ردگیری پشته چاپ کند، این متغیر به نمونه استثنا تنظیم می‌شود. هدف از آن این است که یک کاربر تعاملی بتواند یک ماژول اشکال‌زدا را ایمپورت کند و بدون نیاز به اجرای دوباره دستوری که باعث خطا شده است، به اشکال‌زدایی پس از خطا (post-mortem debugging) بپردازد. (استفاده معمول import pdb; pdb.pm() برای ورود به اشکال‌زدای پس از خطا (post-mortem debugger) است؛ برای اطلاعات بیشتر ماژول pdb را ببینید.)

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

sys._is_immortal(op)¶

اگر شیء داده‌شده نامیرا باشد، True را برمی‌گرداند، در غیر این صورت False را برمی‌گرداند.

نکته

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

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

این تابع باید تنها برای اهداف تخصصی استفاده شود. وجود آن در تمام پیاده‌سازی‌های پایتون تضمین نمی‌شود.

sys._is_interned(string)¶

اگر رشته‌ی داده‌شده «درونی‌سازی‌شده» باشد، True و در غیر این صورت False برمی‌گرداند.

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

تضمینی برای وجود آن در همه پیاده‌سازی‌های پایتون وجود ندارد.

sys.last_type¶

sys.last_value¶

sys.last_traceback¶

این سه متغیر منسوخ شده‌اند؛ به‌جای آن‌ها از sys.last_exc استفاده کنید. آن‌ها نمایش قدیمی sys.last_exc را نگه می‌دارند، همان‌طور که از exc_info() در بالا برگردانده شده است.

sys.lazy_modules¶

مجموعه‌ای (set) از رشته‌های نام ماژول با نام کامل (fully qualified) که در مفسر فعلی به صورت تنبل ایمپورت شده‌اند اما هنوز بارگذاری نشده‌اند. هنگامی که برای اولین بار به یک ماژولِ به صورت تنبل ایمپورت‌شده دسترسی پیدا می‌شود، نام آن معمولاً از این مجموعه حذف می‌شود.

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

در حال حاضر، lazy_modules همچنین ممکن است شامل موارد زیر باشد:

• نام‌های ویژگی‌ها (غیرماژول‌ها)، مانند "pathlib.Path" پس از اجرای lazy from pathlib import Path، و

• نام آیتم‌هایی که قبلاً به آن‌ها دسترسی پیدا شده است.

در نسخه‌های آینده‌ی پایتون، ممکن است این موارد حذف شوند و/یا موارد اضافی دیگری اضافه شوند.

همچنین نگاه کنید به set_lazy_imports() و PEP 810.

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

sys.maxsize¶

یک عدد صحیح که بیشینه مقداری را که یک متغیر از نوع Py_ssize_t می‌تواند بگیرد، مشخص می‌کند. این مقدار معمولاً در پلتفرم ۳۲ بیتی 2**31 - 1 و در پلتفرم ۶۴ بیتی 2**63 - 1 است.

sys.maxunicode¶

یک عدد صحیح که مقدار بزرگ‌ترین نقطه کد یونیکد را می‌دهد، یعنی 1114111 (0x10FFFF در مبنای شانزده).

تغییر یافته در نسخه‌ی 3.3: پیش از PEP 393، sys.maxunicode بسته به گزینه‌ی پیکربندی‌ای که مشخص می‌کرد نویسه‌های یونیکد به‌صورت UCS-2 ذخیره می‌شوند یا UCS-4، یا 0xFFFF بود یا 0x10FFFF.

sys.meta_path¶

فهرستی از اشیای meta path finder که متدهای find_spec() آن‌ها فراخوانی می‌شوند تا بررسی شود که آیا یکی از اشیاء می‌تواند ماژول موردنظر برای ایمپورت را پیدا کند. به‌طور پیش‌فرض، این فهرست شامل ورودی‌هایی است که معنای پیش‌فرض ایمپورت پایتون را پیاده‌سازی می‌کنند. متد find_spec() حداقل با نام مطلق ماژول در حال ایمپورت فراخوانی می‌شود. اگر ماژول موردنظر برای ایمپورت در یک بسته قرار داشته باشد، در این صورت ویژگی __path__ بسته والد به‌عنوان آرگومان دوم ارسال می‌شود. این متد یک module spec برمی‌گرداند، یا اگر ماژول یافت نشود، None برمی‌گرداند.

همچنین ببینید

importlib.abc.MetaPathFinder

کلاس پایه انتزاعی که رابط اشیای یابنده را در meta_path تعریف می‌کند.

importlib.machinery.ModuleSpec

کلاس مشخصی که find_spec() باید نمونه‌هایی از آن را برگرداند.

تغییر یافته در نسخه‌ی 3.4: مشخصات ماژول در پایتون 3.4 توسط PEP 451 معرفی شدند.

تغییر یافته در نسخه‌ی 3.12: مکانیزم جایگزینی که اگر یک آیتم از meta_path متد find_spec() را نداشت، به دنبال متد find_module() می‌گشت، حذف شد.

sys.modules¶

این یک دیکشنری است که نام ماژول‌ها را به ماژول‌هایی که از قبل بارگذاری شده‌اند نگاشت می‌کند. می‌توان این دیکشنری را برای اجبار به بارگذاری مجدد ماژول‌ها و ترفندهای دیگر دستکاری کرد. با این حال، جایگزینی دیکشنری لزوماً آن‌طور که انتظار می‌رود کار نمی‌کند و حذف آیتم‌های ضروری از دیکشنری ممکن است باعث شکست پایتون شود. اگر می‌خواهید این دیکشنری سراسری را پیمایش کنید، همیشه از sys.modules.copy() یا tuple(sys.modules) استفاده کنید تا از بروز استثناها جلوگیری شود، زیرا اندازه آن ممکن است در حین پیمایش به‌عنوان عارضه جانبی کد یا فعالیت در نخ‌های دیگر تغییر کند.

sys.orig_argv¶

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

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

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

sys.path¶

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

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

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

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

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

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

یک برنامه آزاد است این فهرست را برای اهداف خود تغییر دهد. فقط رشته‌ها باید به sys.path اضافه شوند؛ تمام انواع داده دیگر در حین ایمپورت نادیده گرفته می‌شوند.

همچنین ببینید

• ماژول site این بخش نحوه‌ی استفاده از پرونده‌های .pth برای گسترش sys.path را توضیح می‌دهد.

sys._path0¶

Path prepended to sys.path at Python startup:

• Current directory if running a module with python -m module command line.

• Script's directory if running a script with python script.py.

• Otherwise an empty string, which means the current working directory, for python -c code or python (REPL) command line.

If -P or -I command line options are used or if PYTHONSAFEPATH environment variable is used, sys._path0 is None and sys.path is left unchanged.

اضافه شده در نسخه‌ی 3.15.2 (unreleased).

sys.path_hooks¶

فهرستی از اشیای فراخوانی‌پذیر که یک آرگومان مسیر می‌گیرند تا سعی کنند برای مسیر یک finder ایجاد کنند. اگر بتوان یک finder ایجاد کرد، باید توسط آن شیء فراخوانی‌پذیر برگردانده شود، در غیر این صورت آن شیء فراخوانی‌پذیر باید ImportError را پرتاب کند.

در ابتدا در PEP 302 مشخص شده است.

sys.path_importer_cache¶

یک دیکشنری که به‌عنوان نهانگاه برای اشیای finder عمل می‌کند. کلیدها مسیرهایی هستند که به sys.path_hooks ارسال شده‌اند و مقادیر، یابنده‌هایی هستند که پیدا می‌شوند. اگر یک مسیر، مسیر معتبر سامانه فایل‌بندی‌ای باشد اما هیچ یابنده‌ای در sys.path_hooks پیدا نشود، None ذخیره می‌شود.

در ابتدا در PEP 302 مشخص شده است.

sys.platform¶

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

سیستم	مقدار platform
AIX	'aix'
اندروید	'android'
Emscripten	'emscripten'
FreeBSD	'freebsd'
iOS	'ios'
لینوکس	'linux'
macOS	'darwin'
ویندوز	'win32'
Windows/Cygwin	'cygwin'
WASI	'wasi'

در سیستم‌های یونیکسی که در جدول فهرست نشده‌اند، مقدار، نام سیستم‌عامل با حروف کوچک است که توسط uname -s برگردانده می‌شود و بخش نخست نسخه که توسط uname -r برگردانده می‌شود، به آن افزوده شده است؛ برای مثال 'sunos5'، در زمان ساخت پایتون. بنابراین، مگر اینکه بخواهید نسخه خاصی از سیستم را بررسی کنید، توصیه می‌شود از اصطلاح زیر استفاده کنید:

if sys.platform.startswith('sunos'):
    # SunOS-specific code here...

تغییر یافته در نسخه‌ی 3.3: در لینوکس، sys.platform دیگر شامل نسخه‌ی اصلی نمی‌شود. این مقدار همیشه 'linux' است، به‌جای 'linux2' یا 'linux3'.

تغییر یافته در نسخه‌ی 3.8: در AIX، sys.platform دیگر شامل نسخه‌ی اصلی نمی‌شود. این مقدار به‌جای 'aix5' یا 'aix7'، همیشه 'aix' است.

تغییر یافته در نسخه‌ی 3.13: در اندروید، sys.platform اکنون به‌جای 'linux' مقدار 'android' را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.14: در FreeBSD، sys.platform دیگر شامل نسخه‌ی اصلی نمی‌شود. همیشه 'freebsd' است، به جای 'freebsd13' یا 'freebsd14'.

همچنین ببینید

os.name دانه‌بندی درشت‌تری دارد. os.uname() اطلاعات نسخه‌ی وابسته به سیستم را ارائه می‌دهد.

ماژول platform بررسی‌های دقیقی برای هویت سیستم فراهم می‌کند.

sys.platlibdir¶

نام پوشه‌ی کتابخانه‌ی مختص پلتفرم. از آن برای ساخت مسیر کتابخانه‌ی استاندارد و مسیرهای ماژول‌های توسعه‌ای نصب‌شده استفاده می‌شود.

این مقدار در بیشتر سکوها برابر با "lib" است. در Fedora و SuSE، این مقدار در سکوهای ۶۴ بیتی برابر با "lib64" است که مسیرهای sys.path زیر را به دست می‌دهد (که در آن X.Y نسخه‌ی major.minor پایتون است):

• /usr/lib64/pythonX.Y/: کتابخانه استاندارد (مانند os.py از ماژول os)

• /usr/lib64/pythonX.Y/lib-dynload/: ماژول‌های توسعه‌ای C از کتابخانه استاندارد (مانند ماژول errno، نام دقیق پرونده وابسته به پلتفرم است)

• /usr/lib/pythonX.Y/site-packages/ (همیشه از lib استفاده کنید، نه sys.platlibdir): ماژول‌های شخص ثالث

• /usr/lib64/pythonX.Y/site-packages/: ماژول‌های توسعه‌ای C از بسته‌های شخص ثالث

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

sys.prefix¶

رشته‌ای که پیشوند پوشه‌ی ویژه‌ی سایت را مشخص می‌کند، جایی که پرونده‌های پایتون مستقل از سکو در آن نصب می‌شوند؛ در یونیکس، مقدار پیش‌فرض /usr/local است. این مقدار را می‌توان در زمان ساخت با آرگومان --prefix به اسکریپت configure تنظیم کرد. برای مسیرهای مشتق‌شده مسیرهای نصب را ببینید.

نکته

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

تغییر یافته در نسخه‌ی 3.14: هنگام اجرا در یک محیط مجازی، prefix و exec_prefix اکنون به‌جای site توسط راه‌اندازی مسیر به پیشوند محیط مجازی تنظیم می‌شوند. این بدان معناست که prefix و exec_prefix همیشه به محیط مجازی اشاره می‌کنند، حتی زمانی که site غیرفعال باشد (-S).

sys.ps1¶

sys.ps2¶

رشته‌هایی که اعلان اصلی و ثانویه مفسر را مشخص می‌کنند. این‌ها تنها در صورتی تعریف می‌شوند که مفسر در حالت تعاملی باشد. مقادیر اولیه آن‌ها در این حالت '>>> ' و '... ' هستند. اگر یک شیء غیررشته‌ای به یکی از این متغیرها اختصاص داده شود، str() آن هر بار که مفسر برای خواندن یک دستور تعاملی جدید آماده می‌شود، دوباره ارزیابی می‌شود؛ این می‌تواند برای پیاده‌سازی یک اعلان پویا استفاده شود.

sys.setdlopenflags(n)¶

پرچم‌هایی را که مفسر برای فراخوانی‌های dlopen() به کار می‌برد، تنظیم کنید، مانند زمانی که مفسر ماژول‌های توسعه‌ای را بارگذاری می‌کند. از جمله، اگر به‌صورت sys.setdlopenflags(0) فراخوانی شود، این کار حل با تأخیر نمادها را هنگام ایمپورت یک ماژول فعال می‌کند. برای اشتراک‌گذاری نمادها میان ماژول‌های توسعه‌ای، به‌صورت sys.setdlopenflags(os.RTLD_GLOBAL) فراخوانی کنید. نام‌های نمادین برای مقادیر پرچم را می‌توان در ماژول os یافت (ثابت‌های RTLD_xxx، برای مثال os.RTLD_LAZY).

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

sys.set_int_max_str_digits(maxdigits)¶

محدودیت طول تبدیل عدد صحیح به رشته را که این مفسر از آن استفاده می‌کند، تنظیم کنید. همچنین get_int_max_str_digits() را ببینید.

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

sys.set_lazy_imports(mode)¶

حالت سراسری ایمپورت‌های تنبل را تنظیم می‌کند. پارامتر mode باید یکی از رشته‌های زیر باشد:

• "normal": فقط ایمپورت‌هایی که صراحتاً با کلیدواژه‌ی lazy مشخص شده‌اند، تنبل هستند

• "all": تمام ایمپورت‌های سطح بالا به طور بالقوه تنبل می‌شوند

این تابع برای کاربران پیشرفته‌ای در نظر گرفته شده است که نیاز دارند ایمپورت‌های تنبل را در سرتاسر برنامه‌ی خود کنترل کنند. توسعه‌دهندگان کتابخانه‌ها به‌طور کلی نباید از این تابع استفاده کنند زیرا روی اجرای ران‌تایم برنامه‌ها تأثیر می‌گذارد.

علاوه بر حالت، ایمپورت‌های تنبل را می‌توان از طریق فیلتر ارائه‌شده توسط set_lazy_imports_filter() کنترل کرد.

همچنین نگاه کنید به get_lazy_imports() و PEP 810.

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

sys.set_lazy_imports_filter(filter)¶

کال‌بک فیلتر ایمپورت‌های تنبل را تنظیم می‌کند. پارامتر filter باید یک شیء فراخوانی‌پذیر یا برای پاک کردن فیلتر برابر با None باشد.

تابع فیلتر برای هر ایمپورتِ به طور بالقوه تنبلی فراخوانی می‌شود تا مشخص شود که آیا واقعاً باید تنبل باشد یا خیر. این تابع باید امضای زیر را داشته باشد:

def filter(importing_module: str, imported_module: str,
           fromlist: tuple[str, ...] | None) -> bool

این تابع با سه آرگومان جایگاهی فراخوانی می‌شود:

• importing_module نام ماژولی است که ایمپورت را انجام می‌دهد

• imported_module نام تفکیک‌شده‌ی ماژولی است که در حال ایمپورت شدن است (برای مثال، دستور lazy from .spam import eggs مقدار package.spam را ارسال می‌کند)

• fromlist تاپل نام‌هایی است که در حال ایمپورت شدن هستند (برای دستورات from ... import)، یا برای ایمپورت‌های معمولی مقدار None است

این فیلتر باید برای مجاز کردن تنبلی ایمپورت، مقدار True را برگرداند، یا برای وادار کردن به ایمپورت مشتاقانه، مقدار False را برگرداند.

این یک ویژگی پیشرفته است که برای کاربران متخصصی در نظر گرفته شده است که به کنترل دقیق روی رفتار ایمپورت تنبل نیاز دارند.

همچنین نگاه کنید به get_lazy_imports_filter() و PEP 810.

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

sys.setprofile(profilefunc)¶

تابع پروفایل سیستم را تنظیم کنید، که به شما امکان می‌دهد یک پروفایل‌گیر برای کد منبع پایتون را در پایتون پیاده‌سازی کنید. برای اطلاعات بیشتر درباره پروفایل‌گیر پایتون، فصل profile --- پروفایل‌گیر خالص پایتون را ببینید. تابع پروفایل سیستم مشابه تابع ردگیری سیستم فراخوانی می‌شود (به settrace() مراجعه کنید)، اما با رویدادهای متفاوتی فراخوانی می‌شود؛ برای مثال، به‌ازای هر خط کدی که اجرا می‌شود فراخوانی نمی‌شود (فقط در فراخوانی و بازگشت فراخوانی می‌شود، اما رویداد بازگشت حتی زمانی که استثنایی تنظیم شده باشد گزارش می‌شود). این تابع مختص نخ است، اما راهی برای آگاهی پروفایل‌گیر از تعویض‌های زمینه بین نخ‌ها وجود ندارد، بنابراین استفاده از آن در حضور چند نخ معنادار نیست. همچنین، از مقدار بازگشتی آن استفاده نمی‌شود، بنابراین می‌تواند به‌سادگی None را برگرداند. خطا در تابع پروفایل باعث می‌شود که این تابع برداشته شود.

نکته

برای setprofile() از همان سازوکار ردگیری‌ای استفاده می‌شود که برای settrace() به کار می‌رود. برای ردگیری فراخوانی‌ها با setprofile() درون یک تابع ردگیری (مثلاً در یک نقطه‌ی توقف اشکال‌زدا)، call_tracing() را ببینید.

توابع پروفایل‌گیری باید سه آرگومان داشته باشند: frame، event و arg. frame فریم پشته‌ی فعلی است. event یک رشته است: 'call'، 'return'، 'c_call'، 'c_return' یا 'c_exception'. arg به نوع رویداد بستگی دارد.

رویدادها معانی زیر را دارند:

'call'

یک تابع فراخوانی می‌شود (یا وارد بلوک کد دیگری می‌شوید). تابع پروفایل فراخوانی می‌شود؛ arg برابر None است.

'return'

یک تابع (یا بلوک کد دیگر) در آستانه بازگشت است. تابع پروفایل فراخوانی می‌شود؛ arg مقداری است که بازگردانده خواهد شد، یا اگر رویداد به دلیل پرتاب شدن یک استثنا رخ داده باشد، None است.

'c_call'

یک تابع C در آستانه فراخوانی است. این ممکن است یک تابع افزونه‌ای یا توکار باشد. arg شیء تابع C است.

'c_return'

یک تابع C بازگشت کرده است. arg شیء تابع C است.

'c_exception'

یک تابع C استثناای را پرتاب کرده است. arg شیء تابع C است.

یک رویداد حسابرسی sys.setprofile را بدون آرگومان پرتاب می‌کند.

sys.setrecursionlimit(limit)¶

حداکثر عمق پشته مفسر پایتون را روی limit تنظیم می‌کند. این محدودیت مانع از آن می‌شود که بازگشت بی‌نهایت باعث سرریز پشته C و از کار افتادن پایتون شود.

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

اگر حد جدید در عمق بازگشت فعلی بیش از حد کم باشد، استثنای RecursionError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.5.1: اکنون اگر حد جدید در عمق بازگشت فعلی بیش از حد کم باشد، استثنای RecursionError پرتاب می‌شود.

sys.setswitchinterval(interval)¶

بازه‌ی تعویض نخ مفسر (به ثانیه) را تنظیم می‌کند. این مقدار ممیز شناور، مدت ایده‌آل «اسلایس‌های زمانی» (timeslices) اختصاص‌داده‌شده به نخ‌های پایتونی که به‌طور همزمان اجرا می‌شوند را تعیین می‌کند. لطفاً توجه داشته باشید که مقدار واقعی می‌تواند بیشتر باشد، به‌ویژه اگر از توابع یا متدهای درونی با اجرای طولانی استفاده شود. هم‌چنین، این‌که در پایان بازه کدام نخ برای اجرا زمان‌بندی شود، تصمیم سیستم‌عامل است. مفسر زمان‌بند اختصاصی خود را ندارد.

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

sys.settrace(tracefunc)¶

تابع ردگیری سیستم را تنظیم کنید، که به شما امکان می‌دهد یک اشکال‌زدای کد منبع پایتون را در پایتون پیاده‌سازی کنید. این تابع مختص هر نخ است؛ برای اینکه یک اشکال‌زدا از چندین نخ پشتیبانی کند، باید برای هر نخی که اشکال‌زدایی می‌شود با استفاده از settrace() یک تابع ردگیری ثبت کند یا از threading.settrace() استفاده کند.

توابع ردگیری باید ۳ آرگومان داشته باشند: frame، event و arg. frame فریم پشته جاری است. event یک رشته است: 'call'، 'line'، 'return'، 'exception' یا 'opcode'. arg به نوع رویداد بستگی دارد.

تابع ردگیری هر زمان که وارد یک محدوده محلی جدید شود (با event تنظیم‌شده روی 'call') فراخوانی می‌شود؛ این تابع باید ارجاعی به یک تابع ردگیری محلی برای استفاده در محدوده جدید برگرداند، یا None اگر محدوده نباید ردگیری شود.

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

اگر خطایی در تابع ردگیری رخ دهد، آن لغو می‌شود، درست مانند این که settrace(None) فراخوانی شده باشد.

نکته

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

رویدادها معانی زیر را دارند:

'call'

یک تابع فراخوانی می‌شود (یا وارد بلوک کد دیگری می‌شوید). تابع ردگیری سراسری فراخوانی می‌شود؛ arg برابر None است؛ مقدار بازگشتی، تابع ردگیری محلی را مشخص می‌کند.

'line'

مفسر در حال اجرای یک سطر جدید کد یا اجرای مجدد شرط یک حلقه است. تابع ردگیریِ محلی فراخوانی می‌شود؛ arg برابر با None است؛ مقدارِ برگشتی تابع ردگیریِ محلیِ جدید را مشخص می‌کند. برای توضیح مفصل نحوه عملکرد به InternalDocs/code_objects.md مراجعه کنید. رویدادهای سطر به سطر می‌توانند برای یک قاب با تنظیم f_trace_lines به False روی آن frame غیرفعال شوند.

'return'

یک تابع (یا بلوک کد دیگر) در شرف بازگشت است. تابع ردگیری محلی فراخوانی می‌شود؛ arg مقداری است که برگردانده خواهد شد، یا اگر رویداد ناشی از پرتاب شدن یک استثنا باشد None است. مقدار بازگشتی تابع ردگیری نادیده گرفته می‌شود.

'exception'

استثنایی رخ داده است. تابع ردگیری محلی فراخوانی می‌شود؛ arg یک تاپل (exception, value, traceback) است؛ مقدار بازگشتی، تابع ردگیری محلی جدید را مشخص می‌کند.

'opcode'

مفسر در آستانه اجرای یک آپ‌کدی جدید (opcode) است (برای جزئیات آپ‌کدی به dis مراجعه کنید). تابع ردگیری محلی فراخوانی می‌شود؛ arg برابر None است؛ مقدار بازگشتی، تابع ردگیری محلی جدید را مشخص می‌کند. به‌طور پیش‌فرض، رویدادهای به‌ازای هر آپ‌کدی منتشر نمی‌شوند: این رویدادها باید به‌صراحت با تنظیم f_trace_opcodes روی True در فریم درخواست شوند.

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

برای استفاده‌ی دقیق‌تر، می‌توانید با انتساب صریح frame.f_trace = tracefunc یک تابع ردگیری را تنظیم کنید، به جای آنکه به تنظیم غیرمستقیم آن از طریق مقدار بازگشتی یک تابع ردگیری از پیش نصب‌شده تکیه کنید. این کار همچنین برای فعال‌سازی تابع ردگیری در فریم جاری لازم است، که settrace() آن را انجام نمی‌دهد. توجه داشته باشید که برای اینکه این کار کند، باید یک تابع ردگیری سراسری با settrace() نصب شده باشد تا سازوکار ردگیری ران‌تایم فعال شود، اما لازم نیست همان تابع ردگیری باشد (برای مثال، می‌تواند یک تابع ردگیری کم‌سربار باشد که صرفاً None را برمی‌گرداند تا خود را بلافاصله در هر فریم غیرفعال کند).

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

یک رویداد حسابرسی sys.settrace را بدون آرگومان پرتاب می‌کند.

تابع settrace() فقط برای پیاده‌سازی اشکال‌زداها، پروفایل‌گیرها ، ابزارهای پوشش (coverage) و موارد مشابه در نظر گرفته شده است. رفتار آن بخشی از سکوی پیاده‌سازی است، نه بخشی از تعریف زبان، و بنابراین ممکن است در تمام پیاده‌سازی‌های پایتون در دسترس نباشد.

تغییر یافته در نسخه‌ی 3.7: نوع رویداد 'opcode' افزوده شد؛ ویژگی‌های f_trace_lines و f_trace_opcodes به فریم‌ها افزوده شدند

sys.set_asyncgen_hooks([firstiter] [, finalizer])¶

دو آرگومان کلیدواژه‌ای اختیاری می‌پذیرد که فراخوانی‌پذیر هستند و یک asynchronous generator iterator را به‌عنوان آرگومان می‌پذیرند. فراخوانی‌پذیر firstiter هنگامی فراخوانی خواهد شد که یک تولیدگر ناهمگام برای اولین بار پیمایش شود. finalizer هنگامی فراخوانی خواهد شد که یک تولیدگر ناهمگام در آستانه زباله‌روبی شدن باشد.

یک رویداد حسابرسی sys.set_asyncgen_hooks_firstiter را بدون آرگومان پرتاب می‌کند.

یک رویداد حسابرسی sys.set_asyncgen_hooks_finalizer را بدون آرگومان پرتاب می‌کند.

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

اضافه شده در نسخه‌ی 3.6: برای جزئیات بیشتر PEP 525 را ببینید، و برای یک مثال مرجع از متد نهایی‌ساز، پیاده‌سازی asyncio.Loop.shutdown_asyncgens در Lib/asyncio/base_events.py را ببینید

نکته

این تابع به‌صورت آزمایشی افزوده شده است (برای جزئیات، PEP 411 را ببینید.)

sys.set_coroutine_origin_tracking_depth(depth)¶

امکان فعال یا غیرفعال کردن پیگیری مبدأ هم‌روال را فراهم می‌کند. هنگامی که فعال باشد، ویژگی cr_origin در اشیای هم‌روال شامل تاپلی از تاپل‌های (نام پرونده، شماره‌ی خط، نام تابع) خواهد بود که ردگیری پشته‌ی محل ایجاد شیء هم‌روال را توصیف می‌کند، به‌طوری که جدیدترین فراخوانی در ابتدا قرار دارد. هنگامی که غیرفعال باشد، cr_origin برابر None خواهد بود.

برای فعال‌سازی، مقداری برای depth بزرگ‌تر از ۰ ارسال کنید؛ این کار تعداد فریم‌هایی را که اطلاعات آن‌ها ضبط خواهد شد تنظیم می‌کند. برای غیرفعال‌سازی، depth را روی ۰ تنظیم کنید.

این تنظیم مختص نخ است.

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

نکته

این تابع به‌صورت موقت افزوده شده است (برای جزئیات PEP 411 را ببینید). از آن فقط برای اهداف اشکال‌زدایی استفاده کنید.

sys.activate_stack_trampoline(backend, /)¶

بک‌اند ترامپولین (trampoline) پروفایل‌گیر پشته را فعال کنید. تنها بک‌اند پشتیبانی‌شده "perf" است.

اگر JIT فعال باشد، ترمپولین‌های پشته (Stack trampolines) نمی‌توانند فعال شوند.

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

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

همچنین ببینید

• پشتیبانی پایتون از پروفایل‌گیرهای سازگار با perf map

• https://perf.wiki.kernel.org

sys.deactivate_stack_trampoline()¶

غیرفعال کردن بک‌اند فعلی ترامپولین (trampoline) پروفایل‌گیر پشته.

اگر هیچ پروفایل‌گیر پشته‌ای (stack profiler) فعال نشده باشد، این تابع هیچ تأثیری ندارد.

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

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

sys.is_stack_trampoline_active()¶

اگر ترامپولین پروفایل‌گیر پشته (stack profiler trampoline) فعال باشد، True را برمی‌گرداند.

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

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

sys.remote_exec(pid, script)¶

script، پرونده‌ای حاوی کد پایتون، را در فرایند راه دور با pid داده‌شده اجرا می‌کند.

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

فرایند راه دور باید در حال اجرای یک مفسر CPython با همان نسخه‌ی اصلی و فرعی فرایند محلی باشد. اگر مفسر محلی یا راه دور پیش‌انتشار (آلفا، بتا یا نامزد انتشار) باشد، مفسرهای محلی و راه دور باید دقیقاً نسخه‌ی یکسانی داشته باشند.

برای اطلاعات بیشتر درباره سازوکار اشکال‌زدایی راه‌دور، پروتکل اتصال اشکال‌زدایی راه دور را ببینید.

هنگامی که کد در فرایند راه‌دور اجرا می‌شود، یک رویداد حسابرسی sys.remote_exec با pid و مسیر پرونده اسکریپت پرتاب می‌شود. این رویداد در فرایندی که sys.remote_exec() را فراخوانی کرده است، پرتاب می‌شود.

هنگامی که اسکریپت در فرایند راه‌دور اجرا می‌شود، یک رویداد حسابرسی cpython.remote_debugger_script به‌همراه مسیر درون فرایند راه‌دور پرتاب می‌شود. این رویداد در فرایند راه‌دور پرتاب می‌شود، نه در فرایندی که sys.remote_exec() را فراخوانی کرده است.

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

اضافه شده در نسخه‌ی 3.14: برای جزئیات بیشتر، PEP 768 را ببینید.

sys._enablelegacywindowsfsencoding()¶

برای سازگاری با نسخه‌های پایتون پیش از 3.6، کدگذاری و مدیریت خطای سامانه فایل‌بندی را به‌ترتیب به 'mbcs' و 'replace' تغییر می‌دهد.

این معادل تعریف متغیر محیطی PYTHONLEGACYWINDOWSFSENCODING پیش از اجرای پایتون است.

همچنین sys.getfilesystemencoding() و sys.getfilesystemencodeerrors() را ببینید.

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

نکته

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

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

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.16 حذف خواهد شد: به‌جای آن از PYTHONLEGACYWINDOWSFSENCODING استفاده کنید.

sys.stdin¶

sys.stdout¶

sys.stderr¶

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

• از stdin برای تمام ورودی‌های تعاملی (از جمله فراخوانی‌های input()) استفاده می‌شود؛

• stdout برای خروجی print() و دستورهای عبارت و برای اعلان‌های input() استفاده می‌شود؛

• اعلان‌های خود مفسر و پیام‌های خطای آن به stderr فرستاده می‌شوند.

این جریان‌ها، پرونده‌های متنی عادی هستند، مانند آن‌هایی که تابع open() برمی‌گرداند. پارامترهای آن‌ها به‌صورت زیر انتخاب شده‌اند:

• کدگذاری و مدیریت خطا از PyConfig.stdio_encoding و PyConfig.stdio_errors مقداردهی اولیه می‌شوند.

  در ویندوز، برای دستگاه کنسول از UTF-8 استفاده می‌شود. دستگاه‌های غیرنویسه‌ای مانند پرونده‌های دیسک و پایپ‌ها از کدگذاری زبان locale سیستم (یعنی کدپیج ANSI) استفاده می‌کنند. دستگاه‌های نویسه‌ای غیرکنسولی مانند NUL (یعنی مواردی که isatty() مقدار True برمی‌گرداند) در هنگام راه‌اندازی از مقدار کدپیج‌های ورودی و خروجی کنسول استفاده می‌کنند، به‌ترتیب برای stdin و stdout/stderr. اگر فرایند در ابتدا به یک کنسول متصل نباشد، این مقدار به‌طور پیش‌فرض locale encoding سیستم است.

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

  در همه‌ی سکوها، می‌توانید کدگذاری نویسه‌ها را با تنظیم متغیر محیطی PYTHONIOENCODING پیش از شروع پایتون یا با استفاده از گزینه‌ی جدید خط فرمان -X utf8 و متغیر محیطی PYTHONUTF8 بازنویسی کنید. با این حال، برای کنسول ویندوز، این فقط زمانی اعمال می‌شود که PYTHONLEGACYWINDOWSSTDIO نیز تنظیم شده باشد.

• در حالت تعاملی، جریان stdout به‌صورت سطری بافر می‌شود. در غیر این صورت، مانند پرونده‌های متنی معمولی به‌صورت بلوکی بافر می‌شود. جریان stderr در هر دو حالت به‌صورت خطی بافر می‌شود. شما می‌توانید با استفاده از گزینه‌ی خط فرمان -u یا تنظیم متغیر محیطی PYTHONUNBUFFERED، هر دو جریان را بدون بافر کنید.

تغییر یافته در نسخه‌ی 3.9: stderr غیرتعاملی اکنون به‌جای بافر کامل، به‌صورت خطی بافر می‌شود.

نکته

برای نوشتن یا خواندن داده‌های دودویی به/از جریان‌های استاندارد، از شیء دودویی زیرین buffer استفاده کنید. برای مثال، برای نوشتن بایت‌ها به stdout، از sys.stdout.buffer.write(b'abc') استفاده کنید.

با این حال، اگر در حال نوشتن یک کتابخانه هستید (و کنترلی بر اینکه کد آن در چه زمینه‌ای اجرا می‌شود ندارید)، توجه داشته باشید که جریان‌های استاندارد ممکن است با اشیای شبه‌پرونده مانند io.StringIO جایگزین شوند که از ویژگی buffer پشتیبانی نمی‌کنند.

sys.__stdin__¶

sys.__stdout__¶

sys.__stderr__¶

این اشیاء حاوی مقادیر اصلی stdin، stderr و stdout در آغاز برنامه هستند. آن‌ها در طول نهایی‌سازی استفاده می‌شوند و می‌توانند برای چاپ در جریان استاندارد واقعی مفید باشند، صرف‌نظر از اینکه شیء sys.std* تغییر مسیر داده شده باشد.

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

نکته

در برخی شرایط، stdin، stdout و stderr و همچنین مقادیر اصلی __stdin__، __stdout__ و __stderr__ ممکن است None باشند. این حالت معمولاً برای برنامه‌های GUI ویندوز که به کنسول متصل نیستند و برنامه‌های پایتون که با pythonw اجرا می‌شوند، رخ می‌دهد.

sys.stdlib_module_names¶

یک مجموعه تغییرناپذیر (frozenset) از رشته‌ها که شامل نام ماژول‌های کتابخانه‌ی استاندارد است.

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

برای بسته‌ها، فقط بسته‌ی اصلی فهرست می‌شود: زیربسته‌ها و زیرماژول‌ها فهرست نمی‌شوند. برای مثال، بسته‌ی email فهرست شده است، اما زیربسته‌ی email.mime و زیرماژول email.message فهرست نشده‌اند.

همچنین فهرست sys.builtin_module_names را ببینید.

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

sys.thread_info¶

یک named tuple حاوی اطلاعاتی درباره‌ی پیاده‌سازی نخ.

thread_info.name¶

نام پیاده‌سازی نخ:

• "nt": نخ‌های ویندوز

• "pthread": نخ‌های POSIX

• "pthread-stubs": نخ‌های POSIX به‌صورت stub (در سکوهای WebAssembly بدون پشتیبانی از نخ‌ها)

• "solaris": نخ‌های Solaris

thread_info.lock¶

نام پیاده‌سازی قفل:

• "semaphore": یک قفل از یک سمافور استفاده می‌کند (پایتون ۳.۱۴ و قدیمی‌تر)

• "mutex+cond": یک قفل از یک قفل متقابل و یک متغیر شرط استفاده می‌کند (پایتون ۳.۱۴ و قدیمی‌تر)

• "pymutex": یک قفل از پیاده‌سازی PyMutex استفاده می‌کند (پایتون ۳.۱۵ و جدیدتر)

• None اگر این اطلاعات شناخته‌نشده باشد

thread_info.version¶

نام و نسخه‌ی کتابخانه‌ی نخ. این یک رشته است، یا اگر این اطلاعات نامشخص باشد None خواهد بود.

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

sys.tracebacklimit¶

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

sys.unraisablehook(unraisable, /)¶

یک استثنای غیرقابل پرتاب را مدیریت کنید.

هنگامی فراخوانی می‌شود که استثنایی رخ داده باشد اما پایتون هیچ راهی برای مدیریت آن نداشته باشد. برای مثال، زمانی که یک تخریب‌کننده استثنایی را پرتاب می‌کند یا در حین زباله‌روبی (gc.collect()).

آرگومان unraisable دارای ویژگی‌های زیر است:

• exc_type: نوع استثنا.

• exc_value: مقدار استثنا، می‌تواند None باشد.

• exc_traceback: ردگیری پشته‌ی استثنا، می‌تواند None باشد.

• err_msg: پیام خطا، می‌تواند None باشد.

• object: شیء ایجادکننده‌ی استثنا، می‌تواند None باشد.

قلاب پیش‌فرض، مقادیر err_msg و object را به صورت f'{err_msg}: {object!r}' قالب‌بندی می‌کند؛ اگر مقدار err_msg برابر با None باشد، از پیام خطای "Exception ignored in" استفاده کنید. مشابه ماژول traceback، این ویژگی به‌طور پیش‌فرض به استثناها رنگ اضافه می‌کند. این قابلیت را می‌توان با استفاده از متغیرهای محیطی غیرفعال کرد.

می‌توان sys.unraisablehook() را بازنویسی کرد تا چگونگی مدیریت استثناهای غیرقابل‌پرتاب کنترل شود.

تغییر یافته در نسخه‌ی 3.15: استثناها اکنون با متن رنگی چاپ می‌شوند.

همچنین ببینید

excepthook() که استثناهای گرفته‌نشده را مدیریت می‌کند.

هشدار

ذخیره‌ی exc_value با استفاده از یک قلاب سفارشی می‌تواند یک چرخه‌ی ارجاع ایجاد کند. هنگامی که دیگر نیازی به استثنا نیست، باید به‌صورت صریح پاک شود تا چرخه‌ی ارجاع شکسته شود.

ذخیره‌سازی object با استفاده از یک قلاب سفارشی (custom hook) می‌تواند باعث زنده‌سازی مجدد آن شود، اگر به شیءای تنظیم شده باشد که در حال نهایی‌سازی است. برای جلوگیری از زنده‌سازی مجدد اشیاء، پس از تکمیل قلاب سفارشی (custom hook) از ذخیره‌سازی object خودداری کنید.

هنگامی که استثنایی غیرقابل مدیریت رخ می‌دهد، یک رویداد حسابرسی sys.unraisablehook را با آرگومان‌های hook و unraisable پرتاب می‌کند. شیء unraisable همان چیزی است که به قلاب ارسال خواهد شد. اگر هیچ قلابی تنظیم نشده باشد، hook ممکن است None باشد.

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

sys.version¶

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

sys.api_version¶

نسخه‌ی C API، معادل ماکروی C PYTHON_API_VERSION. برای سازگاری با نسخه‌های پیشین تعریف شده است.

در حال حاضر، این ثابت در نسخه‌های جدید پایتون به‌روزرسانی نمی‌شود و برای نسخه‌بندی مفید نیست. این ممکن است در آینده تغییر کند.

sys.version_info¶

یک تاپل شامل پنج کامپوننت از شماره نسخه: major، minor، micro، releaselevel و serial. همه مقادیر به‌جز releaselevel عدد صحیح هستند؛ سطح انتشار یکی از 'alpha'، 'beta'، 'candidate' یا 'final' است. مقدار version_info متناظر با نسخه 2.0 پایتون برابر با (2, 0, 0, 'final', 0) است. این کامپوننت‌ها با نام نیز قابل دسترسی هستند، بنابراین sys.version_info[0] معادل sys.version_info.major است و به همین ترتیب.

تغییر یافته در نسخه‌ی 3.1: ویژگی‌های کامپوننت نام‌دار افزوده شد.

sys.warnoptions¶

این جزئیاتی از پیاده‌سازی چارچوب هشدارها است؛ این مقدار را تغییر ندهید. برای اطلاعات بیشتر درباره چارچوب هشدارها به ماژول warnings مراجعه کنید.

sys.winver¶

شماره نسخه‌ای که برای تشکیل کلیدهای رجیستری در سکوهای ویندوزی به کار می‌رود. این مقدار به‌عنوان منبع رشته 1000 در DLL پایتون ذخیره شده است. این مقدار معمولاً نسخه‌های اصلی و فرعی مفسر پایتون در حال اجرا است. این مقدار در ماژول sys برای اهداف اطلاع‌رسانی ارائه شده است؛ تغییر این مقدار تأثیری بر کلیدهای رجیستری مورد استفاده پایتون ندارد.

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

sys.monitoring

فضای نامی شامل توابع و ثابت‌ها برای ثبت کال‌بک‌ها و کنترل رویدادهای پایش. برای جزئیات، sys.monitoring را ببینید.

sys._xoptions¶

یک دیکشنری از پرچم‌های مختلف خاصِ پیاده‌سازی که از طریق گزینه‌ی خط فرمان -X منتقل می‌شوند. نام گزینه‌ها یا در صورت داده شدن به‌صورت صریح به مقدارهای خود نگاشت می‌شوند، یا به True. مثال:

$ ./python -Xa=b -Xc
Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys._xoptions
{'a': 'b', 'c': True}

این یک روش مخصوص CPython برای دسترسی به گزینه‌های ارسال‌شده از طریق -X است. سایر پیاده‌سازی‌ها ممکن است آن‌ها را از روش‌های دیگری اکسپورت کنند، یا اصلاً اکسپورت نکنند.

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

ارجاعات