منابع ترجمه · Python Built-ins · فصل ۳

توابع درون‌ساخت (مرجع درون‌ساخت‌های پایتون)

۶۶ دقیقه مطالعه · به‌روزرسانی ۳ آبان ۱۴۰۵

منبع اصلی: Python Built-ins, Chapter 3: Built-in Functions — Python Software Foundation

💡 این صفحه مثل یک نوت‌بوک Jupyter است: متغیر و تابعی که در یک سلول تعریف شود، در سلول‌های بعدی همین صفحه در دسترس است. سلول‌ها را به ترتیب اجرا کنید، یا با «⏮ تا اینجا» همهٔ سلول‌های قبلیِ اجرانشده را یک‌جا اجرا کنید.

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

abs(number, /)

قدر مطلق (absolute value) یک عدد را برمی‌گرداند. آرگومان می‌تواند عدد صحیح، عدد ممیز شناور، یا شیئی باشد که __abs__() را پیاده می‌کند. اگر آرگومان عدد مختلط باشد، اندازهٔ (magnitude) آن برگردانده می‌شود.

aiter(async_iterable, /)

aiter(callable, /, stop_value, *, stop_exception=StopAsyncIteration)

aiter(callable, /, *, stop_exception)

یک شیء تکرارگر ناهمگام (asynchronous iterator) برمی‌گرداند. آرگومان اول بسته به وجود آرگومان‌های دیگر بسیار متفاوت تفسیر می‌شود. بدون آرگومان‌های دیگر، آرگومان تنها باید یک تکرارپذیر ناهمگام (asynchronous iterable) باشد و نتیجه معادل فراخوانی x.__aiter__() است.

اگر stop_value یا stop_exception داده شود، آرگومان اول باید یک شیء قابل‌فراخوانی باشد. تکرارگر ناهمگامی که در این حالت ساخته می‌شود، برای هر فراخوانی متد __anext__() خود، callable را بدون آرگومان فراخوانی می‌کند و نتیجه را await می‌کند؛ اگر مقدار await‌شده برابر stop_value باشد، یا اگر فراخوانی استثنایی هماهنگ با stop_exception پرتاب کند، StopAsyncIteration پرتاب می‌شود، وگرنه مقدار برگردانده می‌شود. callable فقط زمانی فراخوانی می‌شود که نتیجهٔ __anext__() await شود.

stop_exception یک کلاس استثنا یا یک تاپل از کلاس‌های استثناست. اگر stop_value مشخص نشده باشد، تکرار فقط وقتی متوقف می‌شود که callable استثنا پرتاب کند. اگر callable استثنای StopAsyncIteration را پرتاب کند که با stop_exception هماهنگ نباشد، به RuntimeError تبدیل می‌شود، همان‌طور که برای مولدهای ناهمگام اتفاق می‌افتد (به PEP 525 نگاه کنید).

برای مثال، خواندن بخش‌های (chunk) با اندازهٔ ثابت از یک جریان ناهمگام تا رسیدن به پایان فایل:

from functools import partial
async for chunk in aiter(partial(reader.read, 1024), b''):
    process_chunk(chunk)

یا مصرف یک asyncio.Queue تا زمانی که خاموش شود:

from asyncio import QueueShutDown
async for item in aiter(queue.get, stop_exception=QueueShutDown):
    process_item(item)

افزوده‌شده در نسخهٔ ۳٫۱۰.

تغییر در نسخهٔ ۳٫۱۶: پارامترهای stop_value و stop_exception اضافه شدند.

all(iterable, /)

اگر همهٔ عناصر iterable درست باشند (یا تکرارپذیر خالی باشد) True برمی‌گرداند. معادل است با:

def all(iterable):
    for element in iterable:
        if not element:
            return False
    return True

await anext(async_iterator, /)

await anext(async_iterator, default, /)

هنگام await شدن، عنصر بعدی را از تکرارگر ناهمگام داده‌شده برمی‌گرداند، یا اگر default داده شده و تکرارگر تمام‌شده (exhausted) باشد، default را برمی‌گرداند.

این نسخهٔ ناهمگام تابع درون‌ساخت next() است و رفتار مشابهی دارد.

این تابع متد __anext__() مربوط به async_iterator را فراخوانی می‌کند و یک awaitable برمی‌گرداند. await کردن آن مقدار بعدی تکرارگر را می‌دهد. اگر default داده شده باشد، در صورت تمام شدن تکرارگر برگردانده می‌شود، وگرنه StopAsyncIteration پرتاب می‌شود.

افزوده‌شده در نسخهٔ ۳٫۱۰.

any(iterable, /)

اگر هر عنصری از iterable درست باشد True برمی‌گرداند. اگر تکرارپذیر خالی باشد False برمی‌گرداند. معادل است با:

def any(iterable):
    for element in iterable:
        if element:
            return True
    return False

ascii(object, /)

مانند repr()، رشته‌ای حاوی نمایش قابل‌چاپ یک شیء برمی‌گرداند، اما نویسه‌های غیر ASCII در رشتهٔ برگردانده‌شده توسط repr() را با escapeهای \x، \u یا \U جایگزین می‌کند. این رشته‌ای شبیه آنچه repr() در پایتون ۲ برمی‌گرداند تولید می‌کند.

bin(integer, /)

یک عدد صحیح را به رشتهٔ دودویی با پیشوند «0b» تبدیل می‌کند. نتیجه یک عبارت معتبر پایتون است. اگر integer شیء int پایتون نباشد، باید متد __index__() را تعریف کند که یک عدد صحیح برگرداند. چند مثال:

>>> bin(3)
'0b11'
>>> bin(-10)
'-0b1010'

اگر پیشوند «0b» را بخواهید یا نخواهید، می‌توانید از روش‌های زیر استفاده کنید.

>>> format(14, '#b'), format(14, 'b')
('0b1110', '1110')
>>> f'{14:#b}', f'{14:b}'
('0b1110', '1110')

همچنین enum.bin() را برای نمایش مقادیر منفی به‌صورت مکمل دو (two’s-complement) ببینید.

برای اطلاعات بیشتر format() را هم ببینید.

class bool(object=False, /)

یک مقدار بولی، یعنی یکی از True یا False، برمی‌گرداند. آرگومان با روال استاندارد آزمون درستی (truth testing) تبدیل می‌شود. اگر آرگومان نادرست یا حذف شده باشد False برمی‌گرداند؛ وگرنه True برمی‌گرداند. کلاس bool زیرکلاسی از int است (انواع عددی را ببینید). نمی‌توان از آن زیرکلاس دیگری ساخت. تنها نمونه‌هایش False و True هستند (نوع بولی را ببینید).

تغییر در نسخهٔ ۳٫۷: پارامتر اکنون فقط‌موضعی (positional-only) است.

breakpoint(*args, **kws)

این تابع شما را در محل فراخوانی به اشکال‌زدا (debugger) می‌برد. به‌طور مشخص، sys.breakpointhook() را فراخوانی می‌کند و args و kws را مستقیماً به آن می‌دهد. به‌طور پیش‌فرض sys.breakpointhook() تابع pdb.set_trace() را بدون آرگومان فراخوانی می‌کند. در این حالت، تابع صرفاً برای راحتی است تا لازم نباشد pdb را صریحاً import کنید یا کد زیادی برای ورود به اشکال‌زدا تایپ کنید. با این حال sys.breakpointhook() را می‌توان روی تابع دیگری تنظیم کرد و breakpoint() آن را خودکار فراخوانی می‌کند، که اجازه می‌دهد وارد اشکال‌زدای دلخواه خود شوید. اگر sys.breakpointhook() در دسترس نباشد، این تابع RuntimeError پرتاب می‌کند.

به‌طور پیش‌فرض رفتار breakpoint() را می‌توان با متغیر محیطی PYTHONBREAKPOINT تغییر داد. برای جزئیات استفاده sys.breakpointhook() را ببینید.

توجه کنید که اگر sys.breakpointhook() جایگزین شده باشد، این تضمین وجود ندارد.

رویداد ممیزی (audit event): builtins.breakpoint با آرگومان breakpointhook.

افزوده‌شده در نسخهٔ ۳٫۷.

class bytearray(source=b'')

class bytearray(source, encoding, errors='strict')

یک آرایهٔ جدید از بایت‌ها برمی‌گرداند. کلاس bytearray دنباله‌ای تغییرپذیر از اعداد صحیح در بازهٔ 0 <= x < 256 است. بیشتر متدهای معمول دنباله‌های تغییرپذیر را، که در نوع‌های دنبالهٔ تغییرپذیر شرح داده شده‌اند، و نیز بیشتر متدهای نوع bytes را (متدهای bytes را ببینید) دارد.

پارامتر اختیاری source را می‌توان به چند روش برای مقداردهی اولیهٔ آرایه به کار برد:

• اگر رشته (string) باشد، باید پارامترهای encoding (و به‌طور اختیاری errors) را هم بدهید؛ bytearray() سپس رشته را با str.encode() به بایت تبدیل می‌کند.
• اگر عدد صحیح باشد، آرایه به همان اندازه خواهد بود و با بایت‌های صفر مقداردهی می‌شود.
• اگر شیئی مطابق با رابط بافر (buffer interface) باشد، یک بافر فقط‌خواندنی از شیء برای مقداردهی آرایهٔ بایت به کار می‌رود.
• اگر تکرارپذیر باشد، باید تکرارپذیری از اعداد صحیح در بازهٔ 0 <= x < 256 باشد که به‌عنوان محتوای اولیهٔ آرایه به کار می‌روند.

بدون آرگومان، آرایه‌ای به اندازهٔ ۰ ساخته می‌شود.

همچنین دنباله‌های دودویی و bytearray را ببینید.

class bytes(source=b'')

class bytes(source, encoding, errors='strict')

یک شیء «bytes» جدید برمی‌گرداند که دنباله‌ای تغییرناپذیر از اعداد صحیح در بازهٔ 0 <= x < 256 است. bytes نسخهٔ تغییرناپذیر bytearray است — متدهای غیرتغییردهندهٔ یکسان و رفتار اندیس‌گذاری و برش یکسانی دارد.

بر این اساس، آرگومان‌های سازنده مانند bytearray() تفسیر می‌شوند.

اشیای bytes را می‌توان با literal هم ساخت؛ رشته‌ها را ببینید.

همچنین دنباله‌های دودویی، bytes و متدهای bytes را ببینید.

callable(object, /)

اگر آرگومان object قابل‌فراخوانی به نظر برسد True و در غیر این صورت False برمی‌گرداند. اگر True برگرداند، همچنان ممکن است فراخوانی شکست بخورد، اما اگر False باشد، فراخوانی object هرگز موفق نخواهد شد. توجه کنید که کلاس‌ها قابل‌فراخوانی‌اند (فراخوانی یک کلاس نمونهٔ جدیدی برمی‌گرداند)؛ نمونه‌ها در صورتی قابل‌فراخوانی‌اند که کلاسشان متد __call__() داشته باشد.

افزوده‌شده در نسخهٔ ۳٫۲: این تابع ابتدا در پایتون ۳٫۰ حذف شد و سپس در پایتون ۳٫۲ بازگردانده شد.

chr(codepoint, /)

رشته‌ای را که نمایندهٔ نویسه‌ای با نقطهٔ کد یونیکد مشخص‌شده است برمی‌گرداند. برای مثال، chr(97) رشتهٔ 'a' را برمی‌گرداند، در حالی که chr(8364) رشتهٔ '€' را برمی‌گرداند. این وارون ord() است.

بازهٔ معتبر برای آرگومان از ۰ تا ۱٬۱۱۴٬۱۱۱ (در مبنای ۱۶: 0x10FFFF) است. اگر خارج از این بازه باشد ValueError پرتاب می‌شود.

@classmethod

یک متد را به متد کلاس (class method) تبدیل می‌کند.

متد کلاس، کلاس را به‌عنوان آرگومان اول ضمنی دریافت می‌کند، همان‌طور که متد نمونه، نمونه را دریافت می‌کند. برای تعریف متد کلاس از این الگو استفاده کنید:

class C:
    @classmethod
    def f(cls, arg1, arg2): ...

شکل @classmethod یک دکوراتور تابع است — برای جزئیات تعریف تابع را ببینید.

متد کلاس را می‌توان روی کلاس (مثل C.f()) یا روی یک نمونه (مثل C().f()) فراخوانی کرد. از نمونه، به‌جز کلاسش، چشم‌پوشی می‌شود. اگر متد کلاس برای یک کلاس مشتق فراخوانی شود، شیء کلاس مشتق به‌عنوان آرگومان اول ضمنی داده می‌شود.

متدهای کلاس با متدهای ایستای C++ یا Java متفاوت‌اند. اگر آن‌ها را می‌خواهید، در همین بخش staticmethod() را ببینید. برای اطلاعات بیشتر دربارهٔ متدهای کلاس، سلسله‌مراتب نوع استاندارد را ببینید.

تغییر در نسخهٔ ۳٫۹: متدهای کلاس اکنون می‌توانند توصیف‌گرهای (descriptors) دیگری مانند property() را بپوشانند.

تغییر در نسخهٔ ۳٫۱۰: متدهای کلاس اکنون ویژگی‌های متد (__module__، __name__، __qualname__، __doc__ و __annotations__) را به ارث می‌برند و ویژگی جدید __wrapped__ را دارند.

منسوخ و حذف‌شده (۳٫۱۱ تا ۳٫۱۳): متدهای کلاس دیگر نمی‌توانند توصیف‌گرهای دیگری مانند property() را بپوشانند.

compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1, *, module=None)

source را به یک شیء کد یا AST کامپایل می‌کند. اشیای کد را می‌توان با exec() یا eval() اجرا کرد. source می‌تواند یک رشتهٔ عادی، یک رشتهٔ بایت یا یک شیء AST باشد. برای اطلاعات دربارهٔ کار با اشیای AST به مستندات ماژول ast مراجعه کنید.

آرگومان filename باید فایلی را که کد از آن خوانده شده نشان دهد؛ اگر از فایل خوانده نشده، مقداری قابل‌شناسایی بدهید (معمولاً '<string>' به کار می‌رود).

آرگومان mode مشخص می‌کند چه نوع کدی باید کامپایل شود؛ اگر source از دنباله‌ای از دستورها تشکیل شده باشد 'exec'، اگر یک عبارت واحد باشد 'eval'، و اگر یک دستور تعاملی واحد باشد 'single' (در حالت آخر، دستورهای عبارتی که به چیزی غیر از None ارزیابی شوند چاپ می‌شوند). همچنین اگر source از یک امضای نوع تابع تشکیل شده باشد، مثلاً (int) -> str، می‌تواند 'func_type' باشد؛ برای اطلاعات بیشتر ast.parse() را ببینید. این حالت نیاز دارد ast.PyCF_ONLY_AST در flags داده شود.

آرگومان‌های اختیاری flags و dont_inherit کنترل می‌کنند که کدام گزینه‌های کامپایلر فعال و کدام ویژگی‌های آینده (future) مجاز شوند. اگر هیچ‌کدام وجود نداشته باشند (یا هر دو صفر باشند)، کد با همان پرچم‌هایی کامپایل می‌شود که بر کدِ فراخوانندهٔ compile() اثر می‌گذارند. اگر آرگومان flags داده شود و dont_inherit داده نشود (یا صفر باشد)، گزینه‌های کامپایلر و دستورهای future مشخص‌شده توسط flags علاوه بر آنچه به هر حال استفاده می‌شد به کار می‌روند. اگر dont_inherit یک عدد صحیح غیرصفر باشد، آرگومان flags همه‌چیز است — پرچم‌های (ویژگی‌های future و گزینه‌های کامپایلر) کد پیرامونی نادیده گرفته می‌شوند.

گزینه‌های کامپایلر و دستورهای future با بیت‌هایی مشخص می‌شوند که می‌توان آن‌ها را با OR بیتی ترکیب کرد تا چند گزینه مشخص شود. فیلد بیتی لازم برای مشخص کردن یک ویژگی future را می‌توان به‌عنوان ویژگی compiler_flag روی نمونهٔ _Feature در ماژول __future__ یافت. پرچم‌های کامپایلر در ماژول ast با پیشوند PyCF_ یافت می‌شوند.

آرگومان optimize سطح بهینه‌سازی کامپایلر را مشخص می‌کند؛ مقدار پیش‌فرض -1 سطح بهینه‌سازی مفسر را، آن‌طور که با گزینه‌های -O تعیین شده، انتخاب می‌کند. سطوح صریح عبارت‌اند از 0 (بدون بهینه‌سازی؛ __debug__ درست است)، 1 (assertها حذف می‌شوند، __debug__ نادرست است) یا 2 (docstringها هم حذف می‌شوند).

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

اگر منبع کامپایل‌شده نامعتبر باشد، این تابع SyntaxError پرتاب می‌کند، از جمله source حاوی نویسهٔ null یا غیرقابل‌رمزگشایی؛ اگر mode یا flags نامعتبر باشد، یا اگر source رشته‌ای حاوی نویسه‌های surrogate باشد، ValueError؛ اگر source برای تجزیه یا کامپایل بیش از حد پیچیده باشد، مثلاً عبارتی با هزاران عملگر تودرتو، MemoryError یا RecursionError؛ و اگر source بیش از حد بزرگ باشد، OverflowError.

اگر می‌خواهید کد پایتون را به نمایش AST آن تجزیه کنید، ast.parse() را ببینید.

رویداد ممیزی: compile با آرگومان‌های source و filename. این رویداد ممکن است توسط کامپایل ضمنی هم صادر شود.

یادداشت: هنگام کامپایل رشته‌ای با کد چندخطی در حالت 'single' یا 'eval'، ورودی باید حداقل با یک نویسهٔ خط جدید پایان یابد. این برای تسهیل تشخیص دستورهای کامل و ناقص در ماژول code است.

هشدار: ممکن است با یک رشتهٔ به‌اندازهٔ کافی بزرگ یا پیچیده هنگام کامپایل به شیء AST، به دلیل محدودیت‌های عمق پشته در کامپایلر AST پایتون، مفسر پایتون از کار بیفتد (crash).

تغییر در نسخهٔ ۳٫۲: استفاده از خط جدید ویندوز و مک مجاز شد. همچنین ورودی در حالت 'exec' دیگر لازم نیست با خط جدید پایان یابد. پارامتر optimize افزوده شد.

تغییر در نسخهٔ ۳٫۵: پیش‌تر هنگام مواجهه با بایت‌های null در source، TypeError پرتاب می‌شد.

تغییر در نسخهٔ ۳٫۸: اکنون می‌توان ast.PyCF_ALLOW_TOP_LEVEL_AWAIT را در flags داد تا از await، async for و async with در سطح بالا پشتیبانی شود. همچنین پشتیبانی از mode='func_type' افزوده شد.

تغییر در نسخهٔ ۳٫۱۲: هنگام مواجهه با بایت‌های null در source به‌جای ValueError، SyntaxError پرتاب می‌شود.

تغییر در نسخهٔ ۳٫۱۵: پارامتر module افزوده شد.

class complex(number=0, /)

class complex(string, /)

class complex(real=0, imag=0)

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

مثال‌ها:

>>> complex('+1.23')
(1.23+0j)
>>> complex('-4.5j')
-4.5j
>>> complex('-1.23+4.5j')
(-1.23+4.5j)
>>> complex('\t( -1.23+4.5J )\n')
(-1.23+4.5j)
>>> complex('-Infinity+NaNj')
(-inf+nanj)
>>> complex(1.23)
(1.23+0j)
>>> complex(imag=-4.5)
-4.5j
>>> complex(-1.23, 4.5)
(-1.23+4.5j)

اگر آرگومان رشته باشد، باید یا فقط بخش حقیقی (با همان قالب float())، یا فقط بخش موهومی (با همان قالب اما با پسوند 'j' یا 'J')، یا هر دو بخش حقیقی و موهومی را داشته باشد (در این حالت علامت بخش موهومی الزامی است). رشته را می‌توان به‌طور اختیاری با فاصله‌های خالی و پرانتزهای گرد '(' و ')' احاطه کرد که نادیده گرفته می‌شوند. رشته نباید بین '+'، '-'، پسوند 'j' یا 'J' و عدد اعشاری فاصلهٔ خالی داشته باشد. برای مثال complex('1+2j') درست است، اما complex('1 + 2j') ValueError پرتاب می‌کند. دقیق‌تر، ورودی، پس از حذف پرانتزها و نویسه‌های فاصلهٔ خالی ابتدا و انتها، باید با قاعدهٔ تولید complexvalue در گرامر زیر مطابقت داشته باشد:

complexvalue: floatvalue |
            : floatvalue ("j" | "J") |
            : floatvalue sign absfloatvalue ("j" | "J")

اگر آرگومان عدد باشد، سازنده مانند int() و float() یک تبدیل عددی انجام می‌دهد. برای یک شیء عمومی پایتون x، complex(x) به x.__complex__() واگذار می‌کند. اگر __complex__() تعریف نشده باشد، به __float__() برمی‌گردد. اگر __float__() تعریف نشده باشد، به __index__() برمی‌گردد.

اگر دو آرگومان داده شود یا از آرگومان‌های کلیدواژه‌ای استفاده شود، هر آرگومان می‌تواند هر نوع عددی (از جمله مختلط) باشد. اگر هر دو آرگومان اعداد حقیقی باشند، عدد مختلطی با مؤلفهٔ حقیقی real و مؤلفهٔ موهومی imag برمی‌گرداند. اگر هر دو آرگومان مختلط باشند، عدد مختلطی با مؤلفهٔ حقیقی real.real-imag.imag و مؤلفهٔ موهومی real.imag+imag.real برمی‌گرداند. اگر یکی از آرگومان‌ها عدد حقیقی باشد، در عبارت‌های بالا فقط مؤلفهٔ حقیقی آن به کار می‌رود.

همچنین complex.from_number() را ببینید که فقط یک آرگومان عددی می‌پذیرد.

اگر همهٔ آرگومان‌ها حذف شوند، 0j برمی‌گرداند.

نوع complex در انواع عددی شرح داده شده است.

تغییر در نسخهٔ ۳٫۶: گروه‌بندی ارقام با زیرخط، مانند literalهای کد، مجاز است.

تغییر در نسخهٔ ۳٫۸: اگر __complex__() و __float__() تعریف نشده باشند به __index__() برمی‌گردد.

منسوخ در نسخهٔ ۳٫۱۴: دادن عدد مختلط به‌عنوان آرگومان real یا imag اکنون منسوخ است؛ آن را فقط باید به‌عنوان یک آرگومان موضعی واحد داد.

delattr(object, name, /)

این تابع خویشاوند setattr() است. آرگومان‌ها یک شیء و یک رشته‌اند. رشته باید نام یکی از ویژگی‌های شیء باشد. تابع ویژگی نام‌برده را حذف می‌کند، به شرطی که شیء اجازه دهد. برای مثال delattr(x, 'foobar') معادل del x.foobar است. name لازم نیست شناسهٔ معتبر پایتون باشد (setattr() را ببینید).

class dict(**kwargs)

class dict(mapping, /, **kwargs)

class dict(iterable, /, **kwargs)

یک دیکشنری جدید می‌سازد. شیء dict کلاس دیکشنری است. برای مستندات دربارهٔ این کلاس انواع نگاشت را ببینید.

برای ظرف‌های دیگر کلاس‌های درون‌ساخت frozendict، list، set و tuple و نیز ماژول collections را ببینید.

dir()

dir(object, /)

بدون آرگومان، فهرست نام‌ها در دامنهٔ محلی (local scope) جاری را برمی‌گرداند. با یک آرگومان، تلاش می‌کند فهرستی از ویژگی‌های معتبر آن شیء برگرداند.

اگر شیء متدی به نام __dir__() داشته باشد، این متد فراخوانی می‌شود و باید فهرست ویژگی‌ها را برگرداند. این اجازه می‌دهد اشیایی که __getattr__() یا __getattribute__() سفارشی پیاده‌سازی می‌کنند، شیوهٔ گزارش ویژگی‌هایشان توسط dir() را سفارشی کنند.

اگر شیء __dir__() نداشته باشد، تابع تمام تلاشش را می‌کند تا از ویژگی __dict__ شیء، در صورت تعریف، و از شیء نوع آن اطلاعات جمع کند. فهرست حاصل لزوماً کامل نیست و وقتی شیء __getattr__() سفارشی دارد ممکن است نادقیق باشد.

سازوکار پیش‌فرض dir() با انواع مختلف اشیا رفتار متفاوتی دارد، چون می‌کوشد مرتبط‌ترین اطلاعات را تولید کند، نه کامل‌ترین:

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

فهرست حاصل به ترتیب الفبایی مرتب است. برای مثال:

>>> import struct
>>> dir()   # show the names in the module namespace
['__builtins__', '__name__', 'struct']
>>> dir(struct)   # show the names in the struct module
['Struct', '__all__', '__builtins__', '__doc__', '__file__',
 '__initializing__', '__loader__', '__name__', '__package__',
 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
 'unpack', 'unpack_from']
>>> class Shape:
...     def __dir__(self):
...         return ['area', 'perimeter', 'location']
...
>>> s = Shape()
>>> dir(s)
['area', 'location', 'perimeter']

یادداشت: چون dir() عمدتاً برای راحتی در اعلان تعاملی ارائه شده، بیشتر می‌کوشد مجموعه‌ای جالب از نام‌ها بدهد تا مجموعه‌ای دقیق یا سازگار، و رفتار جزئی آن ممکن است بین نسخه‌ها تغییر کند. برای مثال، ویژگی‌های فراکلاس (metaclass) هنگامی که آرگومان یک کلاس است در فهرست نتیجه نیستند.

divmod(a, b, /)

دو عدد (غیرمختلط) را به‌عنوان آرگومان می‌گیرد و جفتی از اعداد شامل خارج‌قسمت و باقی‌مانده را هنگام استفاده از تقسیم صحیح برمی‌گرداند. با نوع‌های عملوند مختلط، قواعد عملگرهای حسابی دودویی اعمال می‌شود. برای اعداد صحیح، نتیجه همان (a // b, a % b) است. برای اعداد ممیز شناور نتیجه (q, a % b) است که q معمولاً math.floor(a / b) است اما ممکن است یک واحد کمتر باشد. در هر حال q * b + a % b بسیار نزدیک به a است، اگر a % b غیرصفر باشد علامتش با b یکسان است، و 0 <= abs(a % b) < abs(b).

enumerate(iterable, start=0)

یک شیء enumerate برمی‌گرداند. iterable باید یک دنباله، یک تکرارگر، یا شیء دیگری باشد که تکرار را پشتیبانی می‌کند. متد __next__() تکرارگری که enumerate() برمی‌گرداند، یک تاپل شامل شمارنده (از start که پیش‌فرضش ۰ است) و مقادیر حاصل از تکرار روی iterable برمی‌گرداند.

>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
>>> list(enumerate(seasons))
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
>>> list(enumerate(seasons, start=1))
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]

معادل است با:

def enumerate(iterable, start=0):
    n = start
    for elem in iterable:
        yield n, elem
        n += 1

eval(source, /, globals=None, locals=None)

• source: یک عبارت پایتون (str یا شیء کد).
• globals: فضای نام سراسری (پیش‌فرض: None)؛ dict یا frozendict یا None.
• locals: فضای نام محلی (پیش‌فرض: None)؛ یک نگاشت (mapping) یا None.
• برمی‌گرداند: نتیجهٔ عبارت ارزیابی‌شده.
• پرتاب می‌کند: خطاهای نحوی به‌صورت استثنا گزارش می‌شوند.

هشدار: این تابع کد دلخواه اجرا می‌کند. فراخوانی آن با ورودی نامطمئنِ ارائه‌شده توسط کاربر به آسیب‌پذیری‌های امنیتی می‌انجامد.

آرگومان source به‌عنوان یک عبارت پایتون (از نظر فنی، یک فهرست عبارت‌ها) با استفاده از نگاشت‌های globals و locals به‌عنوان فضای نام سراسری و محلی تجزیه و ارزیابی می‌شود. اگر دیکشنری globals وجود داشته باشد و مقداری برای کلید __builtins__ نداشته باشد، پیش از تجزیهٔ source ارجاعی به دیکشنری ماژول درون‌ساخت builtins زیر آن کلید درج می‌شود. بازنویسی __builtins__ می‌تواند برای محدود کردن یا تغییر نام‌های در دسترس به کار رود، اما این یک سازوکار امنیتی نیست: کد اجراشده همچنان می‌تواند به همهٔ درون‌ساخت‌ها دسترسی داشته باشد. اگر نگاشت locals حذف شود، پیش‌فرضش دیکشنری globals است. اگر هر دو نگاشت حذف شوند، source با globals و locals محیطی که eval() در آن فراخوانی شده اجرا می‌شود. توجه کنید eval() فقط در صورتی به دامنه‌های تودرتو (nested scopes) (غیرمحلی‌ها) در محیط پیرامون دسترسی دارد که پیش‌تر در دامنه‌ای که eval() را فراخوانی می‌کند به آن‌ها ارجاع شده باشد (مثلاً از طریق دستور nonlocal).

مثال:

>>> x = 1
>>> eval('x+1')
2

>>> eval("1, 2")
(1, 2)

این تابع را می‌توان برای اجرای اشیای کد دلخواه (مانند آن‌هایی که با compile() ساخته می‌شوند) هم به کار برد. در این حالت، به‌جای رشته یک شیء کد بدهید. اگر شیء کد با 'exec' به‌عنوان آرگومان mode کامپایل شده باشد، مقدار بازگشتی eval() برابر None خواهد بود.

نکته‌ها: اجرای پویای دستورها توسط تابع exec() پشتیبانی می‌شود. توابع globals() و locals() به ترتیب دیکشنری سراسری و محلی جاری را برمی‌گردانند که ممکن است برای ارسال به eval() یا exec() مفید باشند.

اگر source داده‌شده رشته باشد، فاصله‌ها و tabهای ابتدا و انتها حذف می‌شوند.

برای تابعی که رشته‌هایی با عبارت‌هایی که فقط literal دارند را ارزیابی می‌کند ast.literal_eval() را ببینید.

رویداد ممیزی: exec با شیء کد به‌عنوان آرگومان. رویدادهای کامپایل کد نیز ممکن است صادر شوند.

تغییر در نسخهٔ ۳٫۱۳: آرگومان‌های globals و locals اکنون می‌توانند به‌صورت کلیدواژه‌ای داده شوند. همچنین معناشناسی فضای نام محلی پیش‌فرض همان‌طور که برای درون‌ساخت locals() شرح داده شده تنظیم شد.

تغییر در نسخهٔ ۳٫۱۵: globals اکنون می‌تواند frozendict باشد.

exec(source, /, globals=None, locals=None, *, closure=None)

هشدار: این تابع کد دلخواه اجرا می‌کند. فراخوانی آن با ورودی نامطمئنِ ارائه‌شده توسط کاربر به آسیب‌پذیری‌های امنیتی می‌انجامد.

این تابع از اجرای پویای کد پایتون پشتیبانی می‌کند. source باید یک رشته یا شیء کد باشد. اگر رشته باشد، به‌عنوان مجموعه‌ای از دستورهای پایتون تجزیه و سپس اجرا می‌شود (مگر اینکه خطای نحوی رخ دهد). ^۱ اگر شیء کد باشد، صرفاً اجرا می‌شود. در همهٔ حالت‌ها انتظار می‌رود کدی که اجرا می‌شود به‌عنوان ورودی فایل معتبر باشد (بخش ورودی فایل در راهنمای مرجع را ببینید). توجه داشته باشید که دستورهای nonlocal، yield و return حتی در بافت کدی که به exec() داده می‌شود نیز بیرون از تعریف تابع قابل‌استفاده نیستند. مقدار بازگشتی None است.

در همهٔ حالت‌ها، اگر بخش‌های اختیاری حذف شوند، کد در دامنهٔ جاری اجرا می‌شود. اگر فقط globals داده شود، باید یک دیکشنری (و نه زیرکلاسی از دیکشنری) باشد که برای متغیرهای سراسری و محلی هر دو به کار می‌رود. اگر globals و locals داده شوند، به ترتیب برای متغیرهای سراسری و محلی به کار می‌روند. اگر locals داده شود می‌تواند هر شیء نگاشت باشد. به یاد داشته باشید که در سطح ماژول، globals و locals یک دیکشنری یکسان هستند.

یادداشت: وقتی exec دو شیء جدا به‌عنوان globals و locals می‌گیرد، کد طوری اجرا می‌شود که گویی درون تعریف یک کلاس جاسازی شده است. این یعنی توابع و کلاس‌هایی که در کد اجراشده تعریف می‌شوند نمی‌توانند به متغیرهایی که در سطح بالا انتساب شده‌اند دسترسی داشته باشند (چون متغیرهای «سطح بالا» در تعریف کلاس به‌عنوان متغیرهای کلاس تلقی می‌شوند).

اگر دیکشنری globals مقداری برای کلید __builtins__ نداشته باشد، ارجاعی به دیکشنری ماژول درون‌ساخت builtins زیر آن کلید درج می‌شود. بازنویسی __builtins__ می‌تواند برای محدود کردن یا تغییر نام‌های در دسترس به کار رود، اما این یک سازوکار امنیتی نیست: کد اجراشده همچنان می‌تواند به همهٔ درون‌ساخت‌ها دسترسی داشته باشد.

آرگومان closure یک closure — تاپلی از cellvarها — را مشخص می‌کند. فقط وقتی معتبر است که شیء یک شیء کد حاوی متغیرهای آزاد (closure) باشد. طول تاپل باید دقیقاً با طول ویژگی co_freevars شیء کد برابر باشد.

رویداد ممیزی: exec با شیء کد به‌عنوان آرگومان. رویدادهای کامپایل کد نیز ممکن است صادر شوند.

یادداشت: توابع درون‌ساخت globals() و locals() فضای نام سراسری و محلی جاری را برمی‌گردانند که ممکن است برای ارسال به‌عنوان آرگومان دوم و سوم exec() مفید باشند.

یادداشت: locals پیش‌فرض همان‌طور که برای تابع locals() در پایین شرح داده شده رفتار می‌کند. اگر پس از بازگشت exec() نیاز به دیدن اثر کد روی locals دارید، یک دیکشنری locals صریح بدهید.

تغییر در نسخهٔ ۳٫۱۱: پارامتر closure افزوده شد.

تغییر در نسخهٔ ۳٫۱۳: آرگومان‌های globals و locals اکنون می‌توانند به‌صورت کلیدواژه‌ای داده شوند. معناشناسی فضای نام محلی پیش‌فرض همان‌طور که برای درون‌ساخت locals() شرح داده شده تنظیم شد.

تغییر در نسخهٔ ۳٫۱۵: globals اکنون می‌تواند frozendict باشد.

filter(function, iterable, /)

از آن عناصر iterable که function برایشان درست است یک تکرارگر می‌سازد. iterable می‌تواند یک دنباله، یک ظرف پشتیبان تکرار، یا یک تکرارگر باشد. اگر function برابر None باشد، تابع همانی فرض می‌شود، یعنی همهٔ عناصر iterable که نادرست‌اند حذف می‌شوند.

توجه کنید که filter(function, iterable) معادل عبارت مولد (item for item in iterable if function(item)) است اگر function برابر None نباشد و (item for item in iterable if item) اگر function برابر None باشد.

برای تابع مکمل که عناصر iterable را که function برایشان نادرست است برمی‌گرداند، itertools.filterfalse() را ببینید.

class float(number=0.0, /)

class float(string, /)

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

مثال‌ها:

>>> float('+1.23')
1.23
>>> float('   -12345\n')
-12345.0
>>> float('1e-003')
0.001
>>> float('+1E6')
1000000.0
>>> float('-Infinity')
-inf

اگر آرگومان رشته باشد، باید حاوی یک عدد اعشاری باشد، که به‌طور اختیاری با علامت شروع شده و به‌طور اختیاری در فاصله‌های خالی جاسازی شده است. علامت اختیاری می‌تواند '+' یا '-' باشد؛ علامت '+' بر مقدار تولیدشده اثری ندارد. آرگومان می‌تواند رشته‌ای نماینده NaN (not-a-number) یا بی‌نهایت مثبت یا منفی هم باشد. دقیق‌تر، ورودی، پس از حذف نویسه‌های فاصلهٔ خالی ابتدا و انتها، باید با قاعدهٔ تولید floatvalue در گرامر زیر مطابقت داشته باشد:

sign: "+" | "-"
infinity: "Infinity" | "inf"
nan: "nan"
digit: <a Unicode decimal digit, i.e. characters in Unicode general category Nd>
digitpart: digit (["_"] digit)*
number: [digitpart] "." digitpart | digitpart ["."]
exponent: ("e" | "E") [sign] digitpart
floatnumber: number [exponent]
absfloatvalue: floatnumber | infinity | nan
floatvalue: [sign] absfloatvalue

حروف بزرگ و کوچک اهمیتی ندارند؛ بنابراین مثلاً «inf»، «Inf»، «INFINITY» و «iNfINity» همگی املاهای پذیرفته‌شده برای بی‌نهایت مثبت هستند.

در غیر این صورت، اگر آرگومان عدد صحیح یا عدد ممیز شناور باشد، عدد ممیز شناوری با همان مقدار (در حد دقت ممیز شناور پایتون) برگردانده می‌شود. اگر آرگومان خارج از بازهٔ float پایتون باشد، OverflowError پرتاب می‌شود.

برای یک شیء عمومی پایتون x، float(x) به x.__float__() واگذار می‌کند. اگر __float__() تعریف نشده باشد، به __index__() برمی‌گردد.

همچنین float.from_number() را ببینید که فقط یک آرگومان عددی می‌پذیرد.

اگر آرگومانی داده نشود، 0.0 برگردانده می‌شود.

نوع float در انواع عددی شرح داده شده است.

تغییر در نسخهٔ ۳٫۶: گروه‌بندی ارقام با زیرخط، مانند literalهای کد، مجاز است.

تغییر در نسخهٔ ۳٫۷: پارامتر اکنون فقط‌موضعی است.

تغییر در نسخهٔ ۳٫۸: اگر __float__() تعریف نشده باشد به __index__() برمی‌گردد.

format(value, format_spec="", /)

value را به یک نمایش «قالب‌بندی‌شده» تبدیل می‌کند، آن‌طور که format_spec کنترل می‌کند. تفسیر format_spec به نوع آرگومان value بستگی دارد؛ با این حال یک نحو قالب‌بندی استاندارد وجود دارد که بیشتر نوع‌های درون‌ساخت به کار می‌برند: مینی‌زبان مشخصات قالب.

format_spec پیش‌فرض یک رشتهٔ خالی است که معمولاً همان اثر فراخوانی str(value) را دارد.

فراخوانی format(value, format_spec) به type(value).__format__(value, format_spec) ترجمه می‌شود که هنگام جست‌وجوی متد __format__() مقدار، دیکشنری نمونه را دور می‌زند. اگر جست‌وجوی متد به object برسد و format_spec غیرخالی باشد، یا اگر format_spec یا مقدار بازگشتی رشته نباشد، استثنای TypeError پرتاب می‌شود.

تغییر در نسخهٔ ۳٫۴: object().__format__(format_spec) اگر format_spec رشتهٔ خالی نباشد TypeError پرتاب می‌کند.

class frozendict(**kwargs)

class frozendict(mapping, /, **kwargs)

class frozendict(iterable, /, **kwargs)

یک دیکشنری منجمد (frozen) جدید می‌سازد. شیء frozendict یک کلاس درون‌ساخت است. برای مستندات این کلاس انواع نگاشت را ببینید.

برای ظرف‌های دیگر کلاس‌های درون‌ساخت dict، list، set و tuple و نیز ماژول collections را ببینید.

افزوده‌شده در نسخهٔ ۳٫۱۵.

class frozenset(iterable=(), /)

یک شیء frozenset جدید برمی‌گرداند، که به‌طور اختیاری عناصرش را از iterable می‌گیرد. frozenset یک کلاس درون‌ساخت است. برای مستندات دربارهٔ این کلاس انواع مجموعه را ببینید.

برای ظرف‌های دیگر کلاس‌های درون‌ساخت set، list، tuple و dict و نیز ماژول collections را ببینید.

getattr(object, name, /)

getattr(object, name, default, /)

مقدار ویژگی نام‌برده از object را برمی‌گرداند. name باید رشته باشد. اگر رشته نام یکی از ویژگی‌های شیء باشد، نتیجه مقدار آن ویژگی است. برای مثال getattr(x, 'foobar') معادل x.foobar است. اگر ویژگی نام‌برده وجود نداشته باشد، در صورت ارائه default برگردانده می‌شود، وگرنه AttributeError پرتاب می‌شود. name لازم نیست شناسهٔ معتبر پایتون باشد (setattr() را ببینید).

یادداشت: چون تغییر نام خصوصی (private name mangling) در زمان کامپایل رخ می‌دهد، برای بازیابی ویژگی خصوصی (ویژگی‌هایی با دو زیرخط ابتدایی) با getattr() باید نام آن را دستی تغییر دهید (mangle کنید).

globals()

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

hasattr(object, name, /)

آرگومان‌ها یک شیء و یک رشته‌اند. اگر رشته نام یکی از ویژگی‌های شیء باشد نتیجه True است، وگرنه False. (این با فراخوانی getattr(object, name) و بررسی اینکه آیا AttributeError پرتاب می‌کند یا نه پیاده‌سازی شده است.)

hash(object, /)

مقدار هش شیء را (در صورت داشتن) برمی‌گرداند. مقادیر هش اعداد صحیح‌اند. برای مقایسهٔ سریع کلیدهای دیکشنری هنگام جست‌وجو در دیکشنری به کار می‌روند. مقادیر عددی که برابر مقایسه می‌شوند مقدار هش یکسانی دارند (حتی اگر از نوع‌های متفاوت باشند، مانند ۱ و ۱٫۰).

یادداشت: برای اشیایی با متدهای __hash__() سفارشی، توجه کنید که hash() مقدار بازگشتی را بر اساس پهنای بیت ماشین میزبان کوتاه می‌کند.

help()

help(request)

سامانهٔ راهنمای درون‌ساخت را فراخوانی می‌کند. (این تابع برای استفادهٔ تعاملی در نظر گرفته شده است.) اگر آرگومانی داده نشود، سامانهٔ راهنمای تعاملی روی کنسول مفسر شروع می‌شود. اگر آرگومان رشته باشد، رشته به‌عنوان نام یک ماژول، تابع، کلاس، متد، کلیدواژه یا موضوع مستندات جست‌وجو می‌شود و یک صفحهٔ راهنما روی کنسول چاپ می‌شود. اگر آرگومان هر نوع شیء دیگری باشد، یک صفحهٔ راهنما دربارهٔ شیء تولید می‌شود.

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

این تابع توسط ماژول site به فضای نام درون‌ساخت افزوده می‌شود.

تغییر در نسخهٔ ۳٫۴: تغییرات در pydoc و inspect یعنی امضاهای گزارش‌شده برای callableها اکنون جامع‌تر و سازگارترند.

hex(integer, /)

یک عدد صحیح را به رشتهٔ هگزادسیمال با حروف کوچک و پیشوند «0x» تبدیل می‌کند. اگر integer شیء int پایتون نباشد، باید متد __index__() را تعریف کند که یک عدد صحیح برگرداند. چند مثال:

>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'

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

>>> '%#x' % 255, '%x' % 255, '%X' % 255
('0xff', 'ff', 'FF')
>>> format(255, '#x'), format(255, 'x'), format(255, 'X')
('0xff', 'ff', 'FF')
>>> f'{255:#x}', f'{255:x}', f'{255:X}'
('0xff', 'ff', 'FF')

برای اطلاعات بیشتر format() را ببینید.

همچنین int() را برای تبدیل رشتهٔ هگزادسیمال به عدد صحیح با مبنای ۱۶ ببینید.

یادداشت: برای به دست آوردن نمایش رشته‌ای هگزادسیمال یک float، از متد float.hex() استفاده کنید.

id(object, /)

«هویت (identity)» یک شیء را برمی‌گرداند. این یک عدد صحیح است که تضمین می‌شود در طول عمر آن شیء یکتا و ثابت باشد. دو شیء با دوره‌های عمر غیرهم‌پوشان ممکن است مقدار id() یکسانی داشته باشند.

جزئیات پیاده‌سازی (CPython): این آدرس شیء در حافظه است.

رویداد ممیزی: builtins.id با آرگومان id.

input()

input(prompt, /)

اگر آرگومان prompt وجود داشته باشد، بدون خط جدید انتهایی در خروجی استاندارد نوشته می‌شود. سپس تابع یک خط از ورودی می‌خواند، آن را به رشته تبدیل می‌کند (خط جدید انتهایی را حذف می‌کند) و آن را برمی‌گرداند. وقتی EOF خوانده شود، EOFError پرتاب می‌شود. مثال:

>>> s = input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"

اگر ماژول readline بارگذاری شده باشد، input() از آن برای فراهم کردن ویرایش پیشرفتهٔ خط و قابلیت‌های تاریخچه استفاده می‌کند.

رویدادهای ممیزی: builtins.input با آرگومان prompt پیش از خواندن ورودی؛ و builtins.input/result با نتیجه پس از خواندن موفق ورودی.

class int(number=0, /)

class int(string, /, base=10)

شیء عدد صحیحی را برمی‌گرداند که از یک عدد یا رشته ساخته شده است، یا اگر آرگومانی داده نشود 0 برمی‌گرداند.

مثال‌ها:

>>> int(123.45)
123
>>> int('123')
123
>>> int('   -12_345\n')
-12345
>>> int('FACE', 16)
64206
>>> int('0xface', 0)
64206
>>> int('01110011', base=2)
115

اگر آرگومان __int__() را تعریف کند، int(x) مقدار x.__int__() را برمی‌گرداند. اگر __index__() را تعریف کند، x.__index__() را برمی‌گرداند. برای اعداد ممیز شناور، به سمت صفر کوتاه می‌کند.

اگر آرگومان عدد نباشد یا base داده شده باشد، آنگاه باید نمونه‌ای از str، bytes یا bytearray باشد که یک عدد صحیح در مبنای base را نشان می‌دهد. به‌طور اختیاری رشته می‌تواند با + یا - (بدون فاصله در میان) شروع شود، صفرهای ابتدایی داشته باشد، با فاصله‌های خالی احاطه شده باشد، و زیرخط‌های تکی بین ارقامش پراکنده باشد.

رشتهٔ عدد صحیح در مبنای n شامل ارقامی است که هر کدام مقداری از ۰ تا n-1 را نشان می‌دهند. مقادیر ۰ تا ۹ را می‌توان با هر رقم اعشاری یونیکد نشان داد. مقادیر ۱۰ تا ۳۵ را می‌توان با a تا z (یا A تا Z) نشان داد. base پیش‌فرض ۱۰ است. مبناهای مجاز ۰ و ۲ تا ۳۶ هستند. رشته‌های مبنای ۲، ۸ و ۱۶ را می‌توان، مانند literalهای عدد صحیح در کد، به‌طور اختیاری با 0b/0B، 0o/0O یا 0x/0X پیشوند داد. برای مبنای ۰، رشته به شیوه‌ای مشابه literal عدد صحیح در کد تفسیر می‌شود، به این معنا که مبنای واقعی ۲، ۸، ۱۰ یا ۱۶ است که با پیشوند تعیین می‌شود. مبنای ۰ همچنین صفرهای ابتدایی را ممنوع می‌کند: int('010', 0) معتبر نیست، در حالی که int('010') و int('010', 8) معتبرند.

نوع عدد صحیح در انواع عددی شرح داده شده است.

تغییر در نسخهٔ ۳٫۴: اگر base نمونه‌ای از int نباشد و شیء base متد __index__() داشته باشد، آن متد برای گرفتن عدد صحیح مبنا فراخوانی می‌شود. نسخه‌های پیشین به‌جای __index__() از __int__() استفاده می‌کردند.

تغییر در نسخهٔ ۳٫۶: گروه‌بندی ارقام با زیرخط، مانند literalهای کد، مجاز است.

تغییر در نسخهٔ ۳٫۷: پارامتر اول اکنون فقط‌موضعی است.

تغییر در نسخهٔ ۳٫۸: اگر __int__() تعریف نشده باشد به __index__() برمی‌گردد.

تغییر در نسخهٔ ۳٫۱۱: ورودی‌های رشته‌ای int و نمایش‌های رشته‌ای آن می‌توانند محدود شوند تا از حملات منع سرویس جلوگیری شود. هنگامی که حد در تبدیل رشته به int یا تبدیل int به رشته فراتر رود، ValueError پرتاب می‌شود. مستندات محدودیت طول تبدیل رشتهٔ عدد صحیح را ببینید.

تغییر در نسخهٔ ۳٫۱۴: int() دیگر به متد __trunc__() واگذار نمی‌کند.

isinstance(object, classinfo, /)

اگر آرگومان object نمونه‌ای از آرگومان classinfo یا زیرکلاسی (مستقیم، غیرمستقیم یا مجازی) از آن باشد True برمی‌گرداند. اگر object شیئی از نوع داده‌شده نباشد، تابع همیشه False برمی‌گرداند. اگر classinfo تاپلی از اشیای نوع (یا، به‌طور بازگشتی، تاپل‌های دیگر مشابه) یا یک union نوع از چند نوع باشد، اگر object نمونه‌ای از هر یک از نوع‌ها باشد True برمی‌گرداند. اگر classinfo نوع یا تاپلی از نوع‌ها و چنین تاپل‌هایی نباشد، استثنای TypeError پرتاب می‌شود. ممکن است برای نوع نامعتبر TypeError پرتاب نشود اگر بررسی پیشین موفق شده باشد.

تغییر در نسخهٔ ۳٫۱۰: classinfo می‌تواند union نوع باشد.

issubclass(cls, classinfo, /)

اگر cls زیرکلاس (مستقیم، غیرمستقیم یا مجازی) از classinfo باشد True برمی‌گرداند. هر کلاس زیرکلاس خودش تلقی می‌شود. classinfo می‌تواند تاپلی از اشیای کلاس (یا، به‌طور بازگشتی، تاپل‌های دیگر مشابه) یا یک union نوع باشد؛ در این حالت اگر cls زیرکلاس هر ورودی در classinfo باشد True برمی‌گرداند. در هر حالت دیگر، استثنای TypeError پرتاب می‌شود.

تغییر در نسخهٔ ۳٫۱۰: classinfo می‌تواند union نوع باشد.

iter(iterable, /)

iter(callable, /, stop_value, *, stop_exception=StopIteration)

iter(callable, /, *, stop_exception)

یک شیء تکرارگر برمی‌گرداند. آرگومان اول بسته به وجود آرگومان‌های دیگر بسیار متفاوت تفسیر می‌شود. بدون آرگومان‌های دیگر، آرگومان تنها باید شیء مجموعه‌ای باشد که پروتکل تکرارپذیر (iterable) (متد __iter__()) را پشتیبانی می‌کند، یا باید پروتکل دنباله (متد __getitem__() با آرگومان‌های عدد صحیح که از 0 شروع می‌شوند) را پشتیبانی کند. اگر هیچ‌کدام از این پروتکل‌ها را پشتیبانی نکند، TypeError پرتاب می‌شود.

اگر stop_value یا stop_exception داده شود، آرگومان اول باید یک شیء قابل‌فراخوانی باشد. تکرارگری که در این حالت ساخته می‌شود، برای هر فراخوانی متد __next__() خود، callable را بدون آرگومان فراخوانی می‌کند؛ اگر مقدار بازگشتی با stop_value برابر باشد، یا اگر فراخوانی استثنایی هماهنگ با stop_exception پرتاب کند، StopIteration پرتاب می‌شود، وگرنه مقدار برگردانده می‌شود.

stop_exception یک کلاس استثنا یا یک تاپل از کلاس‌های استثناست. اگر stop_value مشخص نشده باشد، تکرار فقط وقتی متوقف می‌شود که callable استثنا پرتاب کند. اگر callable استثنای StopIteration را که با stop_exception هماهنگ نیست پرتاب کند، به RuntimeError تبدیل می‌شود، همان‌طور که برای مولدها (به PEP 479 نگاه کنید).

همچنین نوع‌های تکرارگر را ببینید.

یک کاربرد مفید شکل دوم iter() ساختن یک بلوک‌خوان (block-reader) است. برای مثال، خواندن بلوک‌های با پهنای ثابت از یک فایل پایگاه دادهٔ دودویی تا رسیدن به پایان فایل:

from functools import partial
with open('mydata.db', 'rb') as f:
    for block in iter(partial(f.read, 64), b''):
        process_block(block)

stop_exception برای callableهایی مفید است که تمام‌شدن را به‌جای برگرداندن یک مقدار ویژه، با پرتاب استثنا گزارش می‌کنند. برای مثال، تخلیهٔ یک صف:

import queue
for item in iter(input_queue.get_nowait, stop_exception=queue.Empty):
    process_item(item)

تغییر در نسخهٔ ۳٫۱۶: پارامتر stop_exception افزوده شد و دادن stop_value به‌صورت کلیدواژه‌ای مجاز شد.

len(object, /)

طول (تعداد عناصر) یک شیء را برمی‌گرداند. آرگومان می‌تواند یک دنباله (مانند رشته، bytes، تاپل، فهرست یا range) یا یک مجموعه (مانند دیکشنری، set یا frozenset) باشد.

جزئیات پیاده‌سازی (CPython): len برای طول‌های بزرگ‌تر از sys.maxsize، مانند range(2 ** 100)، OverflowError پرتاب می‌کند.

class list(iterable=(), /)

list به‌جای اینکه تابع باشد، در واقع یک نوع دنبالهٔ تغییرپذیر است، همان‌طور که در فهرست‌ها و نوع‌های دنباله مستند شده است.

locals()

یک شیء نگاشت برمی‌گرداند که جدول نمادهای محلی جاری را نشان می‌دهد، با نام متغیرها به‌عنوان کلیدها و ارجاع‌های متصل‌شدهٔ فعلی آن‌ها به‌عنوان مقادیر.

در دامنهٔ ماژول، و نیز هنگام استفاده از exec() یا eval() با یک فضای نام واحد، این تابع همان فضای نام globals() را برمی‌گرداند.

در دامنهٔ کلاس، فضای نامی را برمی‌گرداند که به سازندهٔ فراکلاس (metaclass) داده خواهد شد.

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

در همهٔ موارد بالا، هر فراخوانی locals() در یک فریم اجرای مشخص همان شیء نگاشت یکسان را برمی‌گرداند. تغییراتی که از طریق شیء نگاشت برگردانده‌شده از locals() اعمال شوند، به‌صورت متغیرهای محلی انتساب‌شده، دوباره‌انتساب‌شده یا حذف‌شده قابل‌مشاهده خواهند بود، و انتساب، دوباره‌انتساب یا حذف متغیرهای محلی بلافاصله بر محتوای نگاشت برگردانده‌شده اثر می‌گذارد.

در یک دامنهٔ بهینه‌شده (optimized scope) (از جمله توابع، مولدها و coroutineها)، هر فراخوانی locals() در عوض یک دیکشنری تازه شامل اتصال‌های فعلی متغیرهای محلی تابع و ارجاع‌های cell غیرمحلی برمی‌گرداند. در این حالت، تغییرات اتصال نام که از طریق دیکشنری برگردانده‌شده انجام شوند در متغیرهای محلی یا ارجاع‌های cell غیرمحلی متناظر نوشته نمی‌شوند، و انتساب، دوباره‌انتساب یا حذف متغیرهای محلی و ارجاع‌های cell غیرمحلی بر محتوای دیکشنری‌هایی که پیش‌تر برگردانده شده‌اند اثر نمی‌گذارد.

فراخوانی locals() به‌عنوان بخشی از یک comprehension در تابع، مولد یا coroutine معادل فراخوانی آن در دامنهٔ حاوی است، با این تفاوت که متغیرهای تکرار مقداردهی‌شدهٔ comprehension هم شامل می‌شوند. در دامنه‌های دیگر، طوری رفتار می‌کند که گویی comprehension به‌صورت تابع تودرتو اجرا می‌شود.

فراخوانی locals() به‌عنوان بخشی از یک عبارت مولد معادل فراخوانی آن در یک تابع مولد تودرتوست.

تغییر در نسخهٔ ۳٫۱۲: رفتار locals() در comprehension همان‌طور که در PEP 709 شرح داده شده به‌روز شد.

تغییر در نسخهٔ ۳٫۱۳: به‌عنوان بخشی از PEP 667، معناشناسی تغییر دادن اشیای نگاشت برگردانده‌شده از این تابع اکنون تعریف شده است. رفتار در دامنه‌های بهینه‌شده اکنون همان‌طور است که در بالا شرح داده شد. جدا از تعریف‌شدن، رفتار در دامنه‌های دیگر نسبت به نسخه‌های پیشین بدون تغییر ماند.

map(function, iterable, /, *iterables, strict=False)

تکرارگری برمی‌گرداند که function را روی هر عنصر iterable اعمال می‌کند و نتایج را تولید می‌کند. اگر آرگومان‌های iterables اضافی داده شوند، function باید به همان تعداد آرگومان بگیرد و روی عناصر همهٔ تکرارپذیرها به‌طور موازی اعمال می‌شود. با چند تکرارپذیر، تکرارگر وقتی کوتاه‌ترین تکرارپذیر تمام شود متوقف می‌شود. اگر strict برابر True باشد و یکی از تکرارپذیرها پیش از بقیه تمام شود، ValueError پرتاب می‌شود. برای مواردی که ورودی‌های تابع از قبل در تاپل‌های آرگومان مرتب شده‌اند، itertools.starmap() را ببینید.

تغییر در نسخهٔ ۳٫۱۴: پارامتر strict افزوده شد.

max(iterable, /, *, key=None)

max(iterable, /, *, default, key=None)

max(arg1, arg2, /, *args, key=None)

بزرگ‌ترین عنصر در یک تکرارپذیر یا بزرگ‌ترین دو یا چند آرگومان را برمی‌گرداند.

اگر یک آرگومان موضعی داده شود، باید یک تکرارپذیر باشد. بزرگ‌ترین عنصر تکرارپذیر برگردانده می‌شود. اگر دو یا چند آرگومان موضعی داده شود، بزرگ‌ترین آرگومان‌های موضعی برگردانده می‌شود.

دو آرگومان اختیاری فقط‌کلیدواژه‌ای وجود دارد. آرگومان key یک تابع ترتیب‌دهندهٔ تک‌آرگومانی مانند آنچه برای list.sort() به کار می‌رود مشخص می‌کند. آرگومان default شیئی را مشخص می‌کند که در صورت خالی بودن تکرارپذیر داده‌شده برگردانده شود. اگر تکرارپذیر خالی باشد و default داده نشده باشد، ValueError پرتاب می‌شود.

اگر چند عنصر بیشینه باشند، تابع اولین مورد مواجه‌شده را برمی‌گرداند. این با ابزارهای دیگر حافظ پایداری مرتب‌سازی مانند sorted(iterable, key=keyfunc, reverse=True)[0] و heapq.nlargest(1, iterable, key=keyfunc) سازگار است.

تغییر در نسخهٔ ۳٫۴: پارامتر فقط‌کلیدواژه‌ای default افزوده شد.

تغییر در نسخهٔ ۳٫۸: key می‌تواند None باشد.

class memoryview(object)

یک شیء «نمای حافظه (memory view)» از آرگومان داده‌شده برمی‌گرداند. برای اطلاعات بیشتر نمای حافظه را ببینید.

min(iterable, /, *, key=None)

min(iterable, /, *, default, key=None)

min(arg1, arg2, /, *args, key=None)

کوچک‌ترین عنصر در یک تکرارپذیر یا کوچک‌ترین دو یا چند آرگومان را برمی‌گرداند.

اگر یک آرگومان موضعی داده شود، باید یک تکرارپذیر باشد. کوچک‌ترین عنصر تکرارپذیر برگردانده می‌شود. اگر دو یا چند آرگومان موضعی داده شود، کوچک‌ترین آرگومان‌های موضعی برگردانده می‌شود.

دو آرگومان اختیاری فقط‌کلیدواژه‌ای وجود دارد. آرگومان key یک تابع ترتیب‌دهندهٔ تک‌آرگومانی مانند آنچه برای list.sort() به کار می‌رود مشخص می‌کند. آرگومان default شیئی را مشخص می‌کند که در صورت خالی بودن تکرارپذیر داده‌شده برگردانده شود. اگر تکرارپذیر خالی باشد و default داده نشده باشد، ValueError پرتاب می‌شود.

اگر چند عنصر کمینه باشند، تابع اولین مورد مواجه‌شده را برمی‌گرداند. این با ابزارهای دیگر حافظ پایداری مرتب‌سازی مانند sorted(iterable, key=keyfunc)[0] و heapq.nsmallest(1, iterable, key=keyfunc) سازگار است.

تغییر در نسخهٔ ۳٫۴: پارامتر فقط‌کلیدواژه‌ای default افزوده شد.

تغییر در نسخهٔ ۳٫۸: key می‌تواند None باشد.

next(iterator, /)

next(iterator, default, /)

عنصر بعدی را از تکرارگر با فراخوانی متد __next__() آن بازیابی می‌کند. اگر default داده شده باشد، در صورت تمام‌شدن تکرارگر برگردانده می‌شود، وگرنه StopIteration پرتاب می‌شود.

class object()

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

یادداشت: نمونه‌های object ویژگی __dict__ ندارند، بنابراین نمی‌توانید ویژگی دلخواه به نمونه‌ای از object انتساب دهید.

oct(integer, /)

یک عدد صحیح را به رشتهٔ هشتایی (octal) با پیشوند «0o» تبدیل می‌کند. نتیجه یک عبارت معتبر پایتون است. اگر integer شیء int پایتون نباشد، باید متد __index__() را تعریف کند که یک عدد صحیح برگرداند. برای مثال:

>>> oct(8)
'0o10'
>>> oct(-56)
'-0o70'

اگر می‌خواهید عدد صحیح را به رشتهٔ هشتایی با پیشوند «0o» یا بدون آن تبدیل کنید، می‌توانید از روش‌های زیر استفاده کنید.

>>> '%#o' % 10, '%o' % 10
('0o12', '12')
>>> format(10, '#o'), format(10, 'o')
('0o12', '12')
>>> f'{10:#o}', f'{10:o}'
('0o12', '12')

برای اطلاعات بیشتر format() را ببینید.

پانویس (برای exec)

۱. توجه کنید که تجزیه‌گر فقط قرارداد پایان خط به سبک یونیکس را می‌پذیرد. اگر کد را از فایل می‌خوانید، حتماً از حالت تبدیل خط جدید (newline conversion) استفاده کنید تا خط‌های جدید به سبک ویندوز یا مک تبدیل شوند.

open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

file را باز می‌کند و یک شیء فایل متناظر برمی‌گرداند. اگر فایل باز نشود، OSError پرتاب می‌شود. برای مثال‌های بیشتر از نحوهٔ استفاده از این تابع خواندن و نوشتن فایل‌ها را ببینید.

file یک شیء مسیرمانند (path-like object) است که نام مسیر (مطلق یا نسبت به پوشهٔ کاری جاری) فایلی را که باید باز شود، یا یک توصیف‌گر فایل (file descriptor) صحیح از فایلی که باید پوشانده شود، مشخص می‌کند. (اگر توصیف‌گر فایل داده شود، هنگام بسته شدن شیء I/O برگردانده‌شده بسته می‌شود، مگر اینکه closefd روی False تنظیم شده باشد.)

mode یک رشتهٔ اختیاری است که حالتی را که فایل در آن باز می‌شود مشخص می‌کند. پیش‌فرض آن 'r' است که یعنی باز کردن برای خواندن در حالت متنی. مقادیر رایج دیگر 'w' برای نوشتن (کوتاه کردن فایل در صورت وجود)، 'x' برای ساخت انحصاری و 'a' برای افزودن (append) هستند (که در برخی سیستم‌های یونیکس به این معناست که همهٔ نوشتن‌ها بدون توجه به موقعیت seek جاری به انتهای فایل اضافه می‌شوند). در حالت متنی، اگر encoding مشخص نشده باشد، به‌طور پیش‌فرض از UTF-8 استفاده می‌شود؛ اگر حالت UTF-8 پایتون غیرفعال باشد، locale.getencoding() برای گرفتن رمزگذاری locale جاری فراخوانی می‌شود. (برای خواندن و نوشتن بایت‌های خام از حالت دودویی استفاده کنید و encoding را مشخص نکنید.) حالت‌های موجود عبارت‌اند از:

حالت پیش‌فرض 'r' است (باز کردن برای خواندن متن، مترادف 'rt'). حالت‌های 'w+' و 'w+b' فایل را باز و کوتاه می‌کنند. حالت‌های 'r+' و 'r+b' فایل را بدون کوتاه کردن باز می‌کنند.

همان‌طور که در نمای کلی I/O ذکر شد، پایتون بین I/O دودویی و متنی تمایز می‌گذارد. فایل‌هایی که در حالت دودویی باز می‌شوند (شامل 'b' در آرگومان mode) محتوا را به‌صورت اشیای bytes بدون هیچ رمزگشایی برمی‌گردانند. در حالت متنی (پیش‌فرض، یا وقتی 't' در آرگومان mode باشد)، محتوای فایل به‌صورت str برگردانده می‌شود و بایت‌ها ابتدا با رمزگذاری پیش‌فرض یا، در صورت داده شدن، encoding مشخص‌شده رمزگشایی شده‌اند.

یادداشت: پایتون به برداشت سیستم‌عامل زیربنایی از فایل‌های متنی وابسته نیست؛ همهٔ پردازش توسط خود پایتون انجام می‌شود و بنابراین مستقل از پلتفرم است.

buffering یک عدد صحیح اختیاری است که برای تنظیم سیاست بافر به کار می‌رود. 0 را بدهید تا بافر خاموش شود (فقط در حالت دودویی مجاز است)، 1 برای انتخاب بافر خط‌به‌خط (فقط هنگام نوشتن در حالت متنی قابل‌استفاده است)، و عدد صحیح بزرگ‌تر از ۱ برای نشان دادن اندازهٔ بافر تکه‌ای با اندازهٔ ثابت بر حسب بایت. توجه کنید که تعیین اندازهٔ بافر به این روش برای I/O بافردار دودویی اعمال می‌شود، اما TextIOWrapper (یعنی فایل‌هایی که با mode='r+' باز شده‌اند) بافر دیگری خواهد داشت. برای خاموش کردن بافر در TextIOWrapper از پرچم write_through در io.TextIOWrapper.reconfigure() استفاده کنید. وقتی آرگومان buffering داده نشود، سیاست پیش‌فرض بافر به این صورت کار می‌کند:

• فایل‌های دودویی در تکه‌هایی با اندازهٔ ثابت بافر می‌شوند؛ اندازهٔ بافر وقتی اندازهٔ بلوک دستگاه در دسترس باشد max(min(blocksize, 8 MiB), DEFAULT_BUFFER_SIZE) است. در بیشتر سیستم‌ها بافر معمولاً ۱۲۸ کیلوبایت طول دارد.
• فایل‌های متنی «تعاملی» (فایل‌هایی که isatty() برایشان True برمی‌گرداند) از بافر خط‌به‌خط استفاده می‌کنند. سایر فایل‌های متنی از سیاستی که در بالا برای فایل‌های دودویی شرح داده شد پیروی می‌کنند.

encoding نام رمزگذاری است که برای رمزگشایی یا رمزگذاری فایل به کار می‌رود. این فقط باید در حالت متنی استفاده شود. رمزگذاری پیش‌فرض UTF-8 است؛ اگر حالت UTF-8 پایتون غیرفعال باشد، پیش‌فرض وابسته به پلتفرم است (هر چه locale.getencoding() برگرداند). هر رمزگذاری متنی که پایتون پشتیبانی می‌کند قابل‌استفاده است، و encoding="locale" رمزگذاری locale جاری را صریحاً مشخص می‌کند. برای فهرست رمزگذاری‌های پشتیبانی‌شده ماژول codecs را ببینید.

errors یک رشتهٔ اختیاری است که مشخص می‌کند خطاهای رمزگذاری و رمزگشایی چگونه مدیریت شوند — این را در حالت دودویی نمی‌توان به کار برد. تعدادی مدیر خطای استاندارد در دسترس است، هرچند هر نام مدیریت خطایی که با codecs.register_error() ثبت شده باشد نیز معتبر است. نام‌های استاندارد را در مدیران خطا می‌توانید بیابید.

newline تعیین می‌کند نویسه‌های خط جدید از جریان چگونه تجزیه شوند. می‌تواند None، ''، '\n'، '\r' و '\r\n' باشد. به این صورت کار می‌کند:

• هنگام خواندن ورودی از جریان، اگر newline برابر None باشد، حالت خط جدید جهانی (universal newlines) فعال می‌شود. خطوط در ورودی می‌توانند به '\n'، '\r' یا '\r\n' ختم شوند و پیش از بازگرداندن به فراخواننده به '\n' ترجمه می‌شوند. اگر '' باشد، حالت خط جدید جهانی فعال می‌شود، اما پایان خطوط بدون ترجمه به فراخواننده برگردانده می‌شود. اگر هر یک از مقادیر قانونی دیگر باشد، خطوط ورودی فقط با رشتهٔ داده‌شده خاتمه می‌یابند و پایان خط بدون ترجمه به فراخواننده برگردانده می‌شود.
• هنگام نوشتن خروجی به جریان، اگر newline برابر None باشد، هر نویسهٔ '\n' نوشته‌شده به جداکنندهٔ خط پیش‌فرض سیستم، os.linesep، ترجمه می‌شود. اگر newline برابر '' یا '\n' باشد، هیچ ترجمه‌ای انجام نمی‌شود. اگر newline هر یک از مقادیر قانونی دیگر باشد، هر نویسهٔ '\n' نوشته‌شده به رشتهٔ داده‌شده ترجمه می‌شود.

اگر closefd برابر False باشد و به‌جای نام فایل یک توصیف‌گر فایل داده شده باشد، توصیف‌گر فایل زیربنایی هنگام بسته شدن فایل باز نگه داشته می‌شود. اگر نام فایل داده شود closefd باید True (پیش‌فرض) باشد؛ در غیر این صورت خطا پرتاب می‌شود.

می‌توان با دادن یک callable به‌عنوان opener از یک بازکنندهٔ سفارشی استفاده کرد. توصیف‌گر فایل زیربنایی شیء فایل سپس با فراخوانی opener با (file، flags) به دست می‌آید. opener باید یک توصیف‌گر فایل باز برگرداند (دادن os.open به‌عنوان opener عملکردی مشابه دادن None دارد).

فایل تازه ساخته‌شده غیرقابل‌ارث‌بری (non-inheritable) است.

مثال زیر از پارامتر dir_fd تابع os.open() برای باز کردن فایلی نسبت به یک پوشهٔ مشخص استفاده می‌کند:

>>> import os
>>> dir_fd = os.open('somedir', os.O_RDONLY)
>>> def opener(path, flags):
...     return os.open(path, flags, dir_fd=dir_fd)
...
>>> with open('spamspam.txt', 'w', opener=opener) as f:
...     print('This will be written to somedir/spamspam.txt', file=f)
...
>>> os.close(dir_fd)  # don't leak a file descriptor

نوع شیء فایل برگردانده‌شده توسط تابع open() به حالت بستگی دارد. وقتی open() برای باز کردن فایل در حالت متنی ('w'، 'r'، 'wt'، 'rt' و غیره) به کار رود، زیرکلاسی از io.TextIOBase (به‌طور مشخص io.TextIOWrapper) برمی‌گرداند. وقتی برای باز کردن فایل در حالت دودویی با بافر به کار رود، کلاس برگردانده‌شده زیرکلاسی از io.BufferedIOBase است. کلاس دقیق متفاوت است: در حالت خواندن دودویی io.BufferedReader برمی‌گرداند؛ در حالت‌های نوشتن دودویی و افزودن دودویی io.BufferedWriter برمی‌گرداند، و در حالت خواندن/نوشتن io.BufferedRandom برمی‌گرداند. وقتی بافر غیرفعال باشد، جریان خام، زیرکلاسی از io.RawIOBase، یعنی io.FileIO برگردانده می‌شود.

همچنین ماژول‌های مدیریت فایل مانند fileinput، io (که open() در آن اعلان شده)، os، os.path، tempfile و shutil را ببینید.

رویداد ممیزی: open با آرگومان‌های path، mode، flags. آرگومان‌های mode و flags ممکن است از فراخوانی اصلی تغییر یافته یا استنباط شده باشند.

تغییر در نسخهٔ ۳٫۳: پارامتر opener افزوده شد. حالت 'x' افزوده شد. IOError قبلاً پرتاب می‌شد، اکنون نام مستعاری برای OSError است. اگر فایلی که در حالت ساخت انحصاری ('x') باز می‌شود از قبل وجود داشته باشد، اکنون FileExistsError پرتاب می‌شود.

تغییر در نسخهٔ ۳٫۴: فایل اکنون غیرقابل‌ارث‌بری است.

تغییر در نسخهٔ ۳٫۵: اگر فراخوانی سیستمی قطع شود و مدیر سیگنال استثنا پرتاب نکند، تابع اکنون به‌جای پرتاب استثنای InterruptedError فراخوانی سیستمی را دوباره تلاش می‌کند (برای دلیل آن PEP 475 را ببینید). مدیر خطای 'namereplace' افزوده شد.

تغییر در نسخهٔ ۳٫۶: پشتیبانی از پذیرش اشیای پیاده‌ساز os.PathLike افزوده شد. در ویندوز، باز کردن بافر کنسول ممکن است زیرکلاسی از io.RawIOBase غیر از io.FileIO برگرداند.

تغییر در نسخهٔ ۳٫۱۱: حالت 'U' حذف شد.

تغییر در نسخهٔ ۳٫۱۵: UTF-8 اکنون به‌جای رمزگذاری locale وابسته به پلتفرم، رمزگذاری پیش‌فرض است (PEP 686).

ord(character, /)

مقدار ترتیبی (ordinal) یک نویسه را برمی‌گرداند.

اگر آرگومان رشته‌ای یک‌نویسه‌ای باشد، نقطهٔ کد یونیکد آن نویسه را برمی‌گرداند. برای مثال ord('a') عدد صحیح 97 و ord('€') (علامت یورو) عدد 8364 را برمی‌گرداند. این وارون chr() است.

اگر آرگومان شیء bytes یا bytearray با طول ۱ باشد، مقدار تک‌بایت آن را برمی‌گرداند. برای مثال ord(b'a') عدد صحیح 97 را برمی‌گرداند.

pow(base, exp, mod=None)

base به توان exp را برمی‌گرداند؛ اگر mod وجود داشته باشد، base به توان exp به پیمانهٔ mod را برمی‌گرداند (کارآمدتر از pow(base, exp) % mod محاسبه می‌شود). شکل دوآرگومانی pow(base, exp) معادل استفاده از عملگر توان است: base**exp.

وقتی آرگومان‌ها از نوع‌های عددی درون‌ساخت با نوع‌های عملوند مختلط باشند، قواعد تبدیل (coercion) عملگرهای حسابی دودویی اعمال می‌شود. برای عملوندهای int، نتیجه (پس از تبدیل) نوعی همانند عملوندها دارد مگر اینکه آرگومان دوم منفی باشد؛ در آن صورت همهٔ آرگومان‌ها به float تبدیل می‌شوند و نتیجه float تحویل داده می‌شود. برای مثال pow(10, 2) مقدار 100 را برمی‌گرداند، اما pow(10, -2) مقدار 0.01 را. برای پایهٔ منفی از نوع int یا float و توان غیرصحیح، نتیجهٔ مختلط تحویل داده می‌شود. برای مثال pow(-9, 0.5) مقداری نزدیک به 3j برمی‌گرداند. در حالی که برای پایهٔ منفی از نوع int یا float با توان صحیح، نتیجهٔ float تحویل داده می‌شود. برای مثال pow(-9, 2.0) مقدار 81.0 را برمی‌گرداند.

برای عملوندهای int یعنی base و exp، اگر mod وجود داشته باشد، mod هم باید از نوع صحیح باشد و mod باید غیرصفر باشد. اگر mod وجود داشته باشد و exp منفی باشد، base باید نسبت به mod متباین (relatively prime) باشد. در آن صورت pow(inv_base, -exp, mod) برگردانده می‌شود، که inv_base وارون base به پیمانهٔ mod است.

این مثالی از محاسبهٔ وارون ۳۸ به پیمانهٔ ۹۷ است:

>>> pow(38, -1, mod=97)
23
>>> 23 * 38 % 97 == 1
True

تغییر در نسخهٔ ۳٫۸: برای عملوندهای int، شکل سه‌آرگومانی pow اکنون اجازه می‌دهد آرگومان دوم منفی باشد، که محاسبهٔ وارون‌های پیمانه‌ای را ممکن می‌کند.

تغییر در نسخهٔ ۳٫۸: آرگومان‌های کلیدواژه‌ای مجاز شدند. پیش‌تر فقط آرگومان‌های موضعی پشتیبانی می‌شد.

print(*objects, sep=' ', end='\n', file=None, flush=False)

objects را در جریان متنی file چاپ می‌کند، با جداکنندهٔ sep بین آن‌ها و end در پایان. sep، end، file و flush، در صورت وجود، باید به‌صورت آرگومان کلیدواژه‌ای داده شوند.

همهٔ آرگومان‌های غیرکلیدواژه‌ای مانند str() به رشته تبدیل می‌شوند و در جریان نوشته می‌شوند، با جداکنندهٔ sep و با end در پایان. هم sep و هم end باید رشته باشند؛ می‌توانند None هم باشند که یعنی از مقادیر پیش‌فرض استفاده شود. اگر هیچ objects داده نشود، print() فقط end را می‌نویسد.

آرگومان file باید شیئی با متد write(string) باشد؛ اگر وجود نداشته باشد یا None باشد، از sys.stdout استفاده می‌شود. چون آرگومان‌های چاپ‌شده به رشته‌های متنی تبدیل می‌شوند، print() را نمی‌توان با اشیای فایل در حالت دودویی به کار برد. برای آن‌ها به‌جای آن از file.write(...) استفاده کنید.

بافر خروجی معمولاً توسط file تعیین می‌شود. با این حال، اگر flush درست باشد، جریان به‌اجبار تخلیه (flush) می‌شود.

تغییر در نسخهٔ ۳٫۳: آرگومان کلیدواژه‌ای flush افزوده شد.

class property(fget=None, fset=None, fdel=None, doc=None)

یک ویژگی property برمی‌گرداند.

fget تابعی برای گرفتن مقدار ویژگی است. fset تابعی برای تنظیم مقدار ویژگی است. fdel تابعی برای حذف مقدار ویژگی است. و doc یک docstring برای ویژگی می‌سازد.

یک کاربرد معمول تعریف یک ویژگی مدیریت‌شدهٔ x است:

class C:
    def __init__(self):
        self._x = None

    def getx(self):
        return self._x

    def setx(self, value):
        self._x = value

    def delx(self):
        del self._x

    x = property(getx, setx, delx, "I'm the 'x' property.")

اگر c نمونه‌ای از C باشد، c.x getter را فراخوانی می‌کند، c.x = value setter را، و del c.x deleter را.

اگر doc داده شود، docstring ویژگی property خواهد بود. در غیر این صورت property docstring مربوط به fget را (در صورت وجود) کپی می‌کند. این امکان می‌دهد با استفاده از @property به‌عنوان دکوراتور، به‌آسانی ویژگی‌های فقط‌خواندنی بسازید:

class Parrot:
    def __init__(self):
        self._voltage = 100000

    @property
    def voltage(self):
        """Get the current voltage."""
        return self._voltage

دکوراتور @property متد voltage را به «getter» برای یک ویژگی فقط‌خواندنی همنام تبدیل می‌کند و docstring مربوط به voltage را روی «Get the current voltage.» تنظیم می‌کند.

@property.getter، @property.setter، @property.deleter : یک شیء property دارای متدهای getter، setter و deleter است که به‌عنوان دکوراتور قابل‌استفاده‌اند و نسخه‌ای از property می‌سازند که تابع دسترسی متناظر آن روی تابع دکوراتورشده تنظیم شده است. این را بهتر است با یک مثال توضیح داد:

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """I'm the 'x' property."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

این کد دقیقاً معادل مثال اول است. حتماً به توابع اضافی همان نام property اصلی (در اینجا x) را بدهید.

شیء property برگردانده‌شده همچنین ویژگی‌های fget، fset و fdel را دارد که با آرگومان‌های سازنده متناظرند.

تغییر در نسخهٔ ۳٫۵: docstringهای اشیای property اکنون قابل‌نوشتن هستند.

property.__name__ : ویژگی‌ای که نام property را نگه می‌دارد. نام property را می‌توان در زمان اجرا تغییر داد.

افزوده‌شده در نسخهٔ ۳٫۱۳.

class range(stop, /)

class range(start, stop, step=1, /)

range به‌جای اینکه تابع باشد، در واقع یک نوع دنبالهٔ تغییرناپذیر است، همان‌طور که در Range و نوع‌های دنباله مستند شده است.

repr(object, /)

رشته‌ای حاوی نمایش قابل‌چاپ یک شیء را برمی‌گرداند. برای بسیاری از نوع‌ها، این تابع می‌کوشد رشته‌ای برگرداند که اگر به eval() داده شود شیئی با همان مقدار تولید کند؛ در غیر این صورت نمایش رشته‌ای است که درون علامت‌های <> قرار دارد و شامل نام نوع شیء به‌همراه اطلاعات اضافی است که اغلب شامل نام و آدرس شیء است. یک کلاس می‌تواند با تعریف متد __repr__() کنترل کند که این تابع برای نمونه‌هایش چه برمی‌گرداند. اگر sys.displayhook() در دسترس نباشد، این تابع RuntimeError پرتاب می‌کند.

این کلاس نمایشی سفارشی دارد که قابل‌ارزیابی است:

class Person:
   def __init__(self, name, age):
      self.name = name
      self.age = age

   def __repr__(self):
      return f"Person({self.name!r}, {self.age!r})"

reversed(object, /)

یک تکرارگر معکوس برمی‌گرداند. آرگومان باید شیئی باشد که متد __reversed__() دارد یا پروتکل دنباله (متد __len__() و متد __getitem__() با آرگومان‌های صحیح که از 0 شروع می‌شوند) را پشتیبانی می‌کند.

round(number, ndigits=None)

number را با دقت ndigits رقم بعد از ممیز گرد شده برمی‌گرداند. اگر ndigits حذف شده باشد یا None باشد، نزدیک‌ترین عدد صحیح به ورودی را برمی‌گرداند.

برای نوع‌های درون‌ساختی که از round() پشتیبانی می‌کنند، مقادیر به نزدیک‌ترین مضرب ۱۰ به توان منفی ndigits گرد می‌شوند؛ اگر دو مضرب به یک اندازه نزدیک باشند، گرد کردن به سمت گزینهٔ زوج انجام می‌شود (بنابراین مثلاً هم round(0.5) و هم round(-0.5) برابر 0 هستند، و round(1.5) برابر 2 است). هر مقدار صحیحی برای ndigits معتبر است (مثبت، صفر یا منفی). اگر ndigits حذف شده یا None باشد، مقدار بازگشتی یک عدد صحیح است. در غیر این صورت مقدار بازگشتی همان نوع number را دارد.

برای یک شیء عمومی پایتون number، round به number.__round__ واگذار می‌کند.

یادداشت: رفتار round() برای floatها می‌تواند شگفت‌آور باشد: برای مثال، round(2.675, 2) مقدار 2.67 را می‌دهد، نه 2.68 مورد انتظار. این یک باگ نیست: نتیجهٔ این واقعیت است که بیشتر کسرهای اعشاری را نمی‌توان دقیقاً به‌صورت float نمایش داد. برای اطلاعات بیشتر محاسبات ممیز شناور: مسائل و محدودیت‌ها را ببینید.

class set(iterable=(), /)

یک شیء set جدید برمی‌گرداند، که به‌طور اختیاری عناصرش را از iterable می‌گیرد. set یک کلاس درون‌ساخت است. برای مستندات دربارهٔ این کلاس انواع مجموعه را ببینید.

برای ظرف‌های دیگر کلاس‌های درون‌ساخت frozenset، list، tuple و dict و نیز ماژول collections را ببینید.

setattr(object, name, value, /)

این تابع متناظر getattr() است. آرگومان‌ها یک شیء، یک رشته و یک مقدار دلخواه‌اند. رشته می‌تواند نام یک ویژگی موجود یا یک ویژگی جدید باشد. تابع مقدار را به ویژگی انتساب می‌دهد، به شرطی که شیء اجازه دهد. برای مثال setattr(x, 'foobar', 123) معادل x.foobar = 123 است.

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

یادداشت: چون تغییر نام خصوصی در زمان کامپایل رخ می‌دهد، برای تنظیم ویژگی خصوصی (ویژگی‌هایی با دو زیرخط ابتدایی) با setattr() باید نام آن را دستی تغییر دهید (mangle کنید).

class sentinel(name, /, *, repr=None)

یک شیء sentinel یکتای جدید برمی‌گرداند. name باید str باشد و به‌طور پیش‌فرض به‌عنوان نمایش شیء برگردانده‌شده به کار می‌رود:

>>> MISSING = sentinel("MISSING")
>>> MISSING
MISSING

از آرگومان اختیاری repr می‌توان برای مشخص کردن نمایش دیگر استفاده کرد:

>>> MISSING = sentinel("MISSING", repr="<MISSING>")
>>> MISSING
<MISSING>

اشیای sentinel درست (truthy) هستند و فقط با خودشان برابر مقایسه می‌شوند. قرار است با عملگر is مقایسه شوند.

sentinel از زیرکلاس‌سازی پشتیبانی نمی‌کند.

نسخهٔ سطحی و عمیق (shallow و deep copy) یک شیء sentinel خود شیء را برمی‌گرداند.

طبق قرارداد، sentinelها به متغیری با نام متناظر انتساب داده می‌شوند. sentinelهایی که به این روش تعریف شوند در type hintها قابل‌استفاده‌اند:

MISSING = sentinel("MISSING")

def next_value(default: int | MISSING = MISSING):
    ...

اشیای sentinel عملگر | را برای استفاده در عبارت‌های نوع پشتیبانی می‌کنند.

Pickling برای اشیای sentinelی که در دامنهٔ سراسری یک ماژول با نامی هم‌نام با نام sentinel قرار گرفته‌اند، و برای sentinelهایی که در دامنهٔ کلاس با نامی هم‌نام با نام واجد شرایط (qualified name) sentinel قرار گرفته‌اند پشتیبانی می‌شود. sentinelهای دیگر، مانند آن‌هایی که در دامنهٔ تابع تعریف شده‌اند، قابل pickle نیستند. هویت sentinel پس از pickling حفظ می‌شود:

import pickle

PICKLABLE = sentinel("PICKLABLE")

assert pickle.loads(pickle.dumps(PICKLABLE)) is PICKLABLE

class Cls:
    PICKLABLE = sentinel("Cls.PICKLABLE")

assert pickle.loads(pickle.dumps(Cls.PICKLABLE)) is Cls.PICKLABLE

اشیای sentinel ویژگی‌های زیر را دارند:

__name__ : نام sentinel.

__module__ : نام ماژولی که sentinel در آن ساخته شده است. این ویژگی قابل‌نوشتن است.

افزوده‌شده در نسخهٔ ۳٫۱۵.

class slice(stop, /)

class slice(start, stop, step=None, /)

یک شیء slice برمی‌گرداند که مجموعهٔ اندیس‌هایی را که با range(start, stop, step) مشخص شده‌اند نشان می‌دهد. آرگومان‌های start و step به‌طور پیش‌فرض None هستند.

اشیای slice هنگام استفاده از نحو برش (slicing) هم تولید می‌شوند. برای مثال: a[start:stop:step] یا a[start:stop, i].

برای نسخهٔ جایگزینی که یک تکرارگر برمی‌گرداند، itertools.islice() را ببینید.

slice.start، slice.stop، slice.step : این ویژگی‌های فقط‌خواندنی روی مقادیر آرگومان‌ها (یا پیش‌فرض آن‌ها) تنظیم می‌شوند. کارکرد صریح دیگری ندارند؛ با این حال، NumPy و بسته‌های شخص ثالث دیگر از آن‌ها استفاده می‌کنند.

تغییر در نسخهٔ ۳٫۱۲: اشیای slice اکنون هش‌پذیر (hashable) هستند (به شرطی که start، stop و step هش‌پذیر باشند).

sorted(iterable, /, *, key=None, reverse=False)

فهرست مرتب‌شدهٔ جدیدی از عناصر iterable برمی‌گرداند.

دو آرگومان اختیاری دارد که باید به‌صورت آرگومان کلیدواژه‌ای مشخص شوند.

key تابعی تک‌آرگومانی مشخص می‌کند که برای استخراج یک کلید مقایسه از هر عنصر iterable به کار می‌رود (برای مثال key=str.lower). مقدار پیش‌فرض None است (عناصر مستقیماً مقایسه می‌شوند).

reverse یک مقدار بولی است. اگر روی True تنظیم شود، عناصر فهرست طوری مرتب می‌شوند که گویی هر مقایسه معکوس شده است.

از functools.cmp_to_key() برای تبدیل تابع cmp سبک قدیم به تابع key استفاده کنید.

تابع درون‌ساخت sorted() تضمین شده پایدار (stable) است. مرتب‌سازی پایدار است اگر تضمین کند ترتیب نسبی عناصری که برابر مقایسه می‌شوند را تغییر نمی‌دهد — این برای مرتب‌سازی در چند گذر (مثلاً مرتب‌سازی بر اساس بخش، سپس بر اساس رتبهٔ حقوق) مفید است.

الگوریتم مرتب‌سازی فقط از مقایسه‌های < بین عناصر استفاده می‌کند. هرچند تعریف متد __lt__() برای مرتب‌سازی کافی است، PEP 8 توصیه می‌کند هر شش مقایسهٔ غنی (rich comparison) پیاده‌سازی شوند. این کار به جلوگیری از باگ‌ها هنگام استفاده از همان داده با ابزارهای ترتیب‌دهی دیگر مانند max() که به روش زیربنایی متفاوتی تکیه دارند کمک می‌کند. پیاده‌سازی هر شش مقایسه همچنین به جلوگیری از سردرگمی در مقایسه‌های نوع مختلط که ممکن است متد بازتابی __gt__() را فراخوانی کنند کمک می‌کند.

برای مثال‌های مرتب‌سازی و یک آموزش کوتاه مرتب‌سازی، راهنمای مرتب‌سازی را ببینید.

@staticmethod

یک متد را به متد ایستا (static method) تبدیل می‌کند.

متد ایستا آرگومان اول ضمنی دریافت نمی‌کند. برای تعریف متد ایستا از این الگو استفاده کنید:

class C:
    @staticmethod
    def f(arg1, arg2, argN): ...

شکل @staticmethod یک دکوراتور تابع است — برای جزئیات تعریف تابع را ببینید.

متد ایستا را می‌توان روی کلاس (مثل C.f()) یا روی نمونه (مثل C().f()) فراخوانی کرد. علاوه بر این، توصیف‌گر متد ایستا هم قابل‌فراخوانی است، بنابراین می‌توان آن را در تعریف کلاس استفاده کرد (مثل f()).

متدهای ایستا در پایتون شبیه آن‌هایی هستند که در Java یا C++ یافت می‌شوند. همچنین @classmethod را برای گونه‌ای ببینید که برای ساختن سازنده‌های جایگزین کلاس مفید است.

مانند همهٔ دکوراتورها، می‌توان staticmethod را به‌صورت یک تابع معمولی هم فراخوانی کرد و با نتیجهٔ آن کاری انجام داد. این در برخی موارد لازم است که در بدنهٔ کلاس به ارجاع یک تابع نیاز دارید و می‌خواهید از تبدیل خودکار به متد نمونه جلوگیری کنید. برای این موارد از این الگو استفاده کنید:

def regular_function():
    ...

class C:
    method = staticmethod(regular_function)

برای اطلاعات بیشتر دربارهٔ متدهای ایستا سلسله‌مراتب نوع استاندارد را ببینید.

تغییر در نسخهٔ ۳٫۱۰: متدهای ایستا اکنون ویژگی‌های متد (__module__، __name__، __qualname__، __doc__ و __annotations__) را به ارث می‌برند، ویژگی جدید __wrapped__ دارند و اکنون مانند توابع معمولی قابل‌فراخوانی‌اند.

class str(*, encoding='utf-8', errors='strict')

class str(object)

class str(object, encoding, errors='strict')

class str(object, *, errors)

نسخهٔ str از object را برمی‌گرداند. برای جزئیات str() را ببینید.

str کلاس رشتهٔ درون‌ساخت است. برای اطلاعات کلی دربارهٔ رشته‌ها نوع رشتهٔ متنی را ببینید.

sum(iterable, /, start=0)

start و عناصر iterable را از چپ به راست جمع می‌زند و مجموع را برمی‌گرداند. عناصر iterable معمولاً عدد هستند و مقدار شروع اجازه ندارد رشته باشد.

برای برخی موارد استفاده، جایگزین‌های خوبی برای sum() وجود دارد. روش ترجیحی و سریع برای الحاق دنباله‌ای از رشته‌ها فراخوانی ''.join(sequence) است. برای جمع زدن مقادیر ممیز شناور با دقت گسترش‌یافته math.fsum() را ببینید. برای الحاق مجموعه‌ای از تکرارپذیرها، استفاده از itertools.chain() را در نظر بگیرید.

تغییر در نسخهٔ ۳٫۸: پارامتر start می‌تواند به‌صورت آرگومان کلیدواژه‌ای مشخص شود.

تغییر در نسخهٔ ۳٫۱۲: جمع‌زدن floatها به الگوریتمی تغییر کرد که در بیشتر build‌ها دقت بالاتر و جابه‌جایی‌پذیری بهتری می‌دهد.

تغییر در نسخهٔ ۳٫۱۴: تخصص (specialization) برای جمع‌زدن اعداد مختلط، با همان الگوریتم جمع floatها، افزوده شد.

class super()

class super(type, object_or_type=None, /)

یک شیء پروکسی برمی‌گرداند که فراخوانی متدها را به یک کلاس والد یا هم‌نیای type واگذار می‌کند. این برای دسترسی به متدهای ارث‌برده‌شده‌ای که در یک کلاس بازنویسی (override) شده‌اند مفید است.

object_or_type ترتیب حل متد (method resolution order) را که باید جست‌وجو شود تعیین می‌کند. جست‌وجو از کلاسی که بلافاصله بعد از type است آغاز می‌شود.

برای مثال، اگر __mro__ مربوط به object_or_type برابر D -> B -> C -> A -> object باشد و مقدار type برابر B باشد، آنگاه super() در C -> A -> object جست‌وجو می‌کند.

ویژگی __mro__ کلاس متناظر با object_or_type ترتیب جست‌وجوی حل متد را که هم getattr() و هم super() به کار می‌برند فهرست می‌کند. این ویژگی پویاست و هر بار که سلسله‌مراتب وراثت به‌روز شود ممکن است تغییر کند.

اگر آرگومان دوم حذف شود، شیء super برگردانده‌شده نامقید (unbound) است. اگر آرگومان دوم یک شیء باشد، isinstance(obj, type) باید درست باشد. اگر آرگومان دوم یک نوع باشد، issubclass(type2, type) باید درست باشد (این برای متدهای کلاس مفید است).

وقتی مستقیماً درون یک متد معمولی از یک کلاس فراخوانی شود، هر دو آرگومان را می‌توان حذف کرد («super() بدون آرگومان»). در این حالت، type کلاس پیرامون خواهد بود و obj آرگومان اول تابعی که بلافاصله پیرامون است (معمولاً self). (این یعنی super() بدون آرگومان در توابع تودرتو، از جمله عبارت‌های مولد که ضمناً توابع تودرتو می‌سازند، آن‌طور که انتظار می‌رود کار نخواهد کرد.)

دو مورد استفادهٔ معمول برای super وجود دارد. در سلسله‌مراتب کلاسی با وراثت منفرد، می‌توان از super برای ارجاع به کلاس‌های والد بدون نام بردن صریح آن‌ها استفاده کرد، و بدین ترتیب کد را نگهداری‌پذیرتر کرد. این استفاده شباهت زیادی با استفاده از super در زبان‌های برنامه‌نویسی دیگر دارد.

مورد استفادهٔ دوم پشتیبانی از وراثت چندگانهٔ همکارانه (cooperative multiple inheritance) در محیط اجرای پویا است. این مورد استفاده منحصر به پایتون است و در زبان‌های کامپایل‌شدهٔ ایستا یا زبان‌هایی که فقط وراثت منفرد را پشتیبانی می‌کنند یافت نمی‌شود. این امکان می‌دهد «نمودارهای الماسی» پیاده‌سازی شوند که در آن چند کلاس پایه یک متد یکسان را پیاده می‌کنند. طراحی خوب حکم می‌کند چنین پیاده‌سازی‌هایی در هر مورد امضای فراخوانی یکسانی داشته باشند (چون ترتیب فراخوانی‌ها در زمان اجرا تعیین می‌شود، چون این ترتیب با تغییرات سلسله‌مراتب کلاس تطبیق می‌یابد، و چون این ترتیب می‌تواند شامل کلاس‌های هم‌نیایی باشد که پیش از زمان اجرا ناشناخته‌اند).

برای هر دو مورد استفاده، یک فراخوانی معمول کلاس والد به این شکل است:

class C(B):
    def method(self, arg):
        super().method(arg)    # This does the same thing as:
                               # super(C, self).method(arg)

علاوه بر جست‌وجوی متد، super() برای جست‌وجوی ویژگی هم کار می‌کند. یک مورد استفادهٔ ممکن برای این، فراخوانی توصیف‌گرها در یک کلاس والد یا هم‌نیا است.

توجه کنید که super() به‌عنوان بخشی از فرایند اتصال برای جست‌وجوی ویژگی نقطه‌دار صریح مانند super().__getitem__(name) پیاده‌سازی شده است. این کار را با پیاده‌سازی متد __getattribute__() خودش برای جست‌وجوی کلاس‌ها به ترتیبی قابل‌پیش‌بینی که از وراثت چندگانهٔ همکارانه پشتیبانی می‌کند انجام می‌دهد. بر این اساس، super() برای جست‌وجوهای ضمنی با استفاده از دستورها یا عملگرها مانند super()[name] تعریف‌نشده است.

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

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

تغییر در نسخهٔ ۳٫۱۴: اشیای super اکنون قابل pickle و قابل کپی هستند.

class tuple(iterable=(), /)

tuple به‌جای اینکه تابع باشد، در واقع یک نوع دنبالهٔ تغییرناپذیر است، همان‌طور که در تاپل‌ها و نوع‌های دنباله مستند شده است.

class type(object, /)

class type(name, bases, dict, /, **kwargs)

با یک آرگومان، نوع یک object را برمی‌گرداند. مقدار بازگشتی یک شیء نوع است و عموماً همان شیئی است که object.__class__ برمی‌گرداند.

برای آزمودن نوع یک شیء، تابع درون‌ساخت isinstance() توصیه می‌شود، چون زیرکلاس‌ها را در نظر می‌گیرد.

با سه آرگومان، یک شیء نوع جدید برمی‌گرداند. این اساساً شکل پویای دستور class است. رشتهٔ name نام کلاس است و به ویژگی __name__ تبدیل می‌شود. تاپل bases کلاس‌های پایه را دارد و به ویژگی __bases__ تبدیل می‌شود؛ اگر خالی باشد، object، پایهٔ نهایی همهٔ کلاس‌ها، افزوده می‌شود. دیکشنری dict تعریف‌های ویژگی و متد را برای بدنهٔ کلاس دارد؛ ممکن است پیش از تبدیل شدن به ویژگی __dict__ کپی یا پوشانده شود. دو دستور زیر اشیای type یکسانی می‌سازند:

>>> class X:
...     a = 1
...
>>> X = type('X', (), dict(a=1))

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

• مستندات ویژگی‌ها و متدهای کلاس‌ها.
• اشیای نوع (Type Objects)

آرگومان‌های کلیدواژه‌ای که به شکل سه‌آرگومانی داده می‌شوند، به همان شیوه‌ای که کلیدواژه‌ها در تعریف کلاس (به‌جز metaclass) به سازوکار فراکلاس (metaclass) مناسب (معمولاً __init_subclass__()) منتقل می‌شوند، منتقل می‌گردند.

بر خلاف دستور class، شکل سه‌آرگومانی متد __prepare__ فراکلاس را فراخوانی نمی‌کند (آماده‌سازی فضای نام کلاس را ببینید). برای ساخت پویای کلاس با فراکلاس مناسب از types.new_class() استفاده کنید.

همچنین سفارشی‌سازی ساخت کلاس را ببینید.

تغییر در نسخهٔ ۳٫۶: زیرکلاس‌های type که type.__new__ را بازنویسی نمی‌کنند، دیگر نمی‌توانند از شکل تک‌آرگومانی برای گرفتن نوع یک شیء استفاده کنند.

تغییر در نسخهٔ ۳٫۱۵: dict اکنون می‌تواند frozendict باشد.

vars()

vars(object, /)

ویژگی __dict__ را برای یک ماژول، کلاس، نمونه یا هر شیء دیگری که ویژگی __dict__ دارد برمی‌گرداند.

اشیایی مانند ماژول‌ها و نمونه‌ها ویژگی __dict__ قابل‌به‌روزرسانی دارند؛ با این حال، اشیای دیگر ممکن است محدودیت‌های نوشتن روی ویژگی‌های __dict__ خود داشته باشند (مثلاً کلاس‌ها برای جلوگیری از به‌روزرسانی مستقیم دیکشنری از types.MappingProxyType استفاده می‌کنند).

بدون آرگومان، vars() مانند locals() عمل می‌کند.

اگر شیئی مشخص شود اما ویژگی __dict__ نداشته باشد (مثلاً اگر کلاسش ویژگی __slots__ را تعریف کند)، استثنای TypeError پرتاب می‌شود.

تغییر در نسخهٔ ۳٫۱۳: نتیجهٔ فراخوانی این تابع بدون آرگومان همان‌طور که برای درون‌ساخت locals() شرح داده شد به‌روز شد.

zip(*iterables, strict=False)

روی چند تکرارپذیر به‌طور موازی تکرار می‌کند و تاپل‌هایی با یک عنصر از هر کدام تولید می‌کند.

مثال:

>>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):
...     print(item)
...
(1, 'sugar')
(2, 'spice')
(3, 'everything nice')

به‌طور رسمی‌تر: zip() تکرارگری از تاپل‌ها برمی‌گرداند که در آن تاپل i‌ام شامل عنصر i‌ام از هر یک از تکرارپذیرهای آرگومان است.

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

zip() تنبل (lazy) است: عناصر تا زمانی که روی تکرارپذیر تکرار نشود پردازش نمی‌شوند، مثلاً توسط یک حلقهٔ for یا با پوشاندن در list.

نکته‌ای که باید در نظر گرفت این است که تکرارپذیرهای داده‌شده به zip() ممکن است طول‌های متفاوتی داشته باشند؛ گاهی عمداً، و گاهی به دلیل باگ در کدی که این تکرارپذیرها را آماده کرده است. پایتون سه رویکرد مختلف برای مقابله با این مسئله ارائه می‌دهد:

• به‌طور پیش‌فرض، zip() وقتی کوتاه‌ترین تکرارپذیر تمام شود متوقف می‌شود. عناصر باقی‌مانده در تکرارپذیرهای بلندتر را نادیده می‌گیرد و نتیجه را به طول کوتاه‌ترین تکرارپذیر می‌برد:

  >>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))
  [(0, 'fee'), (1, 'fi'), (2, 'fo')]

• zip() اغلب در مواردی به کار می‌رود که فرض می‌شود تکرارپذیرها طول برابر دارند. در چنین مواردی توصیه می‌شود از گزینهٔ strict=True استفاده شود. خروجی آن با zip() معمولی یکسان است:

  >>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))
  [('a', 1), ('b', 2), ('c', 3)]

  بر خلاف رفتار پیش‌فرض، اگر یک تکرارپذیر پیش از بقیه تمام شود ValueError پرتاب می‌کند:

  >>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True):
  ...     print(item)
  ...
  (0, 'fee')
  (1, 'fi')
  (2, 'fo')
  Traceback (most recent call last):
    ...
  ValueError: zip() argument 2 is longer than argument 1

  بدون آرگومان strict=True، هر باگی که به تکرارپذیرهایی با طول‌های متفاوت منجر شود ساکت می‌ماند و احتمالاً در بخش دیگری از برنامه به‌صورت باگی که یافتنش دشوار است ظاهر می‌شود.

• تکرارپذیرهای کوتاه‌تر را می‌توان با یک مقدار ثابت پر کرد تا همهٔ تکرارپذیرها طول یکسانی داشته باشند. این کار توسط itertools.zip_longest() انجام می‌شود.

موارد حدی: با یک آرگومان تکرارپذیر، zip() تکرارگری از تاپل‌های تک‌عنصری برمی‌گرداند. بدون آرگومان، تکرارگر خالی برمی‌گرداند.

نکته‌ها و ترفندها:

• ترتیب ارزیابی چپ به راست تکرارپذیرها تضمین شده است. این امکان یک ایدیوم برای خوشه‌بندی یک دنبالهٔ داده به گروه‌های n‌تایی را با zip(*[iter(s)]*n, strict=True) فراهم می‌کند. این همان تکرارگر را n بار تکرار می‌کند تا هر تاپل خروجی نتیجهٔ n فراخوانی تکرارگر باشد. اثر آن تقسیم ورودی به تکه‌های n‌تایی است.

• zip() همراه با عملگر * را می‌توان برای unzip کردن یک فهرست به کار برد:

  >>> x = [1, 2, 3]
  >>> y = [4, 5, 6]
  >>> list(zip(x, y))
  [(1, 4), (2, 5), (3, 6)]
  >>> x2, y2 = zip(*zip(x, y))
  >>> x == list(x2) and y == list(y2)
  True

تغییر در نسخهٔ ۳٫۱۰: آرگومان strict افزوده شد.

__import__(name, globals=None, locals=None, fromlist=(), level=0)

یادداشت: این یک تابع پیشرفته است که برخلاف importlib.import_module() در برنامه‌نویسی روزمرهٔ پایتون لازم نیست.

این تابع توسط دستور import فراخوانی می‌شود. می‌توان آن را (با import کردن ماژول builtins و انتساب به builtins.__import__) جایگزین کرد تا معناشناسی دستور import تغییر کند، اما این کار به‌شدت توصیه نمی‌شود چون معمولاً ساده‌تر است برای رسیدن به همان اهداف از قلاب‌های import (به PEP 302 نگاه کنید) استفاده شود و این کار برای کدی که فرض می‌کند پیاده‌سازی پیش‌فرض import در حال استفاده است مشکل ایجاد نمی‌کند. استفادهٔ مستقیم از __import__() نیز به نفع importlib.import_module() توصیه نمی‌شود.

تابع ماژول name را import می‌کند، و ممکن است برای تعیین چگونگی تفسیر نام در بافت بسته (package) از globals و locals داده‌شده استفاده کند. fromlist نام اشیا یا زیرماژول‌هایی را که باید از ماژولِ داده‌شده توسط name import شوند مشخص می‌کند. پیاده‌سازی استاندارد اصلاً از آرگومان locals استفاده نمی‌کند و globals را فقط برای تعیین بافت بستهٔ دستور import به کار می‌برد.

level مشخص می‌کند از import مطلق یا نسبی استفاده شود. 0 (پیش‌فرض) یعنی فقط import مطلق انجام شود. مقادیر مثبت level تعداد پوشه‌های والدی را که باید نسبت به پوشهٔ ماژولِ فراخوانندهٔ __import__() جست‌وجو شود نشان می‌دهند (برای جزئیات PEP 328 را ببینید).

وقتی متغیر name به شکل package.module باشد، معمولاً بستهٔ سطح‌بالا (نام تا اولین نقطه) برگردانده می‌شود، نه ماژولی که name نام برده است. با این حال، وقتی آرگومان fromlist غیرخالی داده شود، ماژولی که name نام برده برگردانده می‌شود.

برای مثال، دستور import spam به بایت‌کدی شبیه کد زیر می‌انجامد:

spam = __import__('spam', globals(), locals(), [], 0)

دستور import spam.ham به این فراخوانی می‌انجامد:

spam = __import__('spam.ham', globals(), locals(), [], 0)

توجه کنید __import__() در اینجا ماژول سطح‌بالا را برمی‌گرداند چون این همان شیئی است که توسط دستور import به یک نام متصل می‌شود.

از طرف دیگر، دستور from spam.ham import eggs, sausage as saus به این می‌انجامد:

_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
eggs = _temp.eggs
saus = _temp.sausage

در اینجا ماژول spam.ham از __import__() برگردانده می‌شود. از این شیء، نام‌هایی که باید import شوند بازیابی و به نام‌های متناظرشان انتساب داده می‌شوند.

اگر فقط می‌خواهید ماژولی (احتمالاً درون یک بسته) را با نام import کنید، از importlib.import_module() استفاده کنید.

تغییر در نسخهٔ ۳٫۳: مقادیر منفی برای level دیگر پشتیبانی نمی‌شوند (که مقدار پیش‌فرض را هم به ۰ تغییر می‌دهد).

تغییر در نسخهٔ ۳٫۹: وقتی گزینه‌های خط فرمان -E یا -I به کار می‌روند، متغیر محیطی PYTHONCASEOK اکنون نادیده گرفته می‌شود.