مفسر تعاملی بهتر¶

پایتون اکنون به‌صورت پیش‌فرض از یک پوسته‌ی تعاملی جدید استفاده می‌کند که بر پایه‌ی کد PyPy project است. هنگامی که کاربر REPL را از یک پایانه‌ی تعاملی راه‌اندازی می‌کند، اکنون از قابلیت‌های جدید زیر پشتیبانی می‌شود:

• ویرایش چندسطری با حفظ تاریخچه.

• پشتیبانی مستقیم از دستورهای مخصوص REPL مانند help، exit و quit، بدون نیاز به فراخوانی آن‌ها به‌عنوان تابع.

• اعلان‌ها و ردگیری‌ها با رنگ فعال به‌صورت پیش‌فرض.

• مرور تعاملی راهنما با استفاده از F1 به همراه یک تاریخچه فرمان جداگانه.

• مرور تاریخچه با استفاده از F2 که از خروجی و همچنین اعلان‌های >>> و ... عبور می‌کند.

• «حالت چسباندن» با F3 که چسباندن بلوک‌های بزرگ‌تر کد را آسان‌تر می‌کند (برای بازگشت به اعلان معمولی، دوباره F3 را فشار دهید).

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

(ارائه‌شده توسط Pablo Galindo Salgado، Łukasz Langa و Lysandros Nikolaou در gh-111201 بر پایه‌ی کدی از پروژه‌ی PyPy. پشتیبانی ویندوز ارائه‌شده توسط Dino Viehland و Anthony Shaw.)

پیام‌های خطای بهبودیافته¶

• مفسر اکنون به‌طور پیش‌فرض هنگام نمایش ردگیری‌ها در پایانه از رنگ استفاده می‌کند. این قابلیت قابل کنترل است از طریق متغیر محیطی جدید PYTHON_COLORS و همچنین متغیرهای محیطی کانونیکال NO_COLOR و FORCE_COLOR. (مشارکت‌شده توسط Pablo Galindo Salgado در gh-112730.)

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

  $ python random.py
  Traceback (most recent call last):
    File "/home/me/random.py", line 1, in <module>
      import random
    File "/home/me/random.py", line 3, in <module>
      print(random.randint(5))
            ^^^^^^^^^^^^^^
  AttributeError: module 'random' has no attribute 'randint' (consider renaming '/home/me/random.py' since it has the same name as the standard library module named 'random' and prevents importing that standard library module)
  

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

  $ python numpy.py
  Traceback (most recent call last):
    File "/home/me/numpy.py", line 1, in <module>
      import numpy as np
    File "/home/me/numpy.py", line 3, in <module>
      np.array([1, 2, 3])
      ^^^^^^^^
  AttributeError: module 'numpy' has no attribute 'array' (consider renaming '/home/me/numpy.py' if it has the same name as a library you intended to import)
  

  (مشارکت‌شده توسط Shantanu Jain در gh-95754.)

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

  >>> "Better error messages!".split(max_split=1)
  Traceback (most recent call last):
    File "<python-input-0>", line 1, in <module>
      "Better error messages!".split(max_split=1)
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
  TypeError: split() got an unexpected keyword argument 'max_split'. Did you mean 'maxsplit'?
  

  (مشارکت‌شده توسط Pablo Galindo Salgado و Shantanu Jain در gh-107944.)

سی‌پایتون نخ‌آزاد¶

سی‌پایتون اکنون به‌صورت آزمایشی از اجرا در حالت نخ‌آزاد، با global interpreter lock (GIL) غیرفعال، پشتیبانی می‌کند. این یک ویژگی آزمایشی است و بنابراین به‌صورت پیش‌فرض فعال نیست. حالت نخ‌آزاد به یک پرونده اجرایی متفاوت نیاز دارد که معمولاً python3.13t یا python3.13t.exe نام دارد. می‌توان پرونده‌های دودویی پیش‌ساخته‌ای را که با برچسب نخ‌آزاد مشخص شده‌اند، به‌عنوان بخشی از نصب‌کننده‌های رسمی Windows و macOS نصب کرد، یا می‌توان سی‌پایتون را از کد منبع با گزینه‌ی --disable-gil ساخت.

اجرای نخ‌آزاد با اجرای موازی نخ‌ها روی هسته‌های CPU موجود، امکان بهره‌برداری کامل از توان پردازشی در دسترس را فراهم می‌کند. اگرچه همه‌ی نرم‌افزارها به‌طور خودکار از این امر بهره‌مند نمی‌شوند، برنامه‌هایی که با در نظر گرفتن نخ‌بندی طراحی شده‌اند، روی سخت‌افزار چند‌هسته‌ای سریع‌تر اجرا می‌شوند. حالت نخ‌آزاد آزمایشی است و کار روی بهبود آن ادامه دارد: انتظار داشته باشید با برخی اشکالات و افت عملکرد قابل‌توجه در حالت تک‌نخی مواجه شوید. نسخه‌های نخ‌آزاد سی‌پایتون از اجرای اختیاری با فعال بودن قفل مفسر سراسری در ران‌تایم، با استفاده از متغیر محیطی PYTHON_GIL یا گزینه‌ی خط فرمان -X gil=1 پشتیبانی می‌کنند.

برای بررسی اینکه آیا مفسر فعلی از نخ‌بندی آزاد پشتیبانی می‌کند، python -VV و sys.version شامل عبارت "experimental free-threading build" هستند. از تابع جدید sys._is_gil_enabled() می‌توان برای بررسی اینکه آیا قفل مفسر سراسری در فرایند در حال اجرا واقعاً غیرفعال است، استفاده کرد.

ماژول‌های توسعه‌ای C-API باید به‌طور خاص برای ساخت‌ نخ‌آزاد ساخته شوند. افزونه‌هایی که از اجرا با GIL غیرفعال پشتیبانی می‌کنند، باید از جایگاه Py_mod_gil استفاده کنند. افزونه‌هایی که از مقداردهی اولیه تک‌مرحله‌ای استفاده می‌کنند، باید از PyUnstable_Module_SetGIL() استفاده کنند تا مشخص کنند که آیا از اجرا با GIL غیرفعال پشتیبانی می‌کنند یا خیر. ایمپورت کردن افزونه‌های C که از این سازوکارها استفاده نمی‌کنند، باعث فعال شدن GIL می‌شود، مگر اینکه GIL به‌طور صریح با متغیر محیطی PYTHON_GIL یا گزینه‌ی -X gil=0 غیرفعال شده باشد. برای نصب بسته‌های دارای افزونه‌های C در ساخت‌ نخ‌آزاد، به pip 24.1 یا جدیدتر نیاز است.

انجام این کار به لطف افراد و سازمان‌های بسیاری ممکن شد، از جمله کامیونیتی بزرگ مشارکت‌کنندگان در پایتون و پروژه‌های شخص ثالث برای آزمودن و فعال‌سازی پشتیبانی از نخ‌بندی آزاد. از مشارکت‌کنندگان برجسته می‌توان به Sam Gross، Ken Jin، Donghee Na، Itamar Oren، Matt Page، Brett Simmers، Dino Viehland، Carl Meyer، Nathan Goldbaum، Ralf Gommers، Lysandros Nikolaou و بسیاری دیگر اشاره کرد. بسیاری از این مشارکت‌کنندگان در استخدام Meta هستند که منابع مهندسی چشمگیری برای پشتیبانی از این پروژه فراهم کرده است.

یک کامپایلر آزمایشی در لحظه¶

وقتی سی‌پایتون با استفاده از گزینه‌ی --enable-experimental-jit پیکربندی و ساخته شود، کامپایلری در لحظه افزوده می‌شود که ممکن است سرعت برخی برنامه‌های پایتون را افزایش دهد. در ویندوز، برای فعال‌سازی JIT از PCbuild/build.bat --experimental-jit استفاده کنید یا برای فعال‌سازی مفسر سطح ۲ (Tier 2) از --experimental-jit-interpreter استفاده کنید. نیازمندی‌های ساخت و اطلاعات پشتیبان بیشتر در Tools/jit/README.md آمده‌اند.

گزینه‌ی --enable-experimental-jit این مقادیر (اختیاری) را می‌پذیرد و اگر --enable-experimental-jit بدون مقدار اختیاری ذکر شود، مقدار پیش‌فرض yes است.

• no: کل خط لوله Tier 2 و JIT را غیرفعال می‌کند.

• yes: فعال‌سازی JIT. برای غیرفعال‌سازی JIT در زمان اجرا، متغیر محیطی PYTHON_JIT=0 را تنظیم کنید.

• yes-off: JIT را می‌سازد اما به‌طور پیش‌فرض آن را غیرفعال می‌کند. برای فعال‌سازی JIT در زمان اجرا، متغیر محیطی PYTHON_JIT=1 را تنظیم کنید.

• interpreter: مفسر Tier 2 را فعال می‌کند اما JIT را غیرفعال می‌کند. مفسر را می‌توان با اجرا به‌همراه PYTHON_JIT=0 غیرفعال کرد.

معماری داخلی تقریباً به شرح زیر است:

• با بایت‌کد تخصصی سطح ۱ (Tier 1) آغاز می‌کنیم. برای جزئیات به تازه‌های 3.11 مراجعه کنید.

• وقتی بایت‌کد Tier 1 به‌اندازه کافی داغ شود، به یک نمایش میانی (IR) جدید و کاملاً داخلی ترجمه می‌شود که Tier 2 IR نامیده می‌شود و گاهی نیز به آن میکرو-عملیات («uops») گفته می‌شود.

• نمایش میانی (IR) سطح ۲ از همان ماشین مجازی مبتنی بر پشته‌ی سطح ۱ استفاده می‌کند، اما قالب دستورالعمل آن برای ترجمه به کد ماشین مناسب‌تر است.

• ما چندین مرحله‌ی بهینه‌سازی برای Tier 2 IR داریم که پیش از آنکه تفسیر شود یا به کد ماشین ترجمه شود، اعمال می‌شوند.

• یک مفسر سطح ۲ (Tier 2) وجود دارد، اما این مفسر عمدتاً برای اشکال‌زدایی مراحل اولیه‌ی خط لوله‌ی بهینه‌سازی (pipeline) در نظر گرفته شده است. مفسر سطح ۲ را می‌توان با پیکربندی پایتون از طریق --enable-experimental-jit=interpreter فعال کرد.

• هنگامی که JIT فعال باشد، نمایش میانی سطح ۲ (Tier 2 IR) بهینه‌شده به کد ماشین تبدیل می‌شود و سپس اجرا می‌گردد.

• فرایند ترجمه به کد ماشین از تکنیکی به نام کپی‌وپچ (copy-and-patch) استفاده می‌کند. این فرایند هیچ وابستگی ران‌تایمی ندارد، اما وابستگی جدیدی در زمان ساخت به LLVM وجود دارد.

(JIT توسط برانت بوخر، الهام‌گرفته از مقاله‌ای از هائوران شو و فردریک کیولستاد. نمایش میانی (IR) سطح ۲ توسط مارک شانون و گیدو ون روسوم. بهینه‌ساز سطح ۲ توسط کن جین.)

معناشناسی تغییر برای locals() تعریف شد¶

از نظر تاریخی، نتیجه مورد انتظار تغییر دادن مقدار بازگشتی locals() به هر یک از پیاده‌سازی‌های پایتون واگذار شده بود تا آن را تعریف کند. از پایتون 3.13 به بعد، PEP 667 رفتار تاریخی سی‌پایتون را برای اغلب محدوده‌های اجرای کد استاندارد می‌کند، اما محدوده‌های بهینه‌شده (توابع، تولیدگر‌ها، هم‌روال‌ها، درک‌ها و عبارت‌های تولیدگر) را تغییر می‌دهد تا به‌صراحت تصاویر لحظه‌ای مستقلی از متغیر‌های محلی که در حال حاضر انتساب یافته‌اند، از جمله متغیر‌های غیرمحلی که به‌صورت محلی به آن‌ها ارجاع داده شده و در بستار‌ها ثبت شده‌اند، بازگردانند.

این تغییر در معناشناسی locals() در محدوده‌های بهینه‌شده، بر رفتار پیش‌فرض توابع اجرای کد نیز تأثیر می‌گذارد؛ این توابع در صورت ارائه‌نشدن فضای نام صریح، به‌طور ضمنی locals() را هدف می‌گیرند (مانند exec() و eval()). در نسخه‌های پیشین، اینکه آیا پس از فراخوانی تابع اجرای کد می‌توان با فراخوانی locals() به تغییرات دسترسی داشت یا نه، وابسته به پیاده‌سازی بود. به‌طور خاص در سی‌پایتون، چنین کدی معمولاً به‌ظاهر به‌درستی کار می‌کرد، اما گاهی ممکن بود در محدوده‌های بهینه‌شده، بسته به کدهای دیگر (از جمله اشکال‌زداها و ابزارهای ردگیری اجرای کد) که ممکن بود تصویر لحظه‌ای مشترک را در آن محدوده بازنشانی کنند، شکست بخورد. اکنون، کد همیشه نسبت به یک تصویر لحظه‌ای مستقل از متغیرهای محلی در محدوده‌های بهینه‌شده اجرا می‌شود و در نتیجه، تغییرات هرگز در فراخوانی‌های بعدی locals() قابل مشاهده نخواهند بود. برای دسترسی به تغییراتی که در این موارد ایجاد شده‌اند، اکنون باید یک ارجاع صریح به فضای نام، به تابع مربوطه ارسال شود. به‌عنوان جایگزین، ممکن است منطقی باشد که کد متأثر را به‌روزرسانی کنید تا از یک API اجرای کد سطح بالاتر که فضای نام حاصل از اجرای کد را برمی‌گرداند استفاده کند (برای مثال runpy.run_path() هنگام اجرای پرونده‌های پایتون از دیسک).

برای اطمینان از اینکه اشکال‌زداها و ابزارهای مشابه بتوانند متغیرهای محلی را در محدوده‌های متأثر از این تغییر به‌طور قابل اطمینان به‌روزرسانی کنند، FrameType.f_locals اکنون به‌جای بازگرداندن یک نمونه dict مشترک که به‌طور ناسازگار به‌روزرسانی می‌شد و معناشناسی زمان اجرای تعریف‌نشده‌ای داشت، یک پراکسی نوشتن‌همزمان به متغیرهای محلی فریم و متغیرهای غیرمحلی (nonlocal) ارجاع‌شده به‌صورت محلی در این محدوده‌ها برمی‌گرداند.

برای جزئیات بیشتر، از جمله تغییرات مرتبط در C API و موارد منسوخ‌شده، به PEP 667 مراجعه کنید. یادداشت‌های انتقال برای APIهای پایتون و APIهای C که تحت تأثیر قرار گرفته‌اند نیز در ادامه ارائه شده‌اند.

(PEP و پیاده‌سازی آن توسط Mark Shannon و Tian Gao در gh-74929 ارائه شده‌اند. به‌روزرسانی‌های مستندات توسط Guido van Rossum و Alyssa Coghlan فراهم شده است.)

پشتیبانی از پلتفرم‌های موبایل¶

PEP 730: iOS اکنون یک پلتفرم پشتیبانی‌شده بر اساس PEP 11 است، با هدف‌های arm64-apple-ios و arm64-apple-ios-simulator در سطح ۳ (به ترتیب دستگاه‌های iPhone و iPad که پس از ۲۰۱۳ عرضه شده‌اند، و شبیه‌ساز Xcode iOS در حال اجرا بر روی سخت‌افزار Apple silicon). x86_64-apple-ios-simulator (شبیه‌ساز Xcode iOS در حال اجرا بر روی سخت‌افزار قدیمی‌تر x86_64) یک پلتفرم پشتیبانی‌شده در سطح ۳ نیست، اما از پشتیبانی در حد توان (best-effort) برخوردار خواهد بود. (PEP توسط Russell Keith-Magee نوشته شده و پیاده‌سازی آن در gh-114099 ارائه شده است.)

PEP 738: اندروید اکنون یک پلتفرم پشتیبانی‌شده‌ی PEP 11 است، با هدف‌های aarch64-linux-android و x86_64-linux-android در سطح ۳. هدف‌های ۳۲‌بیتی arm-linux-androideabi و i686-linux-android پلتفرم‌های پشتیبانی‌شده‌ی سطح ۳ نیستند، اما پشتیبانی در حد توان (best-effort) خواهند داشت. (PEP نوشته‌شده و پیاده‌سازی توسط Malcolm Smith در gh-116622 ارائه‌شده است.)

argparse¶

• افزودن پارامتر deprecated به متدهای add_argument() و add_parser()، تا امکان منسوخ‌کردن گزینه‌های خط فرمان، آرگومان‌های جایگاهی و زیرفرمان‌ها فراهم شود. (مشارکت‌شده توسط سرهی استورچاکا در gh-83648.)

array¶

• افزودن کد نوع 'w' (Py_UCS4) برای نویسه‌های یونیکد. به جای کد نوع منسوخ 'u' باید از آن استفاده شود. (مشارکت‌شده توسط Inada Naoki در gh-80480.)

• ثبت array.array به‌عنوان یک MutableSequence با پیاده‌سازی متد clear(). (ارائه‌شده توسط Mike Zimin در gh-114894.)

ast¶

• سازنده‌های نوع‌های گره در ماژول ast اکنون در آرگومان‌هایی که می‌پذیرند سخت‌گیرانه‌تر هستند و هنگامی که آرگومان‌ها حذف شوند، رفتار شهودی‌تری دارند.

  اگر یک فیلد اختیاری روی یک گره AST هنگام ساخت یک نمونه به‌عنوان آرگومان گنجانده نشود، آن فیلد اکنون روی None تنظیم خواهد شد. به‌طور مشابه، اگر یک فیلد فهرستی حذف شود، آن فیلد اکنون روی یک فهرست خالی تنظیم خواهد شد، و اگر یک فیلد expr_context حذف شود، پیش‌فرض آن Load() خواهد بود. (پیش‌تر، در همه‌ی موارد، این ویژگی روی نمونه‌ی گره AST تازه‌ساخته‌شده وجود نداشت.)

  در تمام موارد دیگر، هرگاه آرگومان الزامی حذف شود، سازنده‌ی گره یک DeprecationWarning نشان خواهد داد. این کار در پایتون 3.15 استثنا پرتاب خواهد کرد. به‌طور مشابه، ارسال آرگومان کلیدواژه‌ای به سازنده که به فیلدی روی گره‌ی AST نگاشت نشود، اکنون منسوخ شده است و در پایتون 3.15 استثنا پرتاب خواهد کرد.

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

  (مشارکت Jelle Zijlstra در gh-105858، gh-117486 و gh-118851.)

• ast.parse() اکنون یک آرگومان اختیاری optimize را می‌پذیرد که به compile() منتقل می‌شود. این امر امکان به دست آوردن یک AST بهینه‌شده را فراهم می‌کند. (مشارکت‌شده توسط ایریت کاتریل در gh-108113.)

asyncio¶

• asyncio.as_completed() اکنون شیء‌ای را برمی‌گرداند که هم یک پیمایش‌گر ناهمگام است و هم یک پیمایش‌گر ساده از انتظارپذیرها. انتظارپذیرهایی که توسط پیمایش ناهمگام تولید می‌شوند، شامل اشیاء اصلی وظیفه یا آینده‌نما هستند که به آن پاس داده شده‌اند؛ این امر مرتبط کردن نتایج با وظایف در حال تکمیل را آسان‌تر می‌کند. (مشارکت‌شده توسط Justin Arthur در gh-77714.)

• asyncio.loop.create_unix_server() اکنون هنگام بسته شدن سرور، سوکت یونیکس را به‌طور خودکار حذف می‌کند. (مشارکت‌شده توسط Pierre Ossman در gh-111246.)

• DatagramTransport.sendto() اکنون در صورت فراخوانی با یک شیء بایت خالی، دیتاگرام‌هایی با طول صفر ارسال می‌کند. کنترل جریان ترابری نیز اکنون هنگام محاسبه اندازه بافر، سرآیند دیتاگرام را در نظر می‌گیرد. (مشارکت‌شده توسط Jamie Phan در gh-115199.)

• Queue.shutdown و QueueShutDown برای مدیریت خاتمه صف افزوده شدند. (با مشارکت Laurie Opperman و Yves Duprat در gh-104228.)

• افزودن متدهای Server.close_clients() و Server.abort_clients() که یک سرور asyncio را با قاطعیت بیشتری می‌بندند. (مشارکت‌شده توسط Pierre Ossman در gh-113538.)

• پذیرش تاپلی از جداکننده‌ها در StreamReader.readuntil()، که هنگام مواجهه با هر یک از آن‌ها متوقف می‌شود. (مشارکت‌شده توسط Bruce Merry در gh-81322.)

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

  در حالتی که یک گروه وظیفه از بیرون لغو شود و همچنین باید یک ExceptionGroup را raise کند، اکنون متد cancel() وظیفه‌ی والد را فراخوانی می‌کند. این تضمین می‌کند که یک CancelledError در await بعدی raise خواهد شد، تا لغو شدن از دست نرود.

  یک مزیت اضافی این تغییرات این است که گروه‌های وظیفه اکنون شمارش لغو را حفظ می‌کنند (cancelling()).

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

  (با الهام از مسئله‌ای که Arthur Tacca در gh-116720 گزارش کرده است.)

• وقتی TaskGroup.create_task() روی یک TaskGroup غیرفعال فراخوانی شود، هم‌روال داده‌شده بسته می‌شود (که از یک RuntimeWarning درباره‌ی این که هم‌روال داده‌شده هرگز await نشده است، جلوگیری می‌کند). (با مشارکت آرتور تاکا و جیسون ژانگ در gh-115957.)

• تابع و متدهای create_task آرگومان جدید **kwargs را دریافت کرده‌اند که به سازنده‌ی وظیفه پاس داده می‌شود. این تغییر به‌طور تصادفی در نسخه‌ی 3.13.3 اضافه شد و قرارداد API را برای کارخانه‌های وظیفه‌ی سفارشی نقض کرد. چندین کارخانه‌ی وظیفه‌ی شخص ثالث برای این موضوع راه‌حل‌های موقت پیاده‌سازی کردند. در نسخه‌ی 3.13.4 و نسخه‌های بعدی، قرارداد قدیمی کارخانه دوباره رعایت می‌شود (تا نسخه‌ی 3.14). برای اینکه راه‌حل‌های موقت همچنان کار کنند، آرگومان اضافی **kwargs همچنان اجازه می‌دهد آرگومان‌های کلیدواژه‌ای اضافی به Task و به کارخانه‌های وظیفه‌ی سفارشی پاس داده شوند.

  این بر تابع و متد‌های زیر تأثیر می‌گذارد: asyncio.create_task()، asyncio.loop.create_task()، asyncio.TaskGroup.create_task(). (مشارکت از Thomas Grainger در gh-128307.)

base64¶

• افزودن توابع z85encode() و z85decode() برای کدگذاری bytes به‌صورت Z85 data و کدگشایی داده‌های کدگذاری‌شده با Z85 به bytes. (مشارکت‌شده توسط Matan Perelman در gh-75299.)

compileall¶

• تعداد پیش‌فرض نخ‌های کارگر و فرایندها اکنون با استفاده از os.process_cpu_count() به جای os.cpu_count() انتخاب می‌شود. (با مشارکت Victor Stinner در gh-109649.)

concurrent.futures¶

• تعداد پیش‌فرض نخ‌های کارگر و فرایندها اکنون با استفاده از os.process_cpu_count() به جای os.cpu_count() انتخاب می‌شود. (با مشارکت Victor Stinner در gh-109649.)

configparser¶

• ConfigParser اکنون از بخش‌های بی‌نام پشتیبانی می‌کند که امکان استفاده از جفت‌های کلید-مقدار در سطح بالا را فراهم می‌کند. این قابلیت را می‌توان با پارامتر جدید allow_unnamed_section فعال کرد. (مشارکت‌شده توسط Pedro Sousa Lacerda در gh-66449.)

copy¶

• تابع جدید replace() و پروتکل replace ساخت کپی‌های تغییر‌یافته از اشیاء را بسیار ساده‌تر می‌کنند. این به‌ویژه هنگام کار با اشیاء تغییرناپذیر مفید است. انواع زیر از تابع replace() پشتیبانی می‌کنند و پروتکل replace را پیاده‌سازی می‌کنند:

  • collections.namedtuple()

  • dataclasses.dataclass

  • datetime.datetime, datetime.date, datetime.time

  • inspect.Signature, inspect.Parameter

  • types.SimpleNamespace

  • اشیاء کد

  هر کلاس تعریف‌شده توسط کاربر نیز می‌تواند با تعریف متد __replace__() از copy.replace() پشتیبانی کند. (مشارکت‌شده توسط Serhiy Storchaka در gh-108751.)

ctypes¶

• در نتیجه‌ی بازآرایی داخلی ضروری، مقداردهی اولیه فراکلاس‌های داخلی اکنون در __init__ انجام می‌شود، نه در __new__. این موضوع بر پروژه‌هایی تأثیر می‌گذارد که برای فراهم کردن مقداردهی اولیه سفارشی، از این فراکلاس‌های داخلی زیرکلاس می‌سازند. به‌طور کلی:

  • منطق سفارشی‌ای که در __new__ پس از فراخوانی super().__new__ انجام می‌شد، باید به __init__ منتقل شود.

  • برای ایجاد یک کلاس، فراکلاس را فراخوانی کنید، نه فقط متد __new__ فراکلاس را.

  برای بحث و پیوندهایی به تغییرات در برخی پروژه‌های متأثر، gh-124520 را ببینید.

• اشیاء ctypes.Structure یک ویژگی جدید _align_ دارند که به شما امکان می‌دهد ترازبندی ساختار هنگام بسته‌بندی/واگشایی آن به/از حافظه را به‌طور صریح مشخص کنید. (مشارکت‌شده توسط مت سندرسون در gh-112433)

dbm¶

• افزودن dbm.sqlite3، ماژول جدیدی که یک بک‌اند SQLite را پیاده‌سازی می‌کند، و قرار دادن آن به‌عنوان بک‌اند پیش‌فرض dbm. (مشارکت توسط Raymond Hettinger و Erlend E. Aasland در gh-100414.)

• امکان حذف تمام آیتم‌های پایگاه داده از طریق متدهای جدید clear() در اشیای پایگاه داده‌ی GDBM و NDBM فراهم شد. (با مشارکت Donghee Na در gh-107122.)

dis¶

• خروجی توابع ماژول dis تغییر کرده است تا به‌جای آفست‌ها، برچسب‌های منطقی برای مقصد‌های پرش (jump targets) و هندلرهای استثنا را نمایش دهد. آفست‌ها را می‌توان با گزینه‌ی جدید خط فرمان -O یا آرگومان show_offsets اضافه کرد. (مشارکت‌شده توسط ایریت کاتریل در gh-112137.)

• get_instructions() دیگر ورودی‌های نهانگاه را به‌صورت دستورهای جداگانه بازنمایی نمی‌کند. در عوض، آن‌ها را به‌عنوان بخشی از کلاس Instruction، در فیلد جدید cache_info برمی‌گرداند. آرگومان show_caches در get_instructions() منسوخ شده است و دیگر هیچ اثری ندارد. (مشارکت‌شده توسط ایریت کاتریل در gh-112962.)

doctest¶

• خروجی doctest اکنون به‌صورت پیش‌فرض رنگی است. این را می‌توان از طریق متغیر محیطی جدید PYTHON_COLORS و همچنین متغیرهای محیطی کانونیکال NO_COLOR و FORCE_COLOR کنترل کرد. همچنین به کنترل رنگ مراجعه کنید. (مشارکت‌شده توسط Hugo van Kemenade در gh-117225.)

• متد DocTestRunner.run() اکنون تعداد آزمون‌های نادیده‌گرفته‌شده را شمارش می‌کند. ویژگی‌های DocTestRunner.skips و TestResults.skipped افزوده شدند. (مشارکت‌شده توسط Victor Stinner در gh-108794.)

email¶

• سرآیندهای دارای سطرهای جدید تعبیه‌شده اکنون در خروجی داخل علامت نقل‌قول قرار می‌گیرند. generator اکنون از سریال‌سازی (نوشتن) سرآیندهایی که به شکل نامناسب تا شده یا جداسازی شده‌اند و در نتیجه به‌عنوان چندین سرآیند تجزیه می‌شوند یا به داده‌های مجاور می‌پیوندند، خودداری می‌کند. اگر نیاز دارید این ویژگی ایمنی را غیرفعال کنید، مقدار verify_generated_headers را تنظیم کنید. (مشارکت‌شده توسط Bas Bloemsaat و Petr Viktorin در gh-121650.)

• توابع getaddresses() و parseaddr() اکنون در موقعیت‌های بیشتری که با نشانی‌های ایمیل نامعتبر مواجه می‌شوند، به‌جای مقادیری که ممکن است نادرست باشند، جفت‌های ('', '') برمی‌گردانند. این دو تابع یک پارامتر اختیاری جدید به نام strict دارند (پیش‌فرض True). برای به‌دست‌آوردن رفتار قدیمی (پذیرش ورودی بدشکل)، از strict=False استفاده کنید. می‌توان از getattr(email.utils, 'supports_strict_parsing', False) برای بررسی موجود بودن پارامتر strict استفاده کرد. (مشارکت‌شده توسط Thomas Dwyer و Victor Stinner برای gh-102988 به‌منظور بهبود رفع مشکل CVE 2023-27043.)

enum¶

• EnumDict عمومی شده است تا از زیرکلاس‌سازی EnumType بهتر پشتیبانی کند.

fractions¶

• اشیاء Fraction اکنون از قواعد استاندارد زبان کوچک مشخصات قالب‌بندی برای پُرکننده، ترازبندی، مدیریت علامت، عرض کمینه و گروه‌بندی پشتیبانی می‌کنند. (مشارکت Mark Dickinson در gh-111320.)

glob¶

• افزودن translate()، تابعی که مشخصات مسیر با وایلدکاردهای به سبک پوسته را به عبارت باقاعده تبدیل می‌کند. (مشارکت‌شده توسط بارنی گیل در gh-72904.)

importlib¶

• توابع زیر در importlib.resources اکنون با استفاده از چندین آرگومان جایگاهی، امکان دسترسی به یک پوشه (یا درخت) از منابع را می‌دهند (آرگومان‌های encoding و errors در توابع خواندن متن، اکنون فقط کلیدواژه‌ای هستند):

  • is_resource()

  • open_binary()

  • open_text()

  • path()

  • read_binary()

  • read_text()

  این توابع دیگر منسوخ نیستند و برای حذف برنامه‌ریزی نشده‌اند. (مشارکت‌شده توسط Petr Viktorin در gh-116608.)

• contents() همچنان به نفع API با امکانات کامل Traversable منسوخ است. با این حال، اکنون هیچ برنامه‌ای برای حذف آن وجود ندارد. (مشارکت‌شده توسط Petr Viktorin در gh-116608.)

io¶

• اکنون نهایی‌ساز IOBase هر خطایی را که توسط متد close() ایجاد می‌شود، با استفاده از sys.unraisablehook گزارش‌گیری می‌کند. پیش‌تر، خطاها به‌طور پیش‌فرض به‌صورت بی‌صدا نادیده گرفته می‌شدند و تنها در حالت توسعه پایتون یا هنگام استفاده از نسخه‌ی دیباگ پایتون گزارش‌گیری می‌شدند. (با مشارکت Victor Stinner در gh-62948.)

ipaddress¶

• ویژگی IPv4Address.ipv6_mapped افزوده شد که نشانی IPv6 نگاشت‌شده از IPv4 را برمی‌گرداند. (با مشارکت Charles Machalow در gh-109466.)

• اصلاح رفتار is_global و is_private در IPv4Address، IPv6Address، IPv4Network و IPv6Network. (مشارکت‌شده توسط Jakub Stasiak در gh-113171.)

itertools¶

• batched() پارامتر جدید strict دارد که اگر دسته‌ی نهایی کوتاه‌تر از اندازه‌ی دسته‌ی تعیین‌شده باشد، یک ValueError ایجاد می‌کند. (مشارکت‌شده توسط Raymond Hettinger در gh-113202.)

مارشال‌کردن¶

• افزودن پارامتر allow_code در توابع ماژول. با ارسال allow_code=False از سریال‌سازی و سریال‌زدایی اشیاء کدی که بین نسخه‌های پایتون ناسازگار هستند جلوگیری می‌شود. (مشارکت‌شده توسط Serhiy Storchaka در gh-113626.)

math¶

• تابع جدید fma() عملیات ضرب-جمع همجوش (fused multiply-add) را انجام می‌دهد. این تابع x * y + z را تنها با یک گرد کردن محاسبه می‌کند و بدین ترتیب از هرگونه افت دقت میانی جلوگیری می‌کند. این تابع، تابع fma() ارائه‌شده توسط C99 را دربر می‌گیرد و برای حالت‌های خاص، از مشخصات عملیات «fusedMultiplyAdd» در IEEE 754 پیروی می‌کند. (ارائه‌شده توسط Mark Dickinson و Victor Stinner در gh-73468.)

mimetypes¶

• تابع guess_file_type() برای حدس زدن نوع MIME از روی یک مسیر سامانه فایل‌بندی اضافه شد. استفاده از مسیرها با تابع guess_type() اکنون soft deprecated است. (مشارکت‌شده توسط Serhiy Storchaka در gh-66543.)

mmap¶

• mmap اکنون در ویندوز در برابر فروپاشی محافظت می‌شود، وقتی حافظه‌ی نگاشت‌شده به دلیل خطاهای سامانه فایل‌بندی یا نقض دسترسی در دسترس نباشد. (مشارکت‌شده توسط یانیس وایگند در gh-118209.)

• mmap یک متد جدید seekable() دارد که می‌توان از آن زمانی استفاده کرد که به یک شیء شبه‌پرونده‌ی مکان‌یابی‌پذیر نیاز باشد. متد seek() اکنون موقعیت مطلق جدید را برمی‌گرداند. (مشارکت‌شده توسط Donghee Na و Sylvie Liberman در gh-111835.)

• پارامتر جدید trackfd (فقط برای یونیکس) در mmap تکثیر توصیف‌گر پرونده را کنترل می‌کند؛ اگر نادرست باشد، توصیف‌گر پرونده‌ای که توسط fileno مشخص شده است تکثیر نخواهد شد. (با مشارکت Zackery Spytz و Petr Viktorin در gh-78502.)

multiprocessing¶

• تعداد پیش‌فرض نخ‌های کارگر و فرایندها اکنون با استفاده از os.process_cpu_count() به جای os.cpu_count() انتخاب می‌شود. (با مشارکت Victor Stinner در gh-109649.)

os¶

• افزودن تابع process_cpu_count() برای به‌دست‌آوردن تعداد هسته‌های منطقی CPU که توسط نخ فراخواننده‌ی فرایند جاری قابل استفاده‌اند. (مشارکت‌شده توسط Victor Stinner در gh-109649.)

• cpu_count() و process_cpu_count() را می‌توان از طریق متغیر محیطی جدید PYTHON_CPU_COUNT یا گزینه‌ی جدید خط فرمان -X cpu_count بازنویسی کرد. این گزینه برای کاربرانی که نیاز دارند منابع CPU یک سیستم کانتینری را بدون تغییر کد اپلیکیشن یا خودِ کانتینر محدود کنند، مفید است. (مشارکت‌شده توسط Donghee Na در gh-109595.)

• افزودن یک رابط سطح پایین به توصیف‌گرهای پرونده‌ی تایمر لینوکس از طریق timerfd_create()، timerfd_settime()، timerfd_settime_ns()، timerfd_gettime()، timerfd_gettime_ns()، TFD_NONBLOCK، TFD_CLOEXEC، TFD_TIMER_ABSTIME و TFD_TIMER_CANCEL_ON_SET (با مشارکت Masaru Tsuchiyama در gh-108277.)

• lchmod() و آرگومان follow_symlinks در chmod() اکنون هر دو در ویندوز دسترس‌پذیر هستند. توجه داشته باشید که مقدار پیش‌فرض follow_symlinks در lchmod() در ویندوز False است. (مشارکت‌شده توسط Serhiy Storchaka در gh-59616.)

• fchmod() و پشتیبانی از توصیف‌گرهای پرونده در chmod() هر دو اکنون در ویندوز در دسترس هستند. (مشارکت‌شده توسط Serhiy Storchaka در gh-113191.)

• در ویندوز، mkdir() و makedirs() اکنون از عبور دادن مقدار حالت 0o700 برای اعمال کنترل دسترسی بر پوشه‌ی جدید پشتیبانی می‌کنند. این به‌طور ضمنی بر tempfile.mkdtemp() تأثیر می‌گذارد و یک اقدام کاهشی برای CVE 2024-4030 است. سایر مقادیر حالت همچنان نادیده گرفته می‌شوند. (مشارکت‌شده توسط Steve Dower در gh-118486.)

• posix_spawn() اکنون مقدار None را برای آرگومان env می‌پذیرد، که باعث می‌شود فرایند تازه ایجادشده از محیط فرایند فعلی استفاده کند. (با مشارکت Jakub Kulik در gh-113119.)

• posix_spawn() اکنون می‌تواند در پلتفرم‌هایی که posix_spawn_file_actions_addclosefrom_np() را پشتیبانی می‌کنند، از ویژگی POSIX_SPAWN_CLOSEFROM در پارامتر file_actions استفاده کند. (مشارکت توسط Jakub Kulik در gh-113117.)

os.path¶

• افزودن isreserved() برای بررسی اینکه آیا مسیری در سیستم فعلی رزرو‌شده است. این تابع فقط در ویندوز دسترس‌پذیر است. (مشارکت‌شده توسط Barney Gale در gh-88569.)

• در ویندوز، isabs() دیگر مسیرهایی که دقیقاً با یک اسلش (\ یا /) شروع می‌شوند را مطلق در نظر نمی‌گیرد. (مشارکت‌شده توسط بارنی گیل و جان فاستر در gh-44626.)

• realpath() اکنون حتی اگر پرونده دسترس‌پذیر نباشد، نام‌های پرونده به سبک MS-DOS را حل می‌کند. (مشارکت‌شده توسط Moonsik Park در gh-82367.)

pathlib¶

• افزودن UnsupportedOperation که به‌جای NotImplementedError، زمانی که یک عملیات مسیر پشتیبانی نمی‌شود، raise می‌شود. (مشارکت توسط بارنی گیل در gh-89812.)

• افزودن سازنده‌ی جدید برای ایجاد اشیاء Path از URIهای «file» (file:///)، Path.from_uri(). (با مشارکت Barney Gale در gh-107465.)

• افزودن PurePath.full_match() برای تطبیق مسیرها با وایلدکارد‌های به سبک پوسته، شامل وایلدکارد بازگشتی "**". (مشارکت‌شده توسط Barney Gale در gh-73435.)

• ویژگی کلاس PurePath.parser برای نگه داشتن پیاده‌سازی os.path که برای تجزیه و الحاق سطح پایین مسیر استفاده می‌شود، اضافه شد. این پیاده‌سازی یا posixpath خواهد بود یا ntpath.

• افزودن آرگومان فقط‌کلیدواژه‌ای recurse_symlinks به Path.glob() و rglob(). (به همت بارنی گیل در gh-77609.)

• Path.glob() و rglob() اکنون هنگام دریافت الگویی که به «**» ختم می‌شود، پرونده‌ها و پوشه‌ها را برمی‌گردانند. پیش‌تر، تنها پوشه‌ها برگردانده می‌شدند. (مشارکت از سوی Barney Gale در gh-70303.)

• آرگومان صرفاً کلیدواژه‌ای follow_symlinks به Path.is_file، Path.is_dir، Path.owner() و Path.group() افزوده شد. (با مشارکت Barney Gale در gh-105793 و Kamil Turek در gh-107962.)

pdb¶

• breakpoint() و set_trace() اکنون بلافاصله وارد اشکال‌زدا می‌شوند، نه در سطر بعدی کدی که باید اجرا شود. این تغییر باعث می‌شود اشکال‌زدا هنگامی که breakpoint() در انتهای زمینه قرار گرفته باشد، خارج از زمینه توقف نکند. (مشارکت‌شده توسط Tian Gao در gh-118579.)

• sys.path[0] هنگامی که sys.flags.safe_path تنظیم شده باشد، دیگر با پوشه‌ی اسکریپتی که در حال اشکال‌زدایی است جایگزین نمی‌شود. (مشارکت‌شده توسط Tian Gao و Christian Walther در gh-111762.)

• zipapp اکنون به‌عنوان هدف اشکال‌زدایی پشتیبانی می‌شود. (مشارکت‌شده توسط Tian Gao در gh-118501.)

• امکان جابه‌جایی بین استثناهای زنجیره‌ای هنگام اشکال‌زدایی پس از خاتمه در pm() با استفاده از دستور جدید exceptions [exc_number] برای Pdb اضافه شد. (مشارکت‌شده توسط Matthias Bussonnier در gh-106676.)

• عبارت‌ها و دستورهایی که پیشوندشان یک فرمان pdb است، اکنون به‌درستی شناسایی و اجرا می‌شوند. (مشارکت Tian Gao در gh-108464.)

queue¶

• افزودن Queue.shutdown و ShutDown برای مدیریت خاتمه صف. (مشارکت‌شده توسط Laurie Opperman و Yves Duprat در gh-104750.)

random¶

• افزودن یک رابط خط فرمان. (مشارکت‌شده توسط Hugo van Kemenade در gh-118131.)

re¶

• برای شفافیت بیشتر، re.error به PatternError تغییر نام داده شد. re.error برای سازگاری با نسخه‌های پیشین حفظ شده است.

shutil¶

• پشتیبانی از آرگومان‌های کلیدواژه‌ای dir_fd و follow_symlinks در chown(). (مشارکت‌شده توسط Berker Peksag و Tahia K در gh-62308)

site¶

• پرونده‌های .pth اکنون ابتدا با استفاده از UTF-8 و سپس، در صورت شکست کدگشایی UTF-8، با locale encoding کدگشایی می‌شوند. (مشارکت‌شده توسط Inada Naoki در gh-117802.)

sqlite3¶

• اکنون اگر شیء Connection به‌طور صریح بسته نشده باشد، ResourceWarning منتشر می‌شود. (مشارکت‌شده توسط Erlend E. Aasland در gh-105539.)

• افزودن پارامتر فقط‌کلیدواژه‌ای filter به Connection.iterdump() برای فیلتر کردن اشیاء پایگاه داده جهت برون‌ریزی. (مشارکت‌شده توسط Mariusz Felisiak در gh-91602.)

ssl¶

• API تابع create_default_context() اکنون VERIFY_X509_PARTIAL_CHAIN و VERIFY_X509_STRICT را در پرچم‌های پیش‌فرض خود در بر می‌گیرد.

  نکته

  VERIFY_X509_STRICT ممکن است گواهی‌های پیش از RFC 5280 یا گواهی‌های بدشکلی را که پیاده‌سازی زیربنایی OpenSSL در غیر این صورت ممکن بود بپذیرد، رد کند. اگرچه غیرفعال کردن آن توصیه نمی‌شود، می‌توانید این کار را با استفاده از موارد زیر انجام دهید:

  import ssl
  
  ctx = ssl.create_default_context()
  ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT
  

  (مشارکت‌شده توسط William Woodruff در gh-112389.)

statistics¶

• kde() برای برآورد چگالی هسته‌ای افزوده شد. این کار امکان برآورد یک تابع چگالی احتمال پیوسته از روی تعداد ثابتی نمونه‌ی گسسته را فراهم می‌کند. (با مشارکت Raymond Hettinger در gh-115863.)

• افزودن kde_random() برای نمونه‌گیری از یک تابع چگالی احتمال برآوردشده که توسط kde() ایجاد شده است. (مشارکت‌شده توسط Raymond Hettinger در gh-115863.)

subprocess¶

• ماژول subprocess اکنون در موقعیت‌های بیشتر از تابع posix_spawn() استفاده می‌کند.

  شایان ذکر است که وقتی close_fds برابر True باشد (پیش‌فرض)، در صورتی که کتابخانه‌ی C تابع posix_spawn_file_actions_addclosefrom_np() را ارائه کند، از posix_spawn() استفاده خواهد شد؛ این تابع در نسخه‌های اخیر لینوکس، FreeBSD و Solaris موجود است. در لینوکس، این باید مشابه کد مبتنی بر vfork() موجود در لینوکس عمل کند.

  در صورتی که نیاز داشته باشید subprocess را مجبور کنید که هرگز از posix_spawn() استفاده نکند، می‌توانید یک تنظیم‌کننده‌ی کنترلی خصوصی به نام subprocess._USE_POSIX_SPAWN را روی False قرار دهید. لطفاً در صورت تنظیم این مورد، دلیل و جزئیات پلتفرم خود را در issue tracker گزارش دهید تا بتوانیم منطق انتخاب API خود را برای همه بهبود ببخشیم. (مشارکت‌شده توسط یاکوب کولیک در gh-113117.)

sys¶

• تابع _is_interned() برای آزمودن اینکه آیا یک رشته درون‌سازی (intern) شده است، اضافه شد. وجود این تابع در تمام پیاده‌سازی‌های پایتون تضمین نمی‌شود. (با مشارکت Serhiy Storchaka در gh-78573.)

tempfile¶

• در ویندوز، حالت پیش‌فرض 0o700 که توسط tempfile.mkdtemp() استفاده می‌شود، اکنون به دلیل تغییرات اعمال‌شده در os.mkdir()، دسترسی به پوشه‌ی جدید را محدود می‌کند. این یک اقدام کاهشی برای CVE 2024-4030 است. (مشارکت‌شده توسط Steve Dower در gh-118486.)

time¶

• در ویندوز، monotonic() اکنون از ساعت QueryPerformanceCounter() با وضوح ۱ میکروثانیه استفاده می‌کند، به‌جای ساعت GetTickCount64() که وضوح آن ۱۵٫۶ میلی‌ثانیه است. (مشارکت‌شده توسط Victor Stinner در gh-88494.)

• در ویندوز، time() اکنون از ساعت GetSystemTimePreciseAsFileTime() با وضوح ۱ میکروثانیه استفاده می‌کند، به‌جای ساعت GetSystemTimeAsFileTime() که وضوح ۱۵٫۶ میلی‌ثانیه دارد. (مشارکت‌شده توسط Victor Stinner در gh-63207.)

tkinter¶

• افزودن متدهای ابزارک tkinter: tk_busy_hold()، tk_busy_configure()، tk_busy_cget()، tk_busy_forget()، tk_busy_current() و tk_busy_status(). (مشارکت Miguel، klappnase و Serhiy Storchaka در gh-72684.)

• متد ابزارک tkinter به نام wm_attributes() اکنون نام ویژگی را بدون پیشوند منفی برای دریافت ویژگی‌های پنجره می‌پذیرد، برای مثال w.wm_attributes('alpha')، و به شما اجازه می‌دهد ویژگی‌ها و مقادیری را که باید تنظیم شوند، به‌صورت آرگومان‌های کلیدواژه‌ای مشخص کنید، برای مثال w.wm_attributes(alpha=0.5). (مشارکت‌شده توسط Serhiy Storchaka در gh-43457.)

• wm_attributes() اکنون می‌تواند ویژگی‌ها را با استفاده از پارامتر جدید و اختیاریِ فقط‌کلیدواژه‌ای return_python_dict، به‌صورت یک dict بازگرداند. (مشارکت‌شده توسط Serhiy Storchaka در gh-43457.)

• Text.count() اکنون می‌تواند هنگام استفاده از پارامتر جدید فقط‌کلیدواژه‌ای و اختیاری return_ints، یک int ساده برگرداند. در غیر این صورت، تعداد به صورت یک تاپل تک‌عضوی یا None برگردانده می‌شود. (مشارکت‌شده توسط Serhiy Storchaka در gh-97928.)

• پشتیبانی از نوع المان "vsapi" در متد element_create() از کلاس tkinter.ttk.Style. (مشارکت‌شده توسط Serhiy Storchaka در gh-68166.)

• افزودن متد after_info() برای ابزارک‌های Tkinter. (مشارکت‌شده توسط Cheryl Sabella در gh-77020.)

• متد جدید copy_replace() به PhotoImage اضافه شد تا ناحیه‌ای را از یک تصویر به تصویری دیگر، با امکان بزرگ‌نمایی پیکسلی، زیرنمونه‌گیری (subsampling) یا هر دو، کپی کند. (مشارکت‌شده توسط Serhiy Storchaka در gh-118225.)

• افزودن پارامتر from_coords به متد‌های copy()، zoom() و subsample() از PhotoImage. افزودن پارامتر‌های zoom و subsample به متد copy() از PhotoImage. (مشارکت‌شده توسط Serhiy Storchaka در gh-118225.)

• متدهای read() برای خواندن تصویر از یک پرونده و data() برای دریافت داده‌های تصویر به کلاس PhotoImage اضافه شدند. پارامترهای background و grayscale به متد write() اضافه شدند. (مشارکت‌شده توسط Serhiy Storchaka در gh-118271.)

traceback¶

• ویژگی exc_type_str به TracebackException اضافه شد که نمایش رشته‌ای از exc_type را نگه می‌دارد. ویژگی exc_type که خودِ شیء نوع را نگه می‌دارد، منسوخ اعلام شد. پارامتر save_exc_type (پیش‌فرض True) اضافه شد تا مشخص کند که آیا exc_type باید ذخیره شود یا خیر. (مشارکت‌شده توسط Irit Katriel در gh-112332.)

• پارامتر جدید فقط‌کلیدواژه‌ای show_group به TracebackException.format_exception_only() اضافه شد تا استثناهای تودرتوی یک نمونه‌ی BaseExceptionGroup را (به‌صورت بازگشتی) قالب‌بندی کند. (مشارکت‌شده توسط Irit Katriel در gh-105292.)

types¶

• SimpleNamespace اکنون می‌تواند یک آرگومان جایگاهی واحد برای مقداردهی اولیه آرگومان‌های فضای نام بپذیرد. این آرگومان باید یا یک نگاشت یا یک پیمایش‌پذیر از جفت‌های کلید-مقدار باشد. (مشارکت‌شده توسط Serhiy Storchaka در gh-108191.)

typing¶

• PEP 705: افزودن ReadOnly، یک سازه‌ی تایپینگ ویژه به منظور علامت‌گذاری یک آیتم TypedDict به عنوان فقط‌خواندنی برای بررسی‌گرهای نوع.

• PEP 742: افزودن TypeIs، یک سازه‌ی تایپینگ که می‌توان از آن برای راهنمایی یک بررسی‌گر نوع در نحوه‌ی محدودسازی نوع استفاده کرد.

• افزودن NoDefault، شیء نشانگری که برای نمایش مقادیر پیش‌فرض برخی پارامترها در ماژول typing استفاده می‌شود. (مشارکت‌شده توسط Jelle Zijlstra در gh-116126.)

• افزودن get_protocol_members() برای بازگرداندن مجموعه‌ی اعضایی که یک typing.Protocol را تعریف می‌کنند. (مشارکت‌شده توسط Jelle Zijlstra در gh-104873.)

• تابع is_protocol() برای بررسی اینکه آیا یک کلاس یک Protocol است یا خیر، اضافه شد. (مشارکت‌شده توسط Jelle Zijlstra در gh-104873.)

• ClassVar اکنون می‌تواند در Final تودرتو شود و برعکس. (مشارکت‌شده توسط Mehdi Drissi در gh-89547.)

unicodedata¶

• پایگاه داده‌ی یونیکد به نسخه 15.1.0 به‌روزرسانی شد. (مشارکت‌شده توسط جیمز جریتی در gh-109559.)

venv¶

• افزودن پشتیبانی از ایجاد پرونده‌های نادیده‌گیری (ignore) مربوط به مدیریت کنترل نسخه (SCM) در پوشه‌ی محیط مجازی. به‌طور پیش‌فرض، از Git پشتیبانی می‌شود. این قابلیت از طریق API به‌صورت فعال‌سازی اختیاری (opt-in) پیاده‌سازی شده و می‌توان آن را برای پشتیبانی از SCM‌های دیگر گسترش داد (EnvBuilder و create())؛ همچنین از طریق CLI با استفاده از --without-scm-ignore-files می‌توان از آن صرف‌نظر کرد (opt-out). (مشارکت‌شده توسط Brett Cannon در gh-108125.)

warnings¶

• PEP 702: دکوراتور جدید warnings.deprecated() راهی برای اطلاع‌رسانی منسوخ‌شدگی‌ها به static type checker و هشدار دادن هنگام استفاده از کلاس‌ها و توابع منسوخ فراهم می‌کند. همچنین ممکن است هنگام استفاده از یک تابع یا کلاس دکوراتور‌شده در زمان اجرا، یک DeprecationWarning منتشر شود. (مشارکت‌شده توسط Jelle Zijlstra در gh-104003.)

xml¶

• امکان کنترل تعویق بازتجزیه (reparse deferral) در Expat >=2.6.0 (CVE 2023-52425) با افزودن پنج متد جدید فراهم شد:

  • xml.etree.ElementTree.XMLParser.flush()

  • xml.etree.ElementTree.XMLPullParser.flush()

  • xml.parsers.expat.xmlparser.GetReparseDeferralEnabled()

  • xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()

  • xml.sax.expatreader.ExpatParser.flush()

  (مشارکت Sebastian Pipping در gh-115623.)

• متد close() برای پاک‌سازی صریح به پیمایش‌گری که توسط iterparse() بازگردانده می‌شود، افزوده شد. (مشارکت Serhiy Storchaka در gh-69893.)

zipimport¶

• پشتیبانی از پرونده‌های با قالب ZIP64 اضافه شد. همه عاشق داده‌های عظیم هستند، نه؟ (مشارکت‌شده توسط Tim Hatch در gh-94146.)

PEP 594: حذف «باتری‌های مرده» از کتابخانه استاندارد¶

PEP 594 حذف ۱۹ ماژول از کتابخانه استاندارد را پیشنهاد کرد؛ این ماژول‌ها به دلیل تاریخی، از رده خارج یا ناامن بودن، به‌طور محاوره‌ای «باتری‌های مرده» (dead batteries) نامیده می‌شوند. تمام ماژول‌های زیر در پایتون 3.11 منسوخ شدند و اکنون حذف شده‌اند:

• aifc

  • standard-aifc: از بازتوزیع کتابخانه‌ی aifc در PyPI استفاده کنید.

• audioop

  • audioop-lts: از کتابخانه‌ی audioop-lts از PyPI استفاده کنید.

• chunk

  • standard-chunk: استفاده از بازتوزیع کتابخانه‌ی chunk از PyPI.

• cgi و cgitb

  • cgi.FieldStorage را معمولاً می‌توان با urllib.parse.parse_qsl() برای درخواست‌های GET و HEAD جایگزین کرد و برای درخواست‌های POST و PUT با ماژول email.message یا کتابخانه‌ی multipart.

  • cgi.parse() را می‌توان با فراخوانی مستقیم urllib.parse.parse_qs() روی رشته پرس‌وجوی موردنظر جایگزین کرد، مگر آنکه ورودی multipart/form-data باشد، که در این صورت باید مطابق توضیح داده‌شده در زیر برای cgi.parse_multipart() جایگزین شود.

  • cgi.parse_header() را می‌توان با کارکرد موجود در بسته‌ی email جایگزین کرد؛ این بسته همان RFC‌های MIME را پیاده‌سازی می‌کند. برای مثال، با email.message.EmailMessage:

    from email.message import EmailMessage
    
    msg = EmailMessage()
    msg['content-type'] = 'application/json; charset="utf8"'
    main, params = msg.get_content_type(), msg['content-type'].params
    

  • cgi.parse_multipart() را می‌توان با قابلیت‌های موجود در بسته‌ی email، که همان RFC‌های MIME را پیاده‌سازی می‌کند، یا با کتابخانه‌ی multipart جایگزین کرد. برای مثال، کلاس‌های email.message.EmailMessage و email.message.Message.

  • standard-cgi: و standard-cgitb: از بازتوزیع کتابخانه‌های cgi و cgitb در PyPI استفاده کنید.

• crypt و ماژول توسعه‌ای خصوصی _crypt. ماژول hashlib ممکن است زمانی که صرفاً هش‌کردن یک مقدار مورد نیاز است، جایگزین مناسبی باشد. در غیر این صورت، کتابخانه‌های شخص ثالث گوناگونی در PyPI در دسترس هستند:

  • bcrypt: هش‌سازی مدرن گذرواژه برای نرم‌افزار و سرورهای شما.

  • argon2-cffi: الگوریتم امن هش‌کردن گذرواژه Argon2.

  • legacycrypt: پوششی مبتنی بر ctypes برای فراخوانی کتابخانه‌ای crypt در POSIX و کارکردهای مرتبط.

  • crypt_r: انشعابی از ماژول crypt، پوششی برای فراخوانی کتابخانه‌ای crypt_r(3) و قابلیت‌های مرتبط.

  • standard-crypt و deprecated-crypt-alternative: از بازتوزیع کتابخانه‌ی crypt و پیاده‌سازی مجدد کتابخانه‌ی _crypt از PyPI استفاده کنید.

• imghdr: باید از کتابخانه‌های filetype، puremagic یا python-magic به‌عنوان جایگزین استفاده شود. برای مثال، تابع puremagic.what() می‌تواند برای همه‌ی قالب‌های پرونده‌ای که توسط imghdr پشتیبانی می‌شدند، جایگزین تابع imghdr.what() شود.

  • standard-imghdr: استفاده از بازتوزیع کتابخانه‌ی imghdr از PyPI.

• mailcap: به‌جای آن از ماژول mimetypes استفاده کنید.

  • standard-mailcap: از بازتوزیع کتابخانه‌ی mailcap در PyPI استفاده کنید.

• msilib

• nis

• nntplib: به جای آن از کتابخانه‌ی pynntp در PyPI استفاده کنید.

  • standard-nntplib: از بازتوزیع کتابخانه‌ی nntplib موجود در PyPI استفاده کنید.

• ossaudiodev: برای پخش صدا، به‌جای آن از کتابخانه‌ی pygame از PyPI استفاده کنید.

• pipes: به جای آن از ماژول subprocess استفاده کنید. برای جایگزینی تابع مستند‌نشده‌ی pipes.quote از shlex.quote() استفاده کنید.

  • standard-pipes: استفاده از بازتوزیع کتابخانه‌ی pipes از PyPI.

• sndhdr: کتابخانه‌های filetype، puremagic یا python-magic باید به‌عنوان جایگزین استفاده شوند.

  • standard-sndhdr: از بازتوزیع کتابخانه‌ی sndhdr از PyPI استفاده کنید.

• spwd: به‌جای آن، از کتابخانه‌ی python-pam در PyPI استفاده کنید.

• sunau

  • standard-sunau: از بازتوزیع کتابخانه‌ی sunau از PyPI استفاده کنید.

• telnetlib، به جای آن از کتابخانه‌های telnetlib3 یا Exscript موجود در PyPI استفاده کنید.

  • standard-telnetlib: از بازتوزیع کتابخانه‌ی telnetlib از PyPI استفاده کنید.

• uu: به جای آن، از ماژول base64 به عنوان یک جایگزین مدرن استفاده کنید.

  • standard-uu: از بازتوزیع کتابخانه‌ی uu در PyPI استفاده کنید.

• xdrlib

  • standard-xdrlib: از بازتوزیع کتابخانه‌ی xdrlib از PyPI استفاده کنید.

(با مشارکت ویکتور استینر و زاکری ور در gh-104773 و gh-104780.)

2to3¶

• برنامه 2to3 و ماژول lib2to3 که پیش‌تر در پایتون 3.11 منسوخ شده بودند، حذف شدند. (مشارکت‌شده توسط Victor Stinner در gh-104780.)

builtins¶

• پشتیبانی از توصیف‌گرهای زنجیره‌ای classmethod حذف شد (که در gh-63272 معرفی شده بودند). از این توصیف‌گرها دیگر نمی‌توان برای دربرگرفتن توصیف‌گرهای دیگر، مانند property، استفاده کرد. طراحی اصلی این قابلیت معیوب بود و به چندین مشکل منجر شد. برای «عبور» (pass-through) از یک classmethod، استفاده از ویژگی __wrapped__ را در نظر بگیرید که در پایتون 3.10 افزوده شد. (مشارکت‌شده توسط Raymond Hettinger در gh-89519.)

• هنگام فراخوانی frame.clear() بر روی یک فریم معلق، یک RuntimeError ایجاد می‌شود (همان‌طور که همیشه برای یک فریم در حال اجرا چنین بوده است). (مشارکت Irit Katriel در gh-79932.)

configparser¶

• کلاس بدون مستندات LegacyInterpolation که در رشته مستند از پایتون 3.2 و در زمان اجرا از پایتون 3.11 منسوخ شده بود، حذف شد. (مشارکت‌شده توسط هوگو ون کمِناده در gh-104886.)

importlib.metadata¶

• حذف دسترسی زیرنویسی منسوخ (__getitem__()) برای اشیاء EntryPoint. (با مشارکت Jason R. Coombs در gh-113175.)

locale¶

• تابع locale.resetlocale() که در پایتون 3.11 منسوخ شده بود، حذف شد. به جای آن از locale.setlocale(locale.LC_ALL, "") استفاده کنید. (مشارکت‌شده توسط Victor Stinner در gh-104783.)

آپ‌کد¶

• opcode.ENABLE_SPECIALIZATION به _opcode.ENABLE_SPECIALIZATION منتقل شد. این فیلد در 3.12 افزوده شد، هرگز مستند نشد و برای استفاده‌ی بیرونی در نظر گرفته نشده است. (مشارکت‌شده توسط Irit Katriel در gh-105481.)

• حذف opcode.is_pseudo()، opcode.MIN_PSEUDO_OPCODE و opcode.MAX_PSEUDO_OPCODE که در پایتون 3.12 اضافه‌شده بودند، اما نه مستند‌شده بودند و نه از طریق dis در دسترس قرار گرفته بودند، و برای استفاده‌ی خارجی در نظر گرفته نشده بودند. (مشارکت‌شده توسط Irit Katriel در gh-105481.)

optparse¶

• این ماژول دیگر منسوخِ نرم (soft deprecated) در نظر گرفته نمی‌شود. هرچند argparse همچنان گزینه‌ی ترجیحی برای پروژه‌های جدیدی است که از کتابخانه‌ی شخص ثالث برای پردازش آرگومان‌های خط فرمان استفاده نمی‌کنند، جنبه‌هایی از نحوه‌ی کارکرد argparse وجود دارد که به این معناست که ماژول سطح پایین‌تر optparse ممکن است برای نوشتن کتابخانه‌های پردازش آرگومان، و برای پیاده‌سازی برنامه‌های خط فرمانی که سخت‌گیرانه‌تر از argparse به قراردادهای گوناگون پردازش خط فرمان یونیکس (که ریشه در رفتار تابع getopt() زبان C دارند) پایبند هستند، پایه‌ی بهتری فراهم کند. (مشارکت‌شده توسط Alyssa Coghlan و Serhiy Storchaka در gh-126180.)

pathlib¶

• حذف قابلیت استفاده از اشیاء Path به عنوان مدیرهای زمینه. این قابلیت منسوخ شده بود و از پایتون 3.9 به بعد هیچ اثری نداشته است. (مشارکت‌شده توسط بارنی گیل در gh-83863.)

re¶

• تابع مستندنشده، منسوخ و خراب re.template() و پرچم re.TEMPLATE / re.T حذف شدند. (مشارکت‌شده توسط Serhiy Storchaka و Nikita Sobolev در gh-105687.)

tkinter.tix¶

• حذف ماژول tkinter.tix که در پایتون 3.6 منسوخ شده بود. کتابخانه‌ی شخص ثالث Tix که این ماژول آن را پوشش می‌داد، نگهداری نمی‌شود. (نوشته‌شده توسط Zachary Ware در gh-75552.)

turtle¶

• حذف متد RawTurtle.settiltangle() که در مستندات از پایتون 3.1 و در زمان اجرا از پایتون 3.11 منسوخ شده بود. (مشارکت هوگو ون کمناده در gh-104876.)

typing¶

• فضاهای نام typing.io و typing.re که از پایتون 3.8 منسوخ شده بودند، حذف شدند. آیتم‌های موجود در آن فضاهای نام را می‌توان مستقیماً از ماژول typing ایمپورت کرد. (مشارکت‌شده توسط سباستین ریتاو در gh-92871.)

• روش ایجاد نوع‌های TypedDict با آرگومان‌های کلیدواژه‌ای، که در پایتون 3.11 منسوخ شده بود، حذف شد. (مشارکت Tomas Roun در gh-104786.)

unittest¶

• حذف توابع زیر از unittest که در پایتون 3.11 منسوخ شده‌اند:

  • unittest.findTestCases()

  • unittest.makeSuite()

  • unittest.getTestCaseNames()

  به‌جای آن از متدهای TestLoader استفاده کنید:

  • loadTestsFromModule()

  • loadTestsFromTestCase()

  • getTestCaseNames()

  (مشارکت‌شده توسط هوگو ون کمِناده در gh-104835.)

• متد آزمون‌نشده و بدون مستندات TestProgram.usageExit() که در پایتون 3.11 منسوخ شده بود، حذف شد. (مشارکت توسط Hugo van Kemenade در gh-104992.)

urllib¶

• پارامترهای cafile، capath و cadefault تابع urllib.request.urlopen() که در پایتون 3.6 منسوخ شده بودند، حذف شدند. به‌جای آن‌ها از پارامتر context همراه با یک نمونه‌ی SSLContext استفاده کنید. می‌توان از تابع ssl.SSLContext.load_cert_chain() برای بارگذاری گواهی‌های خاص استفاده کرد، یا اجازه دهید ssl.create_default_context() گواهی‌های مرجع صدور گواهی (CA) مورد اعتماد سیستم‌عامل را انتخاب کند. (با مشارکت Victor Stinner در gh-105382.)

webbrowser¶

• کلاس MacOSX که آزمون‌نشده و مستندنشده بود و در پایتون 3.11 منسوخ شده بود، حذف شد. به جای آن، از کلاس MacOSXOSAScript (معرفی‌شده در پایتون 3.2) استفاده کنید. (مشارکت‌شده توسط Hugo van Kemenade در gh-104804.)

• ویژگی منسوخ MacOSXOSAScript._name حذف شد. به‌جای آن از ویژگی MacOSXOSAScript.name استفاده کنید. (مشارکت‌شده توسط نیکیتا سوبولف در gh-105546.)

در پایتون 3.14 حذف خواهد شد¶

• argparse: پارامترهای type، choices و metavar در argparse.BooleanOptionalAction منسوخ شده‌اند و در نسخه‌ی 3.14 حذف خواهند شد. (مشارکت Nikita Sobolev در gh-92248.)

• ast: قابلیت‌های زیر از زمان پایتون 3.8 در مستندات منسوخ اعلام شده‌اند، اکنون هنگامی که به آن‌ها دسترسی پیدا شود یا از آن‌ها استفاده شود، باعث صدور DeprecationWarning در ران‌تایم می‌شوند و در پایتون 3.14 حذف خواهند شد:

  • ast.Num

  • ast.Str

  • ast.Bytes

  • ast.NameConstant

  • ast.Ellipsis

  به جای آن از ast.Constant استفاده کنید. (مشارکت‌شده توسط Serhiy Storchaka در gh-90953.)

• asyncio:

  • کلاس‌های دیده‌بان فرزند (child watcher) asyncio.MultiLoopChildWatcher، asyncio.FastChildWatcher، asyncio.AbstractChildWatcher و asyncio.SafeChildWatcher منسوخ شده‌اند و در پایتون 3.14 حذف خواهند شد. (مشارکت‌شده توسط Kumar Aditya در gh-94597.)

  • asyncio.set_child_watcher()، asyncio.get_child_watcher()، asyncio.AbstractEventLoopPolicy.set_child_watcher() و asyncio.AbstractEventLoopPolicy.get_child_watcher() منسوخ شده‌اند و در پایتون 3.14 حذف خواهند شد. (مشارکت‌شده توسط Kumar Aditya در gh-94597.)

  • متد get_event_loop() از سیاست پیش‌فرض حلقه رویداد، اکنون در صورتی که هیچ حلقه رویداد جاری تنظیم‌نشده باشد و تصمیم بگیرد یکی ایجاد کند، یک DeprecationWarning منتشر می‌کند. (مشارکت‌شده توسط Serhiy Storchaka و Guido van Rossum در gh-100160.)

• email: پارامتر isdst در email.utils.localtime() منسوخ شد. (مشارکت‌شده توسط Alan Williams در gh-72346.)

• importlib.abc کلاس‌های منسوخ:

  • importlib.abc.ResourceReader

  • importlib.abc.Traversable

  • importlib.abc.TraversableResources

  در عوض از کلاس‌های importlib.resources.abc استفاده کنید:

  • importlib.resources.abc.Traversable

  • importlib.resources.abc.TraversableResources

  (مشارکت‌شده توسط Jason R. Coombs و Hugo van Kemenade در gh-93963.)

• itertools از عملیات کپی، deepcopy و پیکل پشتیبانی مستندنشده، ناکارآمد، به‌طور تاریخی دارای اشکال و ناسازگار داشت. این پشتیبانی در نسخه‌ی 3.14 برای کاهش چشمگیر حجم کد و بار نگهداری حذف خواهد شد. (مشارکت‌شده توسط Raymond Hettinger در gh-101588.)

• multiprocessing: روش آغاز پیش‌فرض در لینوکس، BSD‌ها و سایر پلتفرم‌های POSIX غیر از macOS که 'fork' در حال حاضر پیش‌فرض آن‌هاست، به روشی امن‌تر تغییر خواهد کرد (gh-84559). افزودن هشدار زمان اجرا درباره‌ی این موضوع بیش از حد مخل تلقی شد، زیرا انتظار نمی‌رود اکثر کدها به آن اهمیت دهند. از API‌های get_context() یا set_start_method() استفاده کنید تا به‌صراحت مشخص کنید که چه زمانی کد شما به 'fork' نیاز دارد. به زمینه‌ها و متدهای شروع مراجعه کنید.

• pathlib: is_relative_to() و relative_to(): گذر دادن آرگومان‌های اضافی منسوخ شده است.

• pkgutil: pkgutil.find_loader() و pkgutil.get_loader() اکنون هشدار DeprecationWarning ایجاد می‌کنند؛ به جای آن از importlib.util.find_spec() استفاده کنید. (مشارکت‌شده توسط نیکیتا سوبولف در gh-97850.)

• pty:

  • master_open(): از pty.openpty() استفاده کنید.

  • slave_open(): از pty.openpty() استفاده کنید.

• sqlite3:

  • version و version_info.

  • execute() و executemany() اگر از جای‌نگهدارهای نام‌دار استفاده شود و parameters به جای dict یک دنباله باشد.

• urllib: urllib.parse.Quoter منسوخ شده است: هرگز قرار نبوده که یک API عمومی باشد. (با مشارکت Gregory P. Smith در gh-88168.)

در انتظار حذف در پایتون 3.15¶

• سیستم ایمپورت:

  • تنظیم مقدار __cached__ روی یک ماژول در حالی که تنظیم __spec__.cached انجام نشده است، منسوخ شد. در نسخه‌ی ۳.۱۵ پایتون، __cached__ دیگر توسط سامانه ایمپورت یا کتابخانه‌ی استاندارد تنظیم نشده و در نظر گرفته نخواهد شد. (gh-97879)

  • تنظیم __package__ روی یک ماژول در حالی که __spec__.parent تنظیم نمی‌شود، منسوخ شده است. در پایتون 3.15، __package__ دیگر توسط سیستم ایمپورت یا کتابخانه استاندارد تنظیم یا در نظر گرفته نخواهد شد. (gh-97879)

• ctypes:

  • تابع مستندنشده‌ی ctypes.SetPointerType() از پایتون 3.13 منسوخ شده است.

• http.server:

  • کلاس منسوخ‌شده و کم‌استفاده‌ی CGIHTTPRequestHandler از نسخه‌ی ۳.۱۳ پایتون منسوخ شده است. هیچ جایگزین مستقیمی وجود ندارد. هر چیزی بهتر از CGI است تا یک وب‌سرور را به یک هندلر درخواست متصل کند.

  • پرچم --cgi در رابط خط فرمان python -m http.server از پایتون 3.13 منسوخ شده است.

• importlib:

  • متد load_module(): به‌جای آن از exec_module() استفاده کنید.

• pathlib:

  • متد .PurePath.is_reserved() از نسخه‌ی ۳.۱۳ پایتون منسوخ شده است. برای شناسایی مسیرهای رزرو شده در ویندوز از os.path.isreserved() استفاده کنید.

• platform:

  • تابع platform.java_ver() از نسخه‌ی ۳.۱۳ پایتون منسوخ شده است. این تابع فقط برای پشتیبانی از Jython مفید است، یک API گیج‌کننده دارد و تا حد زیادی آزمایش‌نشده است.

• sysconfig:

  • آرگومان check_home در sysconfig.is_python_build() از پایتون 3.12 منسوخ شده است.

• threading:

  • RLock() در پایتون 3.15 هیچ آرگومانی نخواهد گرفت. ارسال هر آرگومانی از پایتون 3.14 منسوخ شده است، زیرا نسخه‌ی پایتونی اجازه‌ی هیچ آرگومانی را نمی‌دهد، اما نسخه‌ی C اجازه‌ی هر تعداد آرگومان جایگاهی یا کلیدواژه‌ای را می‌دهد و همه‌ی آرگومان‌ها را نادیده می‌گیرد.

• types:

  • types.CodeType: دسترسی به codeobject.co_lnotab در PEP 626 از نسخه‌ی ۳.۱۰ منسوخ شد و برنامه‌ریزی شده بود در نسخه‌ی ۳.۱۲ حذف شود، اما فقط در نسخه‌ی ۳.۱۲ یک DeprecationWarning مناسب دریافت کرد. ممکن است در نسخه‌ی ۳.۱۵ حذف شود. (مشارکتی از Nikita Sobolev در gh-101866.)

• typing:

  • سینتکس آرگومان کلیدواژه‌ایِ مستندنشده برای ایجاد کلاس‌های NamedTuple (برای مثال، Point = NamedTuple("Point", x=int, y=int)) از پایتون 3.13 منسوخ شده است. به جای آن از سینتکس مبتنی بر کلاس یا سینتکس تابعی استفاده کنید.

  • هنگام استفاده از سینتکس تابعی TypedDict، عدم ارسال مقدار به پارامتر fields (TD = TypedDict("TD")) یا ارسال None (TD = TypedDict("TD", None)) از پایتون 3.13 منسوخ شده است. برای ایجاد یک TypedDict با صفر فیلد، از class TD(TypedDict): pass یا TD = TypedDict("TD", {}) استفاده کنید.

  • تابع دکوراتور typing.no_type_check_decorator از نسخه‌ی ۳.۱۳ پایتون منسوخ شده است. پس از هشت سال حضور در ماژول typing، هنوز توسط هیچ‌کدام از بررسی‌کنندگان نوع اصلی پشتیبانی نمی‌شود.

• ماژول‌های sre_compile، sre_constants و sre_parse.

• wave:

  • متدهای getmark()، setmark() و getmarkers() از کلاس‌های Wave_read و Wave_write از نسخه‌ی ۳.۱۳ پایتون منسوخ شده‌اند.

• zipimport:

  • متد zipimport.zipimporter.load_module() از نسخه‌ی ۳.۱۰ پایتون منسوخ شده است. به‌جای آن از exec_module() استفاده کنید. (gh-125746.)

در پایتون 3.16 در انتظار حذف است¶

• سیستم ایمپورت:

  • تنظیم __loader__ روی یک ماژول، در حالی که __spec__.loader تنظیم نمی‌شود، منسوخ شده است. در پایتون 3.16، __loader__ دیگر توسط سیستم ایمپورت یا کتابخانه استاندارد تنظیم یا در نظر گرفته نخواهد شد.

• array:

  • کد قالب 'u' (wchar_t) در مستندات از پایتون 3.3 و در ران‌تایم از پایتون 3.13 منسوخ شده است. به جای آن، از کد قالب 'w' (Py_UCS4) برای نویسه‌های یونیکد استفاده کنید.

• asyncio:

  • asyncio.iscoroutinefunction() منسوخ شده است و در پایتون 3.16 حذف خواهد شد؛ به‌جای آن از inspect.iscoroutinefunction() استفاده کنید. (مشارکت‌شده توسط Jiahao Li و Kumar Aditya در gh-122875.)

  • سامانه سیاست‌گذاری asyncio منسوخ شده است و در پایتون 3.16 حذف خواهد شد. به‌ویژه، کلاس‌ها و توابع زیر منسوخ شده‌اند:

    • asyncio.AbstractEventLoopPolicy

    • asyncio.DefaultEventLoopPolicy

    • asyncio.WindowsSelectorEventLoopPolicy

    • asyncio.WindowsProactorEventLoopPolicy

    • asyncio.get_event_loop_policy()

    • asyncio.set_event_loop_policy()

    کاربران باید برای استفاده از پیاده‌سازی حلقه رویداد مطلوب، از asyncio.run() یا asyncio.Runner به همراه loop_factory استفاده کنند.

    به عنوان مثال، برای استفاده از asyncio.SelectorEventLoop در ویندوز:

    import asyncio
    
    async def main():
        ...
    
    asyncio.run(main(), loop_factory=asyncio.SelectorEventLoop)
    

    (مشارکت Kumar Aditya در gh-127949.)

• builtins:

  • وارون‌سازی بیتی روی نوع‌های بولی، ~True یا ~False، از پایتون 3.12 منسوخ شده است، زیرا نتایجی غیرمنتظره و خلاف شهود تولید می‌کند (-2 و -1). برای نقیض منطقی یک مقدار بولی، به جای آن از not x استفاده کنید. در موارد نادر که به وارون‌سازی بیتی عدد صحیح زیرین نیاز دارید، آن را به‌طور صریح به int تبدیل کنید (~int(x)).

• functools:

  • فراخوانی پیاده‌سازی پایتونِ functools.reduce() با function یا sequence به‌عنوان آرگومان‌های کلیدواژه‌ای، از پایتون 3.14 منسوخ شده است.

• logging:

  • پشتیبانی از هندلرهای گزارش‌گیری سفارشی با آرگومان strm منسوخ شده و برای حذف در پایتون 3.16 برنامه‌ریزی شده است. به‌جای آن، هندلرها را با آرگومان stream تعریف کنید. (مشارکت‌شده توسط Mariusz Felisiak در gh-115032.)

• mimetypes:

  • پسوندهای معتبر برای mimetypes.MimeTypes.add_type() با «.» شروع می‌شوند یا خالی هستند. پسوندهای بدون نقطه منسوخ شده‌اند و در پایتون 3.16 باعث ایجاد ValueError می‌شوند. (مشارکت‌شده توسط Hugo van Kemenade در gh-75223.)

• shutil:

  • استثنای ExecError از پایتون 3.14 منسوخ شده است. از پایتون 3.4 به بعد، هیچ تابعی در shutil از آن استفاده نکرده است و اکنون مستعاری از RuntimeError است.

• symtable:

  • متد Class.get_methods از پایتون 3.14 منسوخ شده است.

• sys:

  • تابع _enablelegacywindowsfsencoding() از پایتون 3.13 منسوخ شده است. به جای آن از متغیر محیطی PYTHONLEGACYWINDOWSFSENCODING استفاده کنید.

• sysconfig:

  • تابع sysconfig.expand_makefile_vars() از نسخه‌ی پایتون 3.14 منسوخ شده است. به جای آن، از آرگومان vars تابع sysconfig.get_paths() استفاده کنید.

• tarfile:

  • ویژگی مستندنشده و استفاده‌نشده‌ی TarFile.tarfile از پایتون 3.13 منسوخ شده است.

در انتظار حذف در پایتون 3.17¶

• datetime:

  • فراخوانی‌های strptime() که از یک رشته‌ی قالب حاوی %e (روز ماه) بدون سال استفاده می‌کنند. این مورد از پایتون ۳.۱۵ منسوخ شده است. (مشارکت توسط Stan Ulbrych در gh-70647.)

• collections.abc:

  • collections.abc.ByteString برای حذف در پایتون 3.17 برنامه‌ریزی شده است.

    برای بررسی اینکه آیا obj پروتکل بافر را پیاده‌سازی می‌کند، در زمان اجرا از isinstance(obj, collections.abc.Buffer) استفاده کنید. برای استفاده در حاشیه‌نویسی نوع، یا از Buffer استفاده کنید یا از یک اجتماع (union) که به‌صراحت نوع‌هایی را که کد شما از آن‌ها پشتیبانی می‌کند مشخص می‌کند (مثلاً، bytes | bytearray | memoryview).

    ByteString در ابتدا قرار بود یک کلاس پایه انتزاعی باشد که به‌عنوان ابرنوع (supertype) هر دو bytes و bytearray عمل کند. اما از آنجا که این کلاس پایه انتزاعی هرگز هیچ متدی نداشت، دانستن اینکه یک شیء نمونه‌ای از ByteString است، در واقع هرگز هیچ چیز مفیدی درباره‌ی آن شیء به شما نمی‌گفت. سایر نوع‌های بافر رایج مانند memoryview نیز هرگز به‌عنوان زیرنوع‌هایی از ByteString شناخته نمی‌شدند (چه در ران‌تایم و چه توسط بررسی‌گرهای نوع ایستا).

    برای جزئیات بیشتر به PEP 688 مراجعه کنید. (مشارکت‌شده توسط شانتانو جین در gh-91896.)

• encodings:

  • ارسال نام‌های کدگذاری غیر اسکی (non-ascii) به encodings.normalize_encoding() منسوخ شده است و برنامه‌ریزی شده تا در نسخه‌ی ۳.۱۷ پایتون حذف شود. (مشارکتی از Stan Ulbrych در gh-136702.)

• profile:

  • ماژول profile منسوخ شده است و در پایتون ۳.۱۷ حذف خواهد شد. به جای آن از profiling.tracing استفاده کنید که یک API سازگار ارائه می‌دهد. برای جزئیات به PEP 799 مراجعه کنید. (مشارکت توسط Pablo Galindo و László Kiss Kollár در gh-138122.)

• webbrowser:

  • کلاس webbrowser.MacOSXOSAScript به نفع کلاس webbrowser.MacOS منسوخ شده است. (gh-137586)

• typing:

  • پیش از پایتون 3.14، اجتماعهای سبک قدیمی (old-style unions) با استفاده از کلاس خصوصی typing._UnionGenericAlias پیاده‌سازی می‌شدند. این کلاس دیگر برای پیاده‌سازی مورد نیاز نیست، اما برای سازگاری با نسخه‌های قبلی حفظ شده است و حذف آن برای پایتون 3.17 برنامه‌ریزی شده است. کاربران باید به جای اتکا به جزئیات پیاده‌سازی خصوصی، از ابزارهای کمکی مستند درون‌نگری مانند typing.get_origin() و typing.get_args() استفاده کنند.

  • typing.ByteString، که از پایتون 3.9 منسوخ شده است، برای حذف در پایتون 3.17 برنامه‌ریزی شده است.

    برای بررسی اینکه آیا obj پروتکل بافر را پیاده‌سازی می‌کند، در زمان اجرا از isinstance(obj, collections.abc.Buffer) استفاده کنید. برای استفاده در حاشیه‌نویسی نوع، یا از Buffer استفاده کنید یا از یک اجتماع (union) که به‌صراحت نوع‌هایی را که کد شما از آن‌ها پشتیبانی می‌کند مشخص می‌کند (مثلاً، bytes | bytearray | memoryview).

    ByteString در ابتدا قرار بود یک کلاس پایه انتزاعی باشد که به‌عنوان ابرنوع (supertype) هر دو bytes و bytearray عمل کند. اما از آنجا که این کلاس پایه انتزاعی هرگز هیچ متدی نداشت، دانستن اینکه یک شیء نمونه‌ای از ByteString است، در واقع هرگز هیچ چیز مفیدی درباره‌ی آن شیء به شما نمی‌گفت. سایر نوع‌های بافر رایج مانند memoryview نیز هرگز به‌عنوان زیرنوع‌هایی از ByteString شناخته نمی‌شدند (چه در ران‌تایم و چه توسط بررسی‌گرهای نوع ایستا).

    برای جزئیات بیشتر به PEP 688 مراجعه کنید. (مشارکت‌شده توسط شانتانو جین در gh-91896.)

• tkinter:

  • متدهای tkinter.Variable یعنی trace_variable()، trace() (یک نام مستعار برای trace_variable())، trace_vdelete() و trace_vinfo() که از پایتون ۳.۱۴ منسوخ شده‌اند، قرار است در پایتون ۳.۱۷ حذف شوند. به‌جای آن‌ها از trace_add()، trace_remove() و trace_info() استفاده کنید. (ارائه‌شده توسط Serhiy Storchaka در gh-120220.)

در انتظار حذف در پایتون 3.18¶

• هنگامی که انتظار یک توصیف‌گر پرونده می‌رود، دیگر مقدار بولی پذیرفته نمی‌شود. (مشارکتی از Serhiy Storchaka در gh-82626.)

• decimal:

  • مشخصه‌ی قالب‌بندی غیراستاندارد و مستند‌نشده‌ی 'N' در Decimal، که تنها در پیاده‌سازی C ماژول decimal پشتیبانی می‌شود، از Python 3.13 منسوخ شده است. (مشارکت‌شده توسط Serhiy Storchaka در gh-89902.)

• موارد منسوخ‌شده تعریف‌شده توسط PEP 829:

  • سطرهای import در پرونده‌های name.pth بدون سر و صدا نادیده گرفته می‌شوند.

  (مشارکتی از Barry Warsaw در gh-148641.)

در انتظار حذف در پایتون 3.19¶

• ctypes:

  • تغییر ضمنی به چیدمان ساختار سازگار با MSVC از طریق تنظیم _pack_ بدون تنظیم _layout_ روی پلتفرم‌های غیر ویندوزی.

• hashlib:

  • در سازندهای تابع هش مانند new() یا سازندهای مستقیم دارای نام هش مانند md5() و sha256()، در پیاده‌سازی‌های مختلف hashlib امکان ارسال یک آرگومان کلیدواژه‌ای با نام data= یا string= نیز به پارامتر داده‌ی اولیه اختیاری آن‌ها وجود داشت.

    پشتیبانی از نام آرگومان کلیدواژه‌ای string اکنون منسوخ شده و قرار است در نسخه‌ی ۳.۱۹ پایتون حذف شود.

    پیش از پایتون ۳.۱۳، پارامتر کلیدواژه‌ای string بسته به پیاده‌سازی بک‌اند عملکردهای هش به شکل درستی پشتیبانی نمی‌شد. برای حداکثر سازگاری با نسخه‌های قبلی، ترجیح دهید داده‌ی اولیه را به عنوان یک آرگومان جایگاهی ارسال کنید.

• http.cookies:

  • متد http.cookies.Morsel.js_output() منسوخ شده است و در پایتون ۳.۱۹ حذف خواهد شد.

  • متد http.cookies.BaseCookie.js_output() منسوخ شده است و در پایتون ۳.۱۹ حذف خواهد شد.

• imaplib:

  • تغییر دادن IMAP4.file اکنون منسوخ شده است و برنامه‌ریزی شده تا در پایتون ۳.۱۹ حذف شود. این ویژگی اکنون استفاده نمی‌شود و تغییر مقدار آن پرونده‌ی فعلی را به طور خودکار نمی‌بندد.

    پیش از پایتون ۳.۱۴، از این ویژگی برای پیاده‌سازی متدهای متناظر read() و readline() برای IMAP4 استفاده می‌شد، اما از آن زمان به بعد دیگر این‌طور نیست.

حذف در نسخه‌ی ۳.۲۰ پایتون در راه است¶

• فراخوانی متد __new__() از struct.Struct بدون آرگومان format منسوخ شده است و در پایتون ۳.۲۰ حذف خواهد شد. فراخوانی متد __init__() روی شیء‌های مقداردهی اولیه‌شده‌ی Struct منسوخ شده است و در پایتون ۳.۲۰ حذف خواهد شد.

  (مشارکت‌کرده توسط Sergey B Kirpichev و Serhiy Storchaka در gh-143715.)

• ویژگی‌های __version__، version و VERSION در این ماژول‌های کتابخانه‌ی استاندارد منسوخ شده‌اند و در پایتون ۳.۲۰ حذف خواهند شد. به‌جای آن‌ها از sys.version_info استفاده کنید.

  • argparse

  • csv

  • ctypes

  • ctypes.macholib

  • decimal (به‌جای آن از decimal.SPEC_VERSION استفاده کنید)

  • http.server

  • imaplib

  • ipaddress

  • json

  • logging (__date__ نیز منسوخ شده است)

  • optparse

  • pickle

  • platform

  • re

  • socketserver

  • tabnanny

  • tarfile

  • tkinter.font

  • tkinter.ttk

  • wsgiref.simple_server

  • xml.etree.ElementTree

  • xml.sax.expatreader

  • xml.sax.handler

  • zlib

  (مشارکت‌کرده توسط Hugo van Kemenade و Stan Ulbrych در gh-76007.)

• موارد منسوخ‌شده تعریف‌شده توسط PEP 829:

  • برای سطرهای import که در پرونده‌های name.pth پیدا شوند، هشدارها تولید می‌شوند.

  • پرونده‌های name.pth دیگر به طور پیش‌فرض با کدگذاری locale رمزگشایی نمی‌شوند. آن‌ها باید با utf-8-sig کدگذاری شوند.

  (مشارکتی از Barry Warsaw در gh-148641.)

• ast:

  • ایجاد نمونه‌ها از گره‌های درخت نحوی انتزاعی (مانند ast.AST یا ast.expr) منسوخ شده است و در پایتون ۳.۲۰ یک خطا ایجاد خواهد کرد.

• typing:

  • فراخوانی بررسی‌های isinstance() و issubclass() روی کلاس‌های پروتکلی که به طور صریح با runtime_checkable() دکوریت نشده‌اند اما از یک کلاس پروتکل با قابلیت بررسی در زمان اجرا ارث‌بری می‌کنند، منسوخ شده است. این کار در پایتون ۳.۲۰ یک خطای TypeError ایجاد خواهد کرد.

    (مشارکت‌کرده توسط Bartosz Sławecki در gh-132604.)

در انتظار حذف در نسخه‌های آینده¶

API‌های زیر در آینده حذف خواهند شد، اگرچه در حال حاضر هیچ تاریخی برای حذف آن‌ها برنامه‌ریزی نشده است.

• argparse:

  • تودرتو کردن گروه‌های آرگومان و تودرتو کردن گروه‌های انحصاری متقابل منسوخ شده است.

  • ارسال آرگومان کلیدواژه‌ای مستند‌نشده‌ی prefix_chars به add_argument_group() اکنون منسوخ شده است.

  • مبدل نوع argparse.FileType منسوخ شده است.

• builtins:

  • تولیدگرها: امضای throw(type, exc, tb) و athrow(type, exc, tb) منسوخ شده است: به جای آن از امضای تک‌آرگومانی throw(exc) و athrow(exc) استفاده کنید.

  • در حال حاضر پایتون مقادیر لفظی عددی را که بلافاصله کلیدواژه‌ای پس از آن‌ها می‌آید، می‌پذیرد؛ برای مثال 0in x، 1or x، 0if 1else 2. این امر امکان نوشتن عبارت‌های گیج‌کننده و مبهمی مانند [0x1for x in y] را فراهم می‌کند (که می‌توان آن را به‌صورت [0x1 for x in y] یا [0x1f or x in y] تفسیر کرد). اگر بلافاصله پس از مقدار لفظی عددی، یکی از کلیدواژه‌های and، else، for، if، in، is و or بیاید، یک هشدار نحوی نشان می‌دهد. در نسخه‌ای در آینده این مورد به یک خطای نحوی تغییر خواهد کرد. (gh-87999)

  • پشتیبانی از متدهای __index__() و __int__() که نوعی غیر از int برمی‌گردانند: این متدها ملزم خواهند شد که نمونه‌ای از یک زیرکلاس اکید از int را برگردانند.

  • پشتیبانی از متد __float__() که زیرکلاس اکیدی از float را بازمی‌گرداند: این متدها ملزم خواهند شد که نمونه‌ای از float را بازگردانند.

  • پشتیبانی از متد __complex__() که زیرکلاس محضی از complex را برمی‌گرداند: این متدها ملزم خواهند بود که نمونه‌ای از complex را برگردانند.

  • ارسال یک عدد مختلط به‌عنوان آرگومان real یا imag در سازنده‌ی complex() اکنون منسوخ شده است؛ این عدد باید تنها به‌صورت یک آرگومان جایگاهی واحد ارسال شود. (مشارکت‌شده توسط Serhiy Storchaka در gh-109218.)

• calendar: ثابت‌های calendar.January و calendar.February منسوخ شده‌اند و با calendar.JANUARY و calendar.FEBRUARY جایگزین شده‌اند. (مشارکت‌شده توسط Prince Roshan در gh-103636.)

• codecs: به‌جای codecs.open() از open() استفاده کنید. (gh-133038)

• codeobject.co_lnotab: به‌جای آن از متد codeobject.co_lines() استفاده کنید.

• datetime:

  • utcnow(): از datetime.datetime.now(tz=datetime.UTC) استفاده کنید.

  • utcfromtimestamp(): از datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC) استفاده کنید.

• gettext: مقدار جمع باید یک عدد صحیح باشد.

• importlib:

  • پارامتر debug_override در cache_from_source() منسوخ شده است: به جای آن از پارامتر optimization استفاده کنید.

• importlib.metadata:

  • رابط تاپل EntryPoints.

  • None ضمنی در مقادیر بازگشتی.

• logging: متد warn() از پایتون 3.3 منسوخ شده است، به‌جای آن از warning() استفاده کنید.

• mailbox: استفاده از ورودی StringIO و حالت متنی منسوخ شده است؛ به جای آن از BytesIO و حالت دودویی استفاده کنید.

• os: فراخوانی os.register_at_fork() در یک فرایند چندنخی.

• os.path: تابع os.path.commonprefix() منسوخ شده است، برای پیشوندهای مسیر از os.path.commonpath() استفاده کنید. تابع os.path.commonprefix() به دلیل داشتن نام و ماژول گمراه‌کننده در حال منسوخ شدن است. این تابع با وجود اینکه در ماژولی درباره‌ی دستکاری مسیر گنجانده شده است، برای استفاده در پیشوندهای مسیر ایمن نیست، به این معنا که با استفاده از این تابع می‌توان به‌طور تصادفی آسیب‌پذیری‌های پیمایش مسیر را به برنامه‌های پایتون تزریق کرد.

• pydoc.ErrorDuringImport: مقدار تاپل برای پارامتر exc_info منسوخ شده است؛ از یک نمونه استثنا استفاده کنید.

• re: اکنون قواعد سخت‌گیرانه‌تری برای ارجاع‌های عددی به گروه‌ها و نام گروه‌ها در عبارات باقاعده اعمال می‌شود. اکنون فقط دنباله‌ای از ارقام اسکی به‌عنوان ارجاع عددی پذیرفته می‌شود. نام گروه در الگوهای بایتی و رشته‌های جایگزین اکنون فقط می‌تواند شامل حروف و ارقام اسکی و زیرخط باشد. (مشارکت‌شده توسط Serhiy Storchaka در gh-91760.)

• shutil: پارامتر onerror در rmtree() در پایتون 3.12 منسوخ شده است؛ به جای آن از پارامتر onexc استفاده کنید.

• گزینه‌ها و پروتکل‌های ssl:

  • ssl.SSLContext بدون آرگومان پروتکل منسوخ شده است.

  • ssl.SSLContext: set_npn_protocols() و selected_npn_protocol() منسوخ شده‌اند: به‌جای آن‌ها از ALPN استفاده کنید.

  • گزینه‌های ssl.OP_NO_SSL*

  • گزینه‌های ssl.OP_NO_TLS*

  • ssl.PROTOCOL_SSLv3

  • ssl.PROTOCOL_TLS

  • ssl.PROTOCOL_TLSv1

  • ssl.PROTOCOL_TLSv1_1

  • ssl.PROTOCOL_TLSv1_2

  • ssl.TLSVersion.SSLv3

  • ssl.TLSVersion.TLSv1

  • ssl.TLSVersion.TLSv1_1

• متدهای threading:

  • threading.Condition.notifyAll(): از notify_all() استفاده کنید.

  • threading.Event.isSet(): از is_set() استفاده کنید.

  • threading.Thread.isDaemon()، threading.Thread.setDaemon(): از ویژگی threading.Thread.daemon استفاده کنید.

  • threading.Thread.getName()، threading.Thread.setName(): از ویژگی threading.Thread.name استفاده کنید.

  • threading.currentThread(): از threading.current_thread() استفاده کنید.

  • threading.activeCount(): از threading.active_count() استفاده کنید.

• typing.Text (gh-92332).

• کلاس داخلی typing._UnionGenericAlias دیگر برای پیاده‌سازی typing.Union استفاده نمی‌شود. برای حفظ سازگاری با کاربرانی که از این کلاس خصوصی استفاده می‌کنند، یک شیم سازگاری (compatibility shim) تا دست‌کم پایتون 3.17 ارائه خواهد شد. (مشارکت Jelle Zijlstra در gh-105499.)

• unittest.IsolatedAsyncioTestCase: برگرداندن مقداری که None نیست از یک مورد آزمون، منسوخ شده است.

• توابع منسوخ urllib.parse: به‌جای آن‌ها urlparse()

  • splitattr()

  • splithost()

  • splitnport()

  • splitpasswd()

  • splitport()

  • splitquery()

  • splittag()

  • splittype()

  • splituser()

  • splitvalue()

  • to_bytes()

• wsgiref: SimpleHandler.stdout.write() نباید نوشتن ناقص (partial write) انجام دهد.

• xml.etree.ElementTree: آزمودن ارزش صدق یک Element منسوخ شده است. در نسخه‌ای در آینده، این آزمون همیشه True را برمی‌گرداند. به‌جای آن، آزمون‌های صریح len(elem) یا elem is not None را ترجیح دهید.

• sys._clear_type_cache() منسوخ شده است: به جای آن از sys._clear_internal_caches() استفاده کنید.

ویژگی‌های جدید¶

• افزودن PyMonitoring C API برای تولید رویدادهای پایشِ PEP 669:

  • PyMonitoringState

  • PyMonitoring_FirePyStartEvent()

  • PyMonitoring_FirePyResumeEvent()

  • PyMonitoring_FirePyReturnEvent()

  • PyMonitoring_FirePyYieldEvent()

  • PyMonitoring_FireCallEvent()

  • PyMonitoring_FireLineEvent()

  • PyMonitoring_FireJumpEvent()

  • PyMonitoring_FireBranchEvent

  • PyMonitoring_FireCReturnEvent()

  • PyMonitoring_FirePyThrowEvent()

  • PyMonitoring_FireRaiseEvent()

  • PyMonitoring_FireCRaiseEvent()

  • PyMonitoring_FireReraiseEvent()

  • PyMonitoring_FireExceptionHandledEvent()

  • PyMonitoring_FirePyUnwindEvent()

  • PyMonitoring_FireStopIterationEvent()

  • PyMonitoring_EnterScope()

  • PyMonitoring_ExitScope()

  (مشارکت‌شده توسط Irit Katriel در gh-111997.)

• افزودن PyMutex، یک قفل متقابل سبک که تنها یک بایت فضا اشغال می‌کند، و توابع جدید PyMutex_Lock() و PyMutex_Unlock(). تابع PyMutex_Lock() در صورتی که عملیات نیاز به مسدود شدن داشته باشد، قفل مفسر سراسری را آزاد می‌کند (اگر در حال حاضر در اختیار داشته باشد). (مشارکت‌شده توسط Sam Gross در gh-108724.)

• افزودن PyTime C API برای فراهم کردن دسترسی به ساعت‌های سیستم:

  • PyTime_t.

  • PyTime_MIN و PyTime_MAX.

  • PyTime_AsSecondsDouble().

  • PyTime_Monotonic().

  • PyTime_MonotonicRaw().

  • PyTime_PerfCounter().

  • PyTime_PerfCounterRaw().

  • PyTime_Time().

  • PyTime_TimeRaw().

  (مشارکت‌شده توسط Victor Stinner و Petr Viktorin در gh-110850.)

• تابع PyDict_ContainsString() با همان رفتار تابع PyDict_Contains() اضافه شد، اما key به‌عنوان یک رشته بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه PyObject*. (مشارکت‌شده توسط Victor Stinner در gh-108314.)

• توابع PyDict_GetItemRef() و PyDict_GetItemStringRef() اضافه شدند که رفتاری مشابه PyDict_GetItemWithError() دارند، اما به‌جای ارجاع امانتی یک ارجاع قوی برمی‌گردانند. علاوه بر این، این توابع در صورت خطا -1 برمی‌گردانند و دیگر نیازی به بررسی PyErr_Occurred() نیست. (مشارکت‌شده توسط Victor Stinner در gh-106004.)

• تابع PyDict_SetDefaultRef() افزوده شد که رفتاری مشابه PyDict_SetDefault() دارد، اما به‌جای ارجاع امانتی، یک ارجاع قوی برمی‌گرداند. این تابع در صورت خطا -1، هنگام درج 0 و در صورتی که کلید از قبل در دیکشنری وجود داشته باشد 1 برمی‌گرداند. (مشارکت‌شده توسط Sam Gross در gh-112066.)

• توابع PyDict_Pop() و PyDict_PopString() برای حذف یک کلید از دیکشنری و به‌طور اختیاری بازگرداندن مقدار حذف‌شده اضافه شدند. این توابع مشابه dict.pop() هستند، هرچند مقدار پیش‌فرضی وجود ندارد و KeyError برای کلیدهای مفقود پرتاب نمی‌شود. (مشارکت‌شده توسط Stefan Behnel و Victor Stinner در gh-111262.)

• توابع PyMapping_GetOptionalItem() و PyMapping_GetOptionalItemString() به ترتیب به عنوان جایگزین‌هایی برای PyObject_GetItem() و PyMapping_GetItemString() اضافه شدند. توابع جدید در صورتی که کلید درخواست‌شده در نگاشت موجود نباشد، استثنای KeyError را ایجاد نمی‌کنند. در صورتی که نبود یک کلید نباید به عنوان شکست در نظر گرفته شود، این گونه‌ها راحت‌تر و سریع‌تر هستند. (مشارکت‌شده توسط Serhiy Storchaka در gh-106307.)

• توابع PyObject_GetOptionalAttr() و PyObject_GetOptionalAttrString() به ترتیب به عنوان جایگزین‌هایی برای PyObject_GetAttr() و PyObject_GetAttrString() اضافه شدند. این توابع جدید اگر ویژگی درخواست‌شده روی شیء یافت نشود، استثنای AttributeError را ایجاد نمی‌کنند. اگر نبود ویژگی نباید به عنوان شکست در نظر گرفته شود، این گونه‌ها ساده‌تر و سریع‌تر هستند. (مشارکت‌شده توسط سرهی استورچاکا در gh-106521.)

• تابع PyErr_FormatUnraisable() به عنوان توسعه‌ای برای PyErr_WriteUnraisable() افزوده شد که امکان سفارشی‌سازی پیام هشدار را فراهم می‌کند. (مشارکت‌شده توسط Serhiy Storchaka در gh-108082.)

• توابع جدیدی افزوده شدند که به‌جای borrowed reference، یک strong reference را برای محلی‌ها، سراسری‌ها و توکارهای فریم برمی‌گردانند، به‌عنوان بخشی از PEP 667:

  • PyEval_GetFrameBuiltins() جایگزین PyEval_GetBuiltins() می‌شود

  • PyEval_GetFrameGlobals() جایگزین PyEval_GetGlobals() می‌شود

  • PyEval_GetFrameLocals() جایگزین PyEval_GetLocals() می‌شود

  (مشارکت‌شده توسط Mark Shannon و Tian Gao در gh-74929.)

• توابع Py_GetConstant() و Py_GetConstantBorrowed() برای دریافت ارجاع‌های قوی یا امانی به ثابت‌ها اضافه شدند. برای مثال، Py_GetConstant(Py_CONSTANT_ZERO) یک ارجاع قوی به ثابت صفر برمی‌گرداند. (مشارکت‌شده توسط Victor Stinner در gh-115754.)

• تابع PyImport_AddModuleRef() که به‌جای ارجاع امانتی، یک ارجاع قوی برمی‌گرداند، به‌عنوان جایگزینی برای PyImport_AddModule() افزوده شد. (مشارکت‌شده توسط ویکتور استینر در gh-105922.)

• افزودن تابع Py_IsFinalizing() برای بررسی اینکه آیا مفسر اصلی پایتون در حال خاموش شدن است یا خیر. (مشارکت‌شده توسط Victor Stinner در gh-108014.)

• تابع PyList_GetItemRef() که ارجاع قوی را به‌جای ارجاع امانتی برمی‌گرداند، به‌عنوان جایگزینی برای PyList_GetItem() افزوده شد. (مشارکت Sam Gross در gh-114329.)

• توابع PyList_Extend() و PyList_Clear() افزوده شدند که مشابه متدهای list.extend() و list.clear() پایتون هستند. (مشارکت‌شده توسط Victor Stinner در gh-111138.)

• تابع PyLong_AsInt() اضافه شد. این تابع مشابه PyLong_AsLong() رفتار می‌کند، اما نتیجه را به‌جای یک long از C، در یک int از C ذخیره می‌کند. (مشارکت‌شده توسط Victor Stinner در gh-108014.)

• توابع PyLong_AsNativeBytes()، PyLong_FromNativeBytes() و PyLong_FromUnsignedNativeBytes() برای ساده‌سازی تبدیل بین نوع‌های عدد صحیح بومی و اشیاء int پایتون اضافه شدند. (مشارکت‌شده توسط Steve Dower در gh-111140.)

• افزودن تابع PyModule_Add() که مشابه PyModule_AddObjectRef() و PyModule_AddObject() است، اما همیشه ارجاع به مقدار را می‌دزدد. (مشارکت‌شده توسط Serhiy Storchaka در gh-86493.)

• تابع PyObject_GenericHash() افزوده شد که تابع هش پیش‌فرض یک شیء پایتون را پیاده‌سازی می‌کند. (مشارکت‌شده توسط Serhiy Storchaka در gh-113024.)

• افزودن تابع Py_HashPointer() برای هش کردن یک اشاره‌گر خام. (مشارکت‌شده توسط Victor Stinner در gh-111545.)

• توابع PyObject_VisitManagedDict() و PyObject_ClearManagedDict() افزوده شدند که باید توسط توابع پیمایش و پاک‌سازی نوعی که از پرچم Py_TPFLAGS_MANAGED_DICT استفاده می‌کند فراخوانی شوند. برای استفاده از این توابع در پایتون 3.11 و 3.12 می‌توان از pythoncapi-compat project بهره برد. (مشارکت‌شده توسط Victor Stinner در gh-107073.)

• توابع PyRefTracer_SetTracer() و PyRefTracer_GetTracer() اضافه شدند که امکان پیگیری ایجاد و نابودی شیء را به همان شیوه‌ای که ماژول tracemalloc انجام می‌دهد، فراهم می‌کنند. (مشارکت پابلو گالیندو در gh-93502.)

• تابع PySys_AuditTuple() به‌عنوان جایگزینی برای PySys_Audit() افزوده شد که آرگومان‌های رویداد را به‌صورت یک شیء tuple پایتون می‌گیرد. (مشارکت‌شده توسط Victor Stinner در gh-85283.)

• تابع PyThreadState_GetUnchecked() به‌عنوان جایگزینی برای PyThreadState_Get() اضافه شد که در صورت NULL بودن، فرایند را با یک خطای مهلک از کار نمی‌اندازد. فراخواننده مسئول بررسی NULL بودن نتیجه است. (مشارکت‌شده توسط ویکتور استینر در gh-108867.)

• تابع PyType_GetFullyQualifiedName() برای به‌دست‌آوردن نام کامل نوع اضافه شد. اگر type.__module__ یک رشته باشد و برابر هیچ‌یک از 'builtins' یا '__main__' نباشد، نام ماژول به ابتدای آن افزوده می‌شود. (مشارکت‌شده توسط Victor Stinner در gh-111696.)

• تابع PyType_GetModuleName() برای دریافت نام ماژول نوع اضافه شد. این کار معادل دریافت ویژگی type.__module__ است. (مشارکت اریک اسنو و ویکتور استینر در gh-111696.)

• توابع PyUnicode_EqualToUTF8AndSize() و PyUnicode_EqualToUTF8() برای مقایسه‌ی یک شیء یونیکد با یک رشته‌ی کدگذاری‌شده به UTF-8 از نوع const char* و 1 اگر برابر باشند یا 0 در غیر این صورت اضافه شدند. این توابع استثنا ایجاد نمی‌کنند. (مشارکت‌شده توسط Serhiy Storchaka در gh-110289.)

• افزودن تابع PyWeakref_GetRef() به‌عنوان جایگزینی برای PyWeakref_GetObject() که یک ارجاع قوی یا NULL را برمی‌گرداند (اگر ارجاع‌شونده دیگر زنده نباشد). (مشارکت‌کرده توسط Victor Stinner در gh-105927.)

• افزودن نسخه‌های اصلاح‌شده‌ی توابعی که خطاها را بی‌سروصدا نادیده می‌گیرند:

  • PyObject_HasAttrWithError() جایگزین PyObject_HasAttr() می‌شود.

  • PyObject_HasAttrStringWithError() جایگزین PyObject_HasAttrString() می‌شود.

  • PyMapping_HasKeyWithError() جایگزین PyMapping_HasKey() می‌شود.

  • PyMapping_HasKeyStringWithError() جایگزین PyMapping_HasKeyString() می‌شود.

  توابع جدید در صورت خطا -1 و مقدار استاندارد 1 برای درست و 0 برای نادرست را برمی‌گردانند.

  (مشارکت Serhiy Storchaka در gh-108511.)

APIهای C تغییر‌یافته¶

• پارامتر keywords در PyArg_ParseTupleAndKeywords() و PyArg_VaParseTupleAndKeywords() اکنون در C از نوع char *const* و در C++ از نوع const char *const* است، به‌جای char**. در C++، این امر باعث می‌شود این توابع با آرگومان‌هایی از نوع const char *const*، const char** یا char *const* بدون تبدیل نوع صریح سازگار باشند. در C، این توابع فقط از آرگومان‌هایی از نوع char *const* پشتیبانی می‌کنند. این را می‌توان با ماکروی PY_CXX_CONST بازتعریف کرد. (مشارکت Serhiy Storchaka در gh-65210.)

• PyArg_ParseTupleAndKeywords() اکنون از نام‌های غیر اسکی برای پارامترهای کلیدواژه‌ای پشتیبانی می‌کند. (مشارکت‌شده توسط Serhiy Storchaka در gh-110815.)

• تابع PyCode_GetFirstFree() اکنون API ناپایدار است و اکنون PyUnstable_Code_GetFirstFree() نامیده می‌شود. (مشارکت‌شده توسط Bogdan Romanyuk در gh-115781.)

• توابع PyDict_GetItem()، PyDict_GetItemString()، PyMapping_HasKey()، PyMapping_HasKeyString()، PyObject_HasAttr()، PyObject_HasAttrString() و PySys_GetObject()، که هر یک تمام خطاهای رخ‌داده هنگام فراخوانی‌اش را پاک می‌کند، اکنون این خطاها را با استفاده از sys.unraisablehook() گزارش می‌کنند. مطابق توصیه‌های مستندات، می‌توانید آن‌ها را با توابع دیگری جایگزین کنید. (با مشارکت Serhiy Storchaka در gh-106672.)

• افزودن پشتیبانی از قالب‌های %T، %#T، %N و %#N به PyUnicode_FromFormat():

  • %T: به دست آوردن نام کامل نوع یک شیء

  • %#T: مانند بالا، اما از دو نقطه به‌عنوان جداکننده استفاده می‌شود

  • %N: به دست آوردن نام کامل یک نوع

  • %#N: مانند بالا، اما از دونقطه به‌عنوان جداکننده استفاده می‌شود

  برای اطلاعات بیشتر به PEP 737 مراجعه کنید. (مشارکت‌شده توسط Victor Stinner در gh-111696.)

• دیگر لازم نیست هنگام استفاده از قالب‌های # در کدهای قالب، پیش از گنجاندن Python.h ماکروی PY_SSIZE_T_CLEAN را تعریف کنید. APIهایی که کدهای قالب را می‌پذیرند، همیشه برای قالب‌های # از Py_ssize_t استفاده می‌کنند. (با مشارکت Inada Naoki در gh-104922.)

• اگر پایتون در حالت اشکال‌زدایی یا با ادعاها ساخته شده باشد، PyTuple_SET_ITEM() و PyList_SET_ITEM() اکنون آرگومان اندیس را با یک ادعا بررسی می‌کنند. (مشارکت‌شده توسط Victor Stinner در gh-106168.)

تغییرات C API محدود¶

• توابع زیر اکنون در API محدود C گنجانده شده‌اند:

  • PyMem_RawMalloc()

  • PyMem_RawCalloc()

  • PyMem_RawRealloc()

  • PyMem_RawFree()

  • PySys_Audit()

  • PySys_AuditTuple()

  • PyType_GetModuleByDef()

  (مشارکت‌شده توسط ویکتور استینر در gh-85283 و gh-116936.)

• پایتونی که با --with-trace-refs (ردگیری ارجاع‌ها) ساخته‌شده است، اکنون از API محدود پشتیبانی می‌کند. (مشارکت‌شده توسط Victor Stinner در gh-108634.)

API‌های C حذف‌شده¶

• چندین تابع، ماکرو، متغیر و غیره با نام‌هایی که پیشوند _Py یا _PY دارند (که خصوصی محسوب می‌شوند) حذف شدند. اگر پروژه‌ی شما تحت تأثیر یکی از این حذف‌ها قرار می‌گیرد و معتقدید که API حذف‌شده باید در دسترس باقی بماند، لطفاً برای درخواست یک C API عمومی، یک مسئله جدید باز کنید و cc: @vstinner را به مسئله اضافه کنید تا Victor Stinner مطلع شود. (مشارکت‌شده توسط Victor Stinner در gh-106320.)

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

  • PyObject_CheckReadBuffer(): برای بررسی اینکه آیا شیء از پروتکل بافر پشتیبانی می‌کند، از PyObject_CheckBuffer() استفاده کنید. توجه داشته باشید که PyObject_CheckBuffer() تضمین نمی‌کند که PyObject_GetBuffer() با موفقیت انجام شود. برای بررسی اینکه آیا شیء واقعاً قابل خواندن است، به مثال بعدی از PyObject_GetBuffer() مراجعه کنید.

  • PyObject_AsCharBuffer()، PyObject_AsReadBuffer(): به‌جای آن‌ها از PyObject_GetBuffer() و PyBuffer_Release() استفاده کنید:

    Py_buffer view;
    if (PyObject_GetBuffer(obj, &view, PyBUF_SIMPLE) < 0) {
        return NULL;
    }
    // برای خواندن از بافر، از `view.buf` و `view.len` استفاده کنید.
    // ممکن است لازم باشد buf را به‌صورت `(const char*)view.buf` قالب‌ریزی کنید.
    PyBuffer_Release(&view);
    

  • PyObject_AsWriteBuffer(): به‌جای آن از PyObject_GetBuffer() و PyBuffer_Release() استفاده کنید:

    Py_buffer view;
    if (PyObject_GetBuffer(obj, &view, PyBUF_WRITABLE) < 0) {
        return NULL;
    }
    // برای نوشتن در بافر، از `view.buf` و `view.len` استفاده کنید.
    PyBuffer_Release(&view);
    

  (مشارکت‌شده توسط Inada Naoki در gh-85275.)

• حذف توابع مختلفی که در پایتون 3.9 منسوخ شده‌اند:

  • PyEval_CallObject()، PyEval_CallObjectWithKeywords(): به جای آن‌ها از PyObject_CallNoArgs() یا PyObject_Call() استفاده کنید.

    هشدار

    در PyObject_Call()، آرگومان‌های جایگاهی باید یک tuple باشند و نباید NULL باشند، و آرگومان‌های کلیدواژه‌ای باید یک dict یا NULL باشند؛ در حالی که توابع حذف‌شده نوع آرگومان‌ها را بررسی می‌کردند و آرگومان‌های جایگاهی و کلیدواژه‌ای NULL را می‌پذیرفتند. برای جایگزینی PyEval_CallObjectWithKeywords(func, NULL, kwargs) با PyObject_Call()، یک تاپل خالی را به‌عنوان آرگومان‌های جایگاهی با استفاده از PyTuple_New(0) ارسال کنید.

  • PyEval_CallFunction(): به‌جای آن از PyObject_CallFunction() استفاده کنید.

  • PyEval_CallMethod(): به جای آن از PyObject_CallMethod() استفاده کنید.

  • PyCFunction_Call(): به جای آن از PyObject_Call() استفاده کنید.

  (مشارکت‌شده توسط Victor Stinner در gh-105107.)

• توابع قدیمی زیر برای پیکربندی مقداردهی اولیه پایتون، که در پایتون 3.11 منسوخ شده بودند، حذف شدند:

  • PySys_AddWarnOptionUnicode(): به‌جای آن از PyConfig.warnoptions استفاده کنید.

  • PySys_AddWarnOption(): به جای آن از PyConfig.warnoptions استفاده کنید.

  • PySys_AddXOption(): به‌جای آن از PyConfig.xoptions استفاده کنید.

  • PySys_HasWarnOptions(): به‌جای آن از PyConfig.xoptions استفاده کنید.

  • PySys_SetPath(): در عوض، PyConfig.module_search_paths را تنظیم کنید.

  • Py_SetPath(): در عوض، PyConfig.module_search_paths را تنظیم کنید.

  • Py_SetStandardStreamEncoding(): به‌جای آن، PyConfig.stdio_encoding را تنظیم کنید و احتمالاً PyConfig.legacy_windows_stdio را نیز تنظیم کنید (در ویندوز).

  • _Py_SetProgramFullPath(): به جای آن، PyConfig.executable را تنظیم کنید.

  به‌جای آن از API جدید PyConfig در پیکربندی مقداردهی اولیه پایتون استفاده کنید (PEP 587)، که در پایتون 3.8 اضافه شد. (مشارکت Victor Stinner در gh-105145.)

• توابع PyEval_AcquireLock() و PyEval_ReleaseLock() که در پایتون 3.2 منسوخ شده بودند، حذف شدند. این توابع وضعیت نخ جاری را به‌روزرسانی نمی‌کردند. می‌توان آن‌ها را با موارد زیر جایگزین کرد:

  • PyEval_SaveThread() و PyEval_RestoreThread()؛

  • سطح پایین PyEval_AcquireThread() و PyEval_RestoreThread()؛

  • یا PyGILState_Ensure() و PyGILState_Release().

  (مشارکت‌شده توسط ویکتور استینر در gh-105182.)

• تابع PyEval_ThreadsInitialized() که در پایتون 3.9 منسوخ شده بود، حذف شد. از پایتون 3.7 به بعد، Py_Initialize() همیشه قفل مفسر سراسری را ایجاد می‌کند: فراخوانی PyEval_InitThreads() هیچ کاری انجام نمی‌دهد و PyEval_ThreadsInitialized() همیشه مقدار غیرصفر برمی‌گرداند. (با مشارکت Victor Stinner در gh-105182.)

• نام مستعار _PyInterpreterState_Get() برای PyInterpreterState_Get() که برای حفظ سازگاری با نسخه‌های قبلی پایتون 3.8 نگه داشته شده بود، حذف شد. می‌توان از pythoncapi-compat project برای دریافت PyInterpreterState_Get() در پایتون 3.8 و نسخه‌های قدیمی‌تر استفاده کرد. (مشارکت‌شده توسط Victor Stinner در gh-106320.)

• تابع خصوصی _PyObject_FastCall() حذف شد: از PyObject_Vectorcall() استفاده کنید که از پایتون 3.8 به بعد در دسترس است (PEP 590). (مشارکت‌شده توسط Victor Stinner در gh-106023.)

• پرونده‌ی سرآیند cpython/pytime.h که تنها شامل توابع خصوصی بود، حذف شد. (مشارکت‌شده توسط Victor Stinner در gh-106316.)

• ثابت مستندنشده‌ی PY_TIMEOUT_MAX از C API محدود حذف شد. (با مشارکت Victor Stinner در gh-110014.)

• ماکروهای قدیمی سطل زباله (trashcan) Py_TRASHCAN_SAFE_BEGIN و Py_TRASHCAN_SAFE_END حذف شدند. هر دو با ماکروهای جدید Py_TRASHCAN_BEGIN و Py_TRASHCAN_END جایگزین شدند. (با مشارکت ایریت کاتریل در gh-105111.)

APIهای منسوخ C¶

• منسوخ کردن توابع قدیمی مقداردهی اولیه پایتون:

  • PySys_ResetWarnOptions(): به‌جای آن sys.warnoptions و warnings.filters را پاکسازی کنید.

  • Py_GetExecPrefix(): به‌جای آن sys.exec_prefix را دریافت کنید.

  • Py_GetPath(): به‌جای آن sys.path را دریافت کنید.

  • Py_GetPrefix(): به‌جای آن sys.prefix را دریافت کنید.

  • Py_GetProgramFullPath(): به‌جای آن sys.executable را دریافت کنید.

  • Py_GetProgramName(): به‌جای آن sys.executable را دریافت کنید.

  • Py_GetPythonHome(): به‌جای آن از PyConfig.home یا متغیر محیطی PYTHONHOME استفاده کنید.

  (مشارکت‌شده توسط ویکتور استینر در gh-105145.)

• منسوخ‌سازی نرم (soft deprecation) توابع PyEval_GetBuiltins()، PyEval_GetGlobals() و PyEval_GetLocals() که یک ارجاع امانتی برمی‌گردانند. (منسوخ‌سازی نرم به‌عنوان بخشی از PEP 667.)

• منسوخ کردن تابع PyImport_ImportModuleNoBlock() که از پایتون ۳.۳ تاکنون صرفاً نام مستعاری برای PyImport_ImportModule() است. (مشارکت‌کرده توسط Victor Stinner در gh-105396.)

• منسوخ‌سازی نرم تابع PyModule_AddObject() انجام شد. این تابع باید با PyModule_Add() یا PyModule_AddObjectRef() جایگزین شود. (مشارکت‌شده توسط Serhiy Storchaka در gh-86493.)

• نوع‌های قدیمی Py_UNICODE و PY_UNICODE_TYPE و تعریف Py_UNICODE_WIDE منسوخ شدند. به‌جای آن‌ها مستقیماً از نوع wchar_t استفاده کنید. از پایتون 3.3 به بعد، Py_UNICODE و PY_UNICODE_TYPE فقط مستعاری برای wchar_t هستند. (مشارکت‌شده توسط Victor Stinner در gh-105156.)

• منسوخ کردن توابع PyWeakref_GetObject() و PyWeakref_GET_OBJECT() که یک ارجاع امانتی را برمی‌گردانند. آن‌ها را با تابع جدید PyWeakref_GetRef() جایگزین کنید که یک ارجاع قوی را برمی‌گرداند. پروژهی pythoncapi-compat project را می‌توان برای دریافت PyWeakref_GetRef() در پایتون ۳.۱۲ و قدیمی‌تر استفاده کرد. (مشارکت‌کرده توسط Victor Stinner در gh-105927.)

تغییرات در API پایتون¶

• PEP 667 چندین تغییر را در معناشناسی locals() و f_locals معرفی می‌کند:

  • فراخوانی locals() در یک محدوده بهینه‌شده اکنون در هر فراخوانی یک تصویر لحظه‌ای مستقل تولید می‌کند و در نتیجه دیگر ارجاع‌های پیش‌تر بازگردانده‌شده را به‌طور ضمنی به‌روزرسانی نمی‌کند. به‌دست‌آوردن رفتار قدیمی سی‌پایتون اکنون مستلزم این است که با فراخوانی‌های صریح، دیکشنری‌ای که در ابتدا بازگردانده شده است با نتایج فراخوانی‌های بعدی locals() به‌روزرسانی شود. به توابع اجرای کد که به‌طور ضمنی locals() را هدف می‌گیرند (مانند exec و eval) باید یک فضای نام صریح پاس داده شود تا بتوان در یک محدوده بهینه‌شده به نتایج آن‌ها دسترسی داشت. (این تغییر به‌عنوان بخشی از PEP 667 انجام شده است.)

  • فراخوانی locals() از یک درک در محدوده ماژول یا کلاس (از جمله از طریق exec یا eval) دوباره طوری رفتار می‌کند که گویی درک به‌صورت یک تابع تودرتوی مستقل در حال اجراست (یعنی متغیرهای محلی محدوده دربرگیرنده گنجانده نمی‌شوند). در پایتون 3.12، این رفتار هنگام پیاده‌سازی PEP 709 به گونه‌ای تغییر کرده بود که متغیرهای محلی محدوده دربرگیرنده را در بر بگیرد. (به‌عنوان بخشی از PEP 667 تغییر کرد.)

  • دسترسی به FrameType.f_locals در یک محدوده بهینه‌شده اکنون یک پراکسی نوشتن‌همزمان برمی‌گرداند، نه یک تصویر لحظه‌ای که در زمان‌های به‌خوبی تعریف‌نشده به‌روزرسانی می‌شود. در صورت نیاز به تصویر لحظه‌ای، باید آن را به‌طور صریح با dict یا متد .copy() پراکسی ایجاد کنید. (این تغییر به‌عنوان بخشی از PEP 667 انجام شده است.)

• functools.partial اکنون هنگامی که به‌عنوان متد استفاده شود، یک FutureWarning منتشر می‌کند. این رفتار در نسخه‌های آینده پایتون تغییر خواهد کرد. اگر می‌خواهید رفتار قدیمی را حفظ کنید، آن را در staticmethod() بپیچید. (مشارکت‌شده توسط Serhiy Storchaka در gh-121027.)

• اکنون OSError توسط getpass.getuser() در صورت هرگونه شکست در بازیابی نام کاربری ایجاد می‌شود، به‌جای ImportError در پلتفرم‌های غیر یونیکس یا KeyError در پلتفرم‌های یونیکس که پایگاه داده رمز عبور در آن‌ها خالی است.

• مقدار ویژگی mode از gzip.GzipFile اکنون یک رشته ('rb' یا 'wb') است، به‌جای یک عدد صحیح (1 یا 2). مقدار ویژگی mode از شیء شبه‌پرونده‌ی خواندنی که توسط zipfile.ZipFile.open() بازگردانده می‌شود، اکنون 'rb' است، به‌جای 'r'. (مشارکت‌شده توسط Serhiy Storchaka در gh-115961.)

• mailbox.Maildir اکنون پرونده‌هایی را که با نقطه (.) آغاز می‌شوند نادیده می‌گیرد. (با مشارکت Zackery Spytz در gh-65559.)

• pathlib.Path.glob() و rglob() اکنون اگر الگویی که به «**» ختم می‌شود داده شود، هم پرونده‌ها و هم پوشه‌ها را برمی‌گردانند، نه فقط پوشه‌ها. برای حفظ رفتار قبلی و تطبیق فقط با پوشه‌ها، یک اسلش انتهایی اضافه کنید.

• ماژول threading اکنون انتظار دارد که ماژول _thread تابع _is_main_interpreter() را داشته باشد. این تابع هیچ آرگومانی نمی‌گیرد و اگر مفسر فعلی، مفسر اصلی باشد، True برمی‌گرداند.

  هر کتابخانه یا برنامه‌ای که یک ماژول _thread سفارشی ارائه می‌دهد، باید _is_main_interpreter() را نیز فراهم کند، درست مانند سایر ویژگی‌های «خصوصی» ماژول. (gh-112826.)

تغییرات در API زبان C¶

• Python.h دیگر سرآیند استاندارد <ieeefp.h> را شامل نمی‌شود. این سرآیند برای تابع finite() گنجانده شده بود که اکنون توسط سرآیند <math.h> ارائه می‌شود. اکنون در صورت نیاز باید به‌طور صریح گنجانده شود. ماکرو HAVE_IEEEFP_H را نیز حذف کنید. (مشارکت Victor Stinner در gh-108765.)

• Python.h دیگر این پرونده‌های سرآیند استاندارد را شامل نمی‌شود: <time.h>، <sys/select.h> و <sys/time.h>. در صورت نیاز، اکنون باید به‌طور صریح گنجانده شوند. برای مثال، <time.h> توابع clock() و gmtime() را فراهم می‌کند، <sys/select.h> تابع select() را فراهم می‌کند و <sys/time.h> توابع futimes()، gettimeofday() و setitimer() را فراهم می‌کند. (مشارکت‌شده توسط Victor Stinner در gh-108765.)

• در ویندوز، Python.h دیگر شامل پرونده‌ی سرآیند استاندارد <stddef.h> نیست. در صورت نیاز، اکنون باید به‌صورت صریح گنجانده شود. برای مثال، این سرآیند تابع offsetof() و نوع‌های size_t و ptrdiff_t را فراهم می‌کند. گنجاندن <stddef.h> به‌صورت صریح از قبل برای همه‌ی پلتفرم‌های دیگر لازم بود؛ ماکروی HAVE_STDDEF_H فقط در ویندوز تعریف می‌شود. (مشارکت‌شده توسط Victor Stinner در gh-108765.)

• اگر ماکروی Py_LIMITED_API تعریف شده باشد، ماکروهای Py_BUILD_CORE، Py_BUILD_CORE_BUILTIN و Py_BUILD_CORE_MODULE اکنون توسط <Python.h> تعریف نمی‌شوند. (مشارکت‌شده توسط Victor Stinner در gh-85283.)

• ماکروهای قدیمی سطل زباله (trashcan) Py_TRASHCAN_SAFE_BEGIN و Py_TRASHCAN_SAFE_END حذف شدند. آن‌ها باید با ماکروهای جدید Py_TRASHCAN_BEGIN و Py_TRASHCAN_END جایگزین شوند.

  یک تابع tp_dealloc که ماکروهای قدیمی را دارد، مانند:

  static void
  mytype_dealloc(mytype *p)
  {
      PyObject_GC_UnTrack(p);
      Py_TRASHCAN_SAFE_BEGIN(p);
      ...
      Py_TRASHCAN_SAFE_END
  }
  

  باید به ماکروهای جدید به شرح زیر مهاجرت کنند:

  static void
  mytype_dealloc(mytype *p)
  {
      PyObject_GC_UnTrack(p);
      Py_TRASHCAN_BEGIN(p, mytype_dealloc)
      ...
      Py_TRASHCAN_END
  }
  

  توجه داشته باشید که Py_TRASHCAN_BEGIN آرگومان دومی دارد که باید همان تابع آزادسازی باشد که این ماکرو در آن قرار دارد. ماکروهای جدید در پایتون 3.8 اضافه شدند و ماکروهای قدیمی در پایتون 3.11 منسوخ شدند. (مشارکت‌شده توسط ایریت کاتریل در gh-105111.)

• PEP 667 چندین تغییر در توابع مرتبط با فریم معرفی می‌کند:

  • اثرات تغییر دادن دیکشنری بازگردانده‌شده از PyEval_GetLocals() در یک محدوده بهینه‌شده تغییر کرده‌اند. مدخل‌های جدید دیکشنری که به این روش اضافه می‌شوند، اکنون تنها برای فراخوانی‌های بعدی PyEval_GetLocals() در آن فریم قابل مشاهده خواهند بود، زیرا PyFrame_GetLocals()، locals() و FrameType.f_locals دیگر به همان دیکشنری نهانگاه‌شده‌ی زیرین دسترسی ندارند. تغییراتی که در مدخل‌های مربوط به نام‌های متغیرهای واقعی و نام‌های افزوده‌شده از طریق رابط‌های پراکسی نوشتن‌همزمان اعمال می‌شوند، در فراخوانی‌های بعدی PyEval_GetLocals() در آن فریم بازنویسی خواهند شد. به‌روزرسانی توصیه‌شده‌ی کد به نحوه‌ی استفاده از تابع بستگی دارد، بنابراین برای جزئیات به اطلاعیه‌ی منسوخ‌شدن تابع مراجعه کنید.

  • فراخوانی PyFrame_GetLocals() در محدوده بهینه‌شده اکنون به‌جای یک تصویر لحظه‌ای که در زمان‌های نامشخص به‌روزرسانی می‌شود، یک پراکسی نوشتن‌همزمان برمی‌گرداند. اگر تصویر لحظه‌ای مورد نیاز است، باید به‌طور صریح ایجاد شود (مثلاً با PyDict_Copy())، یا با فراخوانی API جدید PyEval_GetFrameLocals().

  • PyFrame_FastToLocals() و PyFrame_FastToLocalsWithError() دیگر هیچ اثری ندارند. فراخوانی این توابع از زمان پایتون 3.11، زمانی که PyFrame_GetLocals() برای نخستین بار معرفی شد، زائد بوده است.

  • PyFrame_LocalsToFast() دیگر هیچ اثری ندارد. اکنون که PyFrame_GetLocals() برای محدوده‌های بهینه‌شده یک پراکسی نوشتن‌همزمان برمی‌گرداند، فراخوانی این تابع زائد است.

• پایتون 3.13 بسیاری از توابع خصوصی را حذف کرد. برخی از آن‌ها را می‌توان با استفاده از این جایگزین‌ها جایگزین کرد:

  • _PyDict_Pop(): PyDict_Pop() یا PyDict_PopString()؛

  • _PyDict_GetItemWithError(): PyDict_GetItemRef();

  • _PyErr_WriteUnraisableMsg(): PyErr_FormatUnraisable();

  • _PyEval_SetTrace(): PyEval_SetTrace() یا PyEval_SetTraceAllThreads();

  • _PyList_Extend(): PyList_Extend();

  • _PyLong_AsInt(): PyLong_AsInt();

  • _PyMem_RawStrdup(): strdup();

  • _PyMem_Strdup(): strdup();

  • _PyObject_ClearManagedDict(): PyObject_ClearManagedDict();

  • _PyObject_VisitManagedDict(): PyObject_VisitManagedDict();

  • _PyThreadState_UncheckedGet(): PyThreadState_GetUnchecked();

  • _PyTime_AsSecondsDouble(): PyTime_AsSecondsDouble();

  • _PyTime_GetMonotonicClock(): PyTime_Monotonic() یا PyTime_MonotonicRaw()؛

  • _PyTime_GetPerfCounter(): PyTime_PerfCounter() یا PyTime_PerfCounterRaw()؛

  • _PyTime_GetSystemClock(): PyTime_Time() یا PyTime_TimeRaw()؛

  • _PyTime_MAX: PyTime_MAX;

  • _PyTime_MIN: PyTime_MIN;

  • _PyTime_t: PyTime_t;

  • _Py_HashPointer(): Py_HashPointer();

  • _Py_IsFinalizing(): Py_IsFinalizing().

  می‌توان از pythoncapi-compat project برای به دست آوردن بیشتر این توابع جدید در پایتون 3.12 و نسخه‌های قدیمی‌تر استفاده کرد.