توابع پیش ساخته

مفسر پایتون دارای تعدادی تابع و نوع داده (type) است که در آن بصورت توکار (built-in) همیشه در دسترس می‌باشند. آن‌ها در اینجا به ترتیب حروف الفبا فهرست شده‌اند.

توابع پیش ساخته
A abs() aiter() all() anext() any() ascii() B bin() bool() breakpoint() bytearray() bytes() C callable() chr() classmethod() compile() complex() D delattr() dict() dir() divmod()	E enumerate() eval() exec() F filter() float() format() frozenset() G getattr() globals() H hasattr() hash() help() hex() I id() input() int() isinstance() issubclass() iter()	L len() list() locals() M map() max() memoryview() min() N next() O object() oct() open() ord() P pow() print() property()	R range() repr() reversed() round() S set() setattr() slice() sorted() staticmethod() str() sum() super() T tuple() type() V vars() Z zip() _ __import__()

abs(number, /)

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

aiter(async_iterable, /)

بازگرداندن یک asynchronous iterator برای یک asynchronous iterable معادل فراخوانی x.__aiter__() است.

توجه: برخلاف iter()، aiter() نسخه دو آرگومانی ندارد.

Added in version 3.10.

all(iterable, /)

در صورتی که تمام عناصر iterable درست باشند (یا اگر iterable خالی باشد)، True را برمی گرداند. معادل با:

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

awaitable anext(async_iterator, /)

awaitable anext(async_iterator, default, /)

هنگام اِنتظار (await)، عنصر بعدی را از asynchronous iterator داده شده برمی‌گرداند، یا اگر آرگومان default ارائه شده و تکرارکننده به پایان رسیده باشد، مقدار default را برمی‌گرداند.

این، نسخه ناهمگامِ تابع داخلی next() است و به طور مشابه عمل می‌کند.

این متد __anext__() از async_iterator را فراخوانی می کند و یک awaitable را برمی گرداند. در انتظار این مقدار بعدی تکرار کننده را برمی گرداند. اگر default داده شود، اگر تکرار کننده تمام شده باشد، برگردانده می شود، در غیر این صورت StopAsyncIteration افزایش می یابد.

Added in version 3.10.

any(iterable, /)

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

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

ascii(object, /)

مانند تابع repr()، رشته‌ای حاوی نمایش قابل چاپ یک شیء را برمی‌گرداند، اما نویسه‌های غیر اَسکی (non-ASCII) را در رشته‌ی بازگردانده‌شده توسط تابع repr()، با استفاده از توالی‌های گریز (escapes) \x، \u یا \U اِسکِیپ (escape) می‌کند. این عمل، رشته‌ای مشابه آنچه تابع 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() مراجعه کنید.

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

class bool(object=False, /)

یک مقدار بولی، یعنی یکی از True یا False را بر می‌گرداند. آرگومان با استفاده از استاندارد truth testing procedure تبدیل می شود. اگر آرگومان نادرست یا حذف شده باشد، False را برمی گرداند. در غیر این صورت، True را برمی گرداند. کلاس bool یک زیر کلاس از int است (به Numeric Types --- int, float, complex مراجعه کنید). این کلاس دیگر قابل زیرکلاس‌بندی نیست. تنها نمونه های آن False و True هستند (به Boolean Type - bool مراجعه کنید).

تغییر داده شده در نسخه 3.7: این آرگومان اکنون صرفاً جایگاهی (positional-only) است.

breakpoint(*args, **kws)

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

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

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

یک auditing event builtins.breakpoint با آرگومان breakpointhook پرتاب می‌کند.

Added in version 3.7.

class bytearray(source=b'')

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

یک آرایهٔ جدید از بایت‌ها را برمی‌گرداند. کلاس bytearray دنباله‌ای قابل‌تغییر از اعداد صحیح در بازهٔ 0 <= x < 256 است. این کلاس بیشتر متدهای معمول دنباله‌های قابل‌تغییر را دارد که در Mutable Sequence Types شرح داده شده‌اند، و همچنین بیشتر متدهایی را دارد که نوع bytes دارد؛ به Bytes and Bytearray Operations مراجعه کنید.

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

• اگر source یک رشته «string» باشد، باید پارامترهای encoding و (به‌صورت اختیاری) errors را نیز مشخص کنید؛ سپس تابع bytearray() آن رشته را با استفاده از متد str.encode() به بایت‌ها تبدیل می‌کند.

• اگر «source» یک عدد صحیح «integer» باشد، آرایه به اندازه همان عدد ایجاد شده و با بایت‌های تهی «null byte» مقداردهی اولیه خواهد شد.

• اگر آرگومان، شیئی سازگار با رابط بافر باشد، از یک بافر فقط‌خواندنیِ آن شیء برای مقداردهی اولیهٔ آرایهٔ بایت‌ها استفاده خواهد شد.

• اگر «source» یک تکرارپذیر «iterable» باشد، باید یک تکرارپذیر از اعداد صحیح در بازه 0 <= x < 256 باشد، که این اعداد به‌عنوان محتویات اولیه آرایه استفاده می‌شوند.

بدون آرگومان، یک آرایه با اندازه صفر «0» ایجاد می شود.

همچنین به Binary Sequence Types --- bytes, bytearray, memoryview و Bytearray Objects مراجعه کنید.

class bytes(source=b'')

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

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

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

اشیای bytes را می‌توان با استفاده از ثابت‌های متنی نیز ایجاد کرد؛ برای اطلاعات بیشتر، String and Bytes literals را ببینید.

همچنین به Binary Sequence Types --- bytes, bytearray, memoryview، Bytes Objects و Bytes and Bytearray Operations مراجعه کنید.

callable(object, /)

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

Added in version 3.2: این تابع ابتدا در پایتون ۳٫۰ حذف شد و سپس در پایتون ۳٫۲ دوباره بازگردانده شد.

chr(codepoint, /)

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

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

@classmethod

یک متد را به متد کلاسی تبدیل می‌کند.

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

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

شکل @classmethod یک تزئین‌کننده تابع است؛ برای جزئیات به Function definitions مراجعه کنید.

یک متد کلاس را می‌توان هم روی خود کلاس (مانند C.f()) و هم روی یک نمونه (مانند C().f()) فراخوانی کرد. در حالت دوم، نمونه نادیده گرفته می‌شود و فقط کلاس آن در نظر گرفته می‌شود. اگر متد کلاس برای یک کلاس مشتق‌شده فراخوانی شود، شیء کلاس مشتق‌شده به‌عنوان نخستین آرگومان ضمنی ارسال می‌شود.

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

تغییر داده شده در نسخه 3.9: اکنون متدهای کلاس می‌توانند سایر توصیفگرها، مانند property()، را دربر بگیرند.

تغییر داده شده در نسخه 3.10: اکنون متدهای کلاس ویژگی‌های متد (__module__، __name__، __qualname__، __doc__ و __annotations__) را به ارث می‌برند و همچنین دارای ویژگی جدید __wrapped__ هستند.

منسوخ شده از نسخه‌ی 3.11، در نسخه‌ی 3.13 حذف شده است.: دیگر متدهای کلاس نمی‌توانند سایر توصیفگرها، مانند property()، را دربر بگیرند.

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

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

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

آرگومان mode مشخص می‌کند که چه نوع کدی باید کامپایل شود؛ اگر source شامل دنباله‌ای از دستورها باشد، می‌تواند 'exec' باشد؛ اگر شامل تنها یک عبارت باشد، 'eval'؛ و اگر شامل تنها یک دستور تعاملی باشد، 'single' (در حالت آخر، اگر عبارت مقداری غیر از None تولید کند، آن مقدار چاپ خواهد شد).

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

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

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

اگر کد منبع کامپایل‌شده نامعتبر باشد، این تابع استثنای SyntaxError یا ValueError پرتاب می‌کند.

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

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

توجه

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

هشدار

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

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

تغییر داده شده در نسخه 3.5: پیش از این، هنگام برخورد با بایت‌های تهی در source، استثنای TypeError پرتاب می‌شد.

Added in version 3.8: اکنون می‌توان ast.PyCF_ALLOW_TOP_LEVEL_AWAIT را در پرچم‌ها ارسال کرد تا از await، async for و async with در سطح بالای کد (top-level) پشتیبانی شود.

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 برگردانده می‌شود.

نوع مختلط در Numeric Types --- int, float, complex توضیح داده شده است.

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

تغییر داده شده در نسخه 3.8: اگر __complex__() و __float__() تعریف نشده باشند، به __index__() بازمی‌گردد.

منسوخ شده از نسخه 3.14: ارسال یک عدد مختلط به‌عنوان آرگومان 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 کلاس دیکشنری است. برای مستندات این کلاس، به dict و Mapping Types --- dict مراجعه کنید.

برای سایر انواع محفظه‌ها، به کلاس‌های داخلی list، set و tuple، و همچنین ماژول collections مراجعه کنید.

dir()

dir(object, /)

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

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

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

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

• اگر شیء یک ماژول باشد، فهرست شامل نام ویژگی‌های آن ماژول خواهد بود.

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

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

فهرست حاصل به‌ترتیب الفبایی مرتب می‌شود. برای مثال:

>>> 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__', '__cached__', '__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() در درجهٔ اول برای سهولت استفاده در اعلان تعاملی طراحی شده است، بیشتر تلاش می‌کند مجموعه‌ای مفید از نام‌ها را ارائه دهد تا مجموعه‌ای با تعریف دقیق و سازگار. بنابراین، رفتار دقیق آن ممکن است بین نسخه‌های مختلف تغییر کند. برای مثال، اگر آرگومان یک کلاس باشد، ویژگی‌های فراداده در فهرست نتایج قرار نمی‌گیرند.

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 آغاز می‌شود و مقدار پیش‌فرض آن 0 است) و مقادیر به‌دست‌آمده از پیمایش 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 | code object) -- یک عبارت پایتون.

• globals (dict | None) -- فضای نام سراسری (پیش‌فرض: None).

• locals (mapping | None) -- فضای نام محلی (پیش‌فرض: None).

بازگشت ها:

نتیجهٔ عبارت ارزیابی‌شده.

پرتاب می‌کند:

خطاهای نحوی به‌صورت استثنا گزارش می‌شوند.

هشدار

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

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

مثال:

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

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

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

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

برای تابعی که رشته‌های حاوی عبارت‌هایی متشکل فقط از مقادیر ثابت را ارزیابی می‌کند، به ast.literal_eval() مراجعه کنید.

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

تغییر داده شده در نسخه 3.13: آرگومان‌های globals و locals اکنون می‌توانند به‌صورت آرگومان کلیدواژه‌ای نیز ارسال شوند.

تغییر داده شده در نسخه 3.13: معنای فضای نام پیش‌فرض locals مطابق توضیحات ارائه‌شده برای تابع داخلی locals() تنظیم شده است.

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

هشدار

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

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

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

توجه

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

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

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

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

توجه

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

توجه

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

تغییر داده شده در نسخه 3.11: پارامتر closure اضافه شد.

تغییر داده شده در نسخه 3.13: آرگومان‌های globals و locals اکنون می‌توانند به‌صورت آرگومان کلیدواژه‌ای نیز ارسال شوند.

تغییر داده شده در نسخه 3.13: معنای فضای نام پیش‌فرض locals مطابق توضیحات ارائه‌شده برای تابع داخلی locals() تنظیم شده است.

filter(function, iterable, /)

از میان عناصر iterable، آن‌هایی را که function برایشان مقدار True برمی‌گرداند، انتخاب کرده و یک تکرارگر می‌سازد. iterable می‌تواند یک دنباله، یک محفظهٔ تکرارپذیر، یا یک تکرارگر باشد. اگر function برابر None باشد، تابع همانی در نظر گرفته می‌شود؛ یعنی تمام عناصری از iterable که نادرست (False) هستند، حذف می‌شوند.

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

برای تابع مکملی که عناصر iterable را که function برای آن‌ها مقدار نادرست (false) برمی‌گرداند، بازمی‌گرداند، به 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 (عدد نیست) یا بی‌نهایت مثبت یا منفی را نمایش می‌دهد. به‌طور دقیق‌تر، پس از حذف نویسه‌های فاصلهٔ سفید ابتدا و انتهای رشته، ورودی باید با قاعدهٔ تولید 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

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

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

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

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

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

نوع ممیز شناور در Numeric Types --- int, float, complex توضیح داده شده است.

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

تغییر داده شده در نسخه 3.7: این آرگومان اکنون صرفاً جایگاهی (positional-only) است.

تغییر داده شده در نسخه 3.8: اگر __float__() تعریف نشده باشد، به __index__() بازمی‌گردد.

format(value, format_spec='', /)

value را مطابق با format_spec به یک نمایش قالب‌بندی‌شده تبدیل می‌کند. نحوهٔ تفسیر format_spec به نوع آرگومان value بستگی دارد؛ با این حال، یک نحو استاندارد برای قالب‌بندی وجود دارد که بیشتر انواع داخلی از آن استفاده می‌کنند: Format specification mini-language.

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

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

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

class frozenset(iterable=(), /)

یک شیء جدید از نوع frozenset را برمی‌گرداند که در صورت ارائه، عناصر آن از iterable گرفته می‌شوند. frozenset یک کلاس داخلی است. برای مستندات این کلاس، به frozenset و Set Types --- set, frozenset مراجعه کنید.

برای سایر انواع محفظه‌ها، به کلاس‌های داخلی set، list، tuple و dict، و همچنین ماژول collections مراجعه کنید.

getattr(object, name, /)

getattr(object, name, default, /)

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

توجه

از آنجا که تغییر نام خصوصی در زمان کامپایل انجام می‌شود، برای بازیابی یک ویژگی خصوصی (ویژگی‌هایی که با دو زیرخط آغاز می‌شوند) با استفاده از getattr()، باید نام آن را به‌صورت دستی تغییر دهید.

globals()

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

hasattr(object, name, /)

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

hash(object, /)

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

توجه

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

help()

help(request)

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

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

این تابع توسط ماژول site به فضای نام داخلی (built-in namespace) اضافه می‌شود.

تغییر داده شده در نسخه 3.4: تغییرات اعمال‌شده در pydoc و inspect باعث شده‌اند امضاهای گزارش‌شده برای اشیای فراخوانی‌پذیر اکنون کامل‌تر و سازگارتر باشند.

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

همچنین برای تبدیل یک رشتهٔ شانزده‌شانزدهی به یک عدد صحیح با استفاده از مبنای 16، به int() مراجعه کنید.

توجه

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

id(object, /)

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

این، آدرس شیء در حافظه است.

یک رویداد ممیزی با نام 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 مشخص شده باشد، باید نمونه‌ای از bytes یا bytearray باشد که یک عدد صحیح در مبنای base را نمایش می‌دهد. به‌صورت اختیاری، رشته می‌تواند با + یا - (بدون فاصله بین آن‌ها و عدد) آغاز شود، دارای صفرهای ابتدایی باشد، با فاصلهٔ سفید احاطه شده باشد و بین رقم‌های آن زیرخط‌های تکی قرار گرفته باشند.

یک رشتهٔ عدد صحیح در مبنای n شامل رقم‌هایی است که هر یک مقداری بین 0 تا n-1 را نمایش می‌دهند. مقادیر 0 تا 9 را می‌توان با هر رقم ده‌دهی یونیکد نمایش داد. مقادیر 10 تا 35 را می‌توان با نویسه‌های a تا z (یا A تا Z) نمایش داد. مقدار پیش‌فرض base برابر 10 است. مبناهای مجاز عبارت‌اند از 0 و 2 تا 36. رشته‌های مبنای 2، 8 و 16 می‌توانند، همانند ثابت‌های عدد صحیح در کد، به‌ترتیب با پیشوندهای 0b/0B، 0o/0O یا 0x/0X آغاز شوند. برای مبنای 0، رشته مشابه یک ثابت عدد صحیح در کد تفسیر می‌شود؛ یعنی مبنای واقعی بر اساس پیشوند، یکی از 2، 8، 10 یا 16 خواهد بود. همچنین در مبنای 0 استفاده از صفرهای ابتدایی مجاز نیست؛ بنابراین int('010', 0) معتبر نیست، در حالی که int('010') و int('010', 8) معتبر هستند.

نوع عدد صحیح (integer) در Numeric Types --- int, float, complex توضیح داده شده است.

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

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

تغییر داده شده در نسخه 3.7: پارامتر اول اکنون فقط به‌صورت موقعیتی قابل ارسال است.

تغییر داده شده در نسخه 3.8: اگر __int__() تعریف نشده باشد، به __index__() بازمی‌گردد.

تغییر داده شده در نسخه 3.11: ورودی‌های رشته‌ای int و نمایش‌های رشته‌ای آن را می‌توان برای کمک به جلوگیری از حملات منع سرویس (Denial of Service) محدود کرد. اگر هنگام تبدیل یک رشته به int از این محدودیت فراتر رود، یا تبدیل یک int به رشته باعث عبور از این محدودیت شود، استثنای ValueError پرتاب می‌شود. برای اطلاعات بیشتر، مستندات محدودیت طول تبدیل رشته‌ای اعداد صحیح را ببینید.

تغییر داده شده در نسخه 3.14: int() دیگر فراخوانی را به متد __trunc__() واگذار نمی‌کند.

isinstance(object, classinfo, /)

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

تغییر داده شده در نسخه 3.10: classinfo می‌تواند یک Union Type باشد.

issubclass(class, classinfo, /)

اگر class زیرکلاس (مستقیم، غیرمستقیم یا مجازی) classinfo باشد، مقدار True را برمی‌گرداند. هر کلاس، زیرکلاس خودش نیز در نظر گرفته می‌شود. classinfo می‌تواند یک تاپل از اشیای کلاس (یا به‌صورت بازگشتی، تاپل‌هایی از این نوع) یا یک Union Type باشد؛ در این صورت، اگر class زیرکلاس هر یک از اعضای classinfo باشد، مقدار True برگردانده می‌شود. در هر حالت دیگر، استثنای TypeError پرتاب می‌شود.

تغییر داده شده در نسخه 3.10: classinfo می‌تواند یک Union Type باشد.

iter(iterable, /)

iter(callable, sentinel, /)

یک شیء تکرارگر را برمی‌گرداند. تفسیر آرگومان اول به وجود یا عدم وجود آرگومان دوم بستگی دارد. اگر آرگومان دومی وجود نداشته باشد، آرگومان اول باید یک شیء مجموعه باشد که از پروتکل تکرارپذیر (متد __iter__()) پشتیبانی کند، یا از پروتکل دنباله (متد __getitem__() با آرگومان‌های صحیح که از 0 شروع می‌شوند) پشتیبانی کند. اگر از هیچ‌یک از این پروتکل‌ها پشتیبانی نکند، استثنای TypeError پرتاب می‌شود. اگر آرگومان دوم، یعنی sentinel، ارائه شود، آرگومان اول باید یک شیء فراخوانی‌پذیر باشد. تکرارگر ایجادشده در این حالت، در هر فراخوانی متد __next__()، callable را بدون آرگومان فراخوانی می‌کند؛ اگر مقدار بازگردانده‌شده برابر sentinel باشد، استثنای StopIteration پرتاب می‌شود؛ در غیر این صورت، همان مقدار برگردانده می‌شود.

همچنین به Iterator Types مراجعه کنید.

یکی از کاربردهای مفید شکل دوم 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)

len(object, /)

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

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

class list(iterable=(), /)

list در واقع یک نوع دنبالهٔ تغییرپذیر است، نه یک تابع؛ همان‌گونه که در Lists و Sequence Types --- list, tuple, range مستند شده است.

locals()

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

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

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

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

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

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

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

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

تغییر داده شده در نسخه 3.12: رفتار locals() در comprehensionها مطابق PEP 709 به‌روزرسانی شده است.

تغییر داده شده در نسخه 3.13: به‌عنوان بخشی از PEP 667، اکنون معناشناسی تغییر دادن اشیای نگاشتی که این تابع برمی‌گرداند، تعریف شده است. رفتار این تابع در محدوده‌های بهینه‌شده اکنون همان‌گونه است که در بالا توضیح داده شد. به‌جز تعریف رسمی این رفتار، عملکرد آن در سایر محدوده‌ها نسبت به نسخه‌های پیشین تغییری نکرده است.

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

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

تغییر داده شده در نسخه 3.14: پارامتر strict اضافه شد.

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

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

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

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

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

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

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

تغییر داده شده در نسخه 3.4: پارامتر فقط-کلیدواژهٔ default اضافه شد.

تغییر داده شده در نسخه 3.8: key می‌تواند None باشد.

class memoryview(object)

یک شیء «memory view» ایجادشده از آرگومان داده‌شده را برمی‌گرداند. برای اطلاعات بیشتر، به Memory Views مراجعه کنید.

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

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

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

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

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

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

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

تغییر داده شده در نسخه 3.4: پارامتر فقط-کلیدواژهٔ default اضافه شد.

تغییر داده شده در نسخه 3.8: key می‌تواند None باشد.

next(iterator, /)

next(iterator, default, /)

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

class object

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

توجه

نمونه‌های object دارای ویژگی __dict__ نیستند؛ بنابراین نمی‌توانید ویژگی‌های دلخواهی را به یک نمونه از object اختصاص دهید.

oct(integer, /)

تبدیل یک عدد صحیح به یک رشته باینری که با "0b" پیشوند شده است. نتیجه یک عبارت معتبر پایتون خواهد بود. اگر 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() مراجعه کنید.

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

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

file یک شیء مسیرمانند است که مسیر پرونده (مطلق یا نسبی نسبت به پوشهٔ کاری فعلی) را برای باز شدن مشخص می‌کند، یا یک توصیفگر عددی پرونده مربوط به پرونده‌ای است که باید در یک شیء ورودی/خروجی بسته‌بندی شود. (اگر یک توصیفگر پرونده ارائه شود، هنگام بسته شدن شیء ورودی/خروجیِ بازگشتی نیز بسته خواهد شد، مگر اینکه closefd برابر False تنظیم شده باشد.)

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

نویسه	به معنی
'r'	باز کردن برای خواندن (پیش‌فرض)
'w'	باز کردن برای نوشتن؛ ابتدا محتوای پرونده حذف می‌شود.
'x'	باز کردن برای ایجاد انحصاری؛ در صورتی که پرونده از قبل وجود داشته باشد، عملیات شکست می‌خورد
'a'	باز کردن برای نوشتن؛ اگر پرونده وجود داشته باشد، داده‌ها به انتهای آن افزوده می‌شوند
'b'	حالت دودویی
't'	حالت متن (پیشفرض)
'+'	باز کردن برای به‌روزرسانی (خواندن و نوشتن)

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

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

توجه

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

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

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

• پرونده‌های متنی «تعاملی» (پرونده‌هایی که isatty() برای آن‌ها مقدار True برمی‌گرداند) از بافرگذاری خطی استفاده می‌کنند. سایر پرونده‌های متنی از سیاستی که در بالا برای پرونده‌های دودویی توضیح داده شده است، پیروی می‌کنند.

encoding نام رمزگذاری مورد استفاده برای رمزگشایی یا رمزگذاری پرونده است. این گزینه فقط باید در حالت متنی استفاده شود. رمزگذاری پیش‌فرض به سکو بستگی دارد (هر مقداری که locale.getencoding() برگرداند)، اما می‌توان از هر رمزگذاری متنی که توسط پایتون پشتیبانی می‌شود استفاده کرد. برای مشاهدهٔ فهرست رمزگذاری‌های پشتیبانی‌شده، به ماژول codecs مراجعه کنید.

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

• 'strict' در صورت بروز خطای رمزگذاری، استثنای ValueError پرتاب می‌کند. مقدار پیش‌فرض None نیز همین رفتار را دارد.

• 'ignore' خطاها را نادیده می‌گیرد. توجه داشته باشید که نادیده گرفتن خطاهای رمزگذاری ممکن است به از دست رفتن داده‌ها منجر شود.

• 'replace' باعث می‌شود در محل داده‌های نادرست، یک نویسهٔ جایگزین (مانند '?') درج شود.

• 'surrogateescape' هر بایت نادرست را به‌صورت واحدهای کد جانشین پایینی در بازهٔ U+DC80 تا U+DCFF نمایش می‌دهد. سپس، هنگام نوشتن داده‌ها و استفاده از مدیریت‌کنندهٔ خطای surrogateescape، این واحدهای کد جانشین دوباره به همان بایت‌ها تبدیل می‌شوند. این قابلیت برای پردازش پرونده‌هایی با رمزگذاری نامشخص مفید است.

• 'xmlcharrefreplace' فقط هنگام نوشتن در یک پرونده پشتیبانی می‌شود. نویسه‌هایی که توسط رمزگذاری پشتیبانی نمی‌شوند، با ارجاع نویسهٔ XML متناظر آن‌ها به صورت &#nnn; جایگزین می‌شوند.

• 'backslashreplace' داده‌های نادرست را با توالی‌های گریز دارای بک‌اسلش در پایتون جایگزین می‌کند.

• 'namereplace' (که آن هم فقط هنگام نوشتن پشتیبانی می‌شود) نویسه‌های پشتیبانی‌نشده را با توالی‌های گریز \N{...} جایگزین می‌کند.

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

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

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

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

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

پروندهٔ تازه ایجادشده غیرقابل‌وراثت است.

مثال زیر از پارامتر 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() به حالت (mode) بستگی دارد. هنگامی که open() برای باز کردن پرونده در حالت متنی (مانند 'w'، 'r'، 'wt'، 'rt' و غیره) استفاده شود، زیرکلاسی از io.TextIOBase (به‌طور مشخص io.TextIOWrapper) را بازمی‌گرداند. هنگام باز کردن پرونده در حالت دودویی همراه با بافر، کلاس بازگردانده‌شده زیرکلاسی از io.BufferedIOBase خواهد بود. کلاس دقیق بسته به حالت متفاوت است: در حالت خواندن دودویی، io.BufferedReader؛ در حالت‌های نوشتن دودویی و افزودن به انتهای پرونده، io.BufferedWriter؛ و در حالت خواندن/نوشتن، io.BufferedRandom بازگردانده می‌شود. اگر بافر غیرفعال باشد، جریان خام (raw stream)، یعنی io.FileIO که زیرکلاسی از io.RawIOBase است، بازگردانده می‌شود.

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

یک رویداد ممیزی با نام open و آرگومان‌های path، mode و flags پرتاب می‌کند.

آرگومان‌های mode و flags ممکن است بر اساس فراخوانی اولیه تغییر داده شده یا مقدار آن‌ها استنباط شده باشند.

تغییر داده شده در نسخه 3.3:

• پارامتر opener اضافه شده است.

• حالت 'x' اضافه شده است.

• در گذشته استثنای IOError پرتاب می‌شد؛ اکنون این استثنا نام مستعاری برای OSError است.

• اگر فایلی که در حالت ایجاد انحصاری ('x') باز می‌شود از قبل وجود داشته باشد، اکنون استثنای FileExistsError پرتاب می‌شود.

تغییر داده شده در نسخه 3.4:

• اکنون این پرونده غیرقابل‌وراثت است.

تغییر داده شده در نسخه 3.5:

• اگر فراخوانی سیستمی متوقف شود و مدیریت‌کنندهٔ سیگنال استثنایی پرتاب نکند، اکنون این تابع به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را دوباره امتحان می‌کند (برای دلیل این تغییر، PEP 475 را ببینید).

• مدیر خطای 'namereplace' اضافه شده است.

تغییر داده شده در نسخه 3.6:

• پشتیبانی از پذیرش اشیایی که os.PathLike را پیاده‌سازی می‌کنند، اضافه شده است.

• در ویندوز، باز کردن یک بافر کنسول ممکن است زیرکلاسی از io.RawIOBase غیر از io.FileIO را برگرداند.

تغییر داده شده در نسخه 3.11: حالت 'U' حذف شده است.

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 ارائه شده باشد و exp منفی باشد، base و mod باید نسبت به هم اول باشند. در این حالت، pow(inv_base, -exp, mod) برگردانده می‌شود که در آن inv_base وارونِ base به پیمانهٔ mod است.

در اینجا مثالی از محاسبهٔ وارون پیمانه‌ایِ 38 به پیمانهٔ 97 آورده شده است:

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

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

تغییر داده شده در نسخه 3.8: امکان استفاده از آرگومان‌های کلیدواژه‌ای اضافه شد. پیش از این، فقط آرگومان‌های مکانی پشتیبانی می‌شدند.

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

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

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

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

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

تغییر داده شده در نسخه 3.3: آرگومان کلیدواژه‌ای flush اضافه شد.

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

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

fget تابعی برای دریافت مقدار یک ویژگی است. fset تابعی برای تنظیم مقدار یک ویژگی است. fdel تابعی برای حذف مقدار یک ویژگی است. همچنین doc یک رشتهٔ مستندات برای آن ویژگی ایجاد می‌کند.

یک کاربرد رایج، تعریف ویژگی مدیریت‌شدهٔ 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.» تنظیم می‌کند.

@getter

@setter

@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 متناظر با آرگومان‌های سازنده است.

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

__name__

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

Added in version 3.13.

class range(stop, /)

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

range در واقع یک نوع دنبالهٔ تغییرناپذیر است، نه یک تابع؛ همان‌گونه که در Ranges و Sequence Types --- list, tuple, range مستند شده است.

repr(object, /)

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

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

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

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

reversed(object, /)

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

round(number, ndigits=None)

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

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

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

توجه

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

class set(iterable=(), /)

یک شیء جدید از نوع set را برمی‌گرداند که در صورت ارائه، عناصر آن از iterable گرفته می‌شوند. set یک کلاس داخلی است. برای مستندات این کلاس، به set و Set Types --- set, frozenset مراجعه کنید.

برای سایر انواع محفظه‌ها، به کلاس‌های داخلی frozenset، list، tuple و dict، و همچنین ماژول collections مراجعه کنید.

setattr(object, name, value, /)

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

name لازم نیست یک شناسهٔ پایتون، مطابق تعریف Names (identifiers and keywords)، باشد؛ مگر اینکه خود شیء این موضوع را اعمال کند، برای مثال در یک __getattribute__() سفارشی یا از طریق __slots__. ویژگی‌ای که نام آن یک شناسه نباشد، با استفاده از نماد نقطه قابل دسترسی نیست، اما از طریق getattr() و توابع مشابه قابل دسترسی خواهد بود.

توجه

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

class slice(stop, /)

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

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

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

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

start

stop

step

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

تغییر داده شده در نسخه 3.12: اشیای slice اکنون هش‌پذیر هستند (به شرطی که start، stop و step نیز هش‌پذیر باشند).

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

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

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

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

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

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

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

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

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

@staticmethod

یک متد را به متد ایستا تبدیل می‌کند.

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

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

شکل @staticmethod یک تزئین‌کننده تابع است؛ برای جزئیات به Function definitions مراجعه کنید.

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

متدهای ایستا در پایتون مشابه متدهای ایستای موجود در جاوا یا ++C هستند. همچنین، برای گونه‌ای که در ایجاد سازنده‌های جایگزین برای کلاس مفید است، به classmethod() مراجعه کنید.

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

def regular_function():
    ...

class C:
    method = staticmethod(regular_function)

برای اطلاعات بیشتر دربارهٔ متدهای ایستا، به The standard type hierarchy مراجعه کنید.

تغییر داده شده در نسخه 3.10: متدهای ایستا اکنون ویژگی‌های متد (__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)

نسخه‌ای از object از نوع str را برمی‌گرداند. برای جزئیات بیشتر، به str() مراجعه کنید.

str کلاس رشتهٔ داخلی پایتون است. برای اطلاعات کلی دربارهٔ رشته‌ها، Text Sequence Type --- str را ببینید.

sum(iterable, /, start=0)

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

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

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

تغییر داده شده در نسخه 3.12: الگوریتم جمع اعداد ممیز شناور به الگوریتمی تغییر یافته است که در بیشتر نسخه‌های ساخت (buildها)، دقت بیشتر و جابجاپذیری بهتری فراهم می‌کند.

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

class super

class super(type, object_or_type=None, /)

یک شیء واسط را برمی‌گرداند که فراخوانی متدها را به یک کلاس والد یا هم‌ردهٔ type واگذار می‌کند. این قابلیت برای دسترسی به متدهای به‌ارث‌رسیده‌ای که در یک کلاس بازنویسی شده‌اند، مفید است.

object_or_type ترتیب حل متد را که باید جست‌وجو شود تعیین می‌کند. جست‌وجو از کلاسی که بلافاصله پس از 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) برقرار باشد. اگر آرگومان دوم یک نوع (type) باشد، باید issubclass(type2, type) برقرار باشد (این مورد برای متدهای کلاس مفید است).

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

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

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

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

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__() خودش انجام می‌شود تا کلاس‌ها را با ترتیبی قابل پیش‌بینی جست‌وجو کند؛ ترتیبی که از وراثت چندگانهٔ مشارکتی (cooperative multiple inheritance) پشتیبانی می‌کند. بر این اساس، رفتار super() برای جست‌وجوهای ضمنی که با دستورها یا عملگرهایی مانند super()[name] انجام می‌شوند، تعریف نشده است.

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

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

تغییر داده شده در نسخه 3.14: اکنون اشیای super از سریال‌سازی با pickle و کپی شدن پشتیبانی می‌کنند.

class tuple(iterable=(), /)

tuple در واقع یک نوع دنبالهٔ تغییرناپذیر است، نه یک تابع؛ همان‌گونه که در Tuples و Sequence Types --- list, tuple, range مستند شده است.

class type(object, /)

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

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

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

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

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

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

• مستندات ویژگی‌ها و متدهای کلاس‌ها.

• Type Objects

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

همچنین به Customizing class creation مراجعه کنید.

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

vars()

vars(object, /)

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

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

در صورت نداشتن آرگومان، vars() همانند locals() عمل می‌کند.

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

تغییر داده شده در نسخه 3.13: نتیجهٔ فراخوانی این تابع بدون آرگومان، مطابق توضیحات ارائه‌شده برای تابع داخلی 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() تنبل است؛ عناصر تا زمانی که روی تکرارپذیر پیمایش انجام نشود، پردازش نمی‌شوند؛ برای مثال، با یک حلقهٔ 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() داده شود، یک تکرارگر از تاپل‌های تک‌عضوی برمی‌گرداند. اگر هیچ آرگومانی داده نشود، یک تکرارگر خالی برمی‌گرداند.

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

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

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

  >>> 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
  

تغییر داده شده در نسخه 3.10: آرگومان strict اضافه شد.

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

توجه

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

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

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

level مشخص می‌کند که از درون‌ریزی مطلق استفاده شود یا نسبی. مقدار 0 (که مقدار پیش‌فرض است) به این معناست که فقط درون‌ریزی مطلق انجام شود. مقادیر مثبت برای 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__() بازگردانده می‌شود. سپس، نام‌هایی که باید درون‌ریزی شوند از این شیء استخراج شده و به نام‌های متناظر خود اختصاص داده می‌شوند.

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

تغییر داده شده در نسخه 3.3: مقادیر منفی برای level دیگر پشتیبانی نمی‌شوند (در نتیجه، مقدار پیش‌فرض آن نیز به 0 تغییر کرده است).

تغییر داده شده در نسخه 3.9: هنگامی که گزینه‌های خط فرمان -E یا -I استفاده شوند، متغیر محیطی PYTHONCASEOK نادیده گرفته می‌شود.

پاورقی‌ها

[1]

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