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

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

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

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

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

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

نوع‌های درون‌ساخت اصلی عبارت‌اند از اعداد (numerics)، دنباله‌ها (sequences)، نگاشت‌ها (mappings)، کلاس‌ها، نمونه‌ها و استثناها.

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

برخی عملیات توسط چند نوع شیء پشتیبانی می‌شوند؛ به‌ویژه، عملاً همهٔ اشیا را می‌توان از نظر برابری مقایسه کرد، برای مقدار درستی آزمود، و به رشته تبدیل کرد (با تابع repr() یا تابع کمی متفاوت str()). تابع اخیر وقتی شیئی با تابع print() نوشته می‌شود ضمناً به کار می‌رود.

آزمون مقدار درستی (Truth Value Testing)

هر شیئی را می‌توان از نظر مقدار درستی آزمود، برای استفاده در شرط if یا while یا به‌عنوان عملوند عملیات بولی زیر.

به‌طور پیش‌فرض، شیء درست تلقی می‌شود مگر اینکه کلاسش یا متد __bool__() را تعریف کرده باشد که False برگرداند، یا متد __len__() که وقتی با شیء فراخوانی شود صفر برگرداند. ^۱ اگر یکی از این متدها هنگام فراخوانی استثنا پرتاب کند، استثنا منتشر می‌شود و شیء مقدار درستی ندارد (برای مثال NotImplemented). این‌ها بیشتر اشیای درون‌ساختی هستند که نادرست تلقی می‌شوند:

• ثابت‌هایی که نادرست تعریف شده‌اند: None و False
• صفر از هر نوع عددی: 0، 0.0، 0j، Decimal(0)، Fraction(0, 1)
• دنباله‌ها و مجموعه‌های خالی: ''، ()، []، {}، set()، range(0)

عملیات و توابع درون‌ساختی که نتیجهٔ بولی دارند، مگر خلاف آن گفته شود، همیشه برای نادرست 0 یا False و برای درست 1 یا True برمی‌گردانند. (استثنای مهم: عملیات بولی or و and همیشه یکی از عملوندهایشان را برمی‌گردانند.)

عملیات بولی — and، or، not

این‌ها عملیات بولی هستند، به ترتیب صعودی اولویت:

یادداشت‌ها:

1. این یک عملگر میان‌بر (short-circuit) است، بنابراین آرگومان دوم را فقط در صورتی ارزیابی می‌کند که اولی نادرست باشد.
2. این یک عملگر میان‌بر است، بنابراین آرگومان دوم را فقط در صورتی ارزیابی می‌کند که اولی درست باشد.
3. not اولویت کمتری نسبت به عملگرهای غیربولی دارد، بنابراین not a == b به‌صورت not (a == b) تفسیر می‌شود، و a == not b یک خطای نحوی است.

مقایسه‌ها (Comparisons)

در پایتون هشت عملیات مقایسه وجود دارد. همه اولویت یکسانی دارند (که از اولویت عملیات بولی بالاتر است). مقایسه‌ها را می‌توان به‌طور دلخواه زنجیره کرد؛ برای مثال، x < y <= z معادل x < y and y <= z است، با این تفاوت که y فقط یک بار ارزیابی می‌شود (اما در هر دو حالت وقتی x < y نادرست باشد، z اصلاً ارزیابی نمی‌شود).

این جدول عملیات مقایسه را خلاصه می‌کند:

مگر خلاف آن گفته شود، اشیای نوع‌های مختلف هرگز برابر مقایسه نمی‌شوند. عملگر == همیشه تعریف شده است اما برای برخی نوع‌های شیء (مثلاً اشیای کلاس) معادل is است. عملگرهای <، <=، > و >= فقط در جایی تعریف شده‌اند که معنا دارند؛ برای مثال، وقتی یکی از آرگومان‌ها عدد مختلط باشد استثنای TypeError پرتاب می‌کنند.

نمونه‌های غیرمنطبق یک کلاس معمولاً نامساوی مقایسه می‌شوند مگر اینکه کلاس متد __eq__() را تعریف کرده باشد.

نمونه‌های یک کلاس را نمی‌توان نسبت به نمونه‌های دیگر همان کلاس، یا انواع دیگر شیء، مرتب کرد مگر اینکه کلاس به‌اندازهٔ کافی از متدهای __lt__()، __le__()، __gt__() و __ge__() را تعریف کرده باشد (به‌طور کلی، اگر معنای متعارف عملگرهای مقایسه را بخواهید، __lt__() و __eq__() کافی هستند).

رفتار عملگرهای is و is not را نمی‌توان سفارشی کرد؛ همچنین می‌توان آن‌ها را روی هر دو شیء اعمال کرد و هرگز استثنا پرتاب نمی‌کنند.

دو عملیات دیگر با همان اولویت نحوی، in و not in، توسط نوع‌هایی پشتیبانی می‌شوند که تکرارپذیر هستند یا متد __contains__() را پیاده می‌کنند.

نوع‌های عددی — int، float، complex

سه نوع عددی متمایز وجود دارد: اعداد صحیح (integers)، اعداد ممیز شناور (floating-point numbers) و اعداد مختلط (complex numbers). علاوه بر این، بولی‌ها زیرنوعی از اعداد صحیح هستند. اعداد صحیح دقت نامحدود دارند. اعداد ممیز شناور معمولاً با double در C پیاده‌سازی می‌شوند؛ اطلاعات دربارهٔ دقت و نمایش داخلی اعداد ممیز شناور برای ماشینی که برنامه‌تان روی آن اجرا می‌شود در sys.float_info موجود است. اعداد مختلط بخش حقیقی و موهومی دارند که هر کدام یک عدد ممیز شناور است. برای استخراج این بخش‌ها از عدد مختلط z، از z.real و z.imag استفاده کنید. (کتابخانهٔ استاندارد نوع‌های عددی اضافی fractions.Fraction برای اعداد گویا و decimal.Decimal برای اعداد ممیز شناور با دقت قابل‌تعریف توسط کاربر را شامل می‌شود.)

اعداد با literalهای عددی یا به‌عنوان نتیجهٔ توابع و عملگرهای درون‌ساخت ساخته می‌شوند. literalهای صحیح ساده (از جمله اعداد هگزادسیمال، هشتایی و دودویی) اعداد صحیح تولید می‌کنند. literalهای عددی حاوی ممیز اعشار یا علامت توان، اعداد ممیز شناور تولید می‌کنند. افزودن 'j' یا 'J' به literal عددی یک عدد موهومی (عدد مختلط با بخش حقیقی صفر) تولید می‌کند که می‌توانید آن را با عدد صحیح یا ممیز شناور جمع کنید تا عدد مختلط با بخش‌های حقیقی و موهومی به دست آورید.

سازنده‌های int()، float() و complex() را می‌توان برای تولید اعدادی از یک نوع مشخص به کار برد.

پایتون از حساب مختلط (mixed arithmetic) به‌طور کامل پشتیبانی می‌کند: وقتی یک عملگر حسابی دودویی عملوندهایی از نوع‌های عددی درون‌ساخت مختلف دارد، عملوندی که نوعش «باریک‌تر» است به نوع دیگری گسترش می‌یابد:

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

حساب با عملوندهای مختلط و حقیقی با فرمول ریاضی معمول تعریف شده است، برای مثال:

x + complex(u, v) = complex(x + u, v)
x * complex(u, v) = complex(x * u, x * v)

مقایسه بین اعداد با نوع‌های مختلف طوری رفتار می‌کند که گویی مقادیر دقیق آن اعداد مقایسه می‌شوند. ^۲

همهٔ نوع‌های عددی (به‌جز مختلط) عملیات زیر را پشتیبانی می‌کنند (برای اولویت عملیات، خلاصهٔ عملگرها را ببینید):

یادداشت‌ها:

1. به آن تقسیم صحیح هم گفته می‌شود. برای عملوندهای از نوع int، نتیجه نوع int دارد. برای عملوندهای از نوع float، نتیجه نوع float دارد. به‌طور کلی نتیجه یک عدد صحیح (whole) است، هرچند نوع نتیجه لزوماً int نیست. نتیجه همیشه به سمت منفی بی‌نهایت گرد می‌شود: 1//2 برابر 0 است، (-1)//2 برابر -1، 1//(-2) برابر -1، و (-1)//(-2) برابر 0.
2. برای اعداد مختلط نیست. در صورت مناسب بودن، به‌جای آن با abs() به ممیز شناور تبدیل کنید.
3. تبدیل از float به int کوتاه می‌کند و بخش کسری را دور می‌اندازد. برای تبدیل‌های جایگزین توابع math.floor() و math.ceil() را ببینید.
4. float همچنین رشته‌های «nan» و «inf» را با پیشوند اختیاری «+» یا «-» برای Not a Number (NaN) و بی‌نهایت مثبت یا منفی می‌پذیرد.
5. پایتون pow(0, 0) و 0 ** 0 را برابر 1 تعریف می‌کند، همان‌طور که در زبان‌های برنامه‌نویسی رایج است.
6. literalهای عددی پذیرفته‌شده شامل ارقام 0 تا 9 یا هر معادل یونیکد (نقاط کد با ویژگی Nd) هستند. برای فهرست کامل نقاط کد با ویژگی Nd به استاندارد یونیکد مراجعه کنید.

همهٔ نوع‌های numbers.Real (یعنی int و float) عملیات زیر را هم دارند:

برای عملیات عددی بیشتر ماژول‌های math و cmath را ببینید.

عملیات بیتی روی نوع‌های صحیح

عملیات بیتی فقط برای اعداد صحیح معنا دارند. نتیجهٔ عملیات بیتی طوری محاسبه می‌شود که گویی در مکمل دو (two’s complement) با تعداد نامتناهی بیت علامت انجام شده است.

اولویت عملیات بیتی دودویی همگی از عملیات عددی پایین‌تر و از مقایسه‌ها بالاتر است؛ عملیات یگانی ~ اولویتی برابر عملیات عددی یگانی دیگر (+ و -) دارد.

این جدول عملیات بیتی را به ترتیب صعودی اولویت فهرست می‌کند:

یادداشت‌ها:

1. تعداد شیفت منفی غیرمجاز است و باعث پرتاب ValueError می‌شود.
2. شیفت به چپ به اندازهٔ n بیت معادل ضرب در pow(2, n) است.
3. شیفت به راست به اندازهٔ n بیت معادل تقسیم کف‌گرفته بر pow(2, n) است.
4. انجام این محاسبات با دست‌کم یک بیت گسترش علامت اضافی در نمایش مکمل دوی متناهی (پهنای بیت کاری برابر 1 + max(x.bit_length(), y.bit_length()) یا بیشتر) برای گرفتن همان نتیجه‌ای که با تعداد نامتناهی بیت علامت به دست می‌آید کافی است.

متدهای اضافی روی نوع‌های صحیح

نوع int کلاس پایهٔ انتزاعی (abstract base class) numbers.Integral را پیاده می‌کند. علاوه بر این، چند متد دیگر هم فراهم می‌کند:

int.bit_length() : تعداد بیت‌های لازم برای نمایش یک عدد صحیح به‌صورت دودویی را، بدون علامت و صفرهای ابتدایی، برمی‌گرداند:

>>> n = -37
>>> bin(n)
'-0b100101'
>>> n.bit_length()
6

دقیق‌تر، اگر x غیرصفر باشد، x.bit_length() تنها عدد صحیح مثبت k است که 2**(k-1) <= abs(x) < 2**k. به‌طور معادل، وقتی abs(x) به‌اندازهٔ کافی کوچک است که لگاریتم گردشدهٔ صحیح داشته باشد، k = 1 + int(log(abs(x), 2)). اگر x صفر باشد، x.bit_length() مقدار 0 را برمی‌گرداند.

معادل است با:

def bit_length(self):
    s = bin(self)       # binary representation:  bin(-37) --> '-0b100101'
    s = s.lstrip('-0b') # remove leading zeros and minus sign
    return len(s)       # len('100101') --> 6

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

int.bit_count() : تعداد یک‌ها را در نمایش دودویی قدر مطلق عدد صحیح برمی‌گرداند. به این «شمارش جمعیت (population count)» هم گفته می‌شود. مثال:

>>> n = 19
>>> bin(n)
'0b10011'
>>> n.bit_count()
3
>>> (-n).bit_count()
3

معادل است با:

def bit_count(self):
    return bin(self).count("1")

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

int.to_bytes(length=1, byteorder='big', *, signed=False) : آرایه‌ای از بایت‌ها را که یک عدد صحیح را نمایش می‌دهد برمی‌گرداند.

>>> (1024).to_bytes(2, byteorder='big')
b'\x04\x00'
>>> (1024).to_bytes(10, byteorder='big')
b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00'
>>> (-1024).to_bytes(10, byteorder='big', signed=True)
b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00'
>>> x = 1000
>>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little')
b'\xe8\x03'

عدد صحیح با length بایت نمایش داده می‌شود، و پیش‌فرض ۱ است. اگر عدد صحیح با تعداد بایت داده‌شده قابل‌نمایش نباشد OverflowError پرتاب می‌شود.

آرگومان byteorder ترتیب بایت را که برای نمایش عدد صحیح به کار می‌رود تعیین می‌کند و پیش‌فرضش "big" است. اگر byteorder برابر "big" باشد، پرارزش‌ترین بایت در ابتدای آرایهٔ بایت است. اگر byteorder برابر "little" باشد، پرارزش‌ترین بایت در انتهای آرایهٔ بایت است.

آرگومان signed تعیین می‌کند آیا مکمل دو برای نمایش عدد صحیح به کار می‌رود یا نه. اگر signed برابر False باشد و عدد صحیح منفی داده شود، OverflowError پرتاب می‌شود. مقدار پیش‌فرض signed برابر False است.

مقادیر پیش‌فرض را می‌توان برای تبدیل راحت یک عدد صحیح به شیء تک‌بایتی به کار برد:

>>> (65).to_bytes()
b'A'

با این حال، هنگام استفاده از آرگومان‌های پیش‌فرض، سعی نکنید مقداری بزرگ‌تر از ۲۵۵ را تبدیل کنید وگرنه OverflowError می‌گیرید.

معادل است با:

def to_bytes(n, length=1, byteorder='big', signed=False):
    if byteorder == 'little':
        order = range(length)
    elif byteorder == 'big':
        order = reversed(range(length))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

    return bytes((n >> i*8) & 0xff for i in order)

افزوده‌شده در نسخهٔ ۳٫۲. تغییر در نسخهٔ ۳٫۱۱: مقادیر پیش‌فرض آرگومان برای length و byteorder افزوده شد.

classmethod int.from_bytes(bytes, byteorder='big', *, signed=False) : عدد صحیحی را که آرایهٔ بایت داده‌شده نمایش می‌دهد برمی‌گرداند.

>>> int.from_bytes(b'\x00\x10', byteorder='big')
16
>>> int.from_bytes(b'\x00\x10', byteorder='little')
4096
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True)
-1024
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False)
64512
>>> int.from_bytes([255, 0, 0], byteorder='big')
16711680

آرگومان bytes باید یا یک شیء bytes-مانند (bytes-like object) یا یک تکرارپذیر تولیدکنندهٔ بایت باشد.

آرگومان byteorder ترتیب بایت را که برای نمایش عدد صحیح به کار می‌رود تعیین می‌کند و پیش‌فرضش "big" است. اگر byteorder برابر "big" باشد، پرارزش‌ترین بایت در ابتدای آرایهٔ بایت است. اگر byteorder برابر "little" باشد، پرارزش‌ترین بایت در انتهای آرایهٔ بایت است. برای درخواست ترتیب بایت بومی سیستم میزبان، از sys.byteorder به‌عنوان مقدار ترتیب بایت استفاده کنید.

آرگومان signed نشان می‌دهد آیا مکمل دو برای نمایش عدد صحیح به کار می‌رود.

معادل است با:

def from_bytes(bytes, byteorder='big', signed=False):
    if byteorder == 'little':
        little_ordered = list(bytes)
    elif byteorder == 'big':
        little_ordered = list(reversed(bytes))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

    n = sum(b << i*8 for i, b in enumerate(little_ordered))
    if signed and little_ordered and (little_ordered[-1] & 0x80):
        n -= 1 << 8*len(little_ordered)

    return n

افزوده‌شده در نسخهٔ ۳٫۲. تغییر در نسخهٔ ۳٫۱۱: مقدار پیش‌فرض آرگومان برای byteorder افزوده شد.

int.as_integer_ratio() : جفتی از اعداد صحیح را برمی‌گرداند که نسبتشان برابر عدد صحیح اصلی است و مخرج مثبت دارد. نسبت صحیح اعداد صحیح همیشه خود عدد صحیح به‌عنوان صورت و 1 به‌عنوان مخرج است.

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

int.is_integer() : True برمی‌گرداند. برای سازگاری duck type با float.is_integer() وجود دارد.

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

متدهای اضافی روی Float

نوع float کلاس پایهٔ انتزاعی numbers.Real را پیاده می‌کند. float متدهای اضافی زیر را هم دارد.

classmethod float.from_number(x) : متد کلاسی که عدد ممیز شناوری را که از عدد x ساخته شده برمی‌گرداند.

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

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

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

float.as_integer_ratio() : جفتی از اعداد صحیح را برمی‌گرداند که نسبتشان دقیقاً برابر float اصلی است. نسبت در ساده‌ترین شکل است و مخرج مثبت دارد. روی بی‌نهایت‌ها OverflowError و روی NaNها ValueError پرتاب می‌کند.

float.is_integer() : اگر نمونهٔ float متناهی با مقدار صحیح باشد True برمی‌گرداند، و در غیر این صورت False:

>>> (-2.0).is_integer()
True
>>> (3.2).is_integer()
False

دو متد از تبدیل به/از رشته‌های هگزادسیمال پشتیبانی می‌کنند. چون floatهای پایتون به‌صورت داخلی به‌شکل اعداد دودویی ذخیره می‌شوند، تبدیل float به/از رشتهٔ اعشاری معمولاً شامل یک خطای گرد کردن کوچک است. در مقابل، رشته‌های هگزادسیمال نمایش و مشخص‌سازی دقیق اعداد ممیز شناور را ممکن می‌کنند. این می‌تواند هنگام اشکال‌زدایی و در کارهای عددی مفید باشد.

float.hex() : نمایش عدد ممیز شناور را به‌صورت رشتهٔ هگزادسیمال برمی‌گرداند. برای اعداد ممیز شناور متناهی، این نمایش همیشه شامل 0x ابتدایی و p انتهایی و توان است.

classmethod float.fromhex(s) : متد کلاسی که float نمایش‌داده‌شده با رشتهٔ هگزادسیمال s را برمی‌گرداند. رشتهٔ s می‌تواند فاصلهٔ خالی در ابتدا و انتها داشته باشد.

توجه کنید که float.hex() یک متد نمونه است، در حالی که float.fromhex() یک متد کلاس است.

رشتهٔ هگزادسیمال به این شکل است:

[sign] ['0x'] integer ['.' fraction] ['p' exponent]

که sign اختیاری می‌تواند + یا - باشد، integer و fraction رشته‌هایی از ارقام هگزادسیمال هستند، و exponent یک عدد صحیح اعشاری با علامت ابتدایی اختیاری است. حروف بزرگ و کوچک اهمیتی ندارند، و باید حداقل یک رقم هگزادسیمال در بخش صحیح یا کسری وجود داشته باشد. این نحو شبیه نحو تعیین‌شده در بخش ۶٫۴٫۴٫۲ استاندارد C99، و نیز نحو به‌کاررفته در Java 1.5 به بعد است. به‌ویژه، خروجی float.hex() به‌عنوان literal ممیز شناور هگزادسیمال در کد C یا Java قابل‌استفاده است، و رشته‌های هگزادسیمال تولیدشده با نویسهٔ قالب %a در C یا Double.toHexString در Java توسط float.fromhex() پذیرفته می‌شوند.

توجه کنید که توان به‌صورت اعشاری نوشته می‌شود نه هگزادسیمال، و توانی از ۲ را می‌دهد که ضریب در آن ضرب می‌شود. برای مثال، رشتهٔ هگزادسیمال 0x3.a7p10 عدد ممیز شناور (3 + 10./16 + 7./16**2) * 2.0**10 یعنی 3740.0 را نشان می‌دهد:

>>> float.fromhex('0x3.a7p10')
3740.0

اعمال تبدیل معکوس روی 3740.0 رشتهٔ هگزادسیمال متفاوتی می‌دهد که همان عدد را نشان می‌دهد:

>>> float.hex(3740.0)
'0x1.d380000000000p+11'

متدهای اضافی روی Complex

نوع complex کلاس پایهٔ انتزاعی numbers.Complex را پیاده می‌کند. complex متدهای اضافی زیر را هم دارد.

classmethod complex.from_number(x) : متد کلاسی برای تبدیل یک عدد به عدد مختلط.

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

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

هش کردن نوع‌های عددی

برای اعداد x و y، که احتمالاً از نوع‌های مختلف‌اند، یک الزام است که هر وقت x == y آنگاه hash(x) == hash(y) (برای جزئیات بیشتر مستندات متد __hash__() را ببینید). برای سهولت پیاده‌سازی و کارایی در میان نوع‌های عددی گوناگون (از جمله int، float، decimal.Decimal و fractions.Fraction) هش پایتون برای نوع‌های عددی بر پایهٔ یک تابع ریاضی واحد است که برای هر عدد گویا تعریف شده است، و بنابراین برای همهٔ نمونه‌های int و fractions.Fraction، و همهٔ نمونه‌های متناهی float و decimal.Decimal اعمال می‌شود. اساساً، این تابع با کاهش به پیمانهٔ P برای یک عدد اول ثابت P داده می‌شود. مقدار P به‌عنوان ویژگی sys.hash_info.modulus از sys.hash_info در اختیار پایتون قرار می‌گیرد.

جزئیات پیاده‌سازی (CPython): در حال حاضر، عدد اول به‌کاررفته P = 2**31 - 1 در ماشین‌هایی با long زبان C ۳۲ بیتی و P = 2**61 - 1 در ماشین‌هایی با long زبان C ۶۴ بیتی است.

قواعد با جزئیات:

• اگر x = m / n یک عدد گویای نامنفی باشد و n بر P بخش‌پذیر نباشد، hash(x) را برابر m * invmod(n, P) % P تعریف کنید، که invmod(n, P) وارون n به پیمانهٔ P را می‌دهد.
• اگر x = m / n یک عدد گویای نامنفی باشد و n بر P بخش‌پذیر باشد (اما m نه)، آنگاه n وارونی به پیمانهٔ P ندارد و قاعدهٔ بالا اعمال نمی‌شود؛ در این حالت hash(x) را برابر مقدار ثابت sys.hash_info.inf تعریف کنید.
• اگر x = m / n عدد گویای منفی باشد، hash(x) را برابر -hash(-x) تعریف کنید. اگر هش حاصل -1 باشد، آن را با -2 جایگزین کنید.
• مقادیر مشخص sys.hash_info.inf و -sys.hash_info.inf به‌عنوان مقادیر هش به ترتیب برای بی‌نهایت مثبت یا منفی به کار می‌روند.
• برای عدد complex به نام z، مقادیر هش بخش‌های حقیقی و موهومی با محاسبهٔ hash(z.real) + sys.hash_info.imag * hash(z.imag) ترکیب می‌شوند، که به پیمانهٔ 2**sys.hash_info.width کاهش داده می‌شود تا در range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1)) بیفتد. باز هم، اگر نتیجه -1 باشد، با -2 جایگزین می‌شود.

برای روشن شدن قواعد بالا، این کد پایتون مثال است، معادل هش درون‌ساخت، برای محاسبهٔ هش عدد گویا، float یا complex:

import sys, math

def hash_fraction(m, n):
    """Compute the hash of a rational number m / n.

    Assumes m and n are integers, with n positive.
    Equivalent to hash(fractions.Fraction(m, n)).

    """
    P = sys.hash_info.modulus
    # Remove common factors of P.  (Unnecessary if m and n already coprime.)
    while m % P == n % P == 0:
        m, n = m // P, n // P

    if n % P == 0:
        hash_value = sys.hash_info.inf
    else:
        # Fermat's Little Theorem: pow(n, P-1, P) is 1, so
        # pow(n, P-2, P) gives the inverse of n modulo P.
        hash_value = (abs(m) % P) * pow(n, P - 2, P) % P
    if m < 0:
        hash_value = -hash_value
    if hash_value == -1:
        hash_value = -2
    return hash_value

def hash_float(x):
    """Compute the hash of a float x."""

    if math.isnan(x):
        return object.__hash__(x)
    elif math.isinf(x):
        return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
    else:
        return hash_fraction(*x.as_integer_ratio())

def hash_complex(z):
    """Compute the hash of a complex number z."""

    hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
    # do a signed reduction modulo 2**sys.hash_info.width
    M = 2**(sys.hash_info.width - 1)
    hash_value = (hash_value & (M - 1)) - (hash_value & M)
    if hash_value == -1:
        hash_value = -2
    return hash_value

نوع بولی — bool

بولی‌ها مقادیر درستی را نشان می‌دهند. نوع bool دقیقاً دو نمونهٔ ثابت دارد: True و False.

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

برای عملیات منطقی، از عملگرهای بولی and، or و not استفاده کنید. وقتی عملگرهای بیتی &، |، ^ روی دو بولی اعمال شوند، boolی معادل عملیات منطقی «and»، «or»، «xor» برمی‌گردانند. با این حال، عملگرهای منطقی and، or و != باید به &، | و ^ ترجیح داده شوند.

منسوخ در نسخهٔ ۳٫۱۲: استفاده از عملگر وارونگی بیتی ~ منسوخ شده است و در پایتون ۳٫۱۶ خطا پرتاب خواهد کرد.

bool زیرکلاسی از int است (نوع‌های عددی را ببینید). در بسیاری از بافت‌های عددی، False و True به ترتیب مانند اعداد صحیح ۰ و ۱ رفتار می‌کنند. با این حال، تکیه بر این توصیه نمی‌شود؛ به‌جای آن به‌صراحت با int() تبدیل کنید.

نوع‌های مرتبط با تکرار (Iteration-related types)

پایتون مفهوم تکرار روی ظرف‌ها (containers) را پشتیبانی می‌کند. این با دو متد متمایز پیاده‌سازی می‌شود؛ این‌ها به کلاس‌های تعریف‌شده توسط کاربر اجازه می‌دهند از تکرار پشتیبانی کنند. دنباله‌ها، که در ادامه با جزئیات بیشتر توصیف می‌شوند، همیشه متدهای تکرار را پشتیبانی می‌کنند.

تکرارپذیرها (Iterables)

برای اینکه اشیای ظرف از تکرارپذیر پشتیبانی کنند، یک متد باید تعریف شود:

container.__iter__() : یک شیء تکرارگر برمی‌گرداند. لازم است شیء از پروتکل تکرارگر که در ادامه توصیف می‌شود پشتیبانی کند. اگر ظرفی انواع مختلف تکرار را پشتیبانی کند، می‌توان متدهای اضافی برای درخواست تکرارگرها برای آن انواع تکرار فراهم کرد. (مثالی از شیئی که چند شکل تکرار را پشتیبانی می‌کند ساختار درختی است که هم پیمایش عرض‌اول و هم عمق‌اول را پشتیبانی کند.) این متد با اسلات tp_iter ساختار نوع برای اشیای پایتون در Python/C API متناظر است.

تکرارگرها (Iterators)

خود اشیای تکرارگر لازم است دو متد زیر را پشتیبانی کنند، که با هم پروتکل تکرارگر (iterator protocol) را تشکیل می‌دهند:

iterator.__iter__() : خود شیء تکرارگر را برمی‌گرداند. این لازم است تا هم ظرف‌ها و هم تکرارگرها بتوانند با دستورهای for و in به کار روند. این متد با اسلات tp_iter ساختار نوع برای اشیای پایتون در Python/C API متناظر است.

iterator.__next__() : عنصر بعدی را از تکرارگر برمی‌گرداند. اگر عنصر دیگری نباشد، استثنای StopIteration را پرتاب می‌کند. این متد با اسلات tp_iternext ساختار نوع برای اشیای پایتون در Python/C API متناظر است.

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

وقتی متد __next__() یک تکرارگر StopIteration را پرتاب کرد، باید در فراخوانی‌های بعدی هم به این کار ادامه دهد. پیاده‌سازی‌هایی که این ویژگی را رعایت نمی‌کنند خراب تلقی می‌شوند.

نوع‌های مولد (Generator types)

مولدهای (generators) پایتون — یا دقیق‌تر، توابع مولد و تکرارگرهای مولد — راه مناسبی برای پیاده‌سازی پروتکل تکرارگر فراهم می‌کنند.

تابعی که یک یا چند عبارت yield دارد یک تابع مولد است. برای مثال:

>>> def count_to_three():
...     yield 0
...     yield 1
...     yield 2
...     yield 3

توابع مولد مانند توابع معمولی تعریف‌شده توسط کاربر رفتار می‌کنند (مثلاً ویژگی‌های یکسان دارند)، با این تفاوت که فراخوانی تابع مولد یک تکرارگر مولد برمی‌گرداند:

>>> count_to_three()
<generator object count_to_three at 0x7f33a2305000>

تکرار روی تکرارگر مولد کد تابع مولد زیربنایی را اجرا می‌کند و هر مقدار yieldشده را به نوبت تولید می‌کند:

>>> for number in count_to_three():
...     print(number)
0
1
2
3

>>> list(count_to_three())
[0, 1, 2, 3]

یک کاربرد رایج توابع مولد پیاده‌سازی متد __iter__() اشیای تکرارپذیر سفارشی است. برای مثال:

>>> class CardDeck:
...     def __iter__(self):
...         yield 'three of clubs'
...         yield 'ace of hearts'

>>> list(CardDeck())
['three of clubs', 'ace of hearts']

تکرارگرهای مولد (Generator iterators)

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

generator.__next__() : اجرای یک تابع مولد را شروع می‌کند یا آن را در عبارت yieldی که تابع در حال حاضر در آن معلق است از سر می‌گیرد. وقتی تابع مولد با متد __next__() از سر گرفته می‌شود، عبارت yield جاری همیشه به None ارزیابی می‌شود. سپس اجرا تا عبارت yield بعدی ادامه می‌یابد، جایی که مولد دوباره معلق می‌شود، و مقدار عبارت بعد از کلیدواژهٔ yield به فراخواننده __next__() برگردانده می‌شود. اگر مولد بدون yield کردن مقدار دیگری خارج شود، __next__() استثنای StopIteration را پرتاب می‌کند و علامت می‌دهد که تکرار تمام شده است.

این متد معمولاً ضمناً فراخوانی می‌شود، مثلاً توسط حلقهٔ for، یا توسط تابع درون‌ساخت next().

تکرارگرهای مولد چند متد بیشتر از تکرارگرهای عمومی دارند که می‌توان با آن‌ها اجرای تابع مولد زیربنایی را کنترل کرد:

generator.send(value) : یک مقدار را به تابع مولد «می‌فرستد»: آرگومان value نتیجهٔ عبارت yield جاری می‌شود.

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

وقتی send() برای شروع مولد فراخوانی شود، باید با None به‌عنوان آرگومان فراخوانی شود، چون عبارت yield جاری‌ای که بتواند مقدار را دریافت کند وجود ندارد.

generator.throw(value) و generator.throw(type[, value[, traceback]]) : استثنایی را در نقطه‌ای که مولد در حال حاضر معلق است پرتاب می‌کند.

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

وقتی throw() برای شروع مولد فراخوانی شود، مولد بلافاصله خارج می‌شود (یعنی فراخوانی‌های بعدی __next__() استثنای StopIteration پرتاب می‌کنند) و استثنای پرتاب‌شده به فراخواننده throw() منتشر می‌شود.

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

با این حال، برای سازگاری با گذشته، امضای دوم، به‌پیروی از قراردادی از نسخه‌های قدیمی‌تر پایتون، پشتیبانی می‌شود. آرگومان type باید کلاس استثنا باشد و value باید نمونهٔ استثنا باشد. اگر value داده نشود، سازندهٔ type برای گرفتن نمونه فراخوانی می‌شود. اگر traceback داده شود، روی استثنا تنظیم می‌شود، در غیر این صورت هر ویژگی __traceback__ موجود ذخیره‌شده در value ممکن است پاک شود.

تغییر در نسخهٔ ۳٫۱۲: امضای دوم (type[, value[, traceback]]) منسوخ شده است و ممکن است در نسخهٔ آیندهٔ پایتون حذف شود.

generator.close() : استثنای GeneratorExit را در نقطه‌ای که تابع مولد در حال حاضر معلق است پرتاب می‌کند (معادل فراخوانی throw(GeneratorExit)).

اگر تابع مولد از قبل خارج شده باشد (به دلیل استثنا یا بازگشت عادی)، یا GeneratorExit را پرتاب کند (با نگرفتن استثنا)، close() مقدار None را برمی‌گرداند. اگر مولد مقداری yield کند، RuntimeError پرتاب می‌شود. اگر مولد استثنای دیگری پرتاب کند، به فراخواننده منتشر می‌شود. اگر مولد هنگام بسته شدن مقداری برگرداند، آن مقدار توسط close() برگردانده می‌شود.

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

تغییر در نسخهٔ ۳٫۱۳: اگر مولد هنگام بسته شدن مقداری برگرداند، مقدار توسط close() برگردانده می‌شود. پیش‌تر None برمی‌گرداند.

فراخوانی هر یک از متدهای مولد (__next__()، send()، throw()، close()) در حالی که یکی از این متدها از قبل در حال اجراست استثنای ValueError پرتاب می‌کند.

تکرارگرهای مولد ناهمگام (Asynchronous generator iterators)

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

agen.__anext__() (ناهمگام) : یک awaitable برمی‌گرداند که وقتی اجرا شود، اجرای تابع مولد ناهمگام را شروع می‌کند یا آن را در عبارت yieldی که تابع در حال حاضر در آن معلق است از سر می‌گیرد. وقتی تابع مولد ناهمگام با متد __anext__() از سر گرفته می‌شود، عبارت yield جاری همیشه در awaitable برگردانده‌شده به None ارزیابی می‌شود، که وقتی اجرا شود تا عبارت yield بعدی ادامه می‌یابد. مقدار عبارت بعد از کلیدواژهٔ yield مقدار استثنای StopIteration است که توسط coroutine تکمیل‌کننده پرتاب می‌شود. اگر مولد ناهمگام بدون yield کردن مقدار دیگری خارج شود، awaitable در عوض استثنای StopAsyncIteration را پرتاب می‌کند و علامت می‌دهد که تکرار ناهمگام تمام شده است.

این متد معمولاً ضمناً توسط حلقهٔ async for، یا توسط تابع درون‌ساخت anext() فراخوانی می‌شود.

تکرارگرهای مولد ناهمگام چند متد بیشتر از تکرارگرهای ناهمگام عمومی دارند که می‌توان با آن‌ها اجرای تابع مولد زیربنایی را کنترل کرد:

agen.asend(value) (ناهمگام) : یک awaitable برمی‌گرداند که وقتی اجرا شود، یک مقدار را به تابع مولد ناهمگام زیربنایی «می‌فرستد»: آرگومان value نتیجهٔ عبارت yield جاری می‌شود.

در غیر این صورت، این متد مانند __anext__() رفتار می‌کند: وقتی awaitable برگردانده‌شده اجرا شود، تابع زیربنایی را از سر می‌گیرد و یا مقدار yield‌شدهٔ بعدی را به‌عنوان مقدار StopIteration پرتاب‌شده برمی‌گرداند، یا StopAsyncIteration پرتاب می‌کند.

وقتی asend() برای شروع مولد ناهمگام فراخوانی شود، باید با None به‌عنوان آرگومان فراخوانی شود، چون عبارت yieldی که بتواند مقدار را دریافت کند وجود ندارد.

agen.athrow(value) و agen.athrow(type[, value[, traceback]]) (ناهمگام) : یک awaitable برمی‌گرداند که وقتی اجرا شود، استثنایی را در نقطه‌ای که تابع مولد ناهمگام زیربنایی در حال حاضر معلق است پرتاب می‌کند.

در غیر این صورت، این متد مانند __anext__() رفتار می‌کند: وقتی awaitable برگردانده‌شده اجرا شود، تابع زیربنایی را (با پرتاب استثنا) از سر می‌گیرد و یا مقدار yield‌شدهٔ بعدی را به‌عنوان مقدار StopIteration پرتاب‌شده برمی‌گرداند، یا StopAsyncIteration پرتاب می‌کند. اگر تابع زیربنایی استثنای ارسال‌شده را نگیرد، یا استثنای متفاوتی پرتاب کند، آنگاه وقتی awaitable اجرا شود، آن استثنا به فراخواننده awaitable منتشر می‌شود.

وقتی athrow() برای شروع مولد فراخوانی شود، مولد هنگام اجرای awaitable خارج می‌شود (یعنی نتایج بعدی از __anext__() هنگام اجرا StopAsyncIteration پرتاب می‌کنند) و استثنای پرتاب‌شده به فراخواننده awaitable منتشر می‌شود.

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

با این حال، برای سازگاری با گذشته، امضای دوم پشتیبانی می‌شود. نمونهٔ استثنا از سه آرگومان به همان شیوه generator.throw() ساخته می‌شود.

تغییر در نسخهٔ ۳٫۱۲: امضای دوم (type[, value[, traceback]]) منسوخ شده است و ممکن است در نسخهٔ آیندهٔ پایتون حذف شود.

agen.aclose() (ناهمگام) : یک awaitable برمی‌گرداند که وقتی اجرا شود، GeneratorExit را در نقطه‌ای که تابع مولد ناهمگام زیربنایی در حال حاضر معلق است به آن پرتاب می‌کند (معادل فراخوانی athrow(GeneratorExit)).

اگر تابع مولد ناهمگام سپس با آرامش خارج شود، از قبل بسته شده باشد، یا GeneratorExit را پرتاب کند (با نگرفتن استثنا)، آنگاه awaitable برگردانده‌شده استثنای StopIteration را پرتاب می‌کند. هر awaitable بعدی که توسط فراخوانی‌های بعدی مولد ناهمگام برگردانده شود استثنای StopAsyncIteration را پرتاب می‌کند.

اگر مولد ناهمگام مقداری yield کند، RuntimeError توسط awaitable پرتاب می‌شود. اگر مولد ناهمگام استثنای دیگری پرتاب کند، آن استثنا به فراخواننده awaitable منتشر می‌شود.

اگر مولد ناهمگام از قبل به دلیل استثنا یا خروج عادی خارج شده باشد، فراخوانی‌های بعدی aclose() awaitableی برمی‌گردانند که کاری نمی‌کند.

نوع‌های دنباله — list، tuple، range

سه نوع دنبالهٔ پایه وجود دارد: فهرست‌ها، تاپل‌ها و اشیای range. نوع‌های دنبالهٔ اضافی که برای پردازش داده‌های دودویی و رشته‌های متنی سفارشی شده‌اند در بخش‌های اختصاصی توصیف می‌شوند.

عملیات مشترک دنباله‌ها

عملیات جدول زیر توسط بیشتر نوع‌های دنباله، چه تغییرپذیر و چه تغییرناپذیر، پشتیبانی می‌شود. ABC با نام collections.abc.Sequence فراهم شده تا پیاده‌سازی درست این عملیات روی نوع‌های دنبالهٔ سفارشی آسان‌تر شود.

این جدول عملیات دنباله را به ترتیب صعودی اولویت فهرست می‌کند. در جدول، s و t دنباله‌هایی از یک نوع هستند، n، i، j و k اعداد صحیح‌اند و x شیئی دلخواه است که هر محدودیت نوع و مقدار تحمیل‌شده توسط s را برآورده می‌کند.

عملیات in و not in اولویت‌های یکسانی با عملیات مقایسه دارند. عملیات + (الحاق) و * (تکرار) اولویت یکسانی با عملیات عددی متناظر دارند. ^۳

برای هزینهٔ عملیات گوناگون دنباله پیچیدگی زمانی را ببینید.

دنباله‌های از یک نوع از مقایسه‌ها هم پشتیبانی می‌کنند. به‌ویژه، تاپل‌ها و فهرست‌ها با مقایسهٔ عناصر متناظر به‌صورت لغت‌نامه‌ای (lexicographically) مقایسه می‌شوند. یعنی برای برابر بودن، هر عنصر باید برابر مقایسه شود و دو دنباله باید از یک نوع باشند و طول یکسان داشته باشند. (برای جزئیات کامل مقایسه‌ها را در راهنمای زبان ببینید.)

تکرارگرهای رو به جلو و معکوس روی دنباله‌های تغییرپذیر با استفاده از یک اندیس به مقادیر دسترسی پیدا می‌کنند. آن اندیس حتی اگر دنبالهٔ زیربنایی تغییر کند به پیشروی (یا پس‌روی) ادامه می‌دهد. تکرارگر فقط وقتی پایان می‌یابد که IndexError یا StopIteration مواجه شود (یا وقتی اندیس زیر صفر بیفتد).

یادداشت‌ها:

1. در حالی که عملیات in و not in در حالت کلی فقط برای آزمون ساده شمول به کار می‌روند، برخی دنباله‌های تخصصی (مانند str، bytes و bytearray) آن‌ها را برای آزمون زیردنباله هم به کار می‌برند:

   >>> "gg" in "eggs"
   True

2. مقادیر n کمتر از 0 به‌عنوان 0 تلقی می‌شوند (که دنباله‌ای خالی از همان نوع s می‌دهد). توجه کنید که عناصر دنبالهٔ s کپی نمی‌شوند؛ چندین بار به آن‌ها ارجاع داده می‌شود. این اغلب برنامه‌نویسان تازه‌کار پایتون را آزار می‌دهد؛ این را در نظر بگیرید:

   >>> lists = [[]] * 3
   >>> lists
   [[], [], []]
   >>> lists[0].append(3)
   >>> lists
   [[3], [3], [3]]

   آنچه اتفاق افتاده این است که [[]] فهرستی تک‌عنصری حاوی یک فهرست خالی است، بنابراین هر سه عنصر [[]] * 3 ارجاع‌هایی به همین یک فهرست خالی هستند. تغییر هر یک از عناصر lists همین فهرست واحد را تغییر می‌دهد. می‌توانید فهرستی از فهرست‌های متفاوت را این‌طور بسازید:

   >>> lists = [[] for i in range(3)]
   >>> lists[0].append(3)
   >>> lists[1].append(5)
   >>> lists[2].append(7)
   >>> lists
   [[3], [5], [7]]

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

3. اگر i یا j منفی باشد، اندیس نسبت به انتهای دنبالهٔ s است: len(s) + i یا len(s) + j جایگزین می‌شود. اما توجه کنید که -0 همچنان 0 است.

4. برش s از i تا j به‌صورت دنبالهٔ عناصری با اندیس k تعریف می‌شود که i <= k < j.

   • اگر i حذف شده یا None باشد، 0 به کار می‌رود.
   • اگر j حذف شده یا None باشد، len(s) به کار می‌رود.
   • اگر i یا j کمتر از -len(s) باشد، 0 به کار می‌رود.
   • اگر i یا j بیشتر از len(s) باشد، len(s) به کار می‌رود.
   • اگر i بزرگ‌تر یا مساوی j باشد، برش خالی است.

5. برش s از i تا j با گام k به‌صورت دنبالهٔ عناصری با اندیس x = i + n*k تعریف می‌شود که 0 <= n < (j-i)/k. به عبارت دیگر، اندیس‌ها i، i+k، i+2*k، i+3*k و غیره هستند، و با رسیدن به j متوقف می‌شوند (اما هرگز j را شامل نمی‌شوند). وقتی k مثبت است، اگر i و j بزرگ‌تر باشند به len(s) کاهش می‌یابند. وقتی k منفی است، اگر i و j بزرگ‌تر باشند به len(s) - 1 کاهش می‌یابند. اگر i یا j حذف شده یا None باشند، به مقادیر «انتها» تبدیل می‌شوند (که کدام انتها بستگی به علامت k دارد). توجه کنید، k نمی‌تواند صفر باشد. اگر k برابر None باشد، مانند 1 تلقی می‌شود.

6. الحاق دنباله‌های تغییرناپذیر همیشه شیء جدیدی می‌سازد. این یعنی ساختن دنباله با الحاق مکرر هزینهٔ زمان اجرای درجه دوم (quadratic) نسبت به طول کل دنباله دارد. برای رسیدن به هزینهٔ زمان اجرای خطی، باید به یکی از جایگزین‌های زیر روی بیاورید:

   • اگر اشیای str را الحاق می‌کنید، می‌توانید فهرستی بسازید و در پایان از str.join() استفاده کنید، یا در یک نمونهٔ io.StringIO بنویسید و مقدار آن را پس از تکمیل بازیابی کنید
   • اگر اشیای bytes را الحاق می‌کنید، می‌توانید به همین ترتیب از bytes.join() یا io.BytesIO استفاده کنید، یا می‌توانید الحاق درجا را با شیء bytearray انجام دهید. اشیای bytearray تغییرپذیرند و سازوکار تخصیص اضافی (overallocation) کارآمدی دارند
   • اگر اشیای tuple را الحاق می‌کنید، به‌جای آن یک list را گسترش دهید
   • برای نوع‌های دیگر، مستندات کلاس مربوطه را بررسی کنید

7. برخی نوع‌های دنباله (مانند range) فقط دنباله‌هایی از عناصر را که الگوهای مشخصی را دنبال می‌کنند پشتیبانی می‌کنند، و بنابراین الحاق یا تکرار دنباله را پشتیبانی نمی‌کنند.

8. اگر i خارج از بازهٔ دنباله باشد، IndexError پرتاب می‌شود.

متدهای دنباله

نوع‌های دنباله متدهای زیر را هم پشتیبانی می‌کنند:

list.count(value, /)، range.count(value, /)، tuple.count(value, /) (به‌طور کلی sequence.count(value, /)) : تعداد کل وقوع‌های value را در sequence برمی‌گرداند.

list.index(value[, start[, stop]])، range.index(value[, start[, stop]])، tuple.index(value[, start[, stop]]) (به‌طور کلی sequence.index(value[, start[, stop]])) : اندیس اولین وقوع value را در sequence برمی‌گرداند.

اگر value در sequence پیدا نشود ValueError پرتاب می‌کند.

آرگومان‌های start یا stop جست‌وجوی کارآمد زیربخش‌های دنباله را، از start آغاز و در stop پایان‌یافته، ممکن می‌کنند. این تقریباً معادل start + sequence[start:stop].index(value) است، فقط بدون کپی کردن هیچ داده‌ای.

احتیاط: همهٔ نوع‌های دنباله دادن آرگومان‌های start و stop را پشتیبانی نمی‌کنند.

نوع‌های دنبالهٔ تغییرناپذیر

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

این پشتیبانی به دنباله‌های تغییرناپذیر، مانند نمونه‌های tuple، اجازه می‌دهد به‌عنوان کلید dict به کار روند و در نمونه‌های set و frozenset ذخیره شوند.

تلاش برای هش کردن یک دنبالهٔ تغییرناپذیر که مقادیر غیرهش‌پذیر (unhashable) دارد به TypeError می‌انجامد.

نوع‌های دنبالهٔ تغییرپذیر

عملیات جدول زیر روی نوع‌های دنبالهٔ تغییرپذیر تعریف شده‌اند. ABC با نام collections.abc.MutableSequence فراهم شده تا پیاده‌سازی درست این عملیات روی نوع‌های دنبالهٔ سفارشی آسان‌تر شود.

در جدول s نمونه‌ای از یک نوع دنبالهٔ تغییرپذیر است، t هر شیء تکرارپذیری است و x شیئی دلخواه است که هر محدودیت نوع و مقدار تحمیل‌شده توسط s را برآورده می‌کند (برای مثال، bytearray فقط اعداد صحیحی را می‌پذیرد که محدودیت مقدار 0 <= x <= 255 را برآورده کنند).

یادداشت‌ها:

1. اگر k برابر 1 نباشد، t باید همان طولی را داشته باشد که برشی که جایگزین می‌کند دارد.
2. مقدار n یک عدد صحیح یا شیئی است که __index__() را پیاده می‌کند. مقادیر صفر و منفی n دنباله را پاک می‌کنند. عناصر دنباله کپی نمی‌شوند؛ چندین بار به آن‌ها ارجاع داده می‌شود، همان‌طور که برای s * n در عملیات مشترک دنباله‌ها توضیح داده شد.

متدهای دنبالهٔ تغییرپذیر

نوع‌های دنبالهٔ تغییرپذیر متدهای زیر را هم پشتیبانی می‌کنند:

bytearray.append(value, /)، list.append(value, /) (به‌طور کلی sequence.append(value, /)) : value را به انتهای دنباله اضافه می‌کند. این معادل نوشتن seq[len(seq):len(seq)] = [value] است.

bytearray.clear()، list.clear() (به‌طور کلی sequence.clear()) : همهٔ عناصر را از sequence حذف می‌کند. این معادل نوشتن del sequence[:] است.

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

bytearray.copy()، list.copy() (به‌طور کلی sequence.copy()) : یک کپی سطحی (shallow) از sequence می‌سازد. این معادل نوشتن sequence[:] است.

نکته: متد copy() بخشی از MutableSequence ABC نیست، اما بیشتر نوع‌های مشخص دنبالهٔ تغییرپذیر آن را فراهم می‌کنند.

افزوده‌شده در نسخهٔ ۳٫۳. bytearray.extend(iterable, /)، list.extend(iterable, /) (به‌طور کلی sequence.extend(iterable, /)) : sequence را با محتوای iterable گسترش می‌دهد. در بیشتر موارد این همان نوشتن seq[len(seq):len(seq)] = iterable است.

bytearray.insert(index, value, /)، list.insert(index, value, /) (به‌طور کلی sequence.insert(index, value, /)) : value را در sequence در index داده‌شده درج می‌کند. این معادل نوشتن sequence[index:index] = [value] است.

bytearray.pop(index=-1, /)، list.pop(index=-1, /) (به‌طور کلی sequence.pop(index=-1, /)) : مورد در index را بازیابی می‌کند و همچنین از sequence حذف می‌کند. به‌طور پیش‌فرض آخرین مورد sequence حذف و برگردانده می‌شود.

bytearray.remove(value, /)، list.remove(value, /) (به‌طور کلی sequence.remove(value, /)) : اولین موردی را که sequence[i] == value است از sequence حذف می‌کند.

اگر value در sequence پیدا نشود ValueError پرتاب می‌کند.

bytearray.reverse()، list.reverse() (به‌طور کلی sequence.reverse()) : موارد sequence را درجا برعکس می‌کند. این متد هنگام برعکس کردن دنبالهٔ بزرگ در مصرف فضا صرفه‌جویی می‌کند. برای یادآوری به کاربران که با اثر جانبی کار می‌کند، None برمی‌گرداند.

فهرست‌ها (Lists)

فهرست‌ها دنباله‌های تغییرپذیرند که معمولاً برای نگهداری مجموعه‌ای از موارد همگن به کار می‌روند (درجهٔ دقیق شباهت بسته به کاربرد فرق می‌کند).

class list(iterable=(), /) : فهرست‌ها را می‌توان به چند روش ساخت:

• با یک جفت کروشه برای نشان دادن فهرست خالی: []
• با کروشه و جدا کردن موارد با ویرگول: [a]، [a, b, c]
• با فهرست‌فشرده (list comprehension): [x for x in iterable]
• با سازندهٔ نوع: list() یا list(iterable)

سازنده فهرستی می‌سازد که مواردش همان و به همان ترتیب موارد iterable است. iterable می‌تواند دنباله، ظرفی که تکرار را پشتیبانی می‌کند، یا شیء تکرارگر باشد. اگر iterable از قبل فهرست باشد، یک کپی ساخته و برگردانده می‌شود، شبیه iterable[:]. برای مثال، list('abc') مقدار ['a', 'b', 'c'] و list( (1, 2, 3) ) مقدار [1, 2, 3] را برمی‌گرداند. اگر آرگومانی داده نشود، سازنده فهرست خالی جدید [] می‌سازد.

بسیاری عملیات دیگر هم فهرست تولید می‌کنند، از جمله تابع درون‌ساخت sorted().

فهرست‌ها نسبت به نوع موارد خود عمومی (generic) هستند.

فهرست‌ها همهٔ عملیات مشترک و تغییرپذیر دنباله را پیاده می‌کنند. فهرست‌ها متد اضافی زیر را هم فراهم می‌کنند:

list.sort(*, key=None, reverse=False) : این متد فهرست را درجا مرتب می‌کند و فقط از مقایسه‌های < بین موارد استفاده می‌کند. استثناها سرکوب نمی‌شوند — اگر هر عملیات مقایسه شکست بخورد، کل عملیات مرتب‌سازی شکست می‌خورد (و فهرست احتمالاً در حالت تغییریافتهٔ ناقص رها می‌شود).

sort() دو آرگومان می‌پذیرد که فقط به‌صورت کلیدواژه‌ای قابل ارسال‌اند (آرگومان‌های فقط‌کلیدواژه‌ای):

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

ابزار functools.cmp_to_key() برای تبدیل تابع cmp به سبک ۲٫x به تابع key در دسترس است.

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

این متد برای صرفه‌جویی در فضا هنگام مرتب‌سازی دنبالهٔ بزرگ، دنباله را درجا تغییر می‌دهد. برای یادآوری به کاربران که با اثر جانبی کار می‌کند، دنبالهٔ مرتب‌شده را برنمی‌گرداند (برای درخواست صریح نمونهٔ فهرست مرتب‌شدهٔ جدید از sorted() استفاده کنید).

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

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

جزئیات پیاده‌سازی (CPython): در حالی که فهرستی در حال مرتب شدن است، اثر تلاش برای تغییر دادن یا حتی بررسی فهرست تعریف‌نشده است. پیاده‌سازی C پایتون در این مدت فهرست را خالی نشان می‌دهد، و اگر تشخیص دهد که فهرست در حین مرتب‌سازی تغییر کرده، ValueError پرتاب می‌کند.

همچنین ببینید: برای اطلاعات دقیق دربارهٔ تضمین‌های ایمنی نخ (thread-safety) برای اشیای list، ایمنی نخ برای اشیای list را ببینید.

تاپل‌ها (Tuples)

تاپل‌ها دنباله‌های تغییرناپذیرند که معمولاً برای نگهداری مجموعه‌ای از داده‌های ناهمگن به کار می‌روند (مانند تاپل‌های ۲تایی که تابع درون‌ساخت enumerate() تولید می‌کند). تاپل‌ها در مواردی هم به کار می‌روند که دنبالهٔ تغییرناپذیر از داده‌های همگن لازم است (مانند اجازهٔ ذخیره در نمونهٔ set یا dict).

class tuple(iterable=(), /) : تاپل‌ها را می‌توان به چند روش ساخت:

• با یک جفت پرانتز برای نشان دادن تاپل خالی: ()
• با ویرگول پایانی برای تاپل تک‌عنصری: a, یا (a,)
• با جدا کردن موارد با ویرگول: a, b, c یا (a, b, c)
• با تابع درون‌ساخت tuple(): tuple() یا tuple(iterable)

سازنده تاپلی می‌سازد که مواردش همان و به همان ترتیب موارد iterable است. iterable می‌تواند دنباله، ظرفی که تکرار را پشتیبانی می‌کند، یا شیء تکرارگر باشد. اگر iterable از قبل تاپل باشد، بدون تغییر برگردانده می‌شود. برای مثال، tuple('abc') مقدار ('a', 'b', 'c') و tuple( [1, 2, 3] ) مقدار (1, 2, 3) را برمی‌گرداند. اگر آرگومانی داده نشود، سازنده تاپل خالی جدید () می‌سازد.

توجه کنید که در واقع ویرگول است که تاپل می‌سازد، نه پرانتزها. پرانتزها اختیاری‌اند، به‌جز در حالت تاپل خالی، یا وقتی برای پرهیز از ابهام نحوی لازم باشند. برای مثال، f(a, b, c) فراخوانی تابع با سه آرگومان است، در حالی که f((a, b, c)) فراخوانی تابع با یک ۳‌تاپل به‌عنوان تنها آرگومان است.

تاپل‌ها همهٔ عملیات مشترک دنباله را پیاده می‌کنند.

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

برای مجموعه‌های ناهمگن داده که دسترسی با نام روشن‌تر از دسترسی با اندیس است، collections.namedtuple() ممکن است انتخاب مناسب‌تری از یک شیء تاپل ساده باشد.

بازه‌ها (Ranges)

نوع range دنبالهٔ تغییرناپذیری از اعداد را نشان می‌دهد و معمولاً برای تکرار تعداد مشخصی بار در حلقه‌های for به کار می‌رود.

class range(stop, /) و class range(start, stop, step=1, /) : آرگومان‌های سازندهٔ range باید اعداد صحیح باشند (یا int درون‌ساخت یا هر شیئی که متد ویژهٔ __index__() را پیاده می‌کند). اگر آرگومان step حذف شود، پیش‌فرض آن 1 است. اگر آرگومان start حذف شود، پیش‌فرض آن 0 است. اگر step صفر باشد، ValueError پرتاب می‌شود.

برای step مثبت، محتوای range به نام r با فرمول r[i] = start + step*i تعیین می‌شود، که i >= 0 و r[i] < stop.

برای step منفی، محتوای range همچنان با فرمول r[i] = start + step*i تعیین می‌شود، اما محدودیت‌ها i >= 0 و r[i] > stop هستند.

اگر r[0] محدودیت مقدار را برآورده نکند، شیء range خالی خواهد بود. range‌ها اندیس‌های منفی را پشتیبانی می‌کنند، اما این‌ها به‌صورت اندیس‌گذاری از انتهای دنباله‌ای که با اندیس‌های مثبت تعیین می‌شود تفسیر می‌شوند.

range‌هایی که حاوی مقادیر مطلق بزرگ‌تر از sys.maxsize باشند مجازند اما برخی ویژگی‌ها (مانند len()) ممکن است OverflowError پرتاب کنند.

مثال‌های range:

>>> list(range(10))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> list(range(1, 11))
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> list(range(0, 30, 5))
[0, 5, 10, 15, 20, 25]
>>> list(range(0, 10, 3))
[0, 3, 6, 9]
>>> list(range(0, -10, -1))
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> list(range(0))
[]
>>> list(range(1, 0))
[]

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

start : مقدار پارامتر start (یا 0 اگر پارامتر داده نشده باشد)

stop : مقدار پارامتر stop

step : مقدار پارامتر step (یا 1 اگر پارامتر داده نشده باشد)

مزیت نوع range نسبت به list یا tuple معمولی این است که شیء range همیشه مقدار حافظهٔ یکسان (کوچکی) می‌گیرد، صرف‌نظر از اندازهٔ range‌ای که نشان می‌دهد (چون فقط مقادیر start، stop و step را ذخیره می‌کند و موارد منفرد و زیربازه‌ها را در صورت نیاز محاسبه می‌کند).

اشیای range ABC با نام collections.abc.Sequence را پیاده می‌کنند و ویژگی‌هایی مانند آزمون شمول، جست‌وجوی اندیس عنصر، برش و پشتیبانی از اندیس‌های منفی را فراهم می‌کنند (به نوع‌های دنباله مراجعه کنید):

>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18

آزمودن برابری اشیای range با == و != آن‌ها را به‌صورت دنباله مقایسه می‌کند. یعنی دو شیء range برابر تلقی می‌شوند اگر دنبالهٔ یکسانی از مقادیر را نشان دهند. (توجه کنید که دو شیء range که برابر مقایسه می‌شوند ممکن است ویژگی‌های start، stop و step متفاوتی داشته باشند، برای مثال range(0) == range(2, 1, 3) یا range(0, 3, 2) == range(0, 4, 2).)

تغییر در نسخهٔ ۳٫۲: دنبالهٔ ABC پیاده‌سازی شد. برش و اندیس‌های منفی پشتیبانی می‌شوند. اشیای int برای عضویت در زمان ثابت آزموده می‌شوند، به‌جای تکرار روی همهٔ موارد.

تغییر در نسخهٔ ۳٫۳: == و != طوری تعریف شدند که اشیای range را بر اساس دنبالهٔ مقادیری که تعریف می‌کنند مقایسه کنند (به‌جای مقایسه بر اساس هویت شیء).

ویژگی‌های start، stop و step افزوده شدند.

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

• دستور پخت linspace نشان می‌دهد چگونه نسخهٔ تنبل (lazy) range مناسب کاربردهای ممیز شناور را پیاده کنیم.

خلاصهٔ متدهای نوع‌های دنبالهٔ متنی و دودویی

جدول زیر متدهای نوع‌های دنبالهٔ متنی و دودویی را بر اساس دسته خلاصه می‌کند.

نوع دنبالهٔ متنی — str

داده‌های متنی در پایتون با اشیای str، یا رشته‌ها (strings)، مدیریت می‌شوند. رشته‌ها دنباله‌های تغییرناپذیر از نقاط کد یونیکد هستند. لیترال‌های رشته به روش‌های گوناگون نوشته می‌شوند:

• گیومهٔ تکی: 'allows embedded "double" quotes'
• گیومهٔ دوتایی: "allows embedded 'single' quotes"
• سه‌گیومه‌ای: '''Three single quotes'''، """Three double quotes"""

رشته‌های سه‌گیومه‌ای ممکن است چند خط را دربر گیرند - همهٔ فضاهای خالی مرتبط در لیترال رشته گنجانده می‌شوند.

لیترال‌های رشته‌ای که بخشی از یک عبارت واحدند و فقط فضای خالی بینشان است ضمناً به یک لیترال رشتهٔ واحد تبدیل می‌شوند. یعنی ("spam " "eggs") == "spam eggs".

برای اطلاعات بیشتر دربارهٔ شکل‌های گوناگون لیترال رشته، از جمله دنباله‌های گریز (escape sequences) پشتیبانی‌شده، و پیشوند r («خام»، raw) که بیشتر پردازش دنبالهٔ گریز را غیرفعال می‌کند، لیترال‌های رشته و بایت را ببینید.

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

از آنجا که نوع «نویسه» (character) جداگانه‌ای وجود ندارد، اندیس‌گذاری یک رشته رشته‌هایی به طول ۱ تولید می‌کند. یعنی برای رشتهٔ ناتهی s، s[0] == s[0:1].

همچنین نوع رشتهٔ تغییرپذیر وجود ندارد، اما str.join() یا io.StringIO را می‌توان برای ساخت کارآمد رشته‌ها از چند قطعه به کار برد.

تغییر در نسخهٔ ۳٫۳: برای سازگاری با گذشته با سری پایتون ۲، پیشوند u دوباره روی لیترال‌های رشته مجاز است. بر معنای لیترال‌های رشته تأثیری ندارد و نمی‌توان آن را با پیشوند r ترکیب کرد.

class str(*, encoding='utf-8', errors='strict')، class str(object)، class str(object, encoding, errors='strict')، class str(object, *, errors) : نسخهٔ رشته‌ای object را برمی‌گرداند. اگر object داده نشود، رشتهٔ خالی برمی‌گرداند. در غیر این صورت، رفتار str() بسته به اینکه encoding یا errors داده شده باشد یا نه به این صورت است.

اگر نه encoding و نه errors داده شده باشد، str(object) مقدار type(object).__str__(object) را برمی‌گرداند، که نمایش رشته‌ای «غیررسمی» یا زیبای‌قابل‌چاپ object است. برای اشیای رشته‌ای، خود رشته است. اگر object متد __str__() نداشته باشد، str() به برگرداندن repr(object) بازمی‌گردد.

اگر دست‌کم یکی از encoding یا errors داده شده باشد، object باید یک شیء شبه‌بایت (bytes-like object) باشد (مثلاً bytes یا bytearray). در این حالت، اگر object شیء bytes (یا bytearray) باشد، str(bytes, encoding, errors) معادل bytes.decode(encoding, errors) است. در غیر این صورت، شیء بایت زیربنای شیء بافر پیش از فراخوانی bytes.decode() به دست می‌آید. برای اطلاعات دربارهٔ اشیای بافر نوع‌های دنبالهٔ دودویی و پروتکل بافر را ببینید.

ارسال شیء bytes به str() بدون آرگومان‌های encoding یا errors در حالت اول، یعنی برگرداندن نمایش رشته‌ای غیررسمی قرار می‌گیرد (گزینهٔ خط فرمان -b پایتون را هم ببینید). برای مثال:

>>> str(b'Zoot!')
"b'Zoot!'"

برای اطلاعات بیشتر دربارهٔ کلاس str و متدهایش، نوع دنبالهٔ متنی و بخش متدهای رشته در ادامه را ببینید. برای خروجی رشته‌های قالب‌بندی‌شده، بخش‌های f-stringها و سینتکس رشتهٔ قالب را ببینید. علاوه بر این، بخش خدمات متن را ببینید.

متدهای رشته (String methods)

رشته‌ها همهٔ عملیات مشترک دنباله را به‌همراه متدهای اضافی که در ادامه توصیف می‌شوند پیاده می‌کنند.

رشته‌ها دو سبک قالب‌بندی رشته را هم پشتیبانی می‌کنند، یکی که درجهٔ بالایی از انعطاف و سفارشی‌سازی فراهم می‌کند (str.format()، سینتکس رشتهٔ قالب و قالب‌بندی رشتهٔ سفارشی را ببینید) و دیگری مبتنی بر قالب‌بندی به سبک printf زبان C که دامنهٔ محدودتری از نوع‌ها را مدیریت می‌کند و کمی دشوارتر درست استفاده می‌شود، اما برای مواردی که می‌تواند مدیریت کند اغلب سریع‌تر است (قالب‌بندی رشتهٔ به سبک printf).

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

str.capitalize() : نسخه‌ای از رشته را برمی‌گرداند که نویسهٔ اولش بزرگ شده و بقیه کوچک.

تغییر در نسخهٔ ۳٫۸: نویسهٔ اول اکنون به حالت titlecase درمی‌آید، نه uppercase. این یعنی نویسه‌هایی مانند دیگراف‌ها فقط حرف اولشان بزرگ می‌شود، نه کل نویسه.

str.casefold() : نسخهٔ casefold‌شدهٔ رشته را برمی‌گرداند. رشته‌های casefold‌شده را می‌توان برای تطبیق بدون حساسیت به حروف به کار برد.

Casefolding شبیه کوچک‌سازی حروف است اما تهاجمی‌تر، چون هدفش حذف همهٔ تمایزهای حروف در رشته است. برای مثال، حرف کوچک آلمانی 'ß' معادل "ss" است. چون از قبل کوچک است، lower() روی 'ß' کاری نمی‌کند؛ casefold() آن را به "ss" تبدیل می‌کند. برای مثال:

>>> 'straße'.lower()
'straße'
>>> 'straße'.casefold()
'strasse'

الگوریتم casefolding در بخش ۳٫۱۳٫۳ «Default Case Folding» استاندارد یونیکد توصیف شده است.

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

str.center(width, fillchar=' ', /) : رشته را در رشته‌ای به طول width وسط‌چین شده برمی‌گرداند. پر کردن با fillchar مشخص‌شده (پیش‌فرض فضای خالی ASCII) انجام می‌شود. اگر width کمتر یا مساوی len(s) باشد، رشتهٔ اصلی برگردانده می‌شود. برای مثال:

>>> 'Python'.center(10)
'  Python  '
>>> 'Python'.center(10, '-')
'--Python--'
>>> 'Python'.center(4)
'Python'

str.count(sub[, start[, end]]) : تعداد وقوع‌های بدون هم‌پوشانی زیررشتهٔ sub را در بازهٔ [start, end] برمی‌گرداند. آرگومان‌های اختیاری start و end مانند نمادگذاری برش تفسیر می‌شوند.

اگر sub خالی باشد، تعداد رشته‌های خالی بین نویسه‌ها را برمی‌گرداند که طول رشته به‌اضافهٔ یک است. برای مثال:

>>> 'spam, spam, spam'.count('spam')
3
>>> 'spam, spam, spam'.count('spam', 5)
2
>>> 'spam, spam, spam'.count('spam', 5, 10)
1
>>> 'spam, spam, spam'.count('eggs')
0
>>> 'spam, spam, spam'.count('')
17

str.encode(encoding="utf-8", errors="strict") : رشتهٔ کدگذاری‌شده به bytes را برمی‌گرداند.

encoding به‌طور پیش‌فرض 'utf-8' است؛ برای مقادیر ممکن کدگذاری‌های استاندارد را ببینید.

errors نحوهٔ مدیریت خطاهای کدگذاری را کنترل می‌کند. اگر 'strict' (پیش‌فرض) باشد، استثنای UnicodeError پرتاب می‌شود. مقادیر ممکن دیگر 'ignore'، 'replace'، 'xmlcharrefreplace'، 'backslashreplace' و هر نام دیگر ثبت‌شده با codecs.register_error() هستند. برای جزئیات مدیریت‌کننده‌های خطا را ببینید.

به دلایل کارایی، اعتبار مقدار errors بررسی نمی‌شود مگر آنکه واقعاً خطای کدگذاری رخ دهد، حالت توسعه (development mode) فعال باشد یا ساخت اشکال‌زدایی (debug build) به کار رود. برای مثال:

>>> encoded_str_to_bytes = 'Python'.encode()
>>> type(encoded_str_to_bytes)
<class 'bytes'>
>>> encoded_str_to_bytes
b'Python'

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

تغییر در نسخهٔ ۳٫۹: مقدار آرگومان errors اکنون در حالت توسعه و در حالت اشکال‌زدایی بررسی می‌شود.

str.endswith(suffix[, start[, end]]) : اگر رشته با suffix مشخص‌شده تمام شود True، وگرنه False برمی‌گرداند. suffix می‌تواند تاپلی از پسوندها برای جست‌وجو هم باشد. با start اختیاری، آزمون از آن موقعیت آغاز می‌شود. با end اختیاری، مقایسه در آن موقعیت متوقف می‌شود. استفاده از start و end معادل str[start:end].endswith(suffix) است. برای مثال:

>>> 'Python'.endswith('on')
True
>>> 'a tuple of suffixes'.endswith(('at', 'in'))
False
>>> 'a tuple of suffixes'.endswith(('at', 'es'))
True
>>> 'Python is amazing'.endswith('is', 0, 9)
True

همچنین startswith() و removesuffix() را ببینید.

str.expandtabs(tabsize=8) : نسخه‌ای از رشته را برمی‌گرداند که در آن همهٔ نویسه‌های tab بسته به ستون جاری و اندازهٔ tab داده‌شده با یک یا چند فاصله جایگزین شده‌اند. موقعیت‌های tab هر tabsize نویسه رخ می‌دهند (پیش‌فرض ۸ است، که موقعیت‌های tab را در ستون‌های ۰، ۸، ۱۶ و غیره می‌دهد). برای گسترش رشته، ستون جاری صفر قرار داده می‌شود و رشته نویسه‌به‌نویسه بررسی می‌شود. اگر نویسه tab (\t) باشد، یک یا چند نویسهٔ فاصله در نتیجه درج می‌شود تا ستون جاری با موقعیت tab بعدی برابر شود. (خود نویسهٔ tab کپی نمی‌شود.) اگر نویسه خط جدید (\n) یا return (\r) باشد، کپی می‌شود و ستون جاری به صفر بازنشانی می‌شود. هر نویسهٔ دیگر بدون تغییر کپی می‌شود و ستون جاری یکی افزایش می‌یابد، صرف‌نظر از اینکه نویسه هنگام چاپ چگونه نمایش داده می‌شود. برای مثال:

>>> '01\t012\t0123\t01234'.expandtabs()
'01      012     0123    01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01  012 0123    01234'
>>> print('01\t012\n0123\t01234'.expandtabs(4))
01  012
0123    01234

str.find(sub[, start[, end]]) : کمترین اندیسی در رشته را که زیررشتهٔ sub در برش s[start:end] یافت می‌شود برمی‌گرداند. آرگومان‌های اختیاری start و end مانند نمادگذاری برش تفسیر می‌شوند. اگر sub یافت نشود -1 برمی‌گرداند. برای مثال:

>>> 'spam, spam, spam'.find('sp')
0
>>> 'spam, spam, spam'.find('sp', 5)
6

همچنین rfind() و index() را ببینید.

نکته: متد find() فقط باید زمانی به کار رود که لازم است موقعیت sub را بدانید. برای بررسی اینکه sub زیررشته هست یا نه، از عملگر in استفاده کنید:

>>> 'Py' in 'Python'
True

str.format(*args, **kwargs) : عملیات قالب‌بندی رشته را انجام می‌دهد. رشته‌ای که این متد روی آن فراخوانی می‌شود می‌تواند متن لیترال یا فیلدهای جایگزینی محصور در آکولاد {} داشته باشد. هر فیلد جایگزینی یا اندیس عددی یک آرگومان موضعی یا نام یک آرگومان کلیدواژه‌ای را دربر دارد. نسخه‌ای از رشته را برمی‌گرداند که در آن هر فیلد جایگزینی با مقدار رشته‌ای آرگومان متناظر جایگزین شده است. برای مثال:

>>> "The sum of 1 + 2 is {0}".format(1+2)
'The sum of 1 + 2 is 3'
>>> "The sum of {a} + {b} is {answer}".format(answer=1+2, a=1, b=2)
'The sum of 1 + 2 is 3'
>>> "{1} expects the {0} Inquisition!".format("Spanish", "Nobody")
'Nobody expects the Spanish Inquisition!'

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

نکته: هنگام قالب‌بندی عدد (int، float، complex، decimal.Decimal و زیرکلاس‌ها) با نوع n (مثلاً '{:n}'.format(1234))، تابع به‌طور موقت locale مربوط به LC_CTYPE را برابر locale مربوط به LC_NUMERIC قرار می‌دهد تا فیلدهای decimal_point و thousands_sep تابع localeconv() را در صورتی که غیر ASCII یا طولانی‌تر از ۱ بایت باشند و locale مربوط به LC_NUMERIC با locale مربوط به LC_CTYPE فرق داشته باشد رمزگشایی کند. این تغییر موقت بر نخ‌های دیگر اثر می‌گذارد.

تغییر در نسخهٔ ۳٫۷: هنگام قالب‌بندی عدد با نوع n، تابع در برخی موارد به‌طور موقت locale مربوط به LC_CTYPE را برابر locale مربوط به LC_NUMERIC قرار می‌دهد.

str.format_map(mapping, /) : مشابه str.format(**mapping)، با این تفاوت که mapping مستقیماً به کار می‌رود و به dict کپی نمی‌شود. این برای مثال وقتی mapping زیرکلاس dict است مفید است:

>>> class Default(dict):
...     def __missing__(self, key):
...         return key
...
>>> '{name} was born in {country}'.format_map(Default(name='Guido'))
'Guido was born in country'

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

str.index(sub[, start[, end]]) : مانند find()، اما وقتی زیررشته یافت نشود ValueError پرتاب می‌کند. برای مثال:

>>> 'spam, spam, spam'.index('spam')
0
>>> 'spam, spam, spam'.index('eggs')
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    'spam, spam, spam'.index('eggs')
    ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found

همچنین rindex() را ببینید.

str.isalnum() : اگر همهٔ نویسه‌های رشته الفبایی‌عددی (alphanumeric) باشند و دست‌کم یک نویسه وجود داشته باشد True، وگرنه False برمی‌گرداند. نویسهٔ c الفبایی‌عددی است اگر یکی از این‌ها True برگرداند: c.isalpha()، c.isdecimal()، c.isdigit() یا c.isnumeric(). برای مثال:

>>> 'abc123'.isalnum()
True
>>> 'abc123!@#'.isalnum()
False
>>> ''.isalnum()
False
>>> ' '.isalnum()
False

str.isalpha() : اگر همهٔ نویسه‌های رشته الفبایی باشند و دست‌کم یک نویسه وجود داشته باشد True، وگرنه False برمی‌گرداند. نویسه‌های الفبایی نویسه‌هایی هستند که در پایگاه دادهٔ نویسه‌های یونیکد به‌عنوان «Letter» تعریف شده‌اند، یعنی آن‌هایی که ویژگی رده‌بندی کلی‌شان یکی از «Lm»، «Lt»، «Lu»، «Ll» یا «Lo» است. توجه کنید که این با ویژگی Alphabetic تعریف‌شده در بخش ۴٫۱۰ «Letters, Alphabetic, and Ideographic» استاندارد یونیکد فرق دارد. برای مثال:

>>> 'Letters and spaces'.isalpha()
False
>>> 'LettersOnly'.isalpha()
True
>>> 'µ'.isalpha()  # non-ASCII characters can be considered alphabetical too
True

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

str.isascii() : اگر رشته خالی باشد یا همهٔ نویسه‌های رشته ASCII باشند True، وگرنه False برمی‌گرداند. نویسه‌های ASCII نقاط کدی در بازهٔ U+0000-U+007F دارند. برای مثال:

>>> 'ASCII characters'.isascii()
True
>>> 'µ'.isascii()
False

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

str.isdecimal() : اگر همهٔ نویسه‌های رشته نویسه‌های دهدهی (decimal) باشند و دست‌کم یک نویسه وجود داشته باشد True، وگرنه False برمی‌گرداند. نویسه‌های دهدهی آن‌هایی هستند که می‌توان با آن‌ها اعداد در مبنای ۱۰ ساخت، مانند U+0660، ARABIC-INDIC DIGIT ZERO. به‌طور رسمی نویسهٔ دهدهی نویسه‌ای در رده‌بندی کلی یونیکد «Nd» است. برای مثال:

>>> '0123456789'.isdecimal()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isdecimal()  # Arabic-Indic digits zero to nine
True
>>> 'alphabetic'.isdecimal()
False

str.isdigit() : اگر همهٔ نویسه‌های رشته رقم (digit) باشند و دست‌کم یک نویسه وجود داشته باشد True، وگرنه False برمی‌گرداند. ارقام شامل نویسه‌های دهدهی و ارقامی هستند که به رسیدگی ویژه نیاز دارند، مانند ارقام بالانویس سازگاری (compatibility superscript). این شامل ارقامی می‌شود که نمی‌توان با آن‌ها اعداد مبنای ۱۰ ساخت، مانند اعداد Kharosthi. به‌طور رسمی رقم نویسه‌ای است که مقدار ویژگی Numeric_Type=Digit یا Numeric_Type=Decimal دارد.

برای مثال:

>>> '0123456789'.isdigit()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isdigit()  # Arabic-Indic digits zero to nine
True
>>> '⅕'.isdigit()  # Vulgar fraction one fifth
False
>>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
(False, True, True)

همچنین isdecimal() و isnumeric() را ببینید.

str.isidentifier() : اگر رشته طبق تعریف زبان، بخش شناسه‌ها و کلیدواژه‌ها، شناسهٔ معتبر باشد True برمی‌گرداند.

از keyword.iskeyword() می‌توان برای آزمودن اینکه رشتهٔ s شناسهٔ رزروشده‌ای مانند def و class هست یا نه استفاده کرد.

مثال:

>>> from keyword import iskeyword

>>> 'hello'.isidentifier(), iskeyword('hello')
(True, False)
>>> 'def'.isidentifier(), iskeyword('def')
(True, True)

str.islower() : اگر همهٔ نویسه‌های دارای حالت (cased) ^۴ در رشته کوچک (lowercase) باشند و دست‌کم یک نویسهٔ دارای حالت وجود داشته باشد True، وگرنه False برمی‌گرداند.

str.isnumeric() : اگر همهٔ نویسه‌های رشته نویسه‌های عددی (numeric) باشند و دست‌کم یک نویسه وجود داشته باشد True، وگرنه False برمی‌گرداند. نویسه‌های عددی شامل نویسه‌های رقم و همهٔ نویسه‌هایی هستند که ویژگی مقدار عددی یونیکد دارند، مثلاً U+2155، VULGAR FRACTION ONE FIFTH. به‌طور رسمی، نویسه‌های عددی آن‌هایی هستند که مقدار ویژگی Numeric_Type=Digit، Numeric_Type=Decimal یا Numeric_Type=Numeric دارند. برای مثال:

>>> '0123456789'.isnumeric()
True
>>> '٠١٢٣٤٥٦٧٨٩'.isnumeric()  # Arabic-Indic digits zero to nine
True
>>> '⅕'.isnumeric()  # Vulgar fraction one fifth
True
>>> '²'.isdecimal(), '²'.isdigit(),  '²'.isnumeric()
(False, True, True)

همچنین isdecimal() و isdigit() را ببینید.

str.isprintable() : اگر همهٔ نویسه‌های رشته چاپ‌شدنی (printable) باشند True، و اگر دست‌کم یک نویسهٔ چاپ‌نشدنی داشته باشد False برمی‌گرداند.

در اینجا «چاپ‌شدنی» یعنی نویسه برای استفادهٔ repr() در خروجی‌اش مناسب است؛ «چاپ‌نشدنی» یعنی repr() روی نوع‌های درون‌ساخت نویسه را به‌صورت هگز گریز می‌دهد. این ربطی به مدیریت رشته‌های نوشته‌شده در sys.stdout یا sys.stderr ندارد.

نویسه‌های چاپ‌شدنی آن‌هایی هستند که در پایگاه دادهٔ نویسه‌های یونیکد (ماژول unicodedata را ببینید) رده‌بندی کلی‌شان در گروه Letter، Mark، Number، Punctuation یا Symbol (L، M، N، P یا S) است؛ به‌اضافهٔ فاصلهٔ ASCII یعنی 0x20. نویسه‌های چاپ‌نشدنی آن‌هایی هستند که در گروه Separator یا Other (Z یا C) هستند، به‌جز فاصلهٔ ASCII.

برای مثال:

>>> ''.isprintable(), ' '.isprintable()
(True, True)
>>> '\t'.isprintable(), '\n'.isprintable()
(False, False)

همچنین isspace() را ببینید.

str.isspace() : اگر رشته فقط نویسه‌های فضای خالی (whitespace) داشته باشد و دست‌کم یک نویسه وجود داشته باشد True، وگرنه False برمی‌گرداند.

برای مثال:

>>> ''.isspace()
False
>>> ' '.isspace()
True
>>> '\t\n'.isspace() # TAB and BREAK LINE
True
>>> '　'.isspace() # IDEOGRAPHIC SPACE
True

نویسه فضای خالی است اگر در پایگاه دادهٔ نویسه‌های یونیکد (unicodedata را ببینید)، یا رده‌بندی کلی‌اش Zs («Separator, space») باشد، یا کلاس دوجهته (bidirectional)اش یکی از WS، B یا S باشد.

همچنین isprintable() را ببینید.

str.istitle() : اگر رشته رشتهٔ titlecase‌شده باشد و دست‌کم یک نویسه داشته باشد True برمی‌گرداند؛ برای مثال نویسه‌های بزرگ فقط می‌توانند بعد از نویسه‌های بدون حالت (uncased) بیایند و نویسه‌های کوچک فقط بعد از نویسه‌های دارای حالت. در غیر این صورت False برمی‌گرداند.

برای مثال:

>>> 'Spam, Spam, Spam'.istitle()
True
>>> 'spam, spam, spam'.istitle()
False
>>> 'SPAM, SPAM, SPAM'.istitle()
False

همچنین title() را ببینید.

str.isupper() : اگر همهٔ نویسه‌های دارای حالت ^۴ در رشته بزرگ (uppercase) باشند و دست‌کم یک نویسهٔ دارای حالت وجود داشته باشد True، وگرنه False برمی‌گرداند.

>>> 'BANANA'.isupper()
True
>>> 'banana'.isupper()
False
>>> 'baNana'.isupper()
False
>>> ' '.isupper()
False

str.join(iterable, /) : رشته‌ای برمی‌گرداند که الحاق رشته‌های موجود در iterable است. اگر در iterable مقادیر غیررشته‌ای باشد، از جمله اشیای bytes، TypeError پرتاب می‌شود. جداکنندهٔ بین عناصر رشته‌ای است که این متد را فراهم می‌کند. برای مثال:

>>> ', '.join(['spam', 'spam', 'spam'])
'spam, spam, spam'
>>> '-'.join('Python')
'P-y-t-h-o-n'

همچنین split() را ببینید.

str.ljust(width, fillchar=' ', /) : رشته را چپ‌چین‌شده در رشته‌ای به طول width برمی‌گرداند. پر کردن با fillchar مشخص‌شده (پیش‌فرض فاصلهٔ ASCII) انجام می‌شود. اگر width کمتر یا مساوی len(s) باشد، رشتهٔ اصلی برگردانده می‌شود.

برای مثال:

>>> 'Python'.ljust(10)
'Python    '
>>> 'Python'.ljust(10, '.')
'Python....'
>>> 'Monty Python'.ljust(10, '.')
'Monty Python'

همچنین rjust() را ببینید.

str.lower() : نسخه‌ای از رشته را برمی‌گرداند که همهٔ نویسه‌های دارای حالت ^۴ به حروف کوچک تبدیل شده‌اند. برای مثال:

>>> 'Lower Method Example'.lower()
'lower method example'

الگوریتم کوچک‌سازی به‌کاررفته در بخش ۳٫۱۳٫۲ «Default Case Conversion» استاندارد یونیکد توصیف شده است.

str.lstrip(chars=None, /) : نسخه‌ای از رشته را برمی‌گرداند که نویسه‌های ابتدایی (leading) آن حذف شده‌اند. آرگومان chars رشته‌ای است که مجموعهٔ نویسه‌هایی را که باید حذف شوند مشخص می‌کند. اگر حذف شود یا None باشد، chars به‌طور پیش‌فرض فضای خالی را حذف می‌کند، یعنی نویسه‌هایی که str.isspace() برایشان درست است. آرگومان chars پیشوند نیست؛ بلکه همهٔ ترکیب‌های مقادیرش حذف می‌شوند:

>>> '   spacious   '.lstrip()
'spacious   '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'

برای متدی که یک رشتهٔ پیشوند را حذف می‌کند، نه همهٔ نویسه‌های یک مجموعه را، str.removeprefix() را ببینید. برای مثال:

>>> 'Arthur: three!'.lstrip('Arthur: ')
'ee!'
>>> 'Arthur: three!'.removeprefix('Arthur: ')
'three!'

static str.maketrans(dict, /) و static str.maketrans(from, to, remove='', /) : این متد ایستا (static) جدول ترجمه‌ای برمی‌گرداند که برای str.translate() قابل استفاده است.

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

اگر دو آرگومان باشد، باید رشته‌هایی به طول برابر باشند و در دیکشنری حاصل، هر نویسه در from به نویسهٔ هم‌موقعیت در to نگاشت می‌شود. اگر آرگومان سوم باشد، باید رشته‌ای باشد که نویسه‌هایش در نتیجه به None نگاشت می‌شوند.

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

str.partition(sep, /) : رشته را در اولین وقوع sep تقسیم می‌کند و ۳‌تاپلی شامل بخش پیش از جداکننده، خود جداکننده و بخش پس از جداکننده برمی‌گرداند. اگر جداکننده یافت نشود، ۳‌تاپلی شامل خود رشته و بعد دو رشتهٔ خالی برمی‌گرداند.

برای مثال:

>>> 'Monty Python'.partition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".partition(' ')
('Monty', ' ', "Python's Flying Circus")
>>> 'Monty Python'.partition('-')
('Monty Python', '', '')

همچنین rpartition() را ببینید.

str.removeprefix(prefix, /) : اگر رشته با رشتهٔ prefix شروع شود، string[len(prefix):] را برمی‌گرداند. در غیر این صورت، کپی رشتهٔ اصلی را برمی‌گرداند:

>>> 'TestHook'.removeprefix('Test')
'Hook'
>>> 'BaseTestCase'.removeprefix('Test')
'BaseTestCase'

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

همچنین removesuffix() و startswith() را ببینید.

str.removesuffix(suffix, /) : اگر رشته با رشتهٔ suffix تمام شود و آن suffix خالی نباشد، string[:-len(suffix)] را برمی‌گرداند. در غیر این صورت، کپی رشتهٔ اصلی را برمی‌گرداند:

>>> 'MiscTests'.removesuffix('Tests')
'Misc'
>>> 'TmpDirMixin'.removesuffix('Tests')
'TmpDirMixin'

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

همچنین removeprefix() و endswith() را ببینید.

str.replace(old, new, /, count=-1) : نسخه‌ای از رشته را برمی‌گرداند که همهٔ وقوع‌های زیررشتهٔ old با new جایگزین شده‌اند. اگر count داده شود، فقط count وقوع اول جایگزین می‌شوند. اگر count مشخص نشود یا -1 باشد، همهٔ وقوع‌ها جایگزین می‌شوند. برای مثال:

>>> 'spam, spam, spam'.replace('spam', 'eggs')
'eggs, eggs, eggs'
>>> 'spam, spam, spam'.replace('spam', 'eggs', 1)
'eggs, spam, spam'

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

str.rfind(sub[, start[, end]]) : بیشترین اندیسی در رشته را که زیررشتهٔ sub یافت می‌شود برمی‌گرداند، طوری که sub در s[start:end] قرار گیرد. آرگومان‌های اختیاری start و end مانند نمادگذاری برش تفسیر می‌شوند. در صورت شکست -1 برمی‌گرداند. برای مثال:

>>> 'spam, spam, spam'.rfind('sp')
12
>>> 'spam, spam, spam'.rfind('sp', 0, 10)
6

همچنین find() و rindex() را ببینید.

str.rindex(sub[, start[, end]]) : مانند rfind() اما وقتی زیررشتهٔ sub یافت نشود ValueError پرتاب می‌کند. برای مثال:

>>> 'spam, spam, spam'.rindex('spam')
12
>>> 'spam, spam, spam'.rindex('eggs')
Traceback (most recent call last):
  File "<stdin-0>", line 1, in <module>
    'spam, spam, spam'.rindex('eggs')
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^
ValueError: substring not found

همچنین index() و find() را ببینید.

str.rjust(width, fillchar=' ', /) : رشته را راست‌چین‌شده در رشته‌ای به طول width برمی‌گرداند. پر کردن با fillchar مشخص‌شده (پیش‌فرض فاصلهٔ ASCII) انجام می‌شود. اگر width کمتر یا مساوی len(s) باشد، رشتهٔ اصلی برگردانده می‌شود.

برای مثال:

>>> 'Python'.rjust(10)
'    Python'
>>> 'Python'.rjust(10, '.')
'....Python'
>>> 'Monty Python'.rjust(10, '.')
'Monty Python'

همچنین ljust() و zfill() را ببینید.

str.rpartition(sep, /) : رشته را در آخرین وقوع sep تقسیم می‌کند و ۳‌تاپلی شامل بخش پیش از جداکننده، خود جداکننده و بخش پس از جداکننده برمی‌گرداند. اگر جداکننده یافت نشود، ۳‌تاپلی شامل دو رشتهٔ خالی و بعد خود رشته برمی‌گرداند.

برای مثال:

>>> 'Monty Python'.rpartition(' ')
('Monty', ' ', 'Python')
>>> "Monty Python's Flying Circus".rpartition(' ')
("Monty Python's Flying", ' ', 'Circus')
>>> 'Monty Python'.rpartition('-')
('', '', 'Monty Python')

همچنین partition() را ببینید.

str.rsplit(sep=None, maxsplit=-1) : فهرستی از کلمات رشته را برمی‌گرداند و sep را به‌عنوان رشتهٔ جداکننده به کار می‌برد. اگر maxsplit داده شود، حداکثر maxsplit تقسیم انجام می‌شود، راست‌ترین‌ها. اگر sep مشخص نشود یا None باشد، هر رشتهٔ فضای خالی جداکننده است. به‌جز تقسیم از راست، rsplit() مانند split() رفتار می‌کند که در ادامه با جزئیات توصیف شده است.

str.rstrip(chars=None, /) : نسخه‌ای از رشته را برمی‌گرداند که نویسه‌های انتهایی (trailing) آن حذف شده‌اند. آرگومان chars رشته‌ای است که مجموعهٔ نویسه‌هایی را که باید حذف شوند مشخص می‌کند. اگر حذف شود یا None باشد، chars به‌طور پیش‌فرض فضای خالی را حذف می‌کند، یعنی نویسه‌هایی که str.isspace() برایشان درست است. آرگومان chars پسوند نیست؛ بلکه همهٔ ترکیب‌های مقادیرش حذف می‌شوند. برای مثال:

>>> '   spacious   '.rstrip()
'   spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'

برای متدی که یک رشتهٔ پسوند را حذف می‌کند، نه همهٔ نویسه‌های یک مجموعه را، removesuffix() را ببینید. برای مثال:

>>> 'Monty Python'.rstrip(' Python')
'M'
>>> 'Monty Python'.removesuffix(' Python')
'Monty'

همچنین strip() را ببینید.

str.split(sep=None, maxsplit=-1) : فهرستی از کلمات رشته را برمی‌گرداند و sep را به‌عنوان رشتهٔ جداکننده به کار می‌برد. اگر maxsplit داده شود، حداکثر maxsplit تقسیم انجام می‌شود (بنابراین فهرست حداکثر maxsplit+1 عنصر خواهد داشت). اگر maxsplit مشخص نشود یا -1 باشد، محدودیتی بر تعداد تقسیم‌ها نیست (همهٔ تقسیم‌های ممکن انجام می‌شود).

اگر sep داده شود، جداکننده‌های متوالی با هم گروه نمی‌شوند و جداکنندهٔ رشته‌های خالی تلقی می‌شوند (برای مثال '1,,2'.split(',') مقدار ['1', '', '2'] را برمی‌گرداند). آرگومان sep می‌تواند از چند نویسه به‌عنوان یک جداکنندهٔ واحد تشکیل شود (برای تقسیم با چند جداکننده از re.split() استفاده کنید). تقسیم رشتهٔ خالی با جداکنندهٔ مشخص [''] برمی‌گرداند.

برای مثال:

>>> '1,2,3'.split(',')
['1', '2', '3']
>>> '1,2,3'.split(',', maxsplit=1)
['1', '2,3']
>>> '1,2,,3,'.split(',')
['1', '2', '', '3', '']
>>> '1<>2<>3<4'.split('<>')
['1', '2', '3<4']

اگر sep مشخص نشود یا None باشد، الگوریتم تقسیم متفاوتی اعمال می‌شود: دنباله‌های متوالی فضای خالی یک جداکنندهٔ واحد تلقی می‌شوند، و اگر رشته فضای خالی ابتدایی یا انتهایی داشته باشد، نتیجه در ابتدا یا انتها رشتهٔ خالی نخواهد داشت. در نتیجه، تقسیم رشتهٔ خالی یا رشته‌ای که فقط از فضای خالی تشکیل شده با جداکنندهٔ None مقدار [] را برمی‌گرداند.

برای مثال:

>>> '1 2 3'.split()
['1', '2', '3']
>>> '1 2 3'.split(maxsplit=1)
['1', '2 3']
>>> '   1   2   3   '.split()
['1', '2', '3']

اگر sep مشخص نشود یا None باشد و maxsplit برابر 0 باشد، فقط دنباله‌های ابتدایی فضای خالی متوالی در نظر گرفته می‌شوند.

برای مثال:

>>> "".split(None, 0)
[]
>>> "   ".split(None, 0)
[]
>>> "   foo   ".split(maxsplit=0)
['foo   ']

همچنین join() و rsplit() را ببینید.

str.splitlines(keepends=False) : فهرستی از خطوط رشته را برمی‌گرداند و در مرزهای خط می‌شکند. شکست‌های خط در فهرست حاصل گنجانده نمی‌شوند مگر آنکه keepends داده شده و درست باشد.

این متد در مرزهای خط زیر تقسیم می‌کند. به‌ویژه، این مرزها فرامجموعهٔ خط‌جدیدهای جهانی (universal newlines) هستند.

تغییر در نسخهٔ ۳٫۲: \v و \f به فهرست مرزهای خط افزوده شدند.

برای مثال:

>>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
['ab c', '', 'de fg', 'kl']
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
['ab c\n', '\n', 'de fg\r', 'kl\r\n']

برخلاف split() وقتی رشتهٔ جداکنندهٔ sep داده شده باشد، این متد برای رشتهٔ خالی فهرست خالی برمی‌گرداند، و شکست خط پایانی به خط اضافی نمی‌انجامد:

>>> "".splitlines()
[]
>>> "One line\n".splitlines()
['One line']

برای مقایسه، split('\n') این را می‌دهد:

>>> ''.split('\n')
['']
>>> 'Two lines\n'.split('\n')
['Two lines', '']

str.startswith(prefix[, start[, end]]) : اگر رشته با prefix شروع شود True، وگرنه False برمی‌گرداند. prefix می‌تواند تاپلی از پیشوندها برای جست‌وجو هم باشد. با start اختیاری، رشته از آن موقعیت آزموده می‌شود. با end اختیاری، مقایسهٔ رشته در آن موقعیت متوقف می‌شود.

برای مثال:

>>> 'Python'.startswith('Py')
True
>>> 'a tuple of prefixes'.startswith(('at', 'a'))
True
>>> 'Python is amazing'.startswith('is', 7)
True

همچنین endswith() و removeprefix() را ببینید.

str.strip(chars=None, /) : نسخه‌ای از رشته را برمی‌گرداند که نویسه‌های ابتدایی و انتهایی آن حذف شده‌اند. آرگومان chars رشته‌ای است که مجموعهٔ نویسه‌هایی را که باید حذف شوند مشخص می‌کند. اگر حذف شود یا None باشد، chars به‌طور پیش‌فرض فضای خالی را حذف می‌کند، یعنی نویسه‌هایی که str.isspace() برایشان درست است. آرگومان chars پیشوند یا پسوند نیست؛ بلکه همهٔ ترکیب‌های مقادیرش حذف می‌شوند.

برای مثال:

>>> '   spacious   '.strip()
'spacious'
>>> 'www.example.com'.strip('cmowz.')
'example'

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

برای مثال:

>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'

همچنین rstrip() را ببینید. str.swapcase() : نسخه‌ای از رشته را برمی‌گرداند که نویسه‌های بزرگ به کوچک و برعکس تبدیل شده‌اند. برای مثال:

>>> 'Hello World'.swapcase()
'hELLO wORLD'

توجه کنید که لزوماً درست نیست که s.swapcase().swapcase() == s. برای مثال:

>>> 'straße'.swapcase().swapcase()
'strasse'

همچنین str.lower() و str.upper() را ببینید.

str.title() : نسخهٔ titlecase‌شدهٔ رشته را برمی‌گرداند که در آن کلمات با نویسهٔ بزرگ شروع می‌شوند و بقیهٔ نویسه‌ها کوچک‌اند.

برای مثال:

>>> 'Hello world'.title()
'Hello World'

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

>>> "they're bill's friends from the UK".title()
"They'Re Bill'S Friends From The Uk"

تابع string.capwords() این مشکل را ندارد، چون کلمات را فقط روی فاصله‌ها تقسیم می‌کند.

به‌عنوان جایگزین، راه‌حلی برای آپوستروف‌ها را می‌توان با عبارت‌های منظم ساخت:

>>> import re
>>> def titlecase(s):
...     return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0).capitalize(),
...                   s)
...
>>> titlecase("they're bill's friends.")
"They're Bill's Friends."

همچنین istitle() را ببینید.

str.translate(table, /) : نسخه‌ای از رشته را برمی‌گرداند که هر نویسه در آن از جدول ترجمهٔ داده‌شده عبور داده شده است. جدول باید شیئی باشد که اندیس‌گذاری را از طریق __getitem__() پیاده می‌کند، که معمولاً نگاشت (mapping) یا دنباله (sequence) است. وقتی با ترتیب یونیکد (عدد صحیح) اندیس‌گذاری شود، شیء جدول می‌تواند هر یک از این کارها را انجام دهد: ترتیب یونیکد یا رشته‌ای برگرداند تا نویسه به یک یا چند نویسهٔ دیگر نگاشت شود؛ None برگرداند تا نویسه از رشتهٔ بازگشتی حذف شود؛ یا استثنای LookupError پرتاب کند تا نویسه به خودش نگاشت شود.

می‌توانید از str.maketrans() برای ساخت نگاشت ترجمه از نگاشت‌های نویسه‌به‌نویسه در قالب‌های گوناگون استفاده کنید.

مثال زیر از یک نگاشت برای جایگزینی 'a' با 'X'، 'b' با 'Y' و حذف 'c' استفاده می‌کند:

>>> 'abc123'.translate({ord('a'): 'X', ord('b'): 'Y', ord('c'): None})
'XY123'

همچنین برای رویکرد انعطاف‌پذیرتر در نگاشت‌های نویسهٔ سفارشی ماژول codecs را ببینید.

str.upper() : نسخه‌ای از رشته را برمی‌گرداند که همهٔ نویسه‌های دارای حالت ^۴ به حروف بزرگ تبدیل شده‌اند. توجه کنید که s.upper().isupper() ممکن است False باشد اگر s نویسه‌های بدون حالت داشته باشد یا اگر رده‌بندی یونیکد نویسه(های) حاصل «Lu» (Letter, uppercase) نباشد، بلکه مثلاً «Lt» (Letter, titlecase) باشد.

الگوریتم بزرگ‌سازی به‌کاررفته در بخش ۳٫۱۳٫۲ «Default Case Conversion» استاندارد یونیکد توصیف شده است.

str.zfill(width, /) : نسخه‌ای از رشته را برمی‌گرداند که از چپ با ارقام ASCII '0' پر شده تا رشته‌ای به طول width بسازد. پیشوند علامت ابتدایی ('+'/'-') با درج پر کردن بعد از نویسهٔ علامت، نه پیش از آن، مدیریت می‌شود. اگر width کمتر یا مساوی len(s) باشد، رشتهٔ اصلی برگردانده می‌شود.

برای مثال:

>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'

همچنین rjust() را ببینید.

لیترال‌های رشتهٔ قالب‌بندی‌شده (f-stringها)

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

تغییر در نسخهٔ ۳٫۷: await و async for را می‌توان در عبارت‌های داخل f-stringها به کار برد.

تغییر در نسخهٔ ۳٫۸: مشخص‌کنندهٔ اشکال‌زدایی (=) افزوده شد.

تغییر در نسخهٔ ۳٫۱۲: بسیاری از محدودیت‌ها بر عبارت‌های داخل f-stringها برداشته شد. به‌ویژه، رشته‌های تودرتو، توضیحات و بک‌اسلش‌ها اکنون مجازند.

f-string (به‌طور رسمی لیترال رشتهٔ قالب‌بندی‌شده، formatted string literal) لیترال رشته‌ای است که با f یا F پیشوند شده است. این نوع لیترال رشته اجازه می‌دهد نتایج عبارت‌های دلخواه پایتون در فیلدهای جایگزینی (replacement fields) که با آکولاد ({}) محصور شده‌اند جاسازی شود. هر فیلد جایگزینی باید یک عبارت داشته باشد، که اختیاراً بعدش می‌آید:

• یک مشخص‌کنندهٔ اشکال‌زدایی (debug specifier) – علامت مساوی (=)؛
• یک مشخص‌کنندهٔ تبدیل (conversion specifier) – !s، !r یا !a؛ و/یا
• یک مشخص‌کنندهٔ قالب (format specifier) با پیشوند دونقطه (:).

برای جزئیات سینتکس این فیلدها بخش تحلیل واژگانی دربارهٔ f-stringها را ببینید.

مشخص‌کنندهٔ اشکال‌زدایی

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

اگر مشخص‌کنندهٔ اشکال‌زدایی – علامت مساوی (=) – بعد از عبارت فیلد جایگزینی بیاید، f-string حاصل شامل متن منبع عبارت، علامت مساوی و مقدار عبارت خواهد بود. این اغلب برای اشکال‌زدایی مفید است:

>>> number = 14.3
>>> f'{number=}'
'number=14.3'

فضای خالی پیش از عبارت، داخل آن و بعد از آن، و همچنین فضای خالی بعد از علامت مساوی، معنادار است — در نتیجه حفظ می‌شود:

>>> f'{ number  -  4  = }'
' number  -  4  = 10.3'

مشخص‌کنندهٔ تبدیل

به‌طور پیش‌فرض، مقدار عبارت فیلد جایگزینی با str() به رشته تبدیل می‌شود:

>>> from fractions import Fraction
>>> one_third = Fraction(1, 3)
>>> f'{one_third}'
'1/3'

وقتی مشخص‌کنندهٔ اشکال‌زدایی ولی مشخص‌کنندهٔ قالب به کار رفته باشد، تبدیل پیش‌فرض در عوض از repr() استفاده می‌کند:

>>> f'{one_third = }'
'one_third = Fraction(1, 3)'

تبدیل را می‌توان با یکی از این مشخص‌کننده‌ها به‌صراحت مشخص کرد:

• !s برای str()
• !r برای repr()
• !a برای ascii()

برای مثال:

>>> str(one_third)
'1/3'
>>> repr(one_third)
'Fraction(1, 3)'

>>> f'{one_third!s} is {one_third!r}'
'1/3 is Fraction(1, 3)'

>>> string = "¡kočka 😸!"
>>> ascii(string)
"'\\xa1ko\\u010dka \\U0001f638!'"

>>> f'{string = !a}'
"string = '\\xa1ko\\u010dka \\U0001f638!'"

مشخص‌کنندهٔ قالب

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

>>> from fractions import Fraction
>>> one_third = Fraction(1, 3)
>>> f'{one_third:.6f}'
'0.333333'
>>> f'{one_third:_^+10}'
'___+1/3___'
>>> f'{one_third!r:_^20}'
'___Fraction(1, 3)___'
>>> f'{one_third = :~>10}~'
'one_third = ~~~~~~~1/3~'

لیترال‌های رشتهٔ الگو (t-stringها)

t-string (به‌طور رسمی لیترال رشتهٔ الگو، template string literal) لیترال رشته‌ای است که با t یا T پیشوند شده است.

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

• به‌جای ارزیابی به شیء str، لیترال‌های رشتهٔ الگو به شیء string.templatelib.Template ارزیابی می‌شوند.

• پروتکل format() استفاده نمی‌شود. در عوض، مشخص‌کنندهٔ قالب و تبدیل‌ها (در صورت وجود) به شیء جدید string.templatelib.Interpolation که برای هر عبارت ارزیابی‌شده ساخته می‌شود ارسال می‌شوند. تصمیم دربارهٔ نحوهٔ مدیریت مشخص‌کننده‌های قالب و تبدیل‌ها بر عهدهٔ کدی است که شیء Template حاصل را پردازش می‌کند.

• مشخص‌کننده‌های قالب که فیلدهای جایگزینی تودرتو دارند پیش از ارسال به شیء Interpolation به‌صورت مشتاقانه (eagerly) ارزیابی می‌شوند. برای مثال، درون‌یابی (interpolation) به شکل {amount:.{precision}f} عبارت درونی {precision} را ارزیابی می‌کند تا مقدار ویژگی format_spec را تعیین کند. اگر precision برابر 2 باشد، مشخص‌کنندهٔ قالب حاصل '.2f' خواهد بود.

• وقتی علامت مساوی '=' در عبارت درون‌یابی داده شود، متن عبارت به لیترال رشته‌ای که پیش از درون‌یابی مربوط می‌آید افزوده می‌شود. این شامل علامت مساوی و هر فضای خالی اطراف آن است. نمونهٔ Interpolation برای عبارت به‌طور عادی ساخته می‌شود، با این تفاوت که conversion به‌طور پیش‌فرض روی 'r' (repr()) تنظیم می‌شود. اگر تبدیل یا مشخص‌کنندهٔ قالب صریحی داده شود، این رفتار پیش‌فرض را نادیده می‌گیرد.

قالب‌بندی رشتهٔ به سبک printf (printf-style string formatting)

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

استفاده از لیترال‌های رشتهٔ قالب‌بندی‌شده، رابط str.format() یا string.Template ممکن است به پرهیز از این خطاها کمک کند. هر یک از این جایگزین‌ها مبادله‌ها و مزایای خاص خود را در سادگی، انعطاف‌پذیری و/یا توسعه‌پذیری دارد.

اشیای رشته‌ای یک عملیات درون‌ساخت منحصربه‌فرد دارند: عملگر % (پیمانه). این همچنین به‌عنوان عملگر قالب‌بندی یا درون‌یابی رشته شناخته می‌شود. با format % values (که format رشته است)، مشخصات تبدیل % در format با صفر یا چند عنصر از values جایگزین می‌شود. اثر آن شبیه استفاده از تابع sprintf() در زبان C است. برای مثال:

>>> print('%s has %d quote types.' % ('Python', 2))
Python has 2 quote types.

اگر format به یک آرگومان واحد نیاز داشته باشد، values می‌تواند یک شیء غیرتاپل باشد. ^۵ در غیر این صورت، values باید تاپلی با دقیقاً همان تعداد مورد مشخص‌شده توسط رشتهٔ قالب، یا یک شیء نگاشت (mapping) واحد (برای مثال دیکشنری) باشد.

مشخص‌کنندهٔ تبدیل (conversion specifier) دو یا چند نویسه دارد و اجزای زیر را دارد که باید به همین ترتیب بیایند:

1. نویسهٔ '%'، که آغاز مشخص‌کننده را علامت می‌زند.

2. کلید نگاشت (اختیاری)، شامل دنبالهٔ پرانتزدار نویسه‌ها (برای مثال (somename)).

3. پرچم‌های تبدیل (اختیاری)، که بر نتیجهٔ برخی انواع تبدیل اثر می‌گذارند.

4. حداقل عرض فیلد (اختیاری). اگر به‌صورت '*' (ستاره) مشخص شود، عرض واقعی از عنصر بعدی تاپل در values خوانده می‌شود، و شیء مورد تبدیل بعد از حداقل عرض فیلد و دقت اختیاری می‌آید.

5. دقت (اختیاری)، به‌صورت '.' (نقطه) و بعد دقت. اگر به‌صورت '*' (ستاره) مشخص شود، دقت واقعی از عنصر بعدی تاپل در values خوانده می‌شود، و مقدار مورد تبدیل بعد از دقت می‌آید.

6. تغییردهندهٔ طول (اختیاری).

7. نوع تبدیل.

وقتی آرگومان راست دیکشنری (یا نوع نگاشت دیگر) است، قالب‌های داخل رشته باید کلید نگاشت پرانتزداری به آن دیکشنری داشته باشند که بلافاصله بعد از نویسهٔ '%' درج شده است. کلید نگاشت مقداری را که باید قالب‌بندی شود از نگاشت انتخاب می‌کند. برای مثال:

>>> print('%(language)s has %(number)03d quote types.' %
...       {'language': "Python", "number": 2})
Python has 002 quote types.

در این حالت هیچ مشخص‌کنندهٔ * نمی‌تواند در قالب بیاید (چون به فهرست پارامتر ترتیبی نیاز دارند).

نویسه‌های پرچم تبدیل این‌ها هستند:

تغییردهندهٔ طول (h، l یا L) ممکن است حاضر باشد، اما نادیده گرفته می‌شود چون برای پایتون لازم نیست – بنابراین مثلاً %ld با %d یکسان است.

نوع‌های تبدیل این‌ها هستند:

برای قالب‌های ممیز شناور، نتیجه باید به دقت داده‌شدهٔ p رقم بعد از ممیز درست گرد شود. حالت گرد کردن با حالت تابع درون‌ساخت round() مطابقت دارد.

یادداشت‌ها:

1. شکل جایگزین باعث می‌شود مشخص‌کنندهٔ هشتی ابتدایی ('0o') پیش از اولین رقم درج شود.

2. شکل جایگزین باعث می‌شود '0x' یا '0X' ابتدایی (بسته به اینکه قالب 'x' یا 'X' به کار رفته) پیش از اولین رقم درج شود.

3. شکل جایگزین باعث می‌شود نتیجه همیشه ممیز دهدهی داشته باشد، حتی اگر هیچ رقمی بعدش نیاید.

   دقت تعداد ارقام بعد از ممیز دهدهی را تعیین می‌کند و پیش‌فرض آن ۶ است.

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

   دقت تعداد ارقام معنادار پیش و پس از ممیز دهدهی را تعیین می‌کند و پیش‌فرض آن ۶ است.

5. اگر دقت N باشد، خروجی به N نویسه کوتاه می‌شود.

6. PEP 237 را ببینید.

از آنجا که رشته‌های پایتون طول صریح دارند، تبدیل‌های %s فرض نمی‌کنند که '\0' پایان رشته است.

تغییر در نسخهٔ ۳٫۱: تبدیل‌های %f برای اعدادی که قدر مطلقشان بیش از 1e50 است دیگر با تبدیل‌های %g جایگزین نمی‌شوند.

نوع‌های دنبالهٔ دودویی (Binary sequence types) — bytes، bytearray، memoryview

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

ماژول array از ذخیرهٔ کارآمد نوع‌های داده‌ای پایه مانند اعداد صحیح ۳۲ بیتی و مقادیر ممیز شناور دقت دوگانهٔ IEEE754 پشتیبانی می‌کند.

اشیای بایت (Bytes objects)

اشیای bytes دنباله‌های تغییرناپذیر از بایت‌های منفرد هستند. چون بسیاری از پروتکل‌های دودویی مهم بر پایهٔ کدگذاری متن ASCII هستند، اشیای bytes چند متد ارائه می‌دهند که فقط هنگام کار با داده‌های سازگار با ASCII معتبرند و از جهات گوناگون دیگر ارتباط نزدیکی با اشیای رشته‌ای دارند.

class bytes(source=b'') و class bytes(source, encoding, errors='strict') : اولاً، سینتکس لیترال‌های bytes تا حد زیادی با لیترال‌های رشته یکی است، با این تفاوت که پیشوند b افزوده می‌شود:

• گیومهٔ تکی: b'still allows embedded "double" quotes'
• گیومهٔ دوتایی: b"still allows embedded 'single' quotes"
• سه‌گیومه‌ای: b'''3 single quotes'''، b"""3 double quotes"""

در لیترال‌های bytes فقط نویسه‌های ASCII مجازند (صرف‌نظر از کدگذاری اعلام‌شدهٔ کد منبع). هر مقدار دودویی بیش از ۱۲۷ باید با دنبالهٔ گریز مناسب در لیترال‌های bytes وارد شود.

مانند لیترال‌های رشته، لیترال‌های bytes هم می‌توانند از پیشوند r برای غیرفعال کردن پردازش دنباله‌های گریز استفاده کنند. برای اطلاعات بیشتر دربارهٔ شکل‌های گوناگون لیترال bytes، از جمله دنباله‌های گریز پشتیبانی‌شده، لیترال‌های رشته و بایت را ببینید.

در حالی که لیترال‌ها و نمایش‌های bytes بر پایهٔ متن ASCII هستند، اشیای bytes در واقع مانند دنباله‌های تغییرناپذیر از اعداد صحیح رفتار می‌کنند، که هر مقدار در دنباله طوری محدود شده که 0 <= x < 256 (تلاش برای نقض این محدودیت ValueError را برمی‌انگیزد). این عمداً انجام شده تا تأکید شود که اگرچه بسیاری از قالب‌های دودویی عناصر مبتنی بر ASCII دارند و می‌توان با برخی الگوریتم‌های متن‌محور به‌طور مفید دست‌کاری‌شان کرد، این در حالت کلی برای داده‌های دودویی دلخواه صادق نیست (اعمال کورکورانهٔ الگوریتم‌های پردازش متن روی قالب‌های داده دودویی که با ASCII سازگار نیستند معمولاً به خرابی داده می‌انجامد).

علاوه بر شکل‌های لیترال، اشیای bytes را به چند روش دیگر هم می‌توان ساخت:

• شیء bytes پر از صفر با طول مشخص: bytes(10)
• از یک تکرارپذیر از اعداد صحیح: bytes(range(20))
• کپی داده‌های دودویی موجود از طریق پروتکل بافر: bytes(obj)

همچنین تابع درون‌ساخت bytes را ببینید.

چون ۲ رقم شانزدهی دقیقاً با یک بایت متناظرند، اعداد شانزدهی قالبی رایج برای توصیف داده‌های دودویی‌اند. بر این اساس، نوع bytes متد کلاسی اضافی برای خواندن داده در آن قالب دارد:

classmethod fromhex(string, /) : این متد کلاسی bytes شیء bytes برمی‌گرداند و شیء رشتهٔ داده‌شده را رمزگشایی می‌کند. رشته باید برای هر بایت دو رقم شانزدهی داشته باشد و فضای خالی ASCII نادیده گرفته می‌شود.

```
>>> bytes.fromhex('2Ef0 F1f2  ')
b'.\xf0\xf1\xf2'
```

> **تغییر در نسخهٔ ۳٫۷:** `bytes.fromhex()` اکنون همهٔ فضاهای خالی ASCII را در رشته نادیده می‌گیرد، نه فقط فاصله‌ها.

> **تغییر در نسخهٔ ۳٫۱۴:** `bytes.fromhex()` اکنون `bytes` ASCII و [اشیای شبه‌بایت](https://docs.python.org/3/glossary.html#term-bytes-like-object) را به‌عنوان ورودی می‌پذیرد.

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

hex(*, bytes_per_sep=1) و hex(sep, bytes_per_sep=1) : شیء رشته‌ای برمی‌گرداند که برای هر بایت در نمونه دو رقم شانزدهی دارد.

```
>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'
```

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

```
>>> value = b'\xf0\xf1\xf2'
>>> value.hex('-')
'f0-f1-f2'
>>> value.hex('_', 2)
'f0_f1f2'
>>> b'UUDDLRLRAB'.hex(' ', -4)
'55554444 4c524c52 4142'
```

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

> **تغییر در نسخهٔ ۳٫۸:** `bytes.hex()` اکنون پارامترهای اختیاری *sep* و *bytes_per_sep* را برای درج جداکننده بین بایت‌ها در خروجی شانزدهی پشتیبانی می‌کند.

از آنجا که اشیای bytes دنباله‌هایی از اعداد صحیح‌اند (شبیه تاپل)، برای شیء bytes به نام b، b[0] یک عدد صحیح خواهد بود، در حالی که b[0:1] شیء bytes به طول ۱ خواهد بود. (این برخلاف رشته‌های متنی است، که در آن‌ها هم اندیس‌گذاری و هم برش رشته‌ای به طول ۱ تولید می‌کند)

نمایش اشیای bytes از قالب لیترال (b'...') استفاده می‌کند چون اغلب مفیدتر از مثلاً bytes([46, 46, 46]) است. همیشه می‌توانید شیء bytes را با list(b) به فهرستی از اعداد صحیح تبدیل کنید.

اشیای بایت‌آرایه (Bytearray objects)

اشیای bytearray همتای تغییرپذیر اشیای bytes هستند.

class bytearray(source=b'') و class bytearray(source, encoding, errors='strict') : سینتکس لیترال اختصاصی برای اشیای bytearray وجود ندارد؛ در عوض همیشه با فراخوانی سازنده ساخته می‌شوند:

• ساخت نمونهٔ خالی: bytearray()
• ساخت نمونهٔ پر از صفر با طول داده‌شده: bytearray(10)
• از یک تکرارپذیر از اعداد صحیح: bytearray(range(20))
• کپی داده‌های دودویی موجود از طریق پروتکل بافر: bytearray(b'Hi!')

چون اشیای bytearray تغییرپذیرند، علاوه بر عملیات مشترک bytes و bytearray که در متدهای bytes و bytearray توصیف شده، عملیات دنبالهٔ تغییرپذیر را هم پشتیبانی می‌کنند.

همچنین تابع درون‌ساخت bytearray را ببینید.

چون ۲ رقم شانزدهی دقیقاً با یک بایت متناظرند، اعداد شانزدهی قالبی رایج برای توصیف داده‌های دودویی‌اند. بر این اساس، نوع bytearray متد کلاسی اضافی برای خواندن داده در آن قالب دارد:

classmethod fromhex(string, /) : این متد کلاسی bytearray شیء bytearray برمی‌گرداند و شیء رشتهٔ داده‌شده را رمزگشایی می‌کند. رشته باید برای هر بایت دو رقم شانزدهی داشته باشد و فضای خالی ASCII نادیده گرفته می‌شود.

```
>>> bytearray.fromhex('2Ef0 F1f2  ')
bytearray(b'.\xf0\xf1\xf2')
```

> **تغییر در نسخهٔ ۳٫۷:** `bytearray.fromhex()` اکنون همهٔ فضاهای خالی ASCII را در رشته نادیده می‌گیرد، نه فقط فاصله‌ها.

> **تغییر در نسخهٔ ۳٫۱۴:** `bytearray.fromhex()` اکنون `bytes` ASCII و [اشیای شبه‌بایت](https://docs.python.org/3/glossary.html#term-bytes-like-object) را به‌عنوان ورودی می‌پذیرد.

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

hex(*, bytes_per_sep=1) و hex(sep, bytes_per_sep=1) : شیء رشته‌ای برمی‌گرداند که برای هر بایت در نمونه دو رقم شانزدهی دارد.

```
>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'
```

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

> **تغییر در نسخهٔ ۳٫۸:** مشابه `bytes.hex()`، متد `bytearray.hex()` اکنون پارامترهای اختیاری *sep* و *bytes_per_sep* را برای درج جداکننده بین بایت‌ها در خروجی شانزدهی پشتیبانی می‌کند.

resize(size, /) : اندازهٔ bytearray را طوری تغییر می‌دهد که شامل size بایت باشد. size باید بزرگ‌تر یا مساوی ۰ باشد.

اگر `bytearray` باید کوچک شود، بایت‌های فراتر از *size* بریده می‌شوند.

اگر `bytearray` باید رشد کند، همهٔ بایت‌های جدید، آن‌هایی که فراتر از *size* هستند، روی بایت‌های تهی (null) تنظیم می‌شوند.

این معادل است با:

```
>>> def resize(ba, size):
...     if len(ba) > size:
...         del ba[size:]
...     else:
...         ba += b'\0' * (size - len(ba))
```

مثال‌ها:

```
>>> shrink = bytearray(b'abc')
>>> shrink.resize(1)
>>> (shrink, len(shrink))
(bytearray(b'a'), 1)
>>> grow = bytearray(b'abc')
>>> grow.resize(5)
>>> (grow, len(grow))
(bytearray(b'abc\x00\x00'), 5)
```

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

take_bytes(n=None, /) : n بایت اول را از bytearray حذف می‌کند و آن‌ها را به‌صورت bytes تغییرناپذیر برمی‌گرداند. به‌طور پیش‌فرض (اگر n برابر None باشد)، همهٔ بایت‌ها را برمی‌گرداند و bytearray را پاک می‌کند.

اگر *n* منفی باشد، از انتها اندیس‌گذاری می‌کند و `len` به‌علاوهٔ *n* بایت اول را برمی‌دارد. اگر *n* خارج از محدوده باشد، `IndexError` پرتاب می‌کند.

برداشتن کمتر از طول کامل بایت‌های باقی‌مانده را در `bytearray` می‌گذارد، که به یک کپی نیاز دارد. اگر بایت‌های باقی‌مانده باید دور ریخته شوند، از `bytearray.resize()` یا `del` برای کوتاه کردن و سپس `bytearray.take_bytes()` بدون اندازه استفاده کنید.

> **جزئیات پیاده‌سازی (CPython):** برداشتن همهٔ بایت‌ها عملیات zero-copy است.

> **افزوده‌شده در نسخهٔ ۳٫۱۵.**
>
> ورودی [What's New](https://docs.python.org/3/whatsnew/3.15.html#whatsnew315-bytearray-take-bytes) را برای الگوهای کد رایجی که می‌توان با `bytearray.take_bytes()` بهینه کرد ببینید.

از آنجا که اشیای bytearray دنباله‌هایی از اعداد صحیح‌اند (شبیه فهرست)، برای شیء bytearray به نام b، b[0] یک عدد صحیح خواهد بود، در حالی که b[0:1] شیء bytearray به طول ۱ خواهد بود. (این برخلاف رشته‌های متنی است، که در آن‌ها هم اندیس‌گذاری و هم برش رشته‌ای به طول ۱ تولید می‌کند) نمایش اشیای bytearray از قالب لیترال bytes (bytearray(b'...')) استفاده می‌کند چون اغلب مفیدتر از مثلاً bytearray([46, 46, 46]) است. همیشه می‌توانید شیء bytearray را با list(b) به فهرستی از اعداد صحیح تبدیل کنید.

همچنین ببینید: برای اطلاعات دقیق دربارهٔ تضمین‌های ایمنی نخ برای اشیای bytearray، ایمنی نخ برای اشیای bytearray را ببینید.

عملیات bytes و bytearray

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

نکته: متدهای اشیای bytes و bytearray رشته‌ها را به‌عنوان آرگومان نمی‌پذیرند، همان‌طور که متدهای رشته‌ها bytes را به‌عنوان آرگومان نمی‌پذیرند. برای مثال، باید بنویسید:

a = "abc"
b = a.replace("a", "f")

و:

a = b"abc"
b = a.replace(b"a", b"f")

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

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

متدهای زیر روی اشیای bytes و bytearray را می‌توان با داده‌های دودویی دلخواه به کار برد.

در همهٔ متدهای زیر که نسخهٔ bytearray دارند: نسخهٔ bytearray این متد درجا عمل نمی‌کند — همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد. (این یادداشت در اصل زیر هر متد تکرار شده است.)

bytes.count(sub[, start[, end]])، bytearray.count(sub[, start[, end]]) : تعداد وقوع‌های بدون هم‌پوشانی زیردنبالهٔ sub را در بازهٔ [start, end] برمی‌گرداند. آرگومان‌های اختیاری start و end مانند نمادگذاری برش تفسیر می‌شوند.

زیردنباله‌ای که جست‌وجو می‌شود می‌تواند هر شیء شبه‌بایت یا عدد صحیح در بازهٔ ۰ تا ۲۵۵ باشد.

اگر sub خالی باشد، تعداد برش‌های خالی بین نویسه‌ها را برمی‌گرداند که طول شیء bytes به‌اضافهٔ یک است.

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

bytes.removeprefix(prefix, /)، bytearray.removeprefix(prefix, /) : اگر داده‌های دودویی با رشتهٔ prefix شروع شوند، bytes[len(prefix):] را برمی‌گرداند. در غیر این صورت، کپی داده‌های دودویی اصلی را برمی‌گرداند:

>>> b'TestHook'.removeprefix(b'Test')
b'Hook'
>>> b'BaseTestCase'.removeprefix(b'Test')
b'BaseTestCase'

prefix می‌تواند هر شیء شبه‌بایت باشد.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

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

bytes.removesuffix(suffix, /)، bytearray.removesuffix(suffix, /) : اگر داده‌های دودویی با رشتهٔ suffix تمام شوند و آن suffix خالی نباشد، bytes[:-len(suffix)] را برمی‌گرداند. در غیر این صورت، کپی داده‌های دودویی اصلی را برمی‌گرداند:

>>> b'MiscTests'.removesuffix(b'Tests')
b'Misc'
>>> b'TmpDirMixin'.removesuffix(b'Tests')
b'TmpDirMixin'

suffix می‌تواند هر شیء شبه‌بایت باشد.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

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

bytes.decode(encoding="utf-8", errors="strict")، bytearray.decode(encoding="utf-8", errors="strict") : بایت‌های رمزگشایی‌شده به str را برمی‌گرداند.

encoding به‌طور پیش‌فرض 'utf-8' است؛ برای مقادیر ممکن کدگذاری‌های استاندارد را ببینید.

errors نحوهٔ مدیریت خطاهای رمزگشایی را کنترل می‌کند. اگر 'strict' (پیش‌فرض) باشد، استثنای UnicodeError پرتاب می‌شود. مقادیر ممکن دیگر 'ignore'، 'replace' و هر نام دیگر ثبت‌شده با codecs.register_error() هستند. برای جزئیات مدیریت‌کننده‌های خطا را ببینید.

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

نکته: ارسال آرگومان encoding به str اجازه می‌دهد هر شیء شبه‌بایت مستقیماً و بدون نیاز به ساخت شیء موقت bytes یا bytearray رمزگشایی شود.

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

تغییر در نسخهٔ ۳٫۹: مقدار آرگومان errors اکنون در حالت توسعه و در حالت اشکال‌زدایی بررسی می‌شود.

bytes.endswith(suffix[, start[, end]])، bytearray.endswith(suffix[, start[, end]]) : اگر داده‌های دودویی با suffix مشخص‌شده تمام شوند True، وگرنه False برمی‌گرداند. suffix می‌تواند تاپلی از پسوندها برای جست‌وجو هم باشد. با start اختیاری، آزمون از آن موقعیت آغاز می‌شود. با end اختیاری، مقایسه در آن موقعیت متوقف می‌شود.

پسوند(های) مورد جست‌وجو می‌تواند هر شیء شبه‌بایت باشد.

bytes.find(sub[, start[, end]])، bytearray.find(sub[, start[, end]]) : کمترین اندیسی در داده‌ها را که زیردنبالهٔ sub یافت می‌شود برمی‌گرداند، طوری که sub در برش s[start:end] قرار گیرد. آرگومان‌های اختیاری start و end مانند نمادگذاری برش تفسیر می‌شوند. اگر sub یافت نشود -1 برمی‌گرداند.

زیردنباله‌ای که جست‌وجو می‌شود می‌تواند هر شیء شبه‌بایت یا عدد صحیح در بازهٔ ۰ تا ۲۵۵ باشد.

نکته: متد find() فقط باید زمانی به کار رود که لازم است موقعیت sub را بدانید. برای بررسی اینکه sub زیررشته هست یا نه، از عملگر in استفاده کنید:

>>> b'Py' in b'Python'
True

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

bytes.index(sub[, start[, end]])، bytearray.index(sub[, start[, end]]) : مانند find()، اما وقتی زیردنباله یافت نشود ValueError پرتاب می‌کند.

زیردنباله‌ای که جست‌وجو می‌شود می‌تواند هر شیء شبه‌بایت یا عدد صحیح در بازهٔ ۰ تا ۲۵۵ باشد.

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

bytes.join(iterable, /)، bytearray.join(iterable, /) : شیء bytes یا bytearray برمی‌گرداند که الحاق دنباله‌های داده‌های دودویی در iterable است. اگر در iterable مقداری باشد که شیء شبه‌بایت نباشد، از جمله اشیای str، TypeError پرتاب می‌شود. جداکنندهٔ بین عناصر محتوای شیء bytes یا bytearray است که این متد را فراهم می‌کند.

static bytes.maketrans(from, to, /)، static bytearray.maketrans(from, to, /) : این متد ایستا جدول ترجمه‌ای برمی‌گرداند که برای bytes.translate() قابل استفاده است و هر نویسه در from را به نویسهٔ هم‌موقعیت در to نگاشت می‌کند؛ from و to هر دو باید اشیای شبه‌بایت و هم‌طول باشند.

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

bytes.partition(sep, /)، bytearray.partition(sep, /) : دنباله را در اولین وقوع sep تقسیم می‌کند و ۳‌تاپلی شامل بخش پیش از جداکننده، خود جداکننده یا کپی bytearray آن، و بخش پس از جداکننده برمی‌گرداند. اگر جداکننده یافت نشود، ۳‌تاپلی شامل کپی دنبالهٔ اصلی و بعد دو شیء bytes یا bytearray خالی برمی‌گرداند.

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

bytes.replace(old, new, /, count=-1)، bytearray.replace(old, new, /, count=-1) : کپی دنباله را برمی‌گرداند که همهٔ وقوع‌های زیردنبالهٔ old با new جایگزین شده‌اند. اگر count داده شود، فقط count وقوع اول جایگزین می‌شوند. اگر count مشخص نشود یا -1 باشد، همهٔ وقوع‌ها جایگزین می‌شوند.

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

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

تغییر در نسخهٔ ۳٫۱۵: count اکنون به‌عنوان آرگومان کلیدواژه‌ای پشتیبانی می‌شود.

bytes.rfind(sub[, start[, end]])، bytearray.rfind(sub[, start[, end]]) : بیشترین اندیسی در دنباله را که زیردنبالهٔ sub یافت می‌شود برمی‌گرداند، طوری که sub در s[start:end] قرار گیرد. آرگومان‌های اختیاری start و end مانند نمادگذاری برش تفسیر می‌شوند. در صورت شکست -1 برمی‌گرداند.

زیردنباله‌ای که جست‌وجو می‌شود می‌تواند هر شیء شبه‌بایت یا عدد صحیح در بازهٔ ۰ تا ۲۵۵ باشد.

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

bytes.rindex(sub[, start[, end]])، bytearray.rindex(sub[, start[, end]]) : مانند rfind() اما وقتی زیردنبالهٔ sub یافت نشود ValueError پرتاب می‌کند.

زیردنباله‌ای که جست‌وجو می‌شود می‌تواند هر شیء شبه‌بایت یا عدد صحیح در بازهٔ ۰ تا ۲۵۵ باشد.

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

bytes.rpartition(sep, /)، bytearray.rpartition(sep, /) : دنباله را در آخرین وقوع sep تقسیم می‌کند و ۳‌تاپلی شامل بخش پیش از جداکننده، خود جداکننده یا کپی bytearray آن، و بخش پس از جداکننده برمی‌گرداند. اگر جداکننده یافت نشود، ۳‌تاپلی شامل دو شیء bytes یا bytearray خالی و بعد کپی دنبالهٔ اصلی برمی‌گرداند.

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

bytes.startswith(prefix[, start[, end]])، bytearray.startswith(prefix[, start[, end]]) : اگر داده‌های دودویی با prefix مشخص‌شده شروع شوند True، وگرنه False برمی‌گرداند. prefix می‌تواند تاپلی از پیشوندها برای جست‌وجو هم باشد. با start اختیاری، آزمون از آن موقعیت آغاز می‌شود. با end اختیاری، مقایسه در آن موقعیت متوقف می‌شود.

پیشوند(های) مورد جست‌وجو می‌تواند هر شیء شبه‌بایت باشد.

bytes.translate(table, /, delete=b'')، bytearray.translate(table, /, delete=b'') : کپی شیء bytes یا bytearray را برمی‌گرداند که همهٔ بایت‌های موجود در آرگومان اختیاری delete حذف شده‌اند، و بایت‌های باقی‌مانده از جدول ترجمهٔ داده‌شده، که باید شیء bytes به طول ۲۵۶ باشد، عبور داده شده‌اند.

می‌توانید از متد bytes.maketrans() برای ساخت جدول ترجمه استفاده کنید.

آرگومان table را برای ترجمه‌هایی که فقط نویسه‌ها را حذف می‌کنند روی None تنظیم کنید:

>>> b'read this short text'.translate(None, b'aeiou')
b'rd ths shrt txt'

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

متدهای زیر روی اشیای bytes و bytearray رفتارهای پیش‌فرضی دارند که استفاده از قالب‌های دودویی سازگار با ASCII را فرض می‌کنند، اما همچنان می‌توان با ارسال آرگومان‌های مناسب با داده‌های دودویی دلخواه به کارشان برد. توجه کنید که همهٔ متدهای bytearray در این بخش درجا عمل نمی‌کنند و در عوض اشیای جدید تولید می‌کنند.

bytes.center(width, fillbyte=b' ', /)، bytearray.center(width, fillbyte=b' ', /) : کپی شیء را وسط‌چین‌شده در دنباله‌ای به طول width برمی‌گرداند. پر کردن با fillbyte مشخص‌شده (پیش‌فرض فاصلهٔ ASCII) انجام می‌شود. برای اشیای bytes، اگر width کمتر یا مساوی len(s) باشد، دنبالهٔ اصلی برگردانده می‌شود.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.ljust(width, fillbyte=b' ', /)، bytearray.ljust(width, fillbyte=b' ', /) : کپی شیء را چپ‌چین‌شده در دنباله‌ای به طول width برمی‌گرداند. پر کردن با fillbyte مشخص‌شده (پیش‌فرض فاصلهٔ ASCII) انجام می‌شود. برای اشیای bytes، اگر width کمتر یا مساوی len(s) باشد، دنبالهٔ اصلی برگردانده می‌شود.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.lstrip(bytes=None, /)، bytearray.lstrip(bytes=None, /) : کپی دنباله را با بایت‌های ابتدایی مشخص‌شده حذف‌شده برمی‌گرداند. آرگومان bytes دنبالهٔ دودویی‌ای است که مجموعهٔ مقادیر بایتی را که باید حذف شوند مشخص می‌کند. اگر حذف شود یا None باشد، bytes به‌طور پیش‌فرض فضای خالی ASCII را حذف می‌کند. آرگومان bytes پیشوند نیست؛ بلکه همهٔ ترکیب‌های مقادیرش حذف می‌شوند:

>>> b'   spacious   '.lstrip()
b'spacious   '
>>> b'www.example.com'.lstrip(b'cmowz.')
b'example.com'

دنبالهٔ دودویی مقادیر بایتی که باید حذف شوند می‌تواند هر شیء شبه‌بایت باشد. برای متدی که یک رشتهٔ پیشوند را حذف می‌کند، نه همهٔ نویسه‌های یک مجموعه را، removeprefix() را ببینید. برای مثال:

>>> b'Arthur: three!'.lstrip(b'Arthur: ')
b'ee!'
>>> b'Arthur: three!'.removeprefix(b'Arthur: ')
b'three!'

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.rjust(width, fillbyte=b' ', /)، bytearray.rjust(width, fillbyte=b' ', /) : کپی شیء را راست‌چین‌شده در دنباله‌ای به طول width برمی‌گرداند. پر کردن با fillbyte مشخص‌شده (پیش‌فرض فاصلهٔ ASCII) انجام می‌شود. برای اشیای bytes، اگر width کمتر یا مساوی len(s) باشد، دنبالهٔ اصلی برگردانده می‌شود.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.rsplit(sep=None, maxsplit=-1)، bytearray.rsplit(sep=None, maxsplit=-1) : دنبالهٔ دودویی را به زیردنباله‌هایی از همان نوع تقسیم می‌کند و sep را به‌عنوان رشتهٔ جداکننده به کار می‌برد. اگر maxsplit داده شود، حداکثر maxsplit تقسیم انجام می‌شود، راست‌ترین‌ها. اگر sep مشخص نشود یا None باشد، هر زیردنباله‌ای که فقط از فضای خالی ASCII تشکیل شده جداکننده است. به‌جز تقسیم از راست، rsplit() مانند split() رفتار می‌کند که در ادامه با جزئیات توصیف شده است.

bytes.rstrip(bytes=None, /)، bytearray.rstrip(bytes=None, /) : کپی دنباله را با بایت‌های انتهایی مشخص‌شده حذف‌شده برمی‌گرداند. آرگومان bytes دنبالهٔ دودویی‌ای است که مجموعهٔ مقادیر بایتی را که باید حذف شوند مشخص می‌کند. اگر حذف شود یا None باشد، bytes به‌طور پیش‌فرض فضای خالی ASCII را حذف می‌کند. آرگومان bytes پسوند نیست؛ بلکه همهٔ ترکیب‌های مقادیرش حذف می‌شوند:

>>> b'   spacious   '.rstrip()
b'   spacious'
>>> b'mississippi'.rstrip(b'ipz')
b'mississ'

دنبالهٔ دودویی مقادیر بایتی که باید حذف شوند می‌تواند هر شیء شبه‌بایت باشد. برای متدی که یک رشتهٔ پسوند را حذف می‌کند، نه همهٔ نویسه‌های یک مجموعه را، removesuffix() را ببینید. برای مثال:

>>> b'Monty Python'.rstrip(b' Python')
b'M'
>>> b'Monty Python'.removesuffix(b' Python')
b'Monty'

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.split(sep=None, maxsplit=-1)، bytearray.split(sep=None, maxsplit=-1) : دنبالهٔ دودویی را به زیردنباله‌هایی از همان نوع تقسیم می‌کند و sep را به‌عنوان رشتهٔ جداکننده به کار می‌برد. اگر maxsplit داده شود و نامنفی باشد، حداکثر maxsplit تقسیم انجام می‌شود (بنابراین فهرست حداکثر maxsplit+1 عنصر خواهد داشت). اگر maxsplit مشخص نشود یا -1 باشد، محدودیتی بر تعداد تقسیم‌ها نیست (همهٔ تقسیم‌های ممکن انجام می‌شود).

اگر sep داده شود، جداکننده‌های متوالی با هم گروه نمی‌شوند و جداکنندهٔ زیردنباله‌های خالی تلقی می‌شوند (برای مثال b'1,,2'.split(b',') مقدار [b'1', b'', b'2'] را برمی‌گرداند). آرگومان sep می‌تواند از دنبالهٔ چندبایتی به‌عنوان یک جداکنندهٔ واحد تشکیل شود. تقسیم دنبالهٔ خالی با جداکنندهٔ مشخص بسته به نوع شیء در حال تقسیم [b''] یا [bytearray(b'')] را برمی‌گرداند. آرگومان sep می‌تواند هر شیء شبه‌بایت باشد.

برای مثال:

>>> b'1,2,3'.split(b',')
[b'1', b'2', b'3']
>>> b'1,2,3'.split(b',', maxsplit=1)
[b'1', b'2,3']
>>> b'1,2,,3,'.split(b',')
[b'1', b'2', b'', b'3', b'']
>>> b'1<>2<>3<4'.split(b'<>')
[b'1', b'2', b'3<4']

اگر sep مشخص نشود یا None باشد، الگوریتم تقسیم متفاوتی اعمال می‌شود: دنباله‌های متوالی فضای خالی ASCII یک جداکنندهٔ واحد تلقی می‌شوند، و اگر دنباله فضای خالی ابتدایی یا انتهایی داشته باشد، نتیجه در ابتدا یا انتها رشتهٔ خالی نخواهد داشت. در نتیجه، تقسیم دنبالهٔ خالی یا دنباله‌ای که فقط از فضای خالی ASCII تشکیل شده بدون جداکنندهٔ مشخص [] را برمی‌گرداند.

برای مثال:

>>> b'1 2 3'.split()
[b'1', b'2', b'3']
>>> b'1 2 3'.split(maxsplit=1)
[b'1', b'2 3']
>>> b'   1   2   3   '.split()
[b'1', b'2', b'3']

bytes.strip(bytes=None, /)، bytearray.strip(bytes=None, /) : کپی دنباله را با بایت‌های ابتدایی و انتهایی مشخص‌شده حذف‌شده برمی‌گرداند. آرگومان bytes دنبالهٔ دودویی‌ای است که مجموعهٔ مقادیر بایتی را که باید حذف شوند مشخص می‌کند. اگر حذف شود یا None باشد، bytes به‌طور پیش‌فرض فضای خالی ASCII را حذف می‌کند. آرگومان bytes پیشوند یا پسوند نیست؛ بلکه همهٔ ترکیب‌های مقادیرش حذف می‌شوند:

>>> b'   spacious   '.strip()
b'spacious'
>>> b'www.example.com'.strip(b'cmowz.')
b'example'

دنبالهٔ دودویی مقادیر بایتی که باید حذف شوند می‌تواند هر شیء شبه‌بایت باشد.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

متدهای زیر روی اشیای bytes و bytearray استفاده از قالب‌های دودویی سازگار با ASCII را فرض می‌کنند و نباید روی داده‌های دودویی دلخواه اعمال شوند. توجه کنید که همهٔ متدهای bytearray در این بخش درجا عمل نمی‌کنند و در عوض اشیای جدید تولید می‌کنند.

bytes.capitalize()، bytearray.capitalize() : کپی دنباله را برمی‌گرداند که هر بایت به‌عنوان نویسهٔ ASCII تفسیر شده، و بایت اول بزرگ و بقیه کوچک شده‌اند. مقادیر بایت غیر ASCII بدون تغییر عبور داده می‌شوند.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.expandtabs(tabsize=8)، bytearray.expandtabs(tabsize=8) : کپی دنباله را برمی‌گرداند که در آن همهٔ نویسه‌های tab ASCII بسته به ستون جاری و اندازهٔ tab داده‌شده با یک یا چند فاصلهٔ ASCII جایگزین شده‌اند. موقعیت‌های tab هر tabsize بایت رخ می‌دهند (پیش‌فرض ۸ است، که موقعیت‌های tab را در ستون‌های ۰، ۸، ۱۶ و غیره می‌دهد). برای گسترش دنباله، ستون جاری صفر قرار داده می‌شود و دنباله بایت‌به‌بایت بررسی می‌شود. اگر بایت نویسهٔ tab ASCII (b'\t') باشد، یک یا چند نویسهٔ فاصله در نتیجه درج می‌شود تا ستون جاری با موقعیت tab بعدی برابر شود. (خود نویسهٔ tab کپی نمی‌شود.) اگر بایت جاری خط جدید ASCII (b'\n') یا carriage return (b'\r') باشد، کپی می‌شود و ستون جاری به صفر بازنشانی می‌شود. هر مقدار بایت دیگر بدون تغییر کپی می‌شود و ستون جاری یکی افزایش می‌یابد، صرف‌نظر از اینکه مقدار بایت هنگام چاپ چگونه نمایش داده می‌شود:

>>> b'01\t012\t0123\t01234'.expandtabs()
b'01      012     0123    01234'
>>> b'01\t012\t0123\t01234'.expandtabs(4)
b'01  012 0123    01234'

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.isalnum()، bytearray.isalnum() : اگر همهٔ بایت‌های دنباله نویسه‌های الفبایی ASCII یا ارقام دهدهی ASCII باشند و دنباله خالی نباشد True، وگرنه False برمی‌گرداند. نویسه‌های الفبایی ASCII مقادیر بایتی در دنبالهٔ b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' هستند. ارقام دهدهی ASCII مقادیر بایتی در دنبالهٔ b'0123456789' هستند.

برای مثال:

>>> b'ABCabc1'.isalnum()
True
>>> b'ABC abc1'.isalnum()
False

bytes.isalpha()، bytearray.isalpha() : اگر همهٔ بایت‌های دنباله نویسه‌های الفبایی ASCII باشند و دنباله خالی نباشد True، وگرنه False برمی‌گرداند. نویسه‌های الفبایی ASCII مقادیر بایتی در دنبالهٔ b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ' هستند.

برای مثال:

>>> b'ABCabc'.isalpha()
True
>>> b'ABCabc1'.isalpha()
False

bytes.isascii()، bytearray.isascii() : اگر دنباله خالی باشد یا همهٔ بایت‌های دنباله ASCII باشند True، وگرنه False برمی‌گرداند. بایت‌های ASCII در بازهٔ ۰ تا 0x7F هستند.

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

bytes.isdigit()، bytearray.isdigit() : اگر همهٔ بایت‌های دنباله ارقام دهدهی ASCII باشند و دنباله خالی نباشد True، وگرنه False برمی‌گرداند. ارقام دهدهی ASCII مقادیر بایتی در دنبالهٔ b'0123456789' هستند.

برای مثال:

>>> b'1234'.isdigit()
True
>>> b'1.23'.isdigit()
False

bytes.islower()، bytearray.islower() : اگر دست‌کم یک نویسهٔ ASCII کوچک در دنباله باشد و هیچ نویسهٔ ASCII بزرگ نباشد True، وگرنه False برمی‌گرداند.

برای مثال:

>>> b'hello world'.islower()
True
>>> b'Hello world'.islower()
False

نویسه‌های ASCII کوچک مقادیر بایتی در دنبالهٔ b'abcdefghijklmnopqrstuvwxyz' هستند. نویسه‌های ASCII بزرگ مقادیر بایتی در دنبالهٔ b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' هستند.

bytes.isspace()، bytearray.isspace() : اگر همهٔ بایت‌های دنباله فضای خالی ASCII باشند و دنباله خالی نباشد True، وگرنه False برمی‌گرداند. نویسه‌های فضای خالی ASCII مقادیر بایتی در دنبالهٔ b' \t\n\r\x0b\f' هستند (فاصله، tab، خط جدید، carriage return، tab عمودی، form feed).

bytes.istitle()، bytearray.istitle() : اگر دنباله titlecase ASCII باشد و دنباله خالی نباشد True، وگرنه False برمی‌گرداند. برای جزئیات بیشتر دربارهٔ تعریف «titlecase» bytes.title() را ببینید.

برای مثال:

>>> b'Hello World'.istitle()
True
>>> b'Hello world'.istitle()
False

bytes.isupper()، bytearray.isupper() : اگر دست‌کم یک نویسهٔ الفبایی ASCII بزرگ در دنباله باشد و هیچ نویسهٔ ASCII کوچک نباشد True، وگرنه False برمی‌گرداند.

برای مثال:

>>> b'HELLO WORLD'.isupper()
True
>>> b'Hello world'.isupper()
False

نویسه‌های ASCII کوچک مقادیر بایتی در دنبالهٔ b'abcdefghijklmnopqrstuvwxyz' هستند. نویسه‌های ASCII بزرگ مقادیر بایتی در دنبالهٔ b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' هستند.

bytes.lower()، bytearray.lower() : کپی دنباله را برمی‌گرداند که همهٔ نویسه‌های ASCII بزرگ به همتای کوچک متناظرشان تبدیل شده‌اند.

برای مثال:

>>> b'Hello World'.lower()
b'hello world'

نویسه‌های ASCII کوچک مقادیر بایتی در دنبالهٔ b'abcdefghijklmnopqrstuvwxyz' هستند. نویسه‌های ASCII بزرگ مقادیر بایتی در دنبالهٔ b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' هستند.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.splitlines(keepends=False)، bytearray.splitlines(keepends=False) : فهرستی از خطوط دنبالهٔ دودویی را برمی‌گرداند و در مرزهای خط ASCII می‌شکند. این متد از رویکرد خط‌جدیدهای جهانی برای تقسیم خطوط استفاده می‌کند. شکست‌های خط در فهرست حاصل گنجانده نمی‌شوند مگر آنکه keepends داده شده و درست باشد.

برای مثال:

>>> b'ab c\n\nde fg\rkl\r\n'.splitlines()
[b'ab c', b'', b'de fg', b'kl']
>>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
[b'ab c\n', b'\n', b'de fg\r', b'kl\r\n']

برخلاف split() وقتی رشتهٔ جداکنندهٔ sep داده شده باشد، این متد برای رشتهٔ خالی فهرست خالی برمی‌گرداند، و شکست خط پایانی به خط اضافی نمی‌انجامد:

>>> b"".split(b'\n'), b"Two lines\n".split(b'\n')
([b''], [b'Two lines', b''])
>>> b"".splitlines(), b"One line\n".splitlines()
([], [b'One line'])

bytes.swapcase()، bytearray.swapcase() : کپی دنباله را برمی‌گرداند که همهٔ نویسه‌های ASCII کوچک به همتای بزرگ متناظرشان تبدیل شده‌اند و برعکس.

برای مثال:

>>> b'Hello World'.swapcase()
b'hELLO wORLD'

نویسه‌های ASCII کوچک مقادیر بایتی در دنبالهٔ b'abcdefghijklmnopqrstuvwxyz' هستند. نویسه‌های ASCII بزرگ مقادیر بایتی در دنبالهٔ b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' هستند.

برخلاف str.swapcase()، برای نسخه‌های دودویی همیشه bin.swapcase().swapcase() == bin برقرار است. تبدیل حروف در ASCII متقارن است، هرچند در حالت کلی برای نقاط کد یونیکد دلخواه چنین نیست.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.title()، bytearray.title() : نسخهٔ titlecase‌شدهٔ دنبالهٔ دودویی را برمی‌گرداند که در آن کلمات با نویسهٔ ASCII بزرگ شروع می‌شوند و بقیهٔ نویسه‌ها کوچک‌اند. مقادیر بایت بدون حالت (uncased) بدون تغییر می‌مانند.

برای مثال:

>>> b'Hello world'.title()
b'Hello World'

نویسه‌های ASCII کوچک مقادیر بایتی در دنبالهٔ b'abcdefghijklmnopqrstuvwxyz' هستند. نویسه‌های ASCII بزرگ مقادیر بایتی در دنبالهٔ b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' هستند. همهٔ مقادیر بایت دیگر بدون حالت‌اند.

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

>>> b"they're bill's friends from the UK".title()
b"They'Re Bill'S Friends From The Uk"

راه‌حلی برای آپوستروف‌ها را می‌توان با عبارت‌های منظم ساخت:

>>> import re
>>> def titlecase(s):
...     return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0)[0:1].upper() +
...                              mo.group(0)[1:].lower(),
...                   s)
...
>>> titlecase(b"they're bill's friends.")
b"They're Bill's Friends."

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد. bytes.upper()، bytearray.upper() : کپی دنباله را برمی‌گرداند که همهٔ نویسه‌های ASCII کوچک به همتای بزرگ متناظرشان تبدیل شده‌اند.

برای مثال:

>>> b'Hello World'.upper()
b'HELLO WORLD'

نویسه‌های ASCII کوچک مقادیر بایتی در دنبالهٔ b'abcdefghijklmnopqrstuvwxyz' هستند. نویسه‌های ASCII بزرگ مقادیر بایتی در دنبالهٔ b'ABCDEFGHIJKLMNOPQRSTUVWXYZ' هستند.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

bytes.zfill(width, /)، bytearray.zfill(width, /) : کپی دنباله را برمی‌گرداند که از چپ با ارقام ASCII b'0' پر شده تا دنباله‌ای به طول width بسازد. پیشوند علامت ابتدایی (b'+'/b'-') با درج پر کردن بعد از نویسهٔ علامت، نه پیش از آن، مدیریت می‌شود. برای اشیای bytes، اگر width کمتر یا مساوی len(seq) باشد، دنبالهٔ اصلی برگردانده می‌شود.

برای مثال:

>>> b"42".zfill(5)
b'00042'
>>> b"-42".zfill(5)
b'-0042'

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

قالب‌بندی بایت به سبک printf (printf-style bytes formatting)

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

اشیای bytes (bytes/bytearray) یک عملیات درون‌ساخت منحصربه‌فرد دارند: عملگر % (پیمانه). این همچنین به‌عنوان عملگر قالب‌بندی یا درون‌یابی bytes شناخته می‌شود. با format % values (که format شیء bytes است)، مشخصات تبدیل % در format با صفر یا چند عنصر از values جایگزین می‌شود. اثر آن شبیه استفاده از تابع sprintf() در زبان C است.

اگر format به یک آرگومان واحد نیاز داشته باشد، values می‌تواند یک شیء غیرتاپل باشد. ^۵ در غیر این صورت، values باید تاپلی با دقیقاً همان تعداد مورد مشخص‌شده توسط شیء bytes قالب، یا یک شیء نگاشت (mapping) واحد (برای مثال دیکشنری) باشد.

مشخص‌کنندهٔ تبدیل دو یا چند نویسه دارد و اجزای زیر را دارد که باید به همین ترتیب بیایند:

1. نویسهٔ '%'، که آغاز مشخص‌کننده را علامت می‌زند.

2. کلید نگاشت (اختیاری)، شامل دنبالهٔ پرانتزدار نویسه‌ها (برای مثال (somename)).

3. پرچم‌های تبدیل (اختیاری)، که بر نتیجهٔ برخی انواع تبدیل اثر می‌گذارند.

4. حداقل عرض فیلد (اختیاری). اگر به‌صورت '*' (ستاره) مشخص شود، عرض واقعی از عنصر بعدی تاپل در values خوانده می‌شود، و شیء مورد تبدیل بعد از حداقل عرض فیلد و دقت اختیاری می‌آید.

5. دقت (اختیاری)، به‌صورت '.' (نقطه) و بعد دقت. اگر به‌صورت '*' (ستاره) مشخص شود، دقت واقعی از عنصر بعدی تاپل در values خوانده می‌شود، و مقدار مورد تبدیل بعد از دقت می‌آید.

6. تغییردهندهٔ طول (اختیاری).

7. نوع تبدیل.

وقتی آرگومان راست دیکشنری (یا نوع نگاشت دیگر) است، قالب‌های داخل شیء bytes باید کلید نگاشت پرانتزداری به آن دیکشنری داشته باشند که بلافاصله بعد از نویسهٔ '%' درج شده است. کلید نگاشت مقداری را که باید قالب‌بندی شود از نگاشت انتخاب می‌کند. برای مثال:

>>> print(b'%(language)s has %(number)03d quote types.' %
...       {b'language': b"Python", b"number": 2})
b'Python has 002 quote types.'

در این حالت هیچ مشخص‌کنندهٔ * نمی‌تواند در قالب بیاید (چون به فهرست پارامتر ترتیبی نیاز دارند).

نویسه‌های پرچم تبدیل این‌ها هستند:

تغییردهندهٔ طول (h، l یا L) ممکن است حاضر باشد، اما نادیده گرفته می‌شود چون برای پایتون لازم نیست – بنابراین مثلاً %ld با %d یکسان است.

نوع‌های تبدیل این‌ها هستند:

یادداشت‌ها:

1. شکل جایگزین باعث می‌شود مشخص‌کنندهٔ هشتی ابتدایی ('0o') پیش از اولین رقم درج شود.

2. شکل جایگزین باعث می‌شود '0x' یا '0X' ابتدایی (بسته به اینکه قالب 'x' یا 'X' به کار رفته) پیش از اولین رقم درج شود.

3. شکل جایگزین باعث می‌شود نتیجه همیشه ممیز دهدهی داشته باشد، حتی اگر هیچ رقمی بعدش نیاید.

   دقت تعداد ارقام بعد از ممیز دهدهی را تعیین می‌کند و پیش‌فرض آن ۶ است.

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

   دقت تعداد ارقام معنادار پیش و پس از ممیز دهدهی را تعیین می‌کند و پیش‌فرض آن ۶ است.

5. اگر دقت N باشد، خروجی به N نویسه کوتاه می‌شود.

6. b'%s' منسوخ است، اما در سری ۳٫x حذف نخواهد شد.

7. b'%r' منسوخ است، اما در سری ۳٫x حذف نخواهد شد.

8. PEP 237 را ببینید.

نکته: نسخهٔ bytearray این متد درجا عمل نمی‌کند - همیشه شیء جدیدی تولید می‌کند، حتی اگر تغییری ایجاد نشده باشد.

همچنین ببینید: PEP 461 - افزودن قالب‌بندی % به bytes و bytearray

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

نمای حافظه (Memory views)

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

class memoryview(object) : یک memoryview می‌سازد که به object ارجاع می‌دهد. object باید پروتکل بافر را پشتیبانی کند. اشیای درون‌ساختی که پروتکل بافر را پشتیبانی می‌کنند شامل bytes و bytearray هستند.

memoryview مفهوم عنصر (element) را دارد، که واحد اتمی حافظه است که شیء مبدأ (object) مدیریت می‌کند. برای بسیاری نوع‌های ساده مانند bytes و bytearray، عنصر یک بایت منفرد است، اما نوع‌های دیگر مانند array.array ممکن است عناصر بزرگ‌تری داشته باشند.

memoryviewها نسبت به نوع داده‌های زیربنایی خود عمومی (generic) هستند.

len(view) برابر طول tolist() است، که نمایش فهرست تودرتوی نما است. اگر view.ndim == 1، این برابر تعداد عناصر نما است.

تغییر در نسخهٔ ۳٫۱۲: اگر view.ndim == 0، len(view) اکنون به‌جای برگرداندن ۱، TypeError پرتاب می‌کند.

ویژگی itemsize تعداد بایت‌ها در یک عنصر منفرد را به شما می‌دهد.

memoryview برش و اندیس‌گذاری را برای نمایش داده‌هایش پشتیبانی می‌کند. برش یک‌بعدی به یک زیرنما (subview) می‌انجامد:

>>> v = memoryview(b'abcefg')
>>> v[1]
98
>>> v[-1]
103
>>> v[1:4]
<memory at 0x7f3ddc9f4350>
>>> bytes(v[1:4])
b'bce'

اگر format یکی از مشخص‌کننده‌های قالب بومی (native) ماژول struct باشد، اندیس‌گذاری با عدد صحیح یا تاپلی از اعداد صحیح هم پشتیبانی می‌شود و یک عنصر واحد با نوع درست برمی‌گرداند. memoryviewهای یک‌بعدی را می‌توان با عدد صحیح یا تاپل تک‌عددی اندیس‌گذاری کرد. memoryviewهای چندبعدی را می‌توان با تاپل‌هایی از دقیقاً ndim عدد صحیح اندیس‌گذاری کرد، که ndim تعداد ابعاد است. memoryviewهای صفر‌بعدی را می‌توان با تاپل خالی اندیس‌گذاری کرد.

این هم مثالی با قالب غیربایتی:

>>> import array
>>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444])
>>> m = memoryview(a)
>>> m[0]
-11111111
>>> m[-1]
44444444
>>> m[::2].tolist()
[-11111111, -33333333]

اگر شیء زیربنایی نوشتنی باشد، memoryview انتساب برش یک‌بعدی را پشتیبانی می‌کند. تغییر اندازه مجاز نیست:

>>> data = bytearray(b'abcefg')
>>> v = memoryview(data)
>>> v.readonly
False
>>> v[0] = ord(b'z')
>>> data
bytearray(b'zbcefg')
>>> v[1:4] = b'123'
>>> data
bytearray(b'z123fg')
>>> v[2:3] = b'spam'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: memoryview assignment: lvalue and rvalue have different structures
>>> v[2:6] = b'spam'
>>> data
bytearray(b'z1spam')

memoryviewهای یک‌بعدی از نوع‌های هش‌پذیر (hashable) (فقط‌خواندنی) با قالب‌های ‘B’، ‘b’ یا ‘c’ هم هش‌پذیرند. هش به‌صورت hash(m) == hash(m.tobytes()) تعریف می‌شود:

>>> v = memoryview(b'abcefg')
>>> hash(v) == hash(b'abcefg')
True
>>> hash(v[2:4]) == hash(b'ce')
True
>>> hash(v[::-2]) == hash(b'abcefg'[::-2])
True

تغییر در نسخهٔ ۳٫۳: memoryviewهای یک‌بعدی اکنون قابل برش‌اند. memoryviewهای یک‌بعدی با قالب‌های ‘B’، ‘b’ یا ‘c’ اکنون هش‌پذیر هستند.

تغییر در نسخهٔ ۳٫۴: memoryview اکنون به‌طور خودکار با collections.abc.Sequence ثبت می‌شود.

تغییر در نسخهٔ ۳٫۵: memoryviewها اکنون با تاپلی از اعداد صحیح قابل اندیس‌گذاری‌اند.

تغییر در نسخهٔ ۳٫۱۴: memoryview اکنون نوع عمومی (generic type) است.

memoryview چند متد دارد:

__eq__(exporter) : یک memoryview و یک صادرکنندهٔ (exporter) PEP 3118 برابرند اگر شکل‌هایشان (shapes) هم‌ارز باشد و همهٔ مقادیر متناظر برابر باشند، وقتی کدهای قالب هر یک از عملوندها با سینتکس struct تفسیر شوند.

برای زیرمجموعهٔ رشته‌های قالب `struct` که در حال حاضر توسط `tolist()` پشتیبانی می‌شوند، `v` و `w` برابرند اگر `v.tolist() == w.tolist()`:

```
>>> import array
>>> a = array.array('I', [1, 2, 3, 4, 5])
>>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0])
>>> c = array.array('b', [5, 3, 1])
>>> x = memoryview(a)
>>> y = memoryview(b)
>>> x == a == y == b
True
>>> x.tolist() == a.tolist() == y.tolist() == b.tolist()
True
>>> z = y[::-2]
>>> z == c
True
>>> z.tolist() == c.tolist()
True
```

اگر هر یک از رشته‌های قالب توسط ماژول `struct` پشتیبانی نشود، اشیا همیشه نابرابر مقایسه می‌شوند (حتی اگر رشته‌های قالب و محتوای بافر یکسان باشند):

```
>>> from ctypes import BigEndianStructure, c_long
>>> class BEPoint(BigEndianStructure):
...     _fields_ = [("x", c_long), ("y", c_long)]
...
>>> point = BEPoint(100, 200)
>>> a = memoryview(point)
>>> b = memoryview(point)
>>> a == point
False
>>> a == b
False
```

توجه کنید که، مانند اعداد ممیز شناور، `v is w` برای اشیای memoryview *نتیجه نمی‌دهد* `v == w`.

> **تغییر در نسخهٔ ۳٫۳:** نسخه‌های پیشین حافظهٔ خام را بدون توجه به قالب مورد و ساختار منطقی آرایه مقایسه می‌کردند.

tobytes(order='C') : داده‌های بافر را به‌صورت رشتهٔ بایت (bytestring) برمی‌گرداند. این معادل فراخوانی سازندهٔ bytes روی memoryview است.

```
>>> m = memoryview(b"abc")
>>> m.tobytes()
b'abc'
>>> bytes(m)
b'abc'
```

برای آرایه‌های ناپیوسته نتیجه برابر نمایش فهرست مسطح‌شده با همهٔ عناصر تبدیل‌شده به بایت است. `tobytes()` همهٔ رشته‌های قالب را پشتیبانی می‌کند، از جمله آن‌هایی که در سینتکس ماژول `struct` نیستند.

> **افزوده‌شده در نسخهٔ ۳٫۸:** *order* می‌تواند {'C', 'F', 'A'} باشد. وقتی *order* برابر 'C' یا 'F' باشد، داده‌های آرایهٔ اصلی به ترتیب C یا Fortran تبدیل می‌شود. برای نماهای پیوسته، 'A' کپی دقیق حافظهٔ فیزیکی را برمی‌گرداند. به‌ویژه، ترتیب Fortran درون‌حافظه حفظ می‌شود. برای نماهای ناپیوسته، داده‌ها ابتدا به C تبدیل می‌شوند. *order=None* همان *order='C'* است.

hex(*, bytes_per_sep=1) و hex(sep, bytes_per_sep=1) : شیء رشته‌ای برمی‌گرداند که برای هر بایت در بافر دو رقم شانزدهی دارد.

```
>>> m = memoryview(b"abc")
>>> m.hex()
'616263'
```

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

> **تغییر در نسخهٔ ۳٫۸:** مشابه `bytes.hex()`، متد `memoryview.hex()` اکنون پارامترهای اختیاری *sep* و *bytes_per_sep* را برای درج جداکننده بین بایت‌ها در خروجی شانزدهی پشتیبانی می‌کند.

tolist() : داده‌های بافر را به‌صورت فهرستی از عناصر برمی‌گرداند.

```
>>> memoryview(b'abc').tolist()
[97, 98, 99]
>>> import array
>>> a = array.array('d', [1.1, 2.2, 3.3])
>>> m = memoryview(a)
>>> m.tolist()
[1.1, 2.2, 3.3]
```

> **تغییر در نسخهٔ ۳٫۳:** `tolist()` اکنون همهٔ قالب‌های بومی تک‌نویسه‌ای در سینتکس ماژول `struct` و همچنین نمایش‌های چندبعدی را پشتیبانی می‌کند.

toreadonly() : نسخهٔ فقط‌خواندنی شیء memoryview را برمی‌گرداند. شیء memoryview اصلی بدون تغییر می‌ماند.

```
>>> m = memoryview(bytearray(b'abc'))
>>> mm = m.toreadonly()
>>> mm.tolist()
[97, 98, 99]
>>> mm[0] = 42
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> m[0] = 43
>>> mm.tolist()
[43, 98, 99]
```

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

release() : بافر زیربنایی که شیء memoryview در معرض گذاشته آزاد می‌کند. بسیاری اشیا وقتی نمایی روی آن‌ها نگه داشته شود اقدامات ویژه‌ای انجام می‌دهند (برای مثال، یک bytearray تغییر اندازه را موقتاً ممنوع می‌کند)؛ بنابراین فراخوانی release() برای برداشتن این محدودیت‌ها (و آزاد کردن هر منبع آویزان) در اسرع وقت مفید است.

پس از فراخوانی این متد، هر عملیات بعدی روی نما `ValueError` پرتاب می‌کند (به‌جز خود `release()` که می‌توان چند بار فراخواند):

```
>>> m = memoryview(b'abc')
>>> m.release()
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object
```

پروتکل مدیریت بافت (context management) را می‌توان برای اثری مشابه، با دستور `with`، به کار برد:

```
>>> with memoryview(b'abc') as m:
...     m[0]
...
97
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object
```

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

cast(format, /) و cast(format, shape, /, *, order='C') : memoryview را به قالب یا شکل جدید تبدیل (cast) می‌کند. shape به‌طور پیش‌فرض [byte_length//new_itemsize] است، که یعنی نمای حاصل یک‌بعدی خواهد بود. مقدار بازگشتی memoryview جدیدی است، اما خود بافر کپی نمی‌شود. تبدیل‌های پشتیبانی‌شده 1D -> C-پیوسته (contiguous)، C-پیوسته -> 1D و F-پیوسته -> 1D هستند.

با *shape* چندبعدی، *order* چیدمان حافظهٔ نتیجه را انتخاب می‌کند: `'C'` برای C-پیوسته (ردیف‌اصلی، row-major، پیش‌فرض) یا `'F'` برای Fortran-پیوسته (ستون‌اصلی، column-major). بافر همچنان کپی نمی‌شود، بنابراین `order='F'` نمایی بدون کپی (zero-copy) روی بافری که داده‌های ستون‌اصلی دارد می‌دهد.

قالب مقصد به قالب بومی تک‌عنصری در سینتکس `struct` محدود است. یکی از قالب‌ها باید قالب بایتی ('B'، 'b' یا 'c') باشد. طول بایتی نتیجه باید با طول اصلی یکسان باشد. توجه کنید که همهٔ طول‌های بایتی ممکن است به سیستم‌عامل بستگی داشته باشند.

تبدیل 1D/long به 1D/unsigned bytes:

```
>>> import array
>>> a = array.array('l', [1,2,3])
>>> x = memoryview(a)
>>> x.format
'l'
>>> x.itemsize
8
>>> len(x)
3
>>> x.nbytes
24
>>> y = x.cast('B')
>>> y.format
'B'
>>> y.itemsize
1
>>> len(y)
24
>>> y.nbytes
24
```

تبدیل 1D/unsigned bytes به 1D/char:

```
>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  ...
TypeError: memoryview: invalid type for format 'B'
>>> y = x.cast('c')
>>> y[0] = b'a'
>>> b
bytearray(b'ayz')
```

تبدیل 1D/bytes به 3D/ints به 1D/signed char:

```
>>> import struct
>>> buf = struct.pack("i"*12, *list(range(12)))
>>> x = memoryview(buf)
>>> y = x.cast('i', shape=[2,2,3])
>>> y.tolist()
[[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
>>> y.format
'i'
>>> y.itemsize
4
>>> len(y)
2
>>> y.nbytes
48
>>> z = y.cast('b')
>>> z.format
'b'
>>> z.itemsize
1
>>> len(z)
48
>>> z.nbytes
48
```

تبدیل 1D/unsigned long به 2D/unsigned long:

```
>>> buf = struct.pack("L"*6, *list(range(6)))
>>> x = memoryview(buf)
>>> y = x.cast('L', shape=[2,3])
>>> len(y)
2
>>> y.nbytes
48
>>> y.tolist()
[[0, 1, 2], [3, 4, 5]]
```

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

> **تغییر در نسخهٔ ۳٫۵:** قالب مبدأ هنگام تبدیل به نمای بایتی دیگر محدود نیست.

> **تغییر در نسخهٔ ۳٫۱۶:** تبدیل نمای چندبعدی F-پیوسته به نمای یک‌بعدی اکنون پشتیبانی می‌شود.

count(value, /) : تعداد وقوع‌های value را می‌شمارد.

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

index(value, start=0, stop=sys.maxsize, /) : اندیس اولین وقوع value را (در اندیس start یا بعد از آن و پیش از اندیس stop) برمی‌گرداند.

اگر *value* یافت نشود `ValueError` پرتاب می‌کند.

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

چند ویژگی فقط‌خواندنی هم در دسترس است:

obj : شیء زیربنایی memoryview:

```
>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True
```

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

nbytes : nbytes == product(shape) * itemsize == len(m.tobytes()). این مقدار فضا به بایت است که آرایه در نمایش پیوسته استفاده می‌کند. لزوماً برابر len(m) نیست:

```
>>> import array
>>> a = array.array('i', [1,2,3,4,5])
>>> m = memoryview(a)
>>> len(m)
5
>>> m.nbytes
20
>>> y = m[::2]
>>> len(y)
3
>>> y.nbytes
12
>>> len(y.tobytes())
12
```

آرایه‌های چندبعدی:

```
>>> import struct
>>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)])
>>> x = memoryview(buf)
>>> y = x.cast('d', shape=[3,4])
>>> y.tolist()
[[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]]
>>> len(y)
3
>>> y.nbytes
96
```

تفسیر بافر مسطح به‌عنوان آرایهٔ Fortran-پیوسته (ستون‌اصلی):

```
>>> buf = bytes(range(6))
>>> y = memoryview(buf).cast('B', shape=[3, 2], order='F')
>>> y.f_contiguous
True
>>> y.tolist()
[[0, 3], [1, 4], [2, 5]]
```

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

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

readonly : مقدار بولی که نشان می‌دهد حافظه فقط‌خواندنی است یا نه.

format : رشته‌ای حاوی قالب (به سبک ماژول struct) برای هر عنصر در نما. memoryview را می‌توان از صادرکننده‌هایی با رشته‌های قالب دلخواه ساخت، اما برخی متدها (مثلاً tolist()) به قالب‌های بومی تک‌عنصری محدودند.

> **تغییر در نسخهٔ ۳٫۳:** قالب `'B'` اکنون طبق سینتکس ماژول struct مدیریت می‌شود. این یعنی `memoryview(b'abc')[0] == b'abc'[0] == 97`.

itemsize : اندازهٔ هر عنصر memoryview به بایت:

```
>>> import array, struct
>>> m = memoryview(array.array('H', [32000, 32001, 32002]))
>>> m.itemsize
2
>>> m[0]
32000
>>> struct.calcsize('H') == m.itemsize
True
```

ndim : عدد صحیحی که نشان می‌دهد حافظه چند بعد از آرایهٔ چندبعدی را نمایش می‌دهد.

shape : تاپلی از اعداد صحیح به طول ndim که شکل حافظه را به‌عنوان آرایهٔ N‌بعدی می‌دهد.

> **تغییر در نسخهٔ ۳٫۳:** وقتی ndim = 0، تاپل خالی به‌جای `None`.

strides : تاپلی از اعداد صحیح به طول ndim که اندازه به بایت برای دسترسی به هر عنصر در هر بُعد آرایه را می‌دهد.

> **تغییر در نسخهٔ ۳٫۳:** وقتی ndim = 0، تاپل خالی به‌جای `None`.

suboffsets : به‌طور داخلی برای آرایه‌های سبک PIL به کار می‌رود. مقدار فقط جنبهٔ اطلاعاتی دارد.

c_contiguous : مقدار بولی که نشان می‌دهد حافظه C-پیوسته است یا نه.

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

f_contiguous : مقدار بولی که نشان می‌دهد حافظه Fortran پیوسته است یا نه.

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

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

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

برای اطلاعات دربارهٔ ایمنی نخ اشیای memoryview در ساخت بدون GIL (free-threaded build)، ایمنی نخ برای اشیای memoryview را ببینید.

نوع‌های مجموعه (Set types) — set، frozenset

شیء مجموعه (set) گردایه‌ای نامرتب از اشیای هش‌پذیر متمایز است. کاربردهای رایج شامل آزمون عضویت، حذف تکراری‌ها از یک دنباله و محاسبهٔ عملیات ریاضی مانند اشتراک، اجتماع، تفاضل و تفاضل متقارن است. (برای ظرف‌های دیگر کلاس‌های درون‌ساخت dict، list و tuple و ماژول collections را ببینید.) برای هزینهٔ عملیات گوناگون مجموعه پیچیدگی زمانی را ببینید.

مانند گردایه‌های دیگر، مجموعه‌ها x in set، len(set) و for x in set را پشتیبانی می‌کنند. چون گردایهٔ نامرتب‌اند، مجموعه‌ها موقعیت عنصر یا ترتیب درج را ثبت نمی‌کنند. بنابراین، مجموعه‌ها اندیس‌گذاری، برش یا رفتارهای دنباله‌مانند دیگر را پشتیبانی نمی‌کنند.

در حال حاضر دو نوع مجموعهٔ درون‌ساخت وجود دارد: set و frozenset. نوع set تغییرپذیر است — محتوا را می‌توان با متدهایی مانند add() و remove() تغییر داد. چون تغییرپذیر است، مقدار هش ندارد و نمی‌توان آن را به‌عنوان کلید دیکشنری یا عنصر مجموعهٔ دیگر به کار برد. نوع frozenset تغییرناپذیر و هش‌پذیر است — محتوایش پس از ساخت قابل تغییر نیست؛ بنابراین می‌توان آن را به‌عنوان کلید دیکشنری یا عنصر مجموعهٔ دیگر به کار برد.

مجموعه‌های ناتهی (نه frozenset) را علاوه بر سازندهٔ set می‌توان با قرار دادن فهرستی از عناصر جداشده با ویرگول در آکولاد ساخت، برای مثال: {'jack', 'sjoerd'}.

سازنده‌های هر دو کلاس یکسان کار می‌کنند:

class set(iterable=(), /) و class frozenset(iterable=(), /) : مجموعه یا شیء frozenset جدیدی برمی‌گرداند که عناصرش از iterable گرفته شده است. عناصر مجموعه باید هش‌پذیر باشند. برای نمایش مجموعه‌ای از مجموعه‌ها، مجموعه‌های درونی باید اشیای frozenset باشند. اگر iterable مشخص نشود، مجموعهٔ خالی جدیدی برگردانده می‌شود.

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

• فهرستی از عناصر جداشده با ویرگول در آکولاد: {'jack', 'sjoerd'}
• مجموعه‌فشرده (set comprehension): {c for c in 'abracadabra' if c not in 'abc'}
• سازندهٔ نوع: set()، set('foobar')، set(['a', 'b', 'foo'])

نمونه‌های set و frozenset عملیات زیر را فراهم می‌کنند:

len(s) : تعداد عناصر مجموعهٔ s را برمی‌گرداند (کاردینالیتی s).

x in s : عضویت x را در s می‌آزماید.

x not in s : عدم عضویت x را در s می‌آزماید.

frozenset.isdisjoint(other, /)، set.isdisjoint(other, /) : اگر مجموعه با other هیچ عنصر مشترکی نداشته باشد True برمی‌گرداند. مجموعه‌ها جدا (disjoint) هستند اگر و فقط اگر اشتراکشان مجموعهٔ تهی باشد.

frozenset.issubset(other, /)، set.issubset(other, /)، set <= other : می‌آزماید که آیا هر عنصر مجموعه در other هست.

set < other : می‌آزماید که آیا مجموعه زیرمجموعهٔ سره (proper subset) other است، یعنی set <= other and set != other.

frozenset.issuperset(other, /)، set.issuperset(other, /)، set >= other : می‌آزماید که آیا هر عنصر other در مجموعه هست.

set > other : می‌آزماید که آیا مجموعه ابرمجموعهٔ سره (proper superset) other است، یعنی set >= other and set != other.

frozenset.union(*others)، set.union(*others)، set | other | ... : مجموعهٔ جدیدی با عناصر مجموعه و همهٔ others برمی‌گرداند.

frozenset.intersection(*others)، set.intersection(*others)، set & other & ... : مجموعهٔ جدیدی با عناصر مشترک مجموعه و همهٔ others برمی‌گرداند.

frozenset.difference(*others)، set.difference(*others)، set - other - ... : مجموعهٔ جدیدی با عناصر مجموعه که در others نیستند برمی‌گرداند.

frozenset.symmetric_difference(other, /)، set.symmetric_difference(other, /)، set ^ other : مجموعهٔ جدیدی با عناصری که در مجموعه یا other هستند ولی نه در هر دو برمی‌گرداند.

frozenset.copy()، set.copy() : کپی سطحی مجموعه را برمی‌گرداند.

توجه کنید، نسخه‌های غیرعملگری متدهای union()، intersection()، difference()، symmetric_difference()، issubset() و issuperset() هر تکرارپذیری را به‌عنوان آرگومان می‌پذیرند. در مقابل، همتاهای مبتنی بر عملگر آن‌ها لازم دارند آرگومان‌هایشان مجموعه باشد. این از ساختارهای مستعد خطا مانند set('abc') & 'cbs' به نفع set('abc').intersection('cbs') که خواناتر است پیشگیری می‌کند.

هر دو set و frozenset مقایسهٔ مجموعه با مجموعه را پشتیبانی می‌کنند. دو مجموعه برابرند اگر و فقط اگر هر عنصر هر مجموعه در دیگری باشد (هر کدام زیرمجموعهٔ دیگری باشد). مجموعه‌ای از مجموعهٔ دیگر کوچک‌تر است اگر و فقط اگر مجموعهٔ اول زیرمجموعهٔ سرهٔ دومی باشد (زیرمجموعه باشد، اما برابر نباشد). مجموعه‌ای از مجموعهٔ دیگر بزرگ‌تر است اگر و فقط اگر مجموعهٔ اول ابرمجموعهٔ سرهٔ دومی باشد (ابرمجموعه باشد، اما برابر نباشد).

نمونه‌های set با نمونه‌های frozenset بر اساس اعضایشان مقایسه می‌شوند. برای مثال، set('abc') == frozenset('abc') مقدار True را برمی‌گرداند و set('abc') in set([frozenset('abc')]) هم همین‌طور.

مقایسه‌های زیرمجموعه و برابری به تابع ترتیب کلی (total ordering) تعمیم نمی‌یابند. برای مثال، هر دو مجموعهٔ ناتهی جدا از هم برابر نیستند و زیرمجموعهٔ یکدیگر هم نیستند، بنابراین همهٔ این‌ها False برمی‌گردانند: a<b، a==b یا a>b.

از آنجا که مجموعه‌ها فقط ترتیب جزئی (روابط زیرمجموعه) تعریف می‌کنند، خروجی متد list.sort() برای فهرست‌هایی از مجموعه‌ها تعریف‌نشده است.

عناصر مجموعه، مانند کلیدهای دیکشنری، باید هش‌پذیر باشند.

عملیات دودویی که نمونه‌های set را با frozenset ترکیب می‌کنند نوع عملوند اول را برمی‌گردانند. برای مثال: frozenset('ab') | set('bc') نمونه‌ای از frozenset برمی‌گرداند.

عملیات زیر برای set در دسترس‌اند و روی نمونه‌های تغییرناپذیر frozenset اعمال نمی‌شوند:

set.update(*others)، set |= other | ... : مجموعه را به‌روز می‌کند و عناصر همهٔ others را به آن می‌افزاید.

set.intersection_update(*others)، set &= other & ... : مجموعه را به‌روز می‌کند و فقط عناصری را که در آن و همهٔ others یافت می‌شوند نگه می‌دارد.

set.difference_update(*others)، set -= other | ... : مجموعه را به‌روز می‌کند و عناصری را که در others یافت می‌شوند حذف می‌کند.

set.symmetric_difference_update(other, /)، set ^= other : مجموعه را به‌روز می‌کند و فقط عناصری را که در یکی از دو مجموعه هستند، نه در هر دو، نگه می‌دارد.

set.add(elem, /) : عنصر elem را به مجموعه می‌افزاید.

set.remove(elem, /) : عنصر elem را از مجموعه حذف می‌کند. اگر elem در مجموعه نباشد KeyError پرتاب می‌کند.

set.discard(elem, /) : اگر عنصر elem حاضر باشد آن را از مجموعه حذف می‌کند.

set.pop() : عنصری دلخواه را از مجموعه حذف و برمی‌گرداند. اگر مجموعه خالی باشد KeyError پرتاب می‌کند.

set.clear() : همهٔ عناصر را از مجموعه حذف می‌کند.

توجه کنید، نسخه‌های غیرعملگری متدهای update()، intersection_update()، difference_update() و symmetric_difference_update() هر تکرارپذیری را به‌عنوان آرگومان می‌پذیرند.

توجه کنید، آرگومان elem متدهای __contains__()، remove() و discard() می‌تواند مجموعه باشد. برای پشتیبانی از جست‌وجوی frozenset هم‌ارز، یک frozenset موقت از elem ساخته می‌شود.

مجموعه‌ها و frozensetها نسبت به نوع عناصرشان عمومی هستند.

همچنین ببینید: برای اطلاعات دقیق دربارهٔ تضمین‌های ایمنی نخ برای اشیای set، ایمنی نخ برای اشیای set را ببینید.

نوع‌های نگاشت (Mapping types) — dict، frozendict

شیء نگاشت (mapping) مقادیر هش‌پذیر را به اشیای دلخواه نگاشت می‌کند. در حال حاضر دو نوع نگاشت استاندارد وجود دارد: دیکشنری (dictionary) و frozendict. (برای ظرف‌های دیگر کلاس‌های درون‌ساخت list، set و tuple و ماژول collections را ببینید.) برای هزینهٔ عملیات گوناگون دیکشنری پیچیدگی زمانی را ببینید.

کلیدهای دیکشنری تقریباً مقادیر دلخواه‌اند. مقادیری که هش‌پذیر نیستند، یعنی مقادیر حاوی فهرست، دیکشنری یا نوع‌های تغییرپذیر دیگر (که بر اساس مقدار مقایسه می‌شوند، نه هویت شیء) را نمی‌توان به‌عنوان کلید به کار برد. مقادیری که برابر مقایسه می‌شوند (مانند 1، 1.0 و True) را می‌توان به‌جای هم برای اندیس‌گذاری یک ورودی دیکشنری به کار برد.

class dict(**kwargs)، class dict(mapping, /, **kwargs)، class dict(iterable, /, **kwargs) : دیکشنری جدیدی برمی‌گرداند که از یک آرگومان موضعی اختیاری و مجموعه‌ای احتمالاً خالی از آرگومان‌های کلیدواژه‌ای مقداردهی اولیه شده است.

دیکشنری‌ها را به چند روش می‌توان ساخت:

• فهرستی از جفت‌های key: value جداشده با ویرگول در آکولاد: {'jack': 4098, 'sjoerd': 4127} یا {4098: 'jack', 4127: 'sjoerd'}
• دیکشنری‌فشرده (dict comprehension): {}، {x: x ** 2 for x in range(10)}
• سازندهٔ نوع: dict()، dict([('foo', 100), ('bar', 200)])، dict(foo=100, bar=200)

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

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

دیکشنری‌ها برابر مقایسه می‌شوند اگر و فقط اگر جفت‌های (key, value) یکسان داشته باشند (صرف‌نظر از ترتیب). مقایسه‌های ترتیبی (‘<’، ‘<=’، ‘>=’، ‘>’) TypeError پرتاب می‌کنند. برای نشان دادن ساخت و برابری دیکشنری، مثال‌های زیر همگی دیکشنری برابر با {"one": 1, "two": 2, "three": 3} برمی‌گردانند:

>>> a = dict(one=1, two=2, three=3)
>>> b = {'one': 1, 'two': 2, 'three': 3}
>>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
>>> d = dict([('two', 2), ('one', 1), ('three', 3)])
>>> e = dict({'three': 3, 'one': 1, 'two': 2})
>>> f = dict({'one': 1, 'three': 3}, two=2)
>>> a == b == c == d == e == f
True

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

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

>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(d)
['one', 'two', 'three', 'four']
>>> list(d.values())
[1, 2, 3, 4]
>>> d["one"] = 42
>>> d
{'one': 42, 'two': 2, 'three': 3, 'four': 4}
>>> del d["two"]
>>> d["two"] = None
>>> d
{'one': 42, 'three': 3, 'four': 4, 'two': None}

تغییر در نسخهٔ ۳٫۷: ترتیب دیکشنری تضمین‌شده ترتیب درج است. این رفتار از ۳٫۶ جزئیات پیاده‌سازی CPython بود.

دیکشنری‌ها نسبت به دو نوع عمومی هستند، که (به ترتیب) نوع کلیدها و مقادیر دیکشنری را نشان می‌دهند.

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

list(d) : فهرستی از همهٔ کلیدهای به‌کاررفته در دیکشنری d برمی‌گرداند.

len(d) : تعداد موارد دیکشنری d را برمی‌گرداند.

d[key] : مورد d با کلید key را برمی‌گرداند. اگر key در نگاشت نباشد KeyError پرتاب می‌کند.

اگر زیرکلاسی از dict متد `__missing__()` را تعریف کند و *key* حاضر نباشد، عملیات `d[key]` آن متد را با کلید *key* به‌عنوان آرگومان فراخوانی می‌کند. عملیات `d[key]` سپس هرچه را فراخوانی `__missing__(key)` برگرداند یا پرتاب کند برمی‌گرداند یا پرتاب می‌کند. هیچ عملیات یا متد دیگری `__missing__()` را فراخوانی نمی‌کند. اگر `__missing__()` تعریف نشده باشد، `KeyError` پرتاب می‌شود. `__missing__()` باید متد باشد؛ نمی‌تواند متغیر نمونه باشد:

```
>>> class Counter(dict):
...     def __missing__(self, key):
...         return 0
...
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1
```

مثال بالا بخشی از پیاده‌سازی `collections.Counter` را نشان می‌دهد. متد `__missing__` متفاوتی توسط `collections.defaultdict` به کار می‌رود.

d[key] = value : d[key] را برابر value قرار می‌دهد.

del d[key] : d[key] را از d حذف می‌کند. اگر key در نگاشت نباشد KeyError پرتاب می‌کند.

key in d : اگر d کلید key را داشته باشد True، وگرنه False برمی‌گرداند.

key not in d : معادل not key in d.

iter(d) : تکرارگری روی کلیدهای دیکشنری برمی‌گرداند. این میان‌بر iter(d.keys()) است.

clear() : همهٔ موارد را از دیکشنری حذف می‌کند.

copy() : کپی سطحی دیکشنری را برمی‌گرداند.

classmethod fromkeys(iterable, value=None, /) : دیکشنری جدیدی با کلیدهایی از iterable و مقادیری برابر value می‌سازد.

`fromkeys()` متد کلاسی است که دیکشنری جدید برمی‌گرداند. *value* به‌طور پیش‌فرض `None` است. همهٔ مقادیر به یک نمونهٔ واحد ارجاع می‌دهند، بنابراین معمولاً معنا ندارد *value* شیء تغییرپذیری مانند فهرست خالی باشد. برای گرفتن مقادیر متمایز، به‌جای آن از [دیکشنری‌فشرده](https://docs.python.org/3/reference/expressions.html#dict) استفاده کنید.

get(key, default=None, /) : اگر key در دیکشنری باشد مقدار آن را، وگرنه default را برمی‌گرداند. اگر default داده نشود، به‌طور پیش‌فرض None است، بنابراین این متد هرگز KeyError پرتاب نمی‌کند.

items() : نمای (view) جدیدی از موارد دیکشنری (جفت‌های (key, value)) برمی‌گرداند. مستندات اشیای نما را ببینید.

keys() : نمای جدیدی از کلیدهای دیکشنری برمی‌گرداند. مستندات اشیای نما را ببینید.

pop(key, /)، pop(key, default, /) : اگر key در دیکشنری باشد، آن را حذف و مقدارش را برمی‌گرداند، وگرنه default را برمی‌گرداند. اگر default داده نشود و key در دیکشنری نباشد، KeyError پرتاب می‌شود.

popitem() : جفت (key, value) را از دیکشنری حذف و برمی‌گرداند. جفت‌ها به ترتیب LIFO (آخرین‌ورودی، اولین‌خروجی) برگردانده می‌شوند.

`popitem()` برای تکرار مخرب (destructive) روی دیکشنری مفید است، که اغلب در الگوریتم‌های مجموعه به کار می‌رود. اگر دیکشنری خالی باشد، فراخوانی `popitem()` `KeyError` پرتاب می‌کند.

> **تغییر در نسخهٔ ۳٫۷:** ترتیب LIFO اکنون تضمین شده است. در نسخه‌های پیشین، `popitem()` جفت کلید/مقدار دلخواهی برمی‌گرداند.

reversed(d) : تکرارگر معکوس روی کلیدهای دیکشنری برمی‌گرداند. این میان‌بر reversed(d.keys()) است.

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

setdefault(key, default=None, /) : اگر key در دیکشنری باشد، مقدار آن را برمی‌گرداند. اگر نه، key را با مقدار default درج می‌کند و default را برمی‌گرداند. default به‌طور پیش‌فرض None است.

update(**kwargs)، update(mapping, /, **kwargs)، update(iterable, /, **kwargs) : دیکشنری را با جفت‌های کلید/مقدار از mapping یا iterable و kwargs به‌روز می‌کند و کلیدهای موجود را بازنویسی می‌کند. None برمی‌گرداند.

`update()` یا شیء دیگری با متد `keys()` می‌پذیرد (که در آن `__getitem__()` با هر کلید برگردانده‌شده از متد فراخوانی می‌شود) یا تکرارپذیری از جفت‌های کلید/مقدار (به‌صورت تاپل یا تکرارپذیرهای دیگر به طول دو). اگر آرگومان‌های کلیدواژه‌ای مشخص شوند، دیکشنری سپس با آن جفت‌های کلید/مقدار به‌روز می‌شود: `d.update(red=1, blue=2)`.

values() : نمای جدیدی از مقادیر دیکشنری برمی‌گرداند. مستندات اشیای نما را ببینید.

مقایسهٔ برابری بین یک نمای `dict.values()` و دیگری همیشه `False` برمی‌گرداند. این برای مقایسهٔ `dict.values()` با خودش هم اعمال می‌شود:

```
>>> d = {'a': 1}
>>> d.values() == d.values()
False
```

d | other : دیکشنری جدیدی با کلیدها و مقادیر ادغام‌شدهٔ d و other می‌سازد، که هر دو باید دیکشنری باشند. وقتی d و other کلید مشترک داشته باشند، مقادیر other اولویت دارند.

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

d |= other : دیکشنری d را با کلیدها و مقادیر other، که می‌تواند نگاشت یا تکرارپذیر از جفت‌های کلید/مقدار باشد، به‌روز می‌کند. وقتی d و other کلید مشترک داشته باشند، مقادیر other اولویت دارند.

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

دیکشنری‌ها و نماهای دیکشنری معکوس‌پذیرند.

>>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
>>> d
{'one': 1, 'two': 2, 'three': 3, 'four': 4}
>>> list(reversed(d))
['four', 'three', 'two', 'one']
>>> list(reversed(d.values()))
[4, 3, 2, 1]
>>> list(reversed(d.items()))
[('four', 4), ('three', 3), ('two', 2), ('one', 1)]

تغییر در نسخهٔ ۳٫۸: دیکشنری‌ها اکنون معکوس‌پذیرند.

همچنین ببینید: frozendict و types.MappingProxyType را می‌توان برای ساخت نمای فقط‌خواندنی از یک dict به کار برد.

همچنین ببینید: برای اطلاعات دقیق دربارهٔ تضمین‌های ایمنی نخ برای اشیای dict، ایمنی نخ برای اشیای dict را ببینید.

اشیای نمای دیکشنری (Dictionary view objects)

اشیای برگردانده‌شده توسط dict.keys()، dict.values() و dict.items() اشیای نما (view objects) هستند. آن‌ها نمای پویایی از ورودی‌های دیکشنری فراهم می‌کنند، که یعنی وقتی دیکشنری تغییر کند، نما این تغییرات را بازتاب می‌دهد.

روی نماهای دیکشنری می‌توان تکرار کرد تا داده‌های مربوطه‌شان را تولید کنند، و آزمون عضویت را پشتیبانی می‌کنند:

len(dictview) : تعداد ورودی‌های دیکشنری را برمی‌گرداند.

iter(dictview) : تکرارگری روی کلیدها، مقادیر یا موارد (نمایش‌یافته به‌صورت تاپل‌های (key, value)) دیکشنری برمی‌گرداند.

تکرار روی کلیدها و مقادیر به ترتیب درج انجام می‌شود. این امکان ساخت جفت‌های (value, key) را با zip() می‌دهد: pairs = zip(d.values(), d.keys()). راه دیگر برای ساخت همان فهرست pairs = [(v, k) for (k, v) in d.items()] است.

تکرار روی نماها هنگام افزودن یا حذف ورودی‌ها در دیکشنری ممکن است RuntimeError پرتاب کند یا روی همهٔ ورودی‌ها تکرار نکند.

تغییر در نسخهٔ ۳٫۷: ترتیب دیکشنری تضمین‌شده ترتیب درج است.

x in dictview : اگر x در کلیدها، مقادیر یا موارد دیکشنری زیربنایی باشد True برمی‌گرداند (در حالت اخیر، x باید تاپل (key, value) باشد).

reversed(dictview) : تکرارگر معکوس روی کلیدها، مقادیر یا موارد دیکشنری برمی‌گرداند. نما به ترتیب معکوس درج پیمایش می‌شود.

تغییر در نسخهٔ ۳٫۸: نماهای دیکشنری اکنون معکوس‌پذیرند.

dictview.mapping : types.MappingProxyType برمی‌گرداند که دیکشنری اصلی‌ای را که نما به آن ارجاع می‌دهد در بر می‌گیرد.

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

نماهای کلیدها مجموعه‌مانندند چون ورودی‌هایشان یکتا و هش‌پذیر است. نماهای موارد (items) هم عملیات مجموعه‌مانند دارند چون جفت‌های (کلید، مقدار) یکتا هستند و کلیدها هش‌پذیرند. اگر همهٔ مقادیر در نمای موارد هم هش‌پذیر باشند، نمای موارد می‌تواند با مجموعه‌های دیگر هم‌کنش داشته باشد. (نماهای مقادیر مجموعه‌مانند تلقی نمی‌شوند چون ورودی‌ها عموماً یکتا نیستند.) برای نماهای مجموعه‌مانند، همهٔ عملیات تعریف‌شده برای کلاس پایهٔ انتزاعی collections.abc.Set در دسترس‌اند (برای مثال ==، < یا ^). هنگام استفاده از عملگرهای مجموعه، نماهای مجموعه‌مانند هر تکرارپذیری را به‌عنوان عملوند دیگر می‌پذیرند، برخلاف مجموعه‌ها که فقط مجموعه را به‌عنوان ورودی می‌پذیرند.

مثالی از استفاده از نماهای دیکشنری:

>>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
>>> keys = dishes.keys()
>>> values = dishes.values()

>>> # iteration
>>> n = 0
>>> for val in values:
...     n += val
...
>>> print(n)
504

>>> # keys and values are iterated over in the same order (insertion order)
>>> list(keys)
['eggs', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]

>>> # view objects are dynamic and reflect dict changes
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['bacon', 'spam']

>>> # set operations
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
>>> keys ^ {'sausage', 'juice'} == {'juice', 'sausage', 'bacon', 'spam'}
True
>>> keys | ['juice', 'juice', 'juice'] == {'bacon', 'spam', 'juice'}
True

>>> # get back a read-only proxy for the original dictionary
>>> values.mapping
mappingproxy({'bacon': 1, 'spam': 500})
>>> values.mapping['spam']
500

دیکشنری‌های منجمد (Frozen dictionaries)

class frozendict(**kwargs)، class frozendict(mapping, /, **kwargs)، class frozendict(iterable, /, **kwargs) : دیکشنری منجمد جدیدی برمی‌گرداند که از یک آرگومان موضعی اختیاری و مجموعه‌ای احتمالاً خالی از آرگومان‌های کلیدواژه‌ای مقداردهی اولیه شده است.

frozendict API مشابه dict دارد، با این تفاوت‌ها:

• dict متدهای بیشتری از frozendict دارد:

  • __delitem__()
  • __setitem__()
  • dict.clear()
  • dict.pop()
  • dict.popitem()
  • dict.setdefault()
  • dict.update()

• اگر همهٔ کلیدها و مقادیر هش‌پذیر باشند، frozendict را می‌توان با hash(frozendict) هش کرد.

• frozendict |= other فروزن‌دیکت را درجا تغییر نمی‌دهد بلکه دیکشنری منجمد جدیدی می‌سازد.

frozendict زیرکلاس dict نیست بلکه مستقیماً از object به ارث می‌برد.

مانند دیکشنری‌ها، frozendictها نسبت به دو نوع عمومی هستند، که (به ترتیب) نوع کلیدها و مقادیر frozendict را نشان می‌دهند.

classmethod fromkeys(iterable, value=None, /) : مشابه dict.fromkeys()، اما اگر نوع زیرکلاسی از frozendict باشد یا اگر سازنده frozendict برگردانده باشد، سازندهٔ نوع را دوباره با frozendict مقداردهی‌شده فراخوانی می‌کند.

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

نوع‌های مدیر بافت (Context manager types)

دستور with پایتون مفهوم بافت زمان اجرا (runtime context) تعریف‌شده توسط مدیر بافت (context manager) را پشتیبانی می‌کند. این با یک جفت متد پیاده‌سازی می‌شود که به کلاس‌های تعریف‌شده توسط کاربر اجازه می‌دهند بافت زمان اجرایی تعریف کنند که پیش از اجرای بدنهٔ دستور وارد می‌شود و وقتی دستور پایان می‌یابد از آن خارج می‌شود:

contextmanager.__enter__() : وارد بافت زمان اجرا می‌شود و یا همین شیء یا شیء دیگری مرتبط با بافت زمان اجرا را برمی‌گرداند. مقدار برگردانده‌شده توسط این متد به شناسهٔ بند as دستورهای with که از این مدیر بافت استفاده می‌کنند متصل می‌شود.

مثالی از مدیر بافتی که خودش را برمی‌گرداند شیء فایل است. اشیای فایل از __enter__() خودشان را برمی‌گردانند تا open() را بتوان به‌عنوان عبارت بافت در دستور with به کار برد.

مثالی از مدیر بافتی که شیء مرتبط برمی‌گرداند مدیری است که decimal.localcontext() برمی‌گرداند. این مدیرها بافت دهدهی فعال را روی کپی بافت دهدهی اصلی تنظیم می‌کنند و سپس کپی را برمی‌گردانند. این اجازه می‌دهد در بدنهٔ دستور with تغییراتی در بافت دهدهی جاری ایجاد شود بدون آنکه بر کد خارج از دستور with اثر بگذارد.

contextmanager.__exit__(exc_type, exc_val, exc_tb) : از بافت زمان اجرا خارج می‌شود و پرچم بولی برمی‌گرداند که نشان می‌دهد آیا هر استثنایی که رخ داده باید سرکوب شود. اگر هنگام اجرای بدنهٔ دستور with استثنایی رخ داده باشد، آرگومان‌ها نوع استثنا، مقدار و اطلاعات traceback را دارند. در غیر این صورت، هر سه آرگومان None هستند.

برگرداندن مقدار درست از این متد باعث می‌شود دستور with استثنا را سرکوب کند و اجرا را با دستور بلافاصله بعد از دستور with ادامه دهد. در غیر این صورت استثنا پس از پایان اجرای این متد به انتشار ادامه می‌دهد.

اگر این متد هنگام مدیریت استثنای پیشین از بلوک with استثنایی پرتاب کند، استثنای جدید پرتاب می‌شود و استثنای اصلی در ویژگی __context__ آن ذخیره می‌شود.

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

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

مولدهای (generators) پایتون و دکوراتور contextlib.contextmanager راه مناسبی برای پیاده‌سازی این پروتکل‌ها فراهم می‌کنند. اگر تابع مولد با دکوراتور contextlib.contextmanager تزئین شود، به‌جای تکرارگر تولیدشده توسط تابع مولد بدون دکوراتور، مدیر بافتی برمی‌گرداند که متدهای لازم __enter__() و __exit__() را پیاده می‌کند.

توجه کنید که برای هیچ‌یک از این متدها اسلات خاصی در ساختار نوع برای اشیای پایتون در Python/C API وجود ندارد. نوع‌های افزونه (extension types) که می‌خواهند این متدها را تعریف کنند باید آن‌ها را به‌صورت متد عادی قابل دسترسی در پایتون فراهم کنند. در مقایسه با سربار راه‌اندازی بافت زمان اجرا، سربار یک جست‌وجوی دیکشنری کلاس ناچیز است.

نوع‌های حاشیه‌نویسی نوع (Type annotation types) — Generic Alias، Union

نوع‌های درون‌ساخت هسته برای حاشیه‌نویسی‌های نوع (type annotations) Generic Alias و Union هستند.

نوع Generic Alias

اشیای GenericAlias عموماً با اندیس‌گذاری (subscripting) یک کلاس ساخته می‌شوند. اغلب با کلاس‌های ظرف مانند list یا dict به کار می‌روند. برای مثال، list[int] شیء GenericAlias است که با اندیس‌گذاری کلاس list با آرگومان int ساخته شده است. اشیای GenericAlias عمدتاً برای استفاده با حاشیه‌نویسی‌های نوع در نظر گرفته شده‌اند.

نکته: اندیس‌گذاری یک کلاس عموماً فقط وقتی ممکن است که کلاس متد ویژهٔ __class_getitem__() را پیاده کند.