توابع توکار¶

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

abs(number, /)¶

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

aiter(async_iterable, /)¶

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

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

اضافه شده در نسخه‌ی 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, /)

هنگام انتظار، آیتم بعدی را از پیمایش‌گر ناهمگام داده‌شده برگردانید، یا default اگر داده شده باشد و پیمایش‌گر به پایان رسیده باشد.

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

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

اضافه شده در نسخه‌ی 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 است (به انواع عددی --- int، float، complex مراجعه کنید). این کلاس دیگر قابل زیرکلاس‌بندی نیست. تنها نمونه های آن False و True هستند (به نوع بولی - bool مراجعه کنید).

تغییر یافته در نسخه‌ی 3.7: این پارامتر اکنون فقط‌جایگاهی (positional-only) است.

breakpoint(*args, **kws)¶

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

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

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

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

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

class bytearray(source=b'')

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

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

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

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

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

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

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

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

همچنین به انواع دنباله‌ای دودویی --- bytes، bytearray، memoryview و اشیای Bytearray مراجعه کنید.

class bytes(source=b'')

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

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

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

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

همچنین به انواع دنباله‌ای دودویی --- bytes، bytearray، memoryview، اشیای بایت و عملیات bytes و bytearray مراجعه کنید.

callable(object, /)¶

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

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

chr(codepoint, /)¶

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

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

@classmethod¶

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

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

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

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

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

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

تغییر یافته در نسخه‌ی 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, *, module=None)¶

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ها نیز حذف می‌شوند).

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

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

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

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

نکته

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

هشدار

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

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

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

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

تغییر یافته در نسخه‌ی 3.8: Added support for mode='func_type'.

تغییر یافته در نسخه‌ی 3.12: هنگامی که بایت‌های تهی در source یافت شوند، SyntaxError به‌جای ValueError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.15: پارامتر 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 برگردانده می‌شود.

نوع مختلط در انواع عددی --- 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, frozendict مراجعه کنید.

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

dir()¶

dir(object, /)

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

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

اگر شیء متد __dir__() را ارائه نکند، این تابع در صورت تعریف شدن، تلاش می‌کند تا حد امکان اطلاعات را از ویژگی __dict__ شیء و همچنین از شیء نوع (type object) آن جمع‌آوری کند. فهرست حاصل لزوماً کامل نیست و اگر شیء دارای __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() در درجه‌ی اول برای سهولت استفاده در اعلان تعاملی طراحی شده است، بیشتر تلاش می‌کند مجموعه‌ای مفید از نام‌ها را ارائه دهد تا مجموعه‌ای با تعریف دقیق و سازگار. بنابراین، رفتار دقیق آن ممکن است بین نسخه‌های مختلف تغییر کند. برای مثال، اگر آرگومان یک کلاس باشد، ویژگی‌های فراکلاس در فهرست نتایج قرار نمی‌گیرند.

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 | frozendict | None) -- فضای نام سراسری (پیش‌فرض: None).

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

بازمی‌گرداند:

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

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

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

هشدار

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

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

مثال:

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

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

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

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

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

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

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

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

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

تغییر یافته در نسخه‌ی 3.15: اکنون 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__ می‌تواند برای محدود کردن یا تغییر نام‌های در دسترس استفاده شود، اما این یک سازوکار امنیتی نیست؛ زیرا کدی که اجرا می‌شود همچنان می‌تواند به تمام اشیای توکار دسترسی داشته باشد.

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

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

نکته

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

نکته

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

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

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

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

تغییر یافته در نسخه‌ی 3.15: اکنون globals می‌تواند یک frozendict باشد.

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

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

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

تغییر یافته در نسخه‌ی 3.7: این پارامتر اکنون فقط‌جایگاهی (positional-only) است.

تغییر یافته در نسخه‌ی 3.8: اگر __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__() مربوط به value، دیکشنری نمونه را نادیده می‌گیرد. اگر جست‌وجوی متد به object برسد و format_spec خالی نباشد، یا اگر format_spec یا مقدار بازگشتی رشته نباشند، استثنای TypeError پرتاب می‌شود.

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

class frozendict(**kwargs)

class frozendict(mapping, /, **kwargs)

class frozendict(iterable, /, **kwargs)

یک دیکشنری فریزشده‌ی جدید ایجاد کنید. شیء frozendict یک کلاس توکار است. برای مستندات مربوط به این کلاس، به انواع نگاشت --- dict, frozendict نیز مراجعه کنید.

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

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

class frozenset(iterable=(), /)

یک شیء جدید از نوع frozenset را برمی‌گرداند که در صورت ارائه، عناصر آن از iterable گرفته می‌شوند. frozenset یک کلاس توکار است. برای مستندات این کلاس، به انواع مجموعه‌ای --- 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 ارائه شود، بدون افزودن نویسه‌ی پایان خط در خروجی استاندارد نوشته می‌شود. سپس تابع یک خط از ورودی می‌خواند، آن را به یک رشته تبدیل می‌کند (با حذف نویسه‌ی پایان خط انتهایی) و همان را برمی‌گرداند. اگر به پایان پرونده برسد، استثنای 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) در انواع عددی --- 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(cls, classinfo, /)¶

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

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

iter(iterable, /)¶

iter(callable, sentinel, /)

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

همچنین به انواع مربوط به پیمایش مراجعه کنید.

یکی از کاربردهای مفید شکل دوم 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 در واقع یک نوع دنباله‌ی تغییرپذیر است، نه یک تابع؛ همان‌گونه که در فهرست‌ها و انواع دنباله --- list، tuple، range مستند شده است.

locals()¶

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

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

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

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

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

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

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

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

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

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

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

یک پیمایش‌گر برگردانید که function را به هر item از 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» ایجادشده از آرگومان داده‌شده را برمی‌گرداند. برای اطلاعات بیشتر، به نماهای حافظه مراجعه کنید.

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, /)¶

یک عدد صحیح را به یک رشته‌ی هشت‌هشتی با پیشوند «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() مراجعه کنید.

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 مشخص نشده باشد، به طور پیش‌فرض از UTF-8 استفاده می‌شود؛ اگر حالت UTF-8 پایتون غیرفعال باشد، تابع locale.getencoding() برای دریافت کدگذاری محلی فعلی فراخوانی می‌شود. (برای خواندن و نوشتن بایت‌های خام، از حالت دودویی استفاده کنید و encoding را مشخص نکنید.) حالت‌های موجود عبارتند از:

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

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

همان‌طور که در نمای کلی ذکر شد، پایتون بین ورودی/خروجی دودویی و متنی تمایز قائل می‌شود. پرونده‌هایی که در حالت دودویی گشوده می‌شوند (شامل 'b' در آرگومان mode) محتویات را به شکل شیءهای bytes و بدون هیچ‌گونه کدگشایی برمی‌گردانند. در حالت متنی (حالت پیش‌فرض، یا زمانی که 't' در آرگومان mode گنجانده شده باشد)، محتویات پرونده به شکل 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 نام کدگذاری‌ای است که برای کدگشایی یا کدگذاری پرونده استفاده می‌شود. این پارامتر فقط باید در حالت متنی استفاده شود. کدگذاری پیش‌فرض UTF-8 است؛ اگر حالت UTF-8 پایتون غیرفعال باشد، مقدار پیش‌فرض به پلتفرم بستگی دارد (هر چیزی که locale.getencoding() برگرداند). هر کدگذاری متن که توسط پایتون پشتیبانی شود قابل استفاده است و مقدار encoding="locale" کدگذاری محلی فعلی را به طور صریح مشخص می‌کند. برای فهرست کدگذاری‌های پشتیبانی‌شده، به ماژول codecs مراجعه کنید.

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

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() به حالت بستگی دارد. هنگامی که 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' حذف شده است.

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

ord(character, /)¶

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

اگر آرگومان یک رشته‌ی تک‌نویسه‌ای باشد، نقطه‌ی کد یونیکد آن نویسه برگردانده می‌شود. برای مثال، 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 در جریان نوشته می‌شوند. هر دو مقدار 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 را می‌توان در زمان اجرا تغییر داد.

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

class range(stop, /)

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

range در واقع یک نوع دنباله‌ی تغییرناپذیر است، نه یک تابع؛ همان‌گونه که در بازه‌ها و انواع دنباله --- 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!r}, {self.age!r})"

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

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

setattr(object, name, value, /)¶

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

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

نکته

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

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

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

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

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

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

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

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

نسخه‌های کم‌عمق و عمیق از یک شیء نشانگر، خودِ شیء را برمی‌گردانند.

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

MISSING = sentinel("MISSING")

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

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

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

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

__name__¶

نام نشانگر.

__module__¶

نام ماژولی که نشانگر در آن ایجاد شده است. این ویژگی قابل نوشتن است.

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

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__() را فراخوانی کنند جلوگیری می‌کند.

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

@staticmethod¶

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

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

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

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

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

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

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

def regular_function():
    ...

class C:
    method = staticmethod(regular_function)

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

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

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

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

• اشیای نوع

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

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

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

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

تغییر یافته در نسخه‌ی 3.15: اکنون dict می‌تواند یک frozendict باشد.

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