انواع توکار

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

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

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

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

آزمودن ارزش درستی

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

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

• ثابت‌هایی که نادرست تعریف شده‌اند: None و False

• صفر از هر نوع عددی: 0، 0.0، 0j، Decimal(0)، Fraction(0, 1)

• دنباله‌ها و مجموعه‌های خالی: '', (), [], {}, set(), range(0)

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

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

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

عملیات	نتیجه	یادداشت‌ها
x or y	اگر x درست باشد، آنگاه x، وگرنه y	(1)
x and y	اگر x نادرست باشد، آنگاه x، وگرنه y	(2)
not x	اگر x نادرست باشد، آنگاه True، در غیر این صورت False	(3)

یادداشت‌ها:

1. این یک عملگر اتصال کوتاه است؛ بنابراین تنها در صورتی آرگومان دوم را ارزیابی می‌کند که آرگومان اول نادرست باشد.

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

3. not اولویت کمتری نسبت به عملگرهای غیربولی دارد، بنابراین not a == b به صورت not (a == b) تفسیر می‌شود و a == not b یک خطای سینتکس است.

مقایسه‌ها

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

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

عملیات	معنی
<	کاملاً کمتر از
<=	کوچک‌تر یا مساوی
>	اکیداً بزرگ‌تر از
>=	بزرگ‌تر یا مساوی
==	برابر
!=	نامساوی
is	هویت شیء
is not	نقیض هویت شیء

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

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

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

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

• اگر هر دو آرگومان عدد مختلط باشند، هیچ تبدیلی انجام نمی‌شود؛

• اگر هر یک از آرگومان‌ها عددی مختلط یا ممیز شناور باشد، دیگری به عدد ممیز شناور تبدیل می‌شود؛

• در غیر این صورت، هر دو باید عدد صحیح باشند و هیچ تبدیلی لازم نیست.

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

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

مقایسه میان اعداد از انواع مختلف چنان رفتار می‌کند که گویی مقادیر دقیق آن اعداد در حال مقایسه هستند. [2]

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

عملیات	نتیجه	یادداشت‌ها	مستندات کامل
x + y	مجموع x و y
x - y	تفاضل x و y
x * y	حاصل‌ضرب x و y
x / y	خارج قسمت x و y
x // y	خارج‌قسمت کف‌شده‌ی x و y	(1)(2)
x % y	باقیمانده‌ی x / y	(2)
-x	x منفی‌شده
+x	x بدون تغییر
abs(x)	قدر مطلق یا اندازه‌ی x		abs()
int(x)	x تبدیل‌شده به عدد صحیح	(3)(6)	int()
float(x)	x تبدیل‌شده به ممیز شناور	(4)(6)	float()
complex(re, im)	عدد مختلطی با بخش حقیقی re و بخش موهومی im. مقدار پیش‌فرض im صفر است.	(6)	complex()
c.conjugate()	مزدوج عدد مختلط c
divmod(x, y)	جفت (x // y, x % y)	(2)	divmod()
pow(x, y)	x به توان y	(5)	pow()
x ** y	x به توان y	(5)

یادداشت‌ها:

1. همچنین به آن تقسیم عدد صحیح نیز گفته می‌شود. برای عملوندهایی از نوع int، نتیجه از نوع int است. برای عملوندهایی از نوع float، نتیجه از نوع float است. در حالت کلی، نتیجه یک عدد صحیح کامل است، هرچند نوع نتیجه لزوماً 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" را با پیشوند اختیاری "+" یا "-" برای عدد نیست (NaN) و بی‌نهایت مثبت یا منفی می‌پذیرد.

5. پایتون pow(0, 0) و 0 ** 0 را برابر با 1 تعریف می‌کند، همان‌گونه که در زبان‌های برنامه‌نویسی رایج است.

6. مقادیر لفظی عددی (numeric literals) پذیرفته‌شده شامل رقم‌های 0 تا 9 یا هر معادل یونیکدی آن‌ها هستند (نقطه‌های کد (code points) دارای ویژگی Nd).

   برای فهرست کامل نقطه‌های کد دارای ویژگی Nd به استاندارد یونیکد مراجعه کنید.

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

عملیات	نتیجه
math.trunc(x)	x قطع‌شده به Integral
round(x[, n])	x گرد شده به n رقم، با گرد کردن نیم به زوج. اگر n حذف شود، به طور پیش‌فرض ۰ است.
math.floor(x)	بزرگ‌ترین Integral <= x
math.ceil(x)	کوچک‌ترین Integral بزرگ‌تر یا مساوی x

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

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

عملیات بیتی تنها برای اعداد صحیح معنا دارند. نتیجه‌ی عملیات بیتی چنان محاسبه می‌شود که گویی در مکمل دو و با تعداد نامتناهی بیت علامت انجام شده است.

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

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

عملیات	نتیجه	یادداشت‌ها
x | y	یا <or> بیتیِ x و y	(4)
x ^ y	یای انحصاری بیتی <exclusive or> x و y	(4)
x & y	و <and> بیتیِ x و y	(4)
x << n	x به اندازه‌ی n بیت به چپ منتقل شده است	(1)(2)
x >> n	x به اندازه‌ی n بیت به سمت راست منتقل شده	(1)(3)
~x	بیت‌های x وارونه‌شده

یادداشت‌ها:

1. شمارش‌های انتقال (shift) منفی غیرمجاز هستند و باعث می‌شوند که یک ValueError پرتاب شود.

2. انتقال به چپ به اندازه‌ی n بیت معادل ضرب در pow(2, n) است.

3. یک انتقال به راست به اندازه‌ی n بیت معادل تقسیم کف بر pow(2, n) است.

4. انجام این محاسبات با دست‌کم یک بیت اضافی برای بسط علامت در یک نمایش متناهی مکمل دو (پهنای بیت کاری 1 + max(x.bit_length(), y.bit_length()) یا بیشتر) برای به‌دست‌آوردن همان نتیجه‌ای که گویی تعداد بی‌نهایتی بیت علامت وجود دارد، کافی است.

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

نوع int 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

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

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

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

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)

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

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

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

تغییر یافته در نسخه‌ی 3.11: مقدار پیش‌فرض برای آرگومان byteorder اضافه شد.

int.as_integer_ratio()

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

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

int.is_integer()

True را برمی‌گرداند. برای سازگاری نوع‌دهی اردکی با float.is_integer() وجود دارد.

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

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

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

classmethod float.from_number(x)

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

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

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

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

float.as_integer_ratio()

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

float.is_integer()

اگر نمونه‌ی اعشاری متناهی باشد و مقدار صحیح داشته باشد، True و در غیر این صورت False برمی‌گرداند:

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

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

float.hex()

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

classmethod float.fromhex(s)

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

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

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

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

where the optional sign may be either + or -, integer and fraction are strings of hexadecimal digits, and exponent is a decimal integer with an optional leading sign. Case is not significant, and there must be at least one hexadecimal digit in either the integer or the fraction. This syntax is similar to the syntax specified in section 6.4.4.2 of the C99 standard, and also to the syntax used in Java 1.5 onwards. In particular, the output of float.hex() is usable as a hexadecimal floating-point literal in C or Java code, and hexadecimal strings produced by C's %a format character or Java's Double.toHexString are accepted by 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 کلاس پایه انتزاعی numbers.Complex را پیاده‌سازی می‌کند. complex همچنین متدهای اضافی زیر را نیز دارد.

classmethod complex.from_number(x)

متد کلاس برای تبدیل یک عدد به یک عدد مختلط.

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

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

درهم‌سازی انواع عددی

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

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

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

• اگر 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 جایگزین می‌شود.

برای روشن شدن قواعد بالا، در اینجا نمونه‌ای از کد پایتون آمده است که معادل hash توکار بوده و برای محاسبه‌ی هش یک عدد گویا، 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 و != را به &، | و ^ ترجیح دهید.

منسوخ شده از نسخه‌ی 3.12: استفاده از عملگر وارون‌سازی بیتی ~ منسوخ شده است و در Python 3.16 خطایی پرتاب خواهد کرد.

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

Iteration-related types

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

Iterables

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

container.__iter__()

یک شیء پیمایش‌گر بازمی‌گرداند. این شیء موظف است از پروتکل پیمایش‌گری که در ادامه شرح داده شده است پشتیبانی کند. اگر یک ظرف از انواع مختلف تکرار پشتیبانی می‌کند، می‌توان متدهای اضافی‌ای ارائه داد که به‌طور خاص برای آن انواع تکرار، پیمایش‌گر درخواست کنند. (نمونه‌ای از شیءای که از چند شکل پیمایش پشتیبانی می‌کند، ساختاری درختی است که هم پیمایش عرضی (breadth-first) و هم پیمایش عمقی (depth-first) را پشتیبانی می‌کند.) این متد متناظر با جایگاه tp_iter در ساختار نوع اشیاء پایتون در Python/C API است.

Iterators

خود اشیاء پیمایش‌گر ملزم به پشتیبانی از دو متد زیر هستند که در مجموع پروتکل پیمایش‌گر <iterator protocol> را تشکیل می‌دهند:

iterator.__iter__()

خودِ شیء پیمایش‌گر را بازمی‌گرداند. این امر برای آن ضروری است که بتوان هم از ظرف‌ها و هم از پیمایش‌گرها همراه با دستورهای for و in استفاده کرد. این متد متناظر با جایگاه tp_iter از ساختار نوع اشیاء پایتون در Python/C API است.

iterator.__next__()

آیتم بعدی را از پیمایش‌گر برگردانید. اگر آیتم‌های بیشتری وجود نداشته باشند، استثنای StopIteration را پرتاب کنید. این متد متناظر با جایگاه tp_iternext در ساختار نوع اشیاء پایتون در API پایتون/C است.

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

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

Generator types

Python's generators -- or more precisely, generator functions and generator iterators -- provide a convenient way to implement the iterator protocol.

A function that contains one or more yield expressions is a generator function. For example:

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

Generator functions behave as regular user-defined functions (for example, they have the same attributes), except that calling a generator function returns a generator iterator:

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

Iterating a generator iterator executes code of the underlying generator function, producing each yielded value in turn:

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

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

One common use for generator functions is implementing the __iter__() method of custom iterable objects. For example:

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

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

Generator iterators

Generator iterators implement the iterator protocol. Iterating them drives execution of the underlying generator function.

generator.__next__()

Starts the execution of a generator function or resumes it at the yield expression where the function is currently suspended. When a generator function is resumed with a __next__() method, the current yield expression always evaluates to None. The execution then continues to the next yield expression, where the generator is suspended again, and the value of the expression after the yield keyword is returned to __next__()'s caller. If the generator exits without yielding another value, __next__() raises a StopIteration exception, signalling that iteration has completed.

This method is normally called implicitly, for example by a for loop, or by the built-in next() function.

Generator iterators have a few more methods than generic iterators, which can be used to control the execution of the underlying generator function:

generator.send(value)

"Sends" a value into the generator function: the value argument becomes the result of the current yield expression.

Otherwise, this method behaves like __next__(): it resumes the underlying function and either returns the next yielded value or raises StopIteration.

When send() is called to start the generator, it must be called with None as the argument, because there is no current yield expression that could receive the value.

generator.throw(value)

generator.throw(type[, value[, traceback]])

Raises an exception at the point where the generator is currently suspended.

Otherwise, this method behaves like __next__(): it resumes the underlying function and either returns the next yielded value or raises StopIteration. If the generator function does not catch the passed-in exception, or raises a different exception, then that exception propagates to the caller.

When throw() is called to start the generator, the generator immediately exits (that is, subsequent calls to __next__() will raise StopIteration) and the thrown exception is propagated to throw()'s caller.

In typical use, this is called with a single argument, an exception instance, similar to the way the raise keyword is used.

For backwards compatibility, however, the second signature is supported, following a convention from older versions of Python. The type argument should be an exception class, and value should be an exception instance. If the value is not provided, the type constructor is called to get an instance. If traceback is provided, it is set on the exception, otherwise any existing __traceback__ attribute stored in value may be cleared.

تغییر یافته در نسخه‌ی 3.12: The second signature (type[, value[, traceback]]) is deprecated and may be removed in a future version of Python.

generator.close()

Raises a GeneratorExit exception at the point where the generator function is currently suspended (equivalent to calling throw(GeneratorExit)).

If the generator function has already exited (due to an exception or normal return), or raises GeneratorExit (by not catching the exception), close() returns None. If the generator yields a value, a RuntimeError is raised. If the generator raises any other exception, it is propagated to the caller. If a generator returns a value upon being closed, that value is returned by close().

When a generator iterator is garbage collected before it has exited, close() is called automatically.

تغییر یافته در نسخه‌ی 3.13: If a generator returns a value upon being closed, the value is returned by close(). Previously, it returned None.

Calling any of the generator methods (__next__(), send(), throw(), close()) while one of these methods is already executing raises a ValueError exception.

Asynchronous generator iterators

This subsection describes the methods of an asynchronous generator iterator, which are used to control the execution of an asynchronous generator function.

async agen.__anext__()

Returns an awaitable which when run starts to execute the asynchronous generator function or resumes it at the yield expression where the function is currently suspended. When an asynchronous generator function is resumed with an __anext__() method, the current yield expression always evaluates to None in the returned awaitable, which when run will continue to the next yield expression. The value of the expression after the yield keyword is the value of the StopIteration exception raised by the completing coroutine. If the asynchronous generator exits without yielding another value, the awaitable instead raises a StopAsyncIteration exception, signalling that the asynchronous iteration has completed.

This method is normally called implicitly by an async for loop, or by the built-in anext() function.

Asynchronous generator-iterators have a few more methods than generic asynchronous iterators, which can be used to control the execution of the underlying generator function:

async agen.asend(value)

Returns an awaitable which, when run, "sends" a value into the underlying asynchronous generator function: the value argument becomes the result of the current yield expression.

Otherwise, this method behaves like __anext__(): when the returned awaitable runs, it resumes the underlying function and either returns the next yielded value as the value of the raised StopIteration, or raises StopAsyncIteration.

When asend() is called to start the asynchronous generator, it must be called with None as the argument, because there is no yield expression that could receive the value.

async agen.athrow(value)

async agen.athrow(type[, value[, traceback]])

Returns an awaitable that, when run, raises an exception at the point where the underlying asynchronous generator function is currently suspended.

Otherwise, this method behaves like __anext__(): when the returned awaitable runs, it resumes the underlying function (with an exception raised) and either returns the next yielded value as the value of the raised StopIteration, or raises StopAsyncIteration. If the underlying function does not catch the passed-in exception, or raises a different exception, then when the awaitable is run, that exception propagates to the caller of the awaitable.

When athrow() is called to start the generator, the generator exits when the awaitable runs (that is, subsequent results from __anext__() will raise StopAsyncIteration when run) and the thrown exception is propagated to the awaitable's caller.

In typical use, this is called with a single argument, an exception instance, similar to the way the raise keyword is used.

For backwards compatibility, however, the second signature is supported. An exception instance is created from three arguments in the same way as in generator.throw().

تغییر یافته در نسخه‌ی 3.12: The second signature (type[, value[, traceback]]) is deprecated and may be removed in a future version of Python.

async agen.aclose()

Returns an awaitable that when run will throw a GeneratorExit into the underlying asynchronous generator function at the point where it is currently suspended (equivalent to calling athrow(GeneratorExit)).

If the asynchronous generator function then exits gracefully, is already closed, or raises GeneratorExit (by not catching the exception), then the returned awaitable will raise a StopIteration exception. Any further awaitables returned by subsequent calls to the asynchronous generator will raise a StopAsyncIteration exception.

If the asynchronous generator yields a value, a RuntimeError is raised by the awaitable. If the asynchronous generator raises any other exception, that exception is propagated to the caller of the awaitable.

If the asynchronous generator has already exited due to an exception or normal exit, then further calls to aclose() will return an awaitable that does nothing.

انواع دنباله --- list، tuple، range

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

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

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

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

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

See Time complexity of operations on built-in types for the costs of the various sequence operations.

عملیات	نتیجه	یادداشت‌ها
x in s	اگر یکی از آیتم‌های s برابر با x باشد، True؛ در غیر این صورت False	(1)
x not in s	اگر یکی از آیتم‌های s با x برابر باشد، False؛ در غیر این صورت True	(1)
s + t	الحاق s و t	(6)(7)
s * n یا n * s	معادل افزودن s به خودش n بار است	(2)(7)
s[i]	iامین آیتم s، مبدأ ۰	(3)(8)
s[i:j]	اسلایسی از s از i تا j	(3)(4)
s[i:j:k]	اسلایسی از s از i تا j با گام k	(3)(5)
len(s)	طول s
min(s)	کوچک‌ترین آیتم s
max(s)	بزرگ‌ترین آیتم s

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

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

   • اگر در حال الحاق شیءهای str هستید، می‌توانید یک فهرست بسازید و در پایان از str.join() استفاده کنید، یا در غیر این صورت در یک نمونه از io.StringIO بنویسید و پس از اتمام، مقدار آن را بازیابی کنید

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

   • اگر اشیاء tuple را الحاق می‌کنید، در عوض یک list را گسترش دهید

   • برای سایر انواع، مستندات کلاس مربوطه را بررسی کنید

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

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

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

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

sequence.count(value, /)

تعداد کل تکرارهای value در sequence را بازمی‌گرداند.

sequence.index(value[, start[, stop]])

اندیس اولین وقوع value در sequence را برمی‌گرداند.

اگر مقدار در دنباله یافت نشود، ValueError پرتاب می‌شود.

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

ملاحظه

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

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

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

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

تلاش برای هش کردن یک دنباله‌ی تغییرناپذیر که حاوی مقادیر هش‌ناپذیر باشد، منجر به TypeError خواهد شد.

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

عملیات‌های جدول زیر بر روی انواع دنباله تغییرپذیر تعریف شده‌اند. برای آسان‌تر شدن پیاده‌سازی صحیح این عملیات‌ها بر روی انواع دنباله سفارشی، کلاس پایه انتزاعی (ABC) collections.abc.MutableSequence فراهم شده است.

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

عملیات	نتیجه	یادداشت‌ها
s[i] = x	آیتم i از s با x جایگزین می‌شود
del s[i]	آیتم i از s را حذف می‌کند
s[i:j] = t	اسلایسی از s از i تا j با محتوای پیمایش‌پذیر t جایگزین می‌شود
del s[i:j]	المان‌های s[i:j] را از فهرست حذف می‌کند (همانند s[i:j] = [])
s[i:j:k] = t	المان‌های s[i:j:k] با المان‌های t جایگزین می‌شوند	(1)
del s[i:j:k]	المان‌های s[i:j:k] را از فهرست حذف می‌کند
s += t	s را با محتویات t گسترش می‌دهد (عمدتاً همانند s[len(s):len(s)] = t)
s *= n	s را با محتوای خود که n بار تکرار شده است به‌روزرسانی می‌کند	(2)

یادداشت‌ها:

1. اگر k برابر با 1 نباشد، t باید همان طول اسلایسی را داشته باشد که جایگزین آن می‌شود.

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

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

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

sequence.append(value, /)

value را به انتهای دنباله اضافه می‌کند. این معادل نوشتن seq[len(seq):len(seq)] = [value] است.

sequence.clear()

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

همه آیتم‌های دنباله را حذف می‌کند. این کار معادل نوشتن del sequence[:] است.

sequence.copy()

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

یک کپی سطحی از دنباله بسازید. این معادل نوشتن sequence[:] است.

راهنمایی

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

sequence.extend(iterable, /)

sequence را با محتوای iterable گسترش می‌دهد. در بیشتر موارد، این همانند نوشتن seq[len(seq):len(seq)] = iterable است.

sequence.insert(index, value, /)

مقدار را در دنباله در اندیس داده‌شده درج می‌کند. این معادل نوشتنِ sequence[index:index] = [value] است.

sequence.pop(index=-1, /)

Retrieve the item at index and also remove it from sequence. By default, the last item in sequence is removed and returned.

sequence.remove(value, /)

اولین آیتمی از دنباله را که در آن sequence[i] == value است، حذف کنید.

اگر مقدار در دنباله یافت نشود، ValueError پرتاب می‌شود.

sequence.reverse()

آیتم‌های دنباله را درجا وارونه می‌کند. این متد هنگام وارونه‌کردن یک دنباله بزرگ، صرفه‌جویی در فضا را حفظ می‌کند. برای یادآوری به کاربران اینکه این متد از طریق اثر جانبی عمل می‌کند، مقدار None را بازمی‌گرداند.

فهرست‌ها

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

class list(iterable=(), /)

فهرست‌ها را می‌توان به چند روش ساخت:

• استفاده از یک جفت براکت مربع برای نشان دادن فهرست خالی: []

• با استفاده از کروشه‌ها و جدا کردن آیتم‌ها با کاما: [a]، [a, b, c]

• با استفاده از یک درک فهرستی: [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().

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

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

sort(*, key=None, reverse=False)

این متد فهرست را درجا مرتب می‌کند و تنها از مقایسه‌های < میان آیتم‌ها استفاده می‌کند. استثناها سرکوب نمی‌شوند - اگر هر یک از عملیات مقایسه شکست بخورد، تمام عملیات مرتب‌سازی با شکست مواجه خواهد شد (و به احتمال زیاد فهرست در حالتی تا حدی تغییر یافته باقی خواهد ماند).

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

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

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

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

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

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

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

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

همچنین ملاحظه نمائید

برای اطلاعات مفصل درباره تضمین‌های ایمنی نخ برای اشیاء list، به ایمنی در برابر نخ‌ها برای اشیای فهرست مراجعه کنید.

تاپل‌ها

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

class tuple(iterable=(), /)

تاپل‌ها را می‌توان به روش‌های گوناگونی ساخت:

• استفاده از یک جفت پرانتز برای نشان دادن تاپل خالی: ()

• استفاده از یک ویرگول انتهایی برای یک تاپل تک‌عضوی (singleton tuple): 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() انتخاب مناسب‌تری نسبت به یک شیء تاپل ساده باشد.

بازه‌ها

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

class range(stop, /)

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

آرگومان‌های سازنده‌ی range باید اعداد صحیح باشند (یا int توکار، یا هر شیءای که متد ویژه‌ی __index__() را پیاده‌سازی کند). اگر آرگومان step ذکر نشده باشد، مقدار پیش‌فرض آن 1 است. اگر آرگومان start ذکر نشده باشد، مقدار پیش‌فرض آن 0 است. اگر step صفر باشد، استثنای ValueError پرتاب می‌شود.

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

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

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

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

مثال‌های بازه:

>>> 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))
[]

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

start

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

stop

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

step

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

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

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

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

تغییر یافته در نسخه‌ی 3.2: کلاس پایه انتزاعی (ABC) دنباله را پیاده‌سازی می‌کند. از اسلایس و اندیس‌های منفی پشتیبانی می‌کند. به جای پیمایش تمام آیتم‌ها، بررسی عضویت اشیاء int را در زمان ثابت انجام می‌دهد.

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

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

همچنین ملاحظه نمائید

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

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

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

دسته	str متدها				متدهای bytes و bytearray
قالب‌بندی	str.format()
	str.format_map()
	اف‌استرینگ‌ها
	قالب‌بندی رشته به‌سبک printf				قالب‌بندی بایت‌ها به‌سبک printf
جست‌وجو و جایگزینی	str.find()	str.rfind()			bytes.find()	bytes.rfind()
	str.index()	str.rindex()			bytes.index()	bytes.rindex()
	str.startswith()				bytes.startswith()
	str.endswith()				bytes.endswith()
	str.count()				bytes.count()
	str.replace()				bytes.replace()
تقسیم و الحاق	str.split()		str.rsplit()		bytes.split()		bytes.rsplit()
	str.splitlines()				bytes.splitlines()
	str.partition()				bytes.partition()
	str.rpartition()				bytes.rpartition()
	str.join()				bytes.join()
دسته‌بندی رشته	str.isalpha()				bytes.isalpha()
	str.isdecimal()
	str.isdigit()				bytes.isdigit()
	str.isnumeric()
	str.isalnum()				bytes.isalnum()
	str.isidentifier()
	str.islower()				bytes.islower()
	str.isupper()				bytes.isupper()
	str.istitle()				bytes.istitle()
	str.isspace()				bytes.isspace()
	str.isprintable()
تغییر حالت حروف	str.lower()				bytes.lower()
	str.upper()				bytes.upper()
	str.casefold()
	str.capitalize()				bytes.capitalize()
	str.title()				bytes.title()
	str.swapcase()				bytes.swapcase()
پرکردن و بریدن	str.ljust()		str.rjust()		bytes.ljust()		bytes.rjust()
	str.center()				bytes.center()
	str.expandtabs()				bytes.expandtabs()
	str.strip()				bytes.strip()
	str.lstrip()			str.rstrip()	bytes.lstrip()			bytes.rstrip()
	str.removeprefix()				bytes.removeprefix()
	str.removesuffix()				bytes.removesuffix()
ترجمه و کدگذاری	str.translate()				bytes.translate()
	str.maketrans()				bytes.maketrans()
	str.encode()
					bytes.decode()

نوع دنباله‌ی متنی --- str

داده‌های متنی در پایتون با اشیاء str یا رشته‌ها <strings> مدیریت می‌شوند. رشته‌ها دنباله‌هایی تغییرناپذیر از نقاط کد یونیکد هستند. رشته‌های لفظیی به روش‌های گوناگونی نوشته می‌شوند:

• علامت نقل‌قول تکی: 'allows embedded "double" quotes'

• علامت نقل‌قول دوتایی: "allows embedded 'single' quotes"

• سه‌گانه نقل‌قول‌شده: '''Three single quotes'''، """Three double quotes"""

رشته‌های محصور در سه علامت نقل‌قول می‌توانند چندین خط را در بر بگیرند؛ تمام فاصله‌های خالی مرتبط در رشته‌ی لفظی گنجانده خواهند شد.

مقادیر لفظی رشته‌ای (string literals) که بخشی از یک عبارت واحد هستند و تنها فاصله‌های خالی میان آن‌ها قرار دارد، به‌طور ضمنی به یک لفظی رشته‌ای واحد تبدیل می‌شوند. یعنی ("spam " "eggs") == "spam eggs".

برای اطلاعات بیشتر درباره‌ی شکل‌های گوناگون رشته‌های لفظی، از جمله دنباله‌های خنثی‌سازی پشتیبانی‌شده و پیشوند r («خام») که بیشترِ پردازش دنباله‌های خنثی‌سازی را غیرفعال می‌کند، به مقادیر لفظی رشته و بایت مراجعه کنید.

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

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

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

تغییر یافته در نسخه‌ی 3.3: برای سازگاری رو به عقب با سری Python 2، پیشوند 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 مانند باشد (مثلاً bytes یا bytearray). در این حالت، اگر object یک شیء از نوع bytes (یا bytearray) باشد، آنگاه str(bytes, encoding, errors) معادل bytes.decode(encoding, errors) است. در غیر این صورت، شیء bytes زیرین شیء بافر، پیش از فراخوانی bytes.decode() به دست می‌آید. برای اطلاعات مربوط به اشیاء بافر، انواع دنباله‌ای دودویی --- bytes، bytearray، memoryview و پروتکل بافر را ببینید.

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

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

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

متدهای رشته

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

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

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

str.capitalize()

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

تغییر یافته در نسخه‌ی 3.8: اکنون نویسه‌ی نخست به‌جای حالت بزرگ (uppercase)، در حالت نگارش عنوان‌نویسی (titlecase) قرار می‌گیرد. این بدان معناست که نویسه‌هایی مانند دیگراف‌ها (digraphs) تنها حرف نخست آن‌ها بزرگ‌نویسی می‌شود، نه تمام نویسه.

str.casefold()

یک نسخه‌ی کیس‌فولدشده (casefolded) از رشته را برمی‌گرداند. می‌توان از رشته‌های کیس‌فولدشده برای تطبیق بدون در نظر گرفتن بزرگی و کوچکی حروف (caseless matching) استفاده کرد.

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

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

The casefolding algorithm is described in section 3.13.3 'Default Case Folding' of the Unicode Standard.

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

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 از نظر اعتبار بررسی نمی‌شود، مگر آنکه خطای کدگذاری واقعاً رخ دهد، حالت توسعه پایتون فعال شده باشد یا از ساخت اشکال‌زدایی استفاده شود. برای مثال:

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

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

تغییر یافته در نسخه‌ی 3.9: مقدار آرگومان 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)

رونوشتی از رشته را برمی‌گرداند که در آن همه نویسه‌های تب با یک یا چند فاصله جایگزین شده‌اند؛ بسته به ستون جاری و اندازه تب داده‌شده. موقعیت‌های تب هر tabsize نویسه یک بار رخ می‌دهند (پیش‌فرض ۸ است که موقعیت‌های تب را در ستون‌های ۰، ۸، ۱۶ و به همین ترتیب ایجاد می‌کند). برای گسترش رشته، ستون جاری صفر قرار داده می‌شود و رشته نویسه به نویسه بررسی می‌شود. اگر نویسه یک تب (\t) باشد، یک یا چند نویسه فاصله در نتیجه درج می‌شوند تا زمانی که ستون جاری با موقعیت تب بعدی برابر شود. (خود نویسه تب کپی نمی‌شود.) اگر نویسه یک خط جدید (\n) یا بازگشت (\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 متفاوت باشد. این تغییر موقت بر نخ‌های دیگر تأثیر می‌گذارد.

تغییر یافته در نسخه‌ی 3.7: هنگام قالب‌بندی یک عدد با نوع n، تابع در برخی موارد localeی LC_CTYPE را به‌طور موقت به localeی LC_NUMERIC تنظیم می‌کند.

str.format_map(mapping, /)

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

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

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

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

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

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

str.isalpha()

Return True if all characters in the string are alphabetic and there is at least one character, False otherwise. Alphabetic characters are those characters defined in the Unicode character database as "Letter", i.e., those with general category property being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is different from the Alphabetic property defined in section 4.10 'Letters, Alphabetic, and Ideographic' of the Unicode Standard. For example:

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

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

str.isdecimal()

اگر همه‌ی نویسه‌های رشته نویسه‌های دهدهی باشند و دست‌کم یک نویسه وجود داشته باشد، 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()

اگر همه‌ی نویسه‌های رشته رقم باشند و دست‌کم یک نویسه وجود داشته باشد، True برمی‌گرداند؛ در غیر این صورت False. ارقام شامل نویسه‌های دهدهی و ارقامی هستند که نیازمند رسیدگی ویژه‌اند، مانند ارقام بالانویس سازگاری. این موضوع ارقامی را نیز پوشش می‌دهد که نمی‌توان از آن‌ها برای تشکیل اعداد در مبنای ۱۰ استفاده کرد، مانند اعداد خروشتی. به‌طور رسمی، رقم نویسه‌ای است که دارای مقدار ویژگی 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()

اگر همه‌ی نویسه‌های دارای حالت [4] درون رشته کوچک باشند و دست‌کم یک نویسه‌ی دارای حالت وجود داشته باشد، True بازگردانده می‌شود؛ در غیر این صورت False.

str.isnumeric()

اگر همه‌ی نویسه‌های رشته نویسه‌های عددی باشند و حداقل یک نویسه وجود داشته باشد، 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()

اگر همه‌ی نویسه‌های رشته قابل چاپ باشند، True را برمی‌گرداند؛ اگر حداقل یک نویسه‌ی غیرقابل چاپ داشته باشد، False را برمی‌گرداند.

در اینجا «قابل چاپ» به این معناست که نویسه برای آنکه repr() در خروجی خود از آن استفاده کند مناسب است؛ «غیرقابل چاپ» یعنی repr() روی انواع توکار، نویسه را با مبنای شانزده خنثی می‌کند (hex-escape). این موضوع تأثیری بر نحوه مدیریت رشته‌هایی که به sys.stdout یا sys.stderr نوشته می‌شوند ندارد.

نویسه‌های چاپ‌پذیر آن‌هایی هستند که در پایگاه داده نویسه یونیکد (به unicodedata مراجعه کنید) دارای دسته عمومی در گروه حرف، نشانه، عدد، علائم نگارشی یا نماد (L, M, N, P, or S) هستند؛ به علاوه فاصله ASCII 0x20. نویسه‌های غیرچاپ‌پذیر آن‌هایی هستند که در گروه جداکننده یا سایر (Z or C) قرار دارند، به جز فاصله ASCII.

برای مثال:

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

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

str.isspace()

اگر رشته فقط شامل نویسه‌های فضای خالی باشد و حداقل یک نویسه داشته باشد، True و در غیر این صورت False را برمی‌گرداند.

برای مثال:

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

یک نویسه در صورتی فاصله سفید است که در پایگاه داده نویسه‌های یونیکد (به unicodedata مراجعه کنید)، یا دسته عمومی آن Zs («جداکننده، فاصله») باشد، یا کلاس دوجهته آن یکی از WS، B یا S باشد.

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

str.istitle()

اگر رشته، رشته‌ای با حالت نگارش عنوان‌نویسی (titlecased) باشد و دست‌کم یک نویسه داشته باشد، True بازگردانده می‌شود؛ برای مثال، نویسه‌های بزرگ تنها می‌توانند پس از نویسه‌های بدون حالت (uncased) بیایند و نویسه‌های کوچک تنها پس از نویسه‌های دارای حالت (cased). در غیر این صورت، False بازگردانده می‌شود.

برای مثال:

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

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

str.isupper()

اگر همه‌ی نویسه‌های دارای حالت (cased) [4] درون رشته به شکل حروف بزرگ باشند و دست‌کم یک نویسه‌ی دارای حالت وجود داشته باشد، 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()

یک نسخه از رشته را برمی‌گرداند که تمام نویسه‌های دارای حالت (cased) [4] آن به حروف کوچک تبدیل شده‌اند. برای مثال:

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

The lowercasing algorithm used is described in section 3.13.2 'Default Case Conversion' of the Unicode Standard.

str.lstrip(chars=None, /)

Return a copy of the string with leading characters removed. The chars argument is a string specifying the set of characters to be removed. If omitted or None, the chars argument defaults to removing whitespace, that is characters for which str.isspace() is true. The chars argument is not a prefix; rather, all combinations of its values are stripped:

>>> '   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='', /)

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

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

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

تغییر یافته در نسخه‌ی 3.15: dict can now be a 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'

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

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

str.removesuffix(suffix, /)

اگر رشته با رشته‌ی پسوند پایان یابد و آن پسوند خالی نباشد، string[:-len(suffix)] را بازگردانید. در غیر این صورت، نسخه‌ای از رشته اصلی را بازگردانید:

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

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

همچنین ببینید 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'

تغییر یافته در نسخه‌ی 3.13: 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)

Return a list of the words in the string, using sep as the delimiter string. If maxsplit is given, at most maxsplit splits are done, the rightmost ones. If sep is not specified or None, any whitespace string is a separator. Except for splitting from the right, rsplit() behaves like split() which is described in detail below.

str.rstrip(chars=None, /)

Return a copy of the string with trailing characters removed. The chars argument is a string specifying the set of characters to be removed. If omitted or None, the chars argument defaults to removing whitespace, that is characters for which str.isspace() is true. The chars argument is not a suffix; rather, all combinations of its values are stripped. For example:

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

If sep is not specified or is None, a different splitting algorithm is applied: runs of consecutive whitespace are regarded as a single separator, and the result will contain no empty strings at the start or end if the string has leading or trailing whitespace. Consequently, splitting an empty string or a string consisting of just whitespace with a None separator returns [].

برای مثال:

>>> '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 داده شده و true باشد.

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

بازنمایی	توضیح
\n	تغذیه‌ی سطر (Line Feed)
\r	بازگشت به ابتدای سطر
\r\n	بازگشت به ابتدای سطر + تغذیه‌ی سطر
\v یا \x0b	جدول‌بندی خطی (Line Tabulation)
\f یا \x0c	تغذیه‌ی صفحه
\x1c	جداکننده پرونده
\x1d	جداکننده گروه
\x1e	جداکننده‌ی رکورد
\x85	خط بعدی (کد کنترلی C1)
\u2028	جداکننده‌ی خط
\u2029	جداکننده‌ی پاراگراف

تغییر یافته در نسخه‌ی 3.2: \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, /)

Return a copy of the string with the leading and trailing characters removed. The chars argument is a string specifying the set of characters to be removed. If omitted or None, the chars argument defaults to removing whitespace, that is characters for which str.isspace() is true. The chars argument is not a prefix or suffix; rather, all combinations of its values are stripped.

برای مثال:

>>> '   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()

نسخه‌ای عنوان‌نویسی‌شده (titlecased) از رشته را برمی‌گرداند که در آن واژه‌ها با یک نویسه بزرگ آغاز می‌شوند و نویسه‌های باقی‌مانده کوچک هستند.

برای مثال:

>>> '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__() را پیاده‌سازی می‌کند، معمولاً یک نگاشت یا دنباله. هنگامی که شیء جدول با یک عدد ترتیبی یونیکد (یک عدد صحیح) اندیس‌دهی شود، می‌تواند هر یک از کارهای زیر را انجام دهد: برگرداندن یک عدد ترتیبی یونیکد یا یک رشته، برای نگاشت نویسه به یک یا چند نویسه دیگر؛ برگرداندن None، برای حذف نویسه از رشته برگشتی؛ یا پرتاب استثنای LookupError، برای نگاشت نویسه به خودش.

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

The following example uses a mapping to replace 'a' with 'X', 'b' with 'Y', and delete 'c':

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

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

str.upper()

یک کپی از رشته را برمی‌گرداند که در آن تمام نویسه‌های دارای حالت [4] به حروف بزرگ تبدیل شده‌اند. توجه داشته باشید که s.upper().isupper() ممکن است False باشد اگر s حاوی نویسه‌های بدون حالت باشد یا اگر دسته یونیکد نویسه‌های حاصل "Lu" (حرف، بزرگ) نباشد، بلکه برای مثال "Lt" (حرف، حالت عنوان) باشد.

The uppercasing algorithm used is described in section 3.13.2 'Default Case Conversion' of the Unicode Standard.

str.zfill(width, /)

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

برای مثال:

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

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

مقادیر لفظی رشته‌ای قالب‌بندی‌شده (اف‌استرینگ)

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

تغییر یافته در نسخه‌ی 3.7: می‌توان از await و async for در عبارت‌های درون اف‌استرینگ‌ها استفاده کرد.

تغییر یافته در نسخه‌ی 3.8: افزودن مشخص‌کننده اشکال‌زدایی (=)

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

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

• یک مشخص‌کننده اشکال‌زدایی — یک علامت مساوی (=)؛

• یک مشخص‌کننده تبدیل -- !s، !r یا !a؛ و/یا

• یک مشخص‌کننده قالب با پیشوند دونقطه (:).

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

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

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

اگر یک مشخص‌کننده اشکال‌زدایی (debug specifier) — یعنی یک علامت مساوی (=) — پس از عبارت فیلد جایگزینی ظاهر شود، اف‌استرینگ حاصل شامل متن منبع عبارت، علامت مساوی و مقدار عبارت خواهد بود. این موضوع اغلب برای اشکال‌زدایی مفید است:

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

A t-string (formally a template string literal) is a string literal that is prefixed with t or T.

These strings follow the same syntax and evaluation rules as formatted string literals, with the following differences:

• به جای ارزیابی شدن به یک شیء str، مقادیر لفظی رشته‌ای قالب به یک شیء string.templatelib.Template ارزیابی می‌شوند.

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

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

• When the equals sign '=' is provided in an interpolation expression, the text of the expression is appended to the literal string that precedes the relevant interpolation. This includes the equals sign and any surrounding whitespace. The Interpolation instance for the expression will be created as normal, except that conversion will be set to 'r' (repr()) by default. If an explicit conversion or format specifier is provided, this will override the default behaviour.

قالب‌بندی رشته به‌سبک printf

توجه

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

استفاده از مقادیر لفظی رشته‌ای قالب‌بندی‌شده، رابط 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 می‌تواند یک شیء واحد باشد که تاپل نیست. [5] در غیر این صورت، values باید یک تاپل با دقیقاً همان تعداد آیتمی باشد که رشته قالب مشخص می‌کند، یا یک شیء نگاشت واحد (برای مثال، یک دیکشنری).

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

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.

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

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

پرچم	معنی
'#'	تبدیل مقدار از «قالب جایگزین» استفاده خواهد کرد (که در زیر تعریف شده است).
'0'	برای مقادیر عددی، تبدیل با صفر پر می‌شود.
'-'	مقدار تبدیل‌شده چپ‌چین می‌شود (اگر هر دو داده شوند، تبدیل '0' را نادیده می‌گیرد).
' '	(یک فاصله) باید پیش از یک عدد مثبت (یا رشته‌ی خالی) که از یک تبدیل علامت‌دار حاصل می‌شود، یک فاصله گذاشته شود.
'+'	یک نویسه‌ی علامت ('+' یا '-') پیش از تبدیل قرار می‌گیرد (پرچم «space» را نادیده می‌گیرد).

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

انواع تبدیل عبارتند از:

تبدیل	معنی	یادداشت‌ها
'd'	عدد صحیح ده‌دهی علامت‌دار.
'i'	عدد صحیح ده‌دهی علامت‌دار.
'o'	مقدار مبنای هشت علامت‌دار.	(1)
'u'	نوع منسوخ — این نوع با 'd' یکسان است.	(6)
'x'	مبنای شانزده علامت‌دار (حروف کوچک).	(2)
'X'	مبنای شانزده علامت‌دار (حروف بزرگ).	(2)
'e'	قالب نمایی ممیز شناور (حروف کوچک).	(3)
'E'	قالب نمایی عدد ممیز شناور (حروف بزرگ).	(3)
'f'	قالب دهدهی ممیز شناور.	(3)
'F'	قالب دهدهی ممیز شناور.	(3)
'g'	قالب ممیز شناور. اگر توان کمتر از منفی ۴ باشد یا از دقت کمتر نباشد، از قالب نمایی با حروف کوچک استفاده می‌شود؛ در غیر این صورت قالب اعشاری استفاده می‌شود.	(4)
'G'	قالب ممیز شناور. اگر توان کمتر از -۴ باشد یا از دقت کمتر نباشد، از قالب نمایی با حروف بزرگ استفاده می‌شود؛ در غیر این صورت قالب دهدهی به کار می‌رود.	(4)
'c'	نویسه‌ی منفرد (عدد صحیح یا رشته‌ی تک‌نویسه‌ای را می‌پذیرد).
'r'	رشته (هر شیء پایتون را با استفاده از repr() تبدیل می‌کند).	(5)
's'	رشته (هر شیء پایتون را با استفاده از str() تبدیل می‌کند).	(5)
'a'	رشته (هر شیء پایتون را با استفاده از ascii() تبدیل می‌کند).	(5)
'%'	هیچ آرگومانی تبدیل نمی‌شود و یک نویسه '%' در نتیجه ایجاد می‌شود.

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

یادداشت‌ها:

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

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

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

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

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

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

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

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

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

تغییر یافته در نسخه‌ی 3.1: تبدیل‌های %f برای اعدادی که قدر مطلق آن‌ها بیش از 1e50 است، دیگر با تبدیل‌های %g جایگزین نمی‌شوند.

انواع دنباله‌ای دودویی --- bytes، bytearray، memoryview

انواع توکار اصلی برای دستکاری داده‌های دودویی، bytes و bytearray هستند. memoryview از این انواع پشتیبانی می‌کند و از buffer protocol برای دسترسی به حافظه‌ی سایر اشیای دودویی بدون نیاز به ایجاد کپی استفاده می‌کند.

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

اشیای بایت

اشیای 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"""

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

همانند مقادیر لفظی رشته، مقادیر لفظی بایت نیز می‌توانند از پیشوند r برای غیرفعال کردن پردازش دنباله‌های خنثی‌سازی استفاده کنند. برای اطلاعات بیشتر درباره‌ی صورت‌های مختلف لفظی بایت، از جمله دنباله‌های خنثی‌سازی پشتیبانی‌شده، مقادیر لفظی رشته و بایت را ببینید.

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

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

• یک شیء بایت با طول مشخص که با صفر پر شده است: bytes(10)

• از یک پیمایش‌پذیر از اعداد صحیح: bytes(range(20))

• کپی داده‌های دودویی موجود از طریق پروتکل بافر : bytes(obj)

همچنین bytes توکار را ببینید.

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

classmethod fromhex(string, /)

این متد کلاس bytes، با کدگشایی شیء رشته‌ی داده‌شده، یک شیء bytes برمی‌گرداند. این رشته باید به ازای هر بایت دو رقم مبنای شانزده داشته باشد؛ نویسه‌های فضای خالی ASCII نادیده گرفته می‌شوند.

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

تغییر یافته در نسخه‌ی 3.7: bytes.fromhex() اکنون تمام نویسه‌های فضای سفید ASCII در رشته را نادیده می‌گیرد، نه فقط فاصله‌ها.

تغییر یافته در نسخه‌ی 3.14: bytes.fromhex() اکنون bytes ASCII و اشیاء شبه‌بایت را به‌عنوان ورودی می‌پذیرد.

یک تابع تبدیل معکوس وجود دارد که شیء 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'

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

تغییر یافته در نسخه‌ی 3.8: bytes.hex() اکنون از پارامترهای اختیاری sep و bytes_per_sep برای درج جداکننده‌ها بین بایت‌ها در خروجی مبنای شانزده پشتیبانی می‌کند.

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

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

اشیای Bytearray

اشیای 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, /)

This bytearray class method returns a bytearray object, decoding the given string object. The string must contain two hexadecimal digits per byte, with ASCII whitespace being ignored.

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

تغییر یافته در نسخه‌ی 3.7: bytearray.fromhex() اکنون تمام فضای سفید ASCII در رشته را نادیده می‌گیرد، نه فقط فاصله‌ها را.

تغییر یافته در نسخه‌ی 3.14: bytearray.fromhex() اکنون bytes ASCII و اشیاء شبه‌بایت (bytes-like objects) را به‌عنوان ورودی می‌پذیرد.

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

hex(*, bytes_per_sep=1)

hex(sep, bytes_per_sep=1)

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

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

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

تغییر یافته در نسخه‌ی 3.8: مشابه 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)

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

take_bytes(n=None, /)

Remove the first n bytes from the bytearray and return them as an immutable bytes. By default (if n is None), return all bytes and clear the bytearray.

If n is negative, index from the end and take the first len() plus n bytes. If n is out of bounds, raise IndexError.

Taking less than the full length will leave remaining bytes in the bytearray, which requires a copy. If the remaining bytes should be discarded, use resize() or del to truncate then take_bytes() without a size.

جزئیات پیاده‌سازی در CPython: Taking all bytes is a zero-copy operation.

اضافه شده در نسخه‌ی 3.15: See the What's New entry for common code patterns which can be optimized with 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 هر دو از عملیات دنباله‌ای common پشتیبانی می‌کنند. آن‌ها نه‌تنها با عملوندهایی از همان نوع، بلکه با هر 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 برای داده‌های دودویی دلخواه قابل استفاده‌اند.

bytes.count(sub[, start[, end]])

bytearray.count(sub[, start[, end]])

تعداد رخدادهای غیرهم‌پوشان زیردنباله‌ی sub در بازه‌ی [start، end] را برمی‌گرداند. آرگومان‌های اختیاری start و end مانند نمادگذاری اسلایس تفسیر می‌شوند.

زیردنباله‌ی مورد جستجو می‌تواند هر bytes-like object یا عدد صحیحی در بازه‌ی ۰ تا ۲۵۵ باشد.

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

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

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

توجه

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

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

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 این متد به‌صورت درجا عمل نمی‌کند؛ همیشه یک شیء جدید تولید می‌کند، حتی اگر هیچ تغییری اعمال نشده باشد.

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

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-like object را به‌طور مستقیم کدگشایی کرد، بدون این‌که نیازی به ایجاد یک شیء موقت bytes یا bytearray باشد.

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

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

زیردنباله‌ی مورد جستجو می‌تواند هر bytes-like object یا عدد صحیحی در بازه‌ی ۰ تا ۲۵۵ باشد.

توجه

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

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

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

bytes.index(sub[, start[, end]])

bytearray.index(sub[, start[, end]])

مانند find()، اما اگر زیردنباله یافت نشد، ValueError را پرتاب می‌کند.

زیردنباله‌ی مورد جستجو می‌تواند هر bytes-like object یا عدد صحیحی در بازه‌ی ۰ تا ۲۵۵ باشد.

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

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-like objects باشند و طول یکسانی داشته باشند.

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

bytes.partition(sep, /)

bytearray.partition(sep, /)

دنباله را در نخستین رخداد sep جدا می‌کند و یک ۳-تایی حاوی بخش پیش از جداکننده، خود جداکننده یا کپی bytearray آن، و بخش پس از جداکننده برمی‌گرداند. اگر جداکننده پیدا نشود، یک ۳-تایی حاوی یک کپی از دنباله اصلی و سپس دو شیء خالی bytes یا bytearray برمی‌گرداند.

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

bytes.replace(old, new, /, count=-1)

bytearray.replace(old, new, /, count=-1)

Return a copy of the sequence with all occurrences of subsequence old replaced by new. If count is given, only the first count occurrences are replaced. If count is not specified or -1, then all occurrences are replaced.

زیردنباله‌ای که باید جستجو شود و جایگزین آن می‌توانند هر bytes-like object باشند.

توجه

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

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

bytes.rfind(sub[, start[, end]])

bytearray.rfind(sub[, start[, end]])

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

زیردنباله‌ی مورد جستجو می‌تواند هر bytes-like object یا عدد صحیحی در بازه‌ی ۰ تا ۲۵۵ باشد.

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

bytes.rindex(sub[, start[, end]])

bytearray.rindex(sub[, start[, end]])

مانند rfind() است، اما اگر زیردنباله‌ی sub یافت نشد، استثنای ValueError را پرتاب می‌کند.

زیردنباله‌ی مورد جستجو می‌تواند هر bytes-like object یا عدد صحیحی در بازه‌ی ۰ تا ۲۵۵ باشد.

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

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-like object باشند.

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'

تغییر یافته در نسخه‌ی 3.6: اکنون از 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, /)

Return a copy of the sequence with specified leading bytes removed. The bytes argument is a binary sequence specifying the set of byte values to be removed. If omitted or None, the bytes argument defaults to removing ASCII whitespace. The bytes argument is not a prefix; rather, all combinations of its values are stripped:

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

دنباله‌ی دودویی مقادیر بایت برای حذف، می‌تواند هر bytes-like object باشد. برای متدی که یک رشته‌ی پیشوند واحد را به جای همه‌ی نویسه‌های یک مجموعه حذف می‌کند، 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)

Split the binary sequence into subsequences of the same type, using sep as the delimiter string. If maxsplit is given, at most maxsplit splits are done, the rightmost ones. If sep is not specified or None, any subsequence consisting solely of ASCII whitespace is a separator. Except for splitting from the right, rsplit() behaves like split() which is described in detail below.

bytes.rstrip(bytes=None, /)

bytearray.rstrip(bytes=None, /)

Return a copy of the sequence with specified trailing bytes removed. The bytes argument is a binary sequence specifying the set of byte values to be removed. If omitted or None, the bytes argument defaults to removing ASCII whitespace. The bytes argument is not a suffix; rather, all combinations of its values are stripped:

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

دنباله‌ی دودویی از مقادیر بایتی که باید حذف شوند، می‌تواند هر bytes-like object باشد. برای دیدن متدی که یک رشته‌ی پسوند واحد را حذف می‌کند، نه همه‌ی یک مجموعه از نویسه‌ها، 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 می‌تواند هر شیء شبه‌بایت (bytes-like object) باشد.

برای مثال:

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

If sep is not specified or is None, a different splitting algorithm is applied: runs of consecutive ASCII whitespace are regarded as a single separator, and the result will contain no empty strings at the start or end if the sequence has leading or trailing whitespace. Consequently, splitting an empty sequence or a sequence consisting solely of ASCII whitespace without a specified separator returns [].

برای مثال:

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

Return a copy of the sequence with specified leading and trailing bytes removed. The bytes argument is a binary sequence specifying the set of byte values to be removed. If omitted or None, the bytes argument defaults to removing ASCII whitespace. The bytes argument is not a prefix or suffix; rather, all combinations of its values are stripped:

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

دنباله‌ی دودویی از مقادیر بایت برای حذف می‌تواند هر bytes-like object باشد.

توجه

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

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

bytes.capitalize()

bytearray.capitalize()

نسخه‌ای از دنباله را برمی‌گرداند که در آن هر بایت به‌عنوان یک نویسه ASCII تفسیر می‌شود و بایت اول به حرف بزرگ و بقیه به حروف کوچک تبدیل می‌شوند. مقادیر بایت غیر ASCII بدون تغییر باقی می‌مانند.

توجه

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

bytes.expandtabs(tabsize=8)

bytearray.expandtabs(tabsize=8)

یک کپی از دنباله برمی‌گرداند که در آن همه‌ی نویسه‌های Tab ASCII با یک یا چند فاصله‌ی ASCII جایگزین می‌شوند؛ این جایگزینی به ستون جاری و اندازه‌ی Tab داده‌شده بستگی دارد. جایگاه‌های Tab هر tabsize بایت یک‌بار رخ می‌دهند (پیش‌فرض ۸ است و جایگاه‌های Tab در ستون‌های ۰، ۸، ۱۶ و به همین ترتیب قرار می‌گیرند). برای بسط دنباله، ستون جاری روی صفر تنظیم می‌شود و دنباله بایت به بایت بررسی می‌شود. اگر بایت یک نویسه‌ی Tab ASCII (b'\t') باشد، یک یا چند نویسه‌ی فاصله در نتیجه درج می‌شوند تا ستون جاری برابر با جایگاه Tab بعدی شود. (خود نویسه‌ی Tab کپی نمی‌شود.) اگر بایت جاری یک خط جدید ASCII (b'\n') یا بازگشت به ابتدای سطر (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 در بازه‌ی 0-0x7F قرار دارند.

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

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' هستند (فاصله، تب، خط جدید، بازگشت به ابتدای سطر، تب عمودی، تغذیه فرم).

bytes.istitle()

bytearray.istitle()

اگر دنباله ASCII و به حالت عنوانی (titlecase) باشد و خالی نباشد، 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 می‌شکند. این متد از رویکرد سطرهای جدید همگانی (universal newlines) برای تقسیم سطرها استفاده می‌کند. نویسه‌های خط جدید در فهرست حاصل گنجانده نمی‌شوند، مگر اینکه keepends داده شود و true باشد.

برای مثال:

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

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

برای مثال:

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

توجه

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

Bytes objects (bytes/bytearray) have one unique built-in operation: the % operator (modulo). This is also known as the bytes formatting or interpolation operator. Given format % values (where format is a bytes object), % conversion specifications in format are replaced with zero or more elements of values. The effect is similar to using the sprintf() function in the C language.

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

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

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

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

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

پرچم	معنی
'#'	تبدیل مقدار از «قالب جایگزین» استفاده خواهد کرد (که در زیر تعریف شده است).
'0'	برای مقادیر عددی، تبدیل با صفر پر می‌شود.
'-'	مقدار تبدیل‌شده چپ‌چین می‌شود (اگر هر دو داده شوند، تبدیل '0' را نادیده می‌گیرد).
' '	(یک فاصله) باید پیش از یک عدد مثبت (یا رشته‌ی خالی) که از یک تبدیل علامت‌دار حاصل می‌شود، یک فاصله گذاشته شود.
'+'	یک نویسه‌ی علامت ('+' یا '-') پیش از تبدیل قرار می‌گیرد (پرچم «space» را نادیده می‌گیرد).

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

انواع تبدیل عبارتند از:

تبدیل	معنی	یادداشت‌ها
'd'	عدد صحیح ده‌دهی علامت‌دار.
'i'	عدد صحیح ده‌دهی علامت‌دار.
'o'	مقدار مبنای هشت علامت‌دار.	(1)
'u'	نوع منسوخ — این نوع با 'd' یکسان است.	(8)
'x'	مبنای شانزده علامت‌دار (حروف کوچک).	(2)
'X'	مبنای شانزده علامت‌دار (حروف بزرگ).	(2)
'e'	قالب نمایی ممیز شناور (حروف کوچک).	(3)
'E'	قالب نمایی عدد ممیز شناور (حروف بزرگ).	(3)
'f'	قالب دهدهی ممیز شناور.	(3)
'F'	قالب دهدهی ممیز شناور.	(3)
'g'	قالب ممیز شناور. اگر توان کمتر از منفی ۴ باشد یا از دقت کمتر نباشد، از قالب نمایی با حروف کوچک استفاده می‌شود؛ در غیر این صورت قالب اعشاری استفاده می‌شود.	(4)
'G'	قالب ممیز شناور. اگر توان کمتر از -۴ باشد یا از دقت کمتر نباشد، از قالب نمایی با حروف بزرگ استفاده می‌شود؛ در غیر این صورت قالب دهدهی به کار می‌رود.	(4)
'c'	تک‌بایت (عدد صحیح یا اشیای تک‌بایتی را می‌پذیرد).
'b'	بایت‌ها (هر شیءای که از buffer protocol پیروی کند یا دارای __bytes__() باشد).	(5)
's'	's' یک نام مستعار برای 'b' است و باید فقط برای پایگاه‌های کد Python2/3 استفاده شود.	(6)
'a'	بایت‌ها (هر شیء پایتون را با استفاده از repr(obj).encode('ascii', 'backslashreplace') تبدیل می‌کند).	(5)
'r'	'r' نام مستعاری برای 'a' است و باید تنها برای پایگاه‌های کد Python2/3 استفاده شود.	(7)
'%'	هیچ آرگومانی تبدیل نمی‌شود و یک نویسه '%' در نتیجه ایجاد می‌شود.

یادداشت‌ها:

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

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

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

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

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

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

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

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

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

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

توجه

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

همچنین ملاحظه نمائید

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

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

نماهای حافظه

اشیای memoryview به کد پایتون اجازه می‌دهند تا بدون کپی کردن، به داده‌های داخلی شیء‌ای که از buffer protocol پشتیبانی می‌کند، دسترسی داشته باشد.

class memoryview(object)

یک memoryview ایجاد کنید که به object ارجاع دارد. object باید از پروتکل بافر پشتیبانی کند. اشیاء توکاری که از پروتکل بافر پشتیبانی می‌کنند، شامل bytes و bytearray هستند.

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

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

len(view) is equal to the length of tolist(), which is the nested list representation of the view. If view.ndim == 1, this is equal to the number of elements in the view.

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

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

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

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

اگر format یکی از مشخص‌کننده‌های قالب بومی ماژول 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

تغییر یافته در نسخه‌ی 3.3: اکنون می‌توان memoryviewهای یک‌بعدی را اسلایس داد. memoryviewهای یک‌بعدی با قالب‌های 'B'، 'b' یا 'c' اکنون hashable هستند.

تغییر یافته در نسخه‌ی 3.4: memoryview اکنون به‌طور خودکار در collections.abc.Sequence ثبت شده است

تغییر یافته در نسخه‌ی 3.5: memoryviews can now be indexed with a tuple of integers.

تغییر یافته در نسخه‌ی 3.14: memoryview اکنون یک نوع عام است.

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

__eq__(exporter)

یک memoryview و یک اکسپورتکننده (exporter) PEP 3118 برابر هستند اگر شکل‌های آن‌ها معادل باشد و اگر تمام مقادیر متناظر، هنگامی که کدهای قالب مربوط به هر یک از عملوندها با استفاده از سینتکس 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 نیست.

تغییر یافته در نسخه‌ی 3.3: نسخه‌های پیشین، حافظه خام را بدون توجه به قالب آیتم و ساختار منطقی آرایه مقایسه می‌کردند.

tobytes(order='C')

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

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

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

اضافه شده در نسخه‌ی 3.8: 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'

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

تغییر یافته در نسخه‌ی 3.8: مشابه 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]

تغییر یافته در نسخه‌ی 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]

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

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

می‌توان از پروتکل مدیریت زمینه برای نتیجه‌ای مشابه، با استفاده از دستور 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

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

cast(format, /)

cast(format, shape, /, *, order='C')

Cast a memoryview to a new format or shape. shape defaults to [byte_length//new_itemsize], which means that the result view will be one-dimensional. The return value is a new memoryview, but the buffer itself is not copied. Supported casts are 1D -> C-contiguous, C-contiguous -> 1D, and F-contiguous -> 1D.

With a multidimensional shape, order selects the memory layout of the result: 'C' for C-contiguous (row-major, the default) or 'F' for Fortran-contiguous (column-major). The buffer is still not copied, so order='F' gives a zero-copy view over a buffer holding column-major data.

قالب مقصد به یک قالب بومی تک‌عنصری در سینتکس 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

تبدیل بایت‌های یک‌بعدی/بدون علامت به یک‌بعدی/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]]

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

تغییر یافته در نسخه‌ی 3.5: قالب منبع دیگر هنگام تبدیل (casting) به یک نمای بایتی (byte view) محدود نیست.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Casting a multi-dimensional F-contiguous view to a one-dimensional view is now supported.

count(value, /)

تعداد رخدادهای value را می‌شمارد.

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

index(value, start=0, stop=sys.maxsize, /)

اندیس نخستین رخداد value را برمی‌گرداند (در اندیس start یا پس از آن و پیش از اندیس stop).

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

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

همچنین چند ویژگی فقط‌خواندنی در دسترس است:

obj

شیء زیرین memoryview:

>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True

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

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

Interpret a flat buffer as a Fortran-contiguous (column-major) array:

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

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

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the order parameter.

readonly

یک بولی که نشان می‌دهد حافظه فقط‌خواندنی است.

format

رشته‌ای حاوی قالب (به سبک ماژول struct) برای هر المان در نما. می‌توان یک memoryview را از اکسپورتکننده‌هایی با رشته‌های قالب دلخواه ایجاد کرد، اما برخی متدها (مانند tolist()) به قالب‌های بومی برای یک المان محدود هستند.

تغییر یافته در نسخه‌ی 3.3: قالب '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-بعدی مشخص می‌کند.

تغییر یافته در نسخه‌ی 3.3: یک تاپل خالی به‌جای None هنگامی که ndim = 0 است.

strides

یک تاپل از اعداد صحیح به طول ndim که اندازه‌ی لازم بر حسب بایت برای دسترسی به هر عنصر در هر بُعد از آرایه را مشخص می‌کند.

تغییر یافته در نسخه‌ی 3.3: یک تاپل خالی به‌جای None هنگامی که ndim = 0 است.

suboffsets

به‌صورت داخلی برای آرایه‌های به‌سبک PIL استفاده می‌شود. این مقدار فقط جنبه اطلاع‌رسانی دارد.

c_contiguous

یک بولی که نشان می‌دهد آیا حافظه C-contiguous است یا خیر.

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

f_contiguous

یک بولی که نشان می‌دهد آیا حافظه به‌صورت Fortran contiguous است یا خیر.

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

contiguous

یک بولی که نشان می‌دهد حافظه contiguous است یا خیر.

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

برای اطلاعات درباره ایمنی نخی اشیای memoryview در free-threaded build، به ایمنی نخ برای اشیای memoryview مراجعه کنید.

انواع مجموعه‌ای --- set، frozenset

A set object is an unordered collection of distinct hashable objects. Common uses include membership testing, removing duplicates from a sequence, and computing mathematical operations such as intersection, union, difference, and symmetric difference. (For other containers see the built-in dict, list, and tuple classes, and the collections module.) See Time complexity of operations on built-in types for the costs of the various set operations.

مانند سایر مجموعه‌ها، مجموعه‌ها از x in set، len(set) و for x in set پشتیبانی می‌کنند. از آن‌جا که مجموعه‌ها بدون ترتیب هستند، موقعیت عنصر یا ترتیب درج را ثبت نمی‌کنند. بنابراین، مجموعه‌ها از اندیس‌دهی، اسلایس یا سایر رفتارهای مشابه دنباله پشتیبانی نمی‌کنند.

در حال حاضر دو نوع مجموعه‌ی توکار وجود دارد: set و frozenset. نوع set تغییرپذیر است --- محتوا را می‌توان با متدهایی مانند add() و remove() تغییر داد. از آن‌جا که این نوع تغییرپذیر است، مقدار هش ندارد و نمی‌توان از آن به‌عنوان کلید دیکشنری یا عنصری از مجموعه‌ای دیگر استفاده کرد. نوع frozenset تغییرناپذیر و hashable است --- محتوای آن پس از ایجاد تغییر نمی‌کند؛ بنابراین می‌توان از آن به‌عنوان کلید دیکشنری یا عنصری از مجموعه‌ای دیگر استفاده کرد.

مجموعه‌های غیرخالی (نه frozensetها) را می‌توان با قرار دادن فهرستی از عناصر که با کاما از هم جدا شده‌اند درون آکولاد ایجاد کرد، برای مثال: {'jack', 'sjoerd'}، علاوه بر سازنده‌ی set.

سازنده‌های هر دو کلاس به یک شکل کار می‌کنند:

class set(iterable=(), /)

class frozenset(iterable=(), /)

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

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

• از فهرستی از عناصر جداشده با کاما درون آکولاد استفاده کنید: {'jack', 'sjoerd'}

• از یک درک مجموعه‌ای استفاده کنید: {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 برمی‌گرداند. مجموعه‌ها مجزا هستند اگر و تنها اگر اشتراک آن‌ها مجموعه تهی باشد.

frozenset.issubset(other, /)

set.issubset(other, /)

set <= other

آزمایش می‌کند که آیا همه‌ی عناصر مجموعه در other هستند.

set < other

آزمایش می‌کند که آیا مجموعه زیرمجموعه‌ی سره‌ی other است، یعنی set <= other and set != other.

frozenset.issuperset(other, /)

set.issuperset(other, /)

set >= other

آزمایش می‌کند که آیا همه عناصر other در مجموعه وجود دارند یا خیر.

set > other

بررسی می‌کند که آیا مجموعه ابرمجموعه سره‌ای از other است یا خیر، یعنی set >= other and set != other.

frozenset.union(*others)

set.union(*others)

set | other | ...

یک مجموعه جدید شامل عناصری از مجموعه و همه‌ی سایر موارد برمی‌گرداند.

frozenset.intersection(*others)

set.intersection(*others)

set & other & ...

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

frozenset.difference(*others)

set.difference(*others)

set - other - ...

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

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')]) نیز همین مقدار را برمی‌گرداند.

مقایسه‌های زیرمجموعه و برابری به یک تابع مرتب‌سازی کامل تعمیم نمی‌یابند. برای مثال، هر دو مجموعه‌ی ناتهی و جدا از هم، برابر نیستند و زیرمجموعه‌ی یکدیگر نیستند، بنابراین همه‌ی موارد زیر False برمی‌گردانند: a<b، a==b یا a>b.

از آن‌جا که مجموعه‌ها فقط ترتیب جزئی (روابط زیرمجموعه) را تعریف می‌کنند، خروجی متد list.sort() برای فهرست‌هایی از مجموعه‌ها تعریف‌نشده است.

عناصر مجموعه، مانند کلیدهای دیکشنری، باید hashable باشند.

عملیات دودویی که نمونه‌های set را با frozenset ترکیب می‌کنند، نوع اولین عملوند را برمی‌گردانند. برای مثال: frozenset('ab') | set('bc') یک نمونه از frozenset برمی‌گرداند.

جدول زیر عملیات در دسترس برای set را که بر نمونه‌های تغییرناپذیر frozenset اعمال نمی‌شوند، فهرست می‌کند:

set.update(*others)

set |= other | ...

مجموعه را به‌روزرسانی می‌کند و عناصر همه‌ی موارد دیگر را اضافه می‌کند.

set.intersection_update(*others)

set &= other & ...

مجموعه را به‌روزرسانی کنید و فقط عناصری را نگه دارید که در آن و در همه‌ی مجموعه‌های دیگر یافت می‌شوند.

set.difference_update(*others)

set -= other | ...

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

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، ایمنی نخی برای اشیای مجموعه را ببینید.

Mapping types --- dict, frozendict

A mapping object maps hashable values to arbitrary objects. There are currently two standard mapping types, the dictionary and frozendict. (For other containers see the built-in list, set, and tuple classes, and the collections module.) See Time complexity of operations on built-in types for the costs of the various dictionary operations.

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

• از یک درک دیکشنری استفاده کنید: {}، {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}

تغییر یافته در نسخه‌ی 3.7: تضمین می‌شود که ترتیب دیکشنری، ترتیب درج باشد. این رفتار از نسخه 3.6، جزئیاتی از پیاده‌سازی CPython بود.

دیکشنری‌ها نسبت به دو نوع generic هستند، که (به‌ترتیب) نشان‌دهنده‌ی انواع کلیدها و مقادیر دیکشنری‌اند.

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

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] را برابر مقدار قرار دهید.

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

get(key, default=None, /)

اگر key در دیکشنری وجود داشته باشد، مقدار key را برمی‌گرداند؛ در غیر این صورت default را برمی‌گرداند. اگر default داده نشده باشد، مقدار پیش‌فرض آن None است، بنابراین این متد هرگز KeyError پرتاب نمی‌کند.

items()

یک نمای جدید از آیتم‌های دیکشنری (جفت‌های (key, value)) برمی‌گرداند. به مستندات اشیای نما مراجعه کنید.

keys()

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

pop(key, /)

pop(key, default, /)

اگر key در دیکشنری باشد، آن را حذف می‌کند و مقدار آن را برمی‌گرداند، در غیر این صورت default را برمی‌گرداند. اگر default داده نشده باشد و key در دیکشنری نباشد، یک KeyError پرتاب می‌شود.

popitem()

یک جفت (key, value) را از دیکشنری حذف می‌کند و برمی‌گرداند. جفت‌ها به ترتیب LIFO برگردانده می‌شوند.

popitem() برای پیمایش مخرب یک دیکشنری مفید است، همان‌طور که اغلب در الگوریتم‌های مجموعه استفاده می‌شود. اگر دیکشنری خالی باشد، فراخوانی popitem() موجب پرتاب KeyError می‌شود.

تغییر یافته در نسخه‌ی 3.7: ترتیب LIFO اکنون تضمین می‌شود. در نسخه‌های پیشین، popitem() یک جفت کلید/مقدار دلخواه را برمی‌گرداند.

reversed(d)

یک پیمایش‌گر معکوس روی کلیدهای دیکشنری برمی‌گرداند. این یک میان‌بر برای reversed(d.keys()) است.

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

setdefault(key, default=None, /)

اگر key در دیکشنری وجود داشته باشد، مقدار آن را برمی‌گرداند. در غیر این صورت، key را با مقدار default درج می‌کند و default را برمی‌گرداند. default به‌طور پیش‌فرض None است.

update(**kwargs)

update(mapping, /, **kwargs)

update(iterable, /, **kwargs)

دیکشنری را با جفت‌های کلید/مقدار از نگاشت یا پیمایش‌پذیر و kwargs به‌روزرسانی می‌کند و کلیدهای موجود را بازنویسی می‌کند. None را برمی‌گرداند.

update() یا شیء دیگری با متد keys() را می‌پذیرد (که در این صورت __getitem__() با هر کلید برگردانده‌شده از آن متد فراخوانی می‌شود) یا یک پیمایش‌پذیر از جفت‌های کلید/مقدار (به‌صورت تاپل‌ها یا پیمایش‌پذیرهای دیگر با طول ۲). اگر آرگومان‌های کلیدواژه‌ای مشخص شده باشند، سپس دیکشنری با آن جفت‌های کلید/مقدار به‌روزرسانی می‌شود: d.update(red=1, blue=2).

values()

یک نمای جدید (view) از مقادیر دیکشنری برمی‌گرداند. به مستندات اشیای view مراجعه کنید.

مقایسه‌ی برابری میان یک نمای dict.values() و نمای دیگر، همیشه False را برمی‌گرداند. این موضوع هنگام مقایسه‌ی dict.values() با خودش نیز صدق می‌کند:

>>> d = {'a': 1}
>>> d.values() == d.values()
False

d | other

یک دیکشنری جدید با کلیدها و مقدارهای ادغام‌شده‌ی d و other ایجاد کنید، که هر دو باید دیکشنری باشند. در صورتی که d و other کلیدهای مشترک داشته باشند، مقدارهای other اولویت دارند.

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

d |= other

دیکشنری d را با کلیدها و مقدارهای other به‌روزرسانی کنید؛ other ممکن است یک نگاشت یا یک پیمایش‌پذیر از جفت‌های کلید/مقدار باشد. هنگامی که d و other کلیدهای مشترک دارند، مقدارهای other اولویت دارند.

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

دیکشنری‌ها و نماهای دیکشنری معکوس‌پذیر هستند.

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

تغییر یافته در نسخه‌ی 3.8: دیکشنری‌ها اکنون برگشت‌پذیر هستند.

همچنین ملاحظه نمائید

frozendict and types.MappingProxyType can be used to create a read-only view of a dict.

همچنین ملاحظه نمائید

برای اطلاعات دقیق درباره‌ی تضمین‌های ایمنی نخ برای اشیاء dict، به ایمنی نخی برای اشیاء دیکشنری مراجعه کنید.

اشیای نمای دیکشنری

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

تغییر یافته در نسخه‌ی 3.7: ترتیب دیکشنری تضمین می‌شود که ترتیب درج باشد.

x in dictview

اگر x در کلیدها، مقادیر یا آیتم‌های دیکشنری زیربنایی وجود داشته باشد، True برمی‌گرداند (در مورد اخیر، x باید یک تاپل (key, value) باشد).

reversed(dictview)

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

تغییر یافته در نسخه‌ی 3.8: نماهای دیکشنری اکنون معکوس‌پذیر هستند.

dictview.mapping

یک types.MappingProxyType برمی‌گرداند که دیکشنری اصلی‌ای را که نما (view) به آن ارجاع می‌دهد، می‌پوشاند.

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

نماهای کلیدها مجموعه‌مانند هستند، زیرا ورودی‌های آن‌ها یکتا و hashable هستند. نماهای آیتم‌ها نیز عملیات مجموعه‌مانند دارند، زیرا جفت‌های (کلید، مقدار) یکتا هستند و کلیدها هش‌پذیر هستند. اگر همه مقادیر در یک نمای آیتم‌ها نیز هش‌پذیر باشند، آنگاه نمای آیتم‌ها می‌تواند با سایر مجموعه‌ها تعامل داشته باشد. (نماهای مقادیر به‌عنوان مجموعه‌مانند در نظر گرفته نمی‌شوند، زیرا ورودی‌ها عموماً یکتا نیستند.) برای نماهای مجموعه‌مانند، تمام عملیات تعریف‌شده برای کلاس پایه انتزاعی 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)

Return a new frozen dictionary initialized from an optional positional argument and a possibly empty set of keyword arguments.

A frozendict has a similar API to the dict API, with the following differences:

• dict has more methods than frozendict:

  • __delitem__()

  • __setitem__()

  • clear()

  • pop()

  • popitem()

  • setdefault()

  • update()

• A frozendict can be hashed with hash(frozendict) if all keys and values can be hashed.

• frozendict |= other does not modify the frozendict in-place but creates a new frozen dictionary.

frozendict is not a dict subclass but inherits directly from object.

Like dictionaries, frozendicts are generic over two types, signifying (respectively) the types of the frozendict's keys and values.

classmethod fromkeys(iterable, value=None, /)

Similar to dict.fromkeys(), but call again the type constructor with an initialized frozendict if the type is a frozendict subclass or if the constructor returned a frozendict.

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

انواع مدیر زمینه

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

contextmanager.__enter__()

وارد زمینه ران‌تایم می‌شود و این شیء یا شیء دیگری مرتبط با زمینه ران‌تایم را برمی‌گرداند. مقدار برگردانده‌شده توسط این متد، به شناسه‌ی موجود در بند as دستورات with که از این مدیر زمینه استفاده می‌کنند، اختصاص می‌یابد.

نمونه‌ای از یک مدیر زمینه که خود را برمی‌گرداند، یک file object است. اشیای پرونده خود را از __enter__() برمی‌گردانند تا امکان استفاده از open() به‌عنوان عبارت زمینه در یک دستور with فراهم شود.

یک نمونه از مدیر زمینه که شیء مرتبطی را برمی‌گرداند، مدیری است که توسط decimal.localcontext() برگردانده می‌شود. این مدیرهای زمینه، زمینه‌ی decimal فعال را به یک رونوشت از زمینه‌ی decimal اصلی تنظیم می‌کنند و سپس آن رونوشت را برمی‌گردانند. این امر امکان می‌دهد که تغییراتی در زمینه‌ی decimal جاری در بدنه‌ی دستور with اعمال شود، بدون آنکه کد خارج از دستور with تحت تأثیر قرار گیرد.

contextmanager.__exit__(exc_type, exc_val, exc_tb)

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

بازگرداندن یک مقدار درست از این متد باعث می‌شود دستور with استثنا را مهار کند و اجرا را با دستورِ بلافاصله پس از دستور with ادامه دهد. در غیر این صورت، پس از پایان اجرای این متد، استثنا به انتشار خود ادامه می‌دهد.

اگر این متد هنگام رسیدگی به یک استثنای پیشین از بلوک with، استثنایی پرتاب کند، استثنای جدید پرتاب می‌شود و استثنای اصلی در ویژگی __context__ آن ذخیره می‌شود.

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

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

تولیدگرهای پایتون (تولیدگر) و دکوراتور contextlib.contextmanager راهی مناسب برای پیاده‌سازی این پروتکل‌ها فراهم می‌کنند. اگر یک تابع تولیدگر با دکوراتور contextlib.contextmanager آراسته شود، به‌جای پیمایش‌گری که توسط یک تابع تولیدگر آراسته‌نشده تولید می‌شود، مدیر زمینه‌ای برمی‌گرداند که متدهای ضروری __enter__() و __exit__() را پیاده‌سازی می‌کند.

توجه داشته باشید که هیچ جایگاه مشخصی برای هیچ‌کدام از این متدها در ساختار نوع اشیاء پایتون در Python/C API وجود ندارد. انواع توسعه‌ای که می‌خواهند این متدها را تعریف کنند، باید آن‌ها را به‌عنوان متدهای معمولی قابل دسترسی از پایتون فراهم کنند. در مقایسه با سربار راه‌اندازی زمینه‌ی ران‌تایم، سربار یک جست‌وجوی تکی در دیکشنری کلاس ناچیز است.

انواع حاشیه‌نویسی نوع --- Generic Alias، Union

انواع توکار اصلی برای حاشیه‌نویسی‌های نوع عبارتند از Generic Alias و Union.

نوع نام مستعار عام

اشیاء GenericAlias معمولاً با زیرنویسی یک کلاس ایجاد می‌شوند. آن‌ها اغلب با کلاس‌های ظرفی، مانند list یا dict استفاده می‌شوند. برای مثال، list[int] یک شیء GenericAlias است که با زیرنویسی کلاس list با آرگومان int ایجاد می‌شود. اشیاء GenericAlias عمدتاً برای استفاده با حاشیه‌نویسی‌های نوع در نظر گرفته شده‌اند.

توجه

به‌طور معمول، تنها در صورتی می‌توان عملیات اندیس‌دهی (subscript) را روی یک کلاس انجام داد که آن کلاس متد ویژه‌ی __class_getitem__() را پیاده‌سازی کرده باشد.

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

برای یک کلاس ظرف، آرگومان(های) ارائه‌شده به زیرنویسی کلاس ممکن است نوع یا انواع عناصری را که یک شیء شامل می‌شود نشان دهند. برای مثال، می‌توان از set[bytes] در حاشیه‌نویسی‌های نوع (type annotations) برای نشان دادن یک set که تمام عناصر آن از نوع bytes هستند استفاده کرد.

برای کلاسی که __class_getitem__() را تعریف می‌کند اما یک ظرف نیست، آرگومان‌های ارائه‌شده برای زیرنویسی آن کلاس، اغلب نوع یا انواع بازگشتی یک یا چند متد تعریف‌شده برای یک شیء را مشخص می‌کنند. برای مثال، عبارت‌های باقاعده را می‌توان هم برای نوع داده‌ی str و هم برای نوع داده‌ی bytes استفاده کرد:

• اگر x = re.search('foo', 'foo')، x یک شیء re.Match خواهد بود که مقادیر بازگشتی x.group(0) و x[0] هر دو از نوع str خواهند بود. می‌توانید این نوع شیء را در حاشیه‌نویسی‌های نوع با GenericAlias re.Match[str] نشان دهید.

• اگر y = re.search(b'bar', b'bar') (به b برای bytes توجه کنید)، y نیز نمونه‌ای از re.Match خواهد بود، اما مقادیر بازگشتی y.group(0) و y[0] هر دو از نوع bytes خواهند بود. در حاشیه‌نویسی‌های نوع، این تنوع از اشیای re.Match را با re.Match[bytes] نمایش می‌دهیم.

اشیای GenericAlias نمونه‌هایی از کلاس types.GenericAlias هستند که می‌توان از آن برای ساخت اشیای GenericAlias به‌طور مستقیم نیز استفاده کرد. نسخه‌های تخصصی‌شده‌ی کلاس‌های عام تعریف‌شده توسط کاربر ممکن است نمونه‌هایی از types.GenericAlias نباشند، اما عملکرد مشابهی ارائه می‌دهند.

T[X, Y, ...]

یک GenericAlias ایجاد می‌کند که نشان‌دهنده‌ی یک نوع T پارامتریزه‌شده با انواع X، Y و موارد دیگر، بسته به T مورد استفاده، است. برای مثال، تابعی که انتظار یک list شامل عناصر float را دارد:

def average(values: list[float]) -> float:
    return sum(values) / len(values)

مثالی دیگر برای اشیاء نگاشت، با استفاده از یک dict، که یک نوع عام است و دو پارامتر نوع دارد؛ این پارامترها نوع کلید و نوع مقدار را نشان می‌دهند. در این مثال، تابع یک dict را با کلیدهایی از نوع str و مقادیری از نوع int انتظار دارد:

def send_post_request(url: str, body: dict[str, int]) -> None:
    ...

توابع توکار isinstance() و issubclass() انواع GenericAlias را برای آرگومان دوم خود نمی‌پذیرند:

>>> isinstance([1, 2], list[str])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot be a parameterized generic

ران‌تایم پایتون حاشیه‌نویسی را اعمال نمی‌کند. این موضوع شامل انواع عام و پارامترهای نوع آن‌ها نیز می‌شود. هنگام ایجاد یک شیء ظرف از روی یک GenericAlias، عناصر درون ظرف با نوعشان تطبیق داده نمی‌شوند. برای مثال، کد زیر توصیه نمی‌شود، اما بدون خطا اجرا می‌شود:

>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]

علاوه بر این، انواع عام پارامتردار، پارامترهای نوع را هنگام ایجاد شیء حذف می‌کنند:

>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>

>>> l = t()
>>> type(l)
<class 'list'>

نمونه‌های GenericAlias در ران‌تایم کلاس نیستند، اگرچه مانند کلاس‌ها رفتار می‌کنند (می‌توان آن‌ها را نمونه‌سازی کرد و از آن‌ها زیرکلاس ساخت):

>>> import inspect
>>> inspect.isclass(list[int])
False

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

فراخوانی repr() یا str() روی یک نوع عام، نوع پارامتری‌شده را نشان می‌دهد:

>>> repr(list[int])
'list[int]'

>>> str(list[int])
'list[int]'

متد __getitem__() در ظروف عام، استثنایی پرتاب می‌کند تا از اشتباهاتی مانند dict[str][str] جلوگیری کند:

>>> dict[str][str]
Traceback (most recent call last):
  ...
TypeError: dict[str] is not a generic class

با این حال، چنین عباراتی زمانی معتبر هستند که از متغیرهای نوع استفاده شود. اندیس باید به تعداد آیتم‌های متغیر نوع موجود در __args__ شیء GenericAlias، المان داشته باشد.

>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]

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

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

• tuple

• list

• dict

• set

• frozendict

• frozenset

• type

• asyncio.Future

• asyncio.Task

• collections.deque

• collections.defaultdict

• collections.OrderedDict

• collections.Counter

• collections.ChainMap

• collections.abc.Awaitable

• collections.abc.Coroutine

• collections.abc.AsyncIterable

• collections.abc.AsyncIterator

• collections.abc.AsyncGenerator

• collections.abc.Iterable

• collections.abc.Iterator

• collections.abc.Generator

• collections.abc.Reversible

• collections.abc.Container

• collections.abc.Collection

• collections.abc.Callable

• collections.abc.Set

• collections.abc.MutableSet

• collections.abc.Mapping

• collections.abc.MutableMapping

• collections.abc.Sequence

• collections.abc.MutableSequence

• collections.abc.ByteString

• collections.abc.MappingView

• collections.abc.KeysView

• collections.abc.ItemsView

• collections.abc.ValuesView

• contextlib.AbstractContextManager

• contextlib.AbstractAsyncContextManager

• dataclasses.Field

• functools.cached_property

• functools.partialmethod

• os.PathLike

• queue.LifoQueue

• queue.Queue

• queue.PriorityQueue

• queue.SimpleQueue

• re.Pattern

• re.Match

• shelve.BsdDbShelf

• shelve.DbfilenameShelf

• shelve.Shelf

• types.MappingProxyType

• weakref.WeakKeyDictionary

• weakref.WeakMethod

• weakref.WeakSet

• weakref.WeakValueDictionary

ویژگی‌های خاص اشیاء GenericAlias

تمام عام‌های پارامتریزه‌شده، ویژگی‌های فقط‌خواندنی خاصی را پیاده‌سازی می‌کنند.

genericalias.__origin__

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

>>> list[int].__origin__
<class 'list'>

genericalias.__args__

این ویژگی یک tuple (احتمالاً به طول ۱) از انواع عام است که به __class_getitem__() اصلی کلاس عام ارسال شده است:

>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])

genericalias.__parameters__

این ویژگی یک تاپل محاسبه‌شده به‌صورت تنبل (احتمالاً خالی) از متغیرهای نوع یکتای موجود در __args__ است:

>>> from typing import TypeVar

>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)

توجه

یک شیء GenericAlias با پارامترهای typing.ParamSpec ممکن است پس از جایگزینی، __parameters__ صحیحی نداشته باشد، زیرا typing.ParamSpec عمدتاً برای بررسی ایستای نوع در نظر گرفته شده است.

genericalias.__unpacked__

یک مقدار بولی که اگر نام مستعار با استفاده از عملگر * واگشایی شده باشد، True است (به TypeVarTuple مراجعه کنید).

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

همچنین ملاحظه نمائید

PEP 484 - راهنماهای نوع

معرفی چارچوب پایتون برای حاشیه‌نویسی‌های نوع .

PEP 585 - راهنمایی نوع برای نوع‌های عام در مجموعه‌های استاندارد

معرفی توانایی پارامتری‌سازی کلاس‌های کتابخانه استاندارد به‌صورت بومی، مشروط بر اینکه متد کلاس ویژه __class_getitem__() را پیاده‌سازی کنند.

نوع‌های عام، نوع‌های عامِ تعریف‌شده توسط کاربر و typing.Generic

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

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

نوع اجتماعی (Union Type)

یک شیء اجتماع‌ای (union)، مقدار حاصل از عملیات | (یای بیتی) روی چندین شیء نوع را در خود نگه می‌دارد. این نوع‌ها عمدتاً برای حاشیه‌نویسی‌های نوع در نظر گرفته شده‌اند. عبارت نوع اجتماع‌ای (union)، سینتکس تمیزتری برای راهنمایی نوع در مقایسه با زیرنویسی روی typing.Union فراهم می‌کند.

X | Y | ...

یک شیء union تعریف می‌کند که شامل انواع X، Y و غیره است. X | Y به معنای X یا Y است. این معادل typing.Union[X, Y] است. برای مثال، تابع زیر آرگومانی از نوع int یا float انتظار دارد:

def square(number: int | float) -> int | float:
    return number ** 2

توجه

The | operator cannot be used at runtime to define unions where one or more members is a forward reference. For example, int | "Foo", where "Foo" is a reference to a class not yet defined, will fail at runtime. For unions which include forward references, present the whole expression as a string, e.g. "int | Foo".

union_object == other

می‌توان اشیاء Union را از نظر برابری با سایر اشیاء Union آزمایش کرد. جزئیات:

• اجتماع‌هایی از اجتماع‌ها مسطح می‌شوند:

  (int | str) | float == int | str | float
  

• نوع‌های اضافی حذف می‌شوند:

  int | str | int == int | str
  

• هنگام مقایسه‌ی اجتماع‌ها، ترتیب نادیده گرفته می‌شود:

  int | str == str | int
  

• این نمونه‌هایی از typing.Union ایجاد می‌کند:

  int | str == typing.Union[int, str]
  type(int | str) is typing.Union
  

• انواع اختیاری را می‌توان به‌صورت یک اجتماع با None نوشت:

  str | None == typing.Optional[str]
  

isinstance(obj, union_object)

issubclass(obj, union_object)

فراخوانی‌های isinstance() و issubclass() نیز با یک شیء union پشتیبانی می‌شوند:

>>> isinstance("", int | str)
True

با این حال، parameterized generics در اشیای union قابل بررسی نیستند:

>>> isinstance(1, int | list[int])  # short-circuit evaluation
True
>>> isinstance([1], int | list[int])
Traceback (most recent call last):
  ...
TypeError: isinstance() argument 2 cannot be a parameterized generic

نوع در معرض دید کاربر برای شیء union، از typing.Union قابل دسترسی است و می‌توان از آن برای بررسی‌های isinstance() استفاده کرد:

>>> import typing
>>> isinstance(int | str, typing.Union)
True
>>> typing.Union()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot create 'typing.Union' instances

توجه

متد __or__() برای اشیای نوع افزوده شد تا از سینتکس X | Y پشتیبانی کند. اگر یک فراکلاس __or__() را پیاده‌سازی کند، ممکن است Union آن را بازنویسی کند:

>>> class M(type):
...     def __or__(self, other):
...         return "Hello"
...
>>> class C(metaclass=M):
...     pass
...
>>> C | int
'Hello'
>>> int | C
int | C

همچنین ملاحظه نمائید

PEP 604 -- PEP پیشنهادکننده‌ی سینتکس X | Y و نوع Union.

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

تغییر یافته در نسخه‌ی 3.14: اشیای Union اکنون نمونه‌هایی از typing.Union هستند. پیش‌تر، آن‌ها نمونه‌هایی از types.UnionType بودند که همچنان نام مستعاری برای typing.Union است.

انواع توکار دیگر

مفسر از چندین نوع دیگر از اشیاء پشتیبانی می‌کند. بیشتر این اشیاء فقط از ۱ یا ۲ عملیات پشتیبانی می‌کنند.

ماژول‌ها

تنها عملیات ویژه بر روی یک ماژول، دسترسی به ویژگی است: m.name، که در آن m یک ماژول است و name به نامی تعریف‌شده در جدول نمادهای m دسترسی می‌یابد. می‌توان به ویژگی‌های ماژول انتساب داد. (توجه داشته باشید که دستور import، به‌معنای دقیق، یک عملیات بر روی شیء ماژول نیست؛ import foo نیازی به وجود یک شیء ماژول با نام foo ندارد، بلکه به یک تعریف (خارجی) برای ماژولی با نام foo در جایی نیاز دارد.)

یک ویژگی خاص هر ماژول، __dict__ است. این دیکشنری حاوی جدول نمادهای ماژول است. تغییر این دیکشنری در واقع جدول نمادهای ماژول را تغییر می‌دهد، اما انتساب مستقیم به ویژگی __dict__ امکان‌پذیر نیست (می‌توانید m.__dict__['a'] = 1 را بنویسید، که m.a را با مقدار 1 تعریف می‌کند، اما نمی‌توانید m.__dict__ = {} را بنویسید). تغییر مستقیم __dict__ توصیه نمی‌شود.

ماژول‌هایی که در مفسر توکار هستند، به این شکل نوشته می‌شوند: <module 'sys' (built-in)>. اگر از یک پرونده بارگذاری شوند، به این شکل نوشته می‌شوند: <module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>.

کلاس‌ها و نمونه‌های کلاس

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

توابع

اشیای تابع با تعریف تابع ایجاد می‌شوند. تنها عملیات روی یک شیء تابع، فراخوانی آن است: func(argument-list).

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

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

متدها

Methods are functions that are called using the attribute notation. There are two flavors: built-in methods (such as append() on lists) and class instance methods. Built-in methods are described with the types that support them.

اگر از طریق یک نمونه به یک متد (تابعی که در فضای نام یک کلاس تعریف شده است) دسترسی پیدا کنید، یک شیء خاص دریافت می‌کنید: یک شیء متد مقید <bound method> (bound method) که به آن متد نمونه نیز گفته می‌شود. هنگام فراخوانی، آرگومان self را به فهرست آرگومان‌ها اضافه می‌کند. متدهای مقید دو ویژگی فقط‌خواندنی خاص دارند: m.__self__ شیءای است که متد روی آن عمل می‌کند، و m.__func__ تابعی است که متد را پیاده‌سازی می‌کند. فراخوانی m(arg-1, arg-2, ..., arg-n) کاملاً معادل فراخوانی m.__func__(m.__self__, arg-1, arg-2, ..., arg-n) است.

مانند اشیای تابع، اشیای متد مقید از دریافت ویژگی‌های دلخواه پشتیبانی می‌کنند. با این حال، از آنجا که ویژگی‌های متد در واقع روی شیء تابع زیربنایی ذخیره شده‌اند (method.__func__)، تنظیم ویژگی‌های متد روی متدهای مقید مجاز نیست. تلاش برای تنظیم یک ویژگی روی یک متد منجر به پرتاب AttributeError می‌شود. برای تنظیم یک ویژگی متد، باید آن را به‌صراحت روی شیء تابع زیربنایی تنظیم کنید:

>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # can't set on the method
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'

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

اشیای کد

اشیای کد در پیاده‌سازی برای بازنمایی کد پایتون قابل‌اجرای «شبه‌کامپایل‌شده» مانند بدنه‌ی تابع استفاده می‌شوند. آن‌ها با اشیای تابع متفاوت هستند، زیرا ارجاعی به محیط اجرای سراسری خود ندارند. اشیای کد توسط تابع توکار compile() برگردانده می‌شوند و می‌توان آن‌ها را از اشیای تابع از طریق ویژگی __code__ آن‌ها استخراج کرد. همچنین ماژول code را ببینید.

دسترسی به __code__ یک رویداد حسابرسی object.__getattr__ را با آرگومان‌های obj و "__code__" پرتاب می‌کند.

می‌توان یک شیء کد را با ارسال آن (به‌جای یک رشته منبع) به توابع توکار exec() یا eval() اجرا یا ارزیابی کرد.

برای اطلاعات بیشتر انواع را ببینید.

اشیای نوع

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

نوع‌ها به این شکل نوشته می‌شوند: <class 'int'>.

شیء تهی

این شیء توسط توابعی برگردانده می‌شود که به‌صراحت مقداری را برنمی‌گردانند. این شیء از هیچ عملیات خاصی پشتیبانی نمی‌کند. دقیقاً یک شیء تهی (null) وجود دارد که None (نامی توکار) نام دارد. type(None)() همان تک‌نمونه را تولید می‌کند.

به صورت None نوشته می‌شود.

شیء Ellipsis

این شیء معمولاً برای نشان دادن اینکه چیزی حذف شده است، به کار می‌رود. این شیء از هیچ عملیات خاصی پشتیبانی نمی‌کند. دقیقاً یک شیء Ellipsis وجود دارد، به نام Ellipsis (یک نام توکار). type(Ellipsis)() تک‌نمونه‌ی Ellipsis را تولید می‌کند.

این به‌صورت Ellipsis یا ... نوشته می‌شود.

در استفاده‌ی معمول، ... به‌عنوان شیء Ellipsis در چند جای مختلف ظاهر می‌شود، برای مثال:

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

• به‌عنوان بدنه یک تابع به‌جای دستور pass.

• در کتابخانه‌های شخص ثالث، مانند Numpy's slicing and striding.

پایتون همچنین از سه‌نقطه به‌شکل‌هایی استفاده می‌کند که شیء Ellipsis نیستند، برای مثال:

• ELLIPSIS در Doctest، به‌عنوان الگویی برای محتوای جاافتاده.

• اعلان پیش‌فرض پایتون در پوسته‌ی interactive هنگامی که ورودی جزئی کامل نیست.

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

شیء NotImplemented

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

این به‌صورت NotImplemented نوشته می‌شود.

اشیاء داخلی

برای این اطلاعات انواع را ببینید. این بخش اشیای فریم پشته، اشیای ردگیری پشته و اشیای اسلایس (slice) را توصیف می‌کند.

ویژگی‌های خاص

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

definition.__name__

نام کلاس، تابع، متد، توصیف‌گر (descriptor) یا نمونه‌ی تولیدگر.

definition.__qualname__

qualified name کلاس، تابع، متد، توصیف‌گر یا نمونه‌ی تولیدگر.

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

definition.__module__

نام ماژولی که کلاس یا تابعی در آن تعریف شده است.

definition.__doc__

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

definition.__type_params__

پارامترهای نوع کلاس‌ها، توابع و نام‌مستعارهای نوع عام. برای کلاس‌ها و توابعی که عام نیستند، این یک تاپل خالی خواهد بود.

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

محدودیت طول تبدیل عدد صحیح به رشته

CPython یک محدودیت سراسری برای تبدیل بین int و str برای کاهش اثر حملات منع سرویس دارد. این محدودیت فقط در مورد مبنای ده یا سایر مبناهای عددی غیر از توان ۲ اعمال می‌شود. تبدیل‌های مبنای شانزده، مبنای هشت و مبنای دو نامحدود هستند. این محدودیت قابل پیکربندی است.

نوع int در CPython عددی با طول دلخواه است که به صورت دودویی ذخیره می‌شود (و معمولاً با نام «bignum» شناخته می‌شود). هیچ الگوریتمی وجود ندارد که بتواند یک رشته را به یک عدد صحیح دودویی یا یک عدد صحیح دودویی را به یک رشته در زمان خطی تبدیل کند، مگر اینکه پایه توانی از ۲ باشد. حتی بهترین الگوریتم‌های شناخته‌شده برای پایه‌ی ۱۰ نیز پیچیدگی کمتر از درجه‌ی دو دارند. تبدیل یک مقدار بزرگ مانند int('1' * 500_000) می‌تواند بیش از یک ثانیه روی یک پردازنده سریع زمان ببرد.

محدود کردن اندازه‌ی تبدیل، راهی عملی برای اجتناب از CVE 2020-10735 فراهم می‌کند.

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

هنگامی که یک عملیات از حد مجاز فراتر رود، ValueError پرتاب می‌شود:

>>> import sys
>>> sys.set_int_max_str_digits(4300)  # Illustrative, this is the default.
>>> _ = int('2' * 5432)
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit
>>> i = int('2' * 4300)
>>> len(str(i))
4300
>>> i_squared = i*i
>>> len(str(i_squared))
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion; use sys.set_int_max_str_digits() to increase the limit
>>> len(hex(i_squared))
7144
>>> assert int(hex(i_squared), base=16) == i*i  # Hexadecimal is unlimited.

محدودیت پیش‌فرض ۴۳۰۰ رقم است، همان‌طور که در sys.int_info.default_max_str_digits ارائه شده است. کمترین محدودیتی که می‌توان آن را پیکربندی کرد، ۶۴۰ رقم است، همان‌طور که در sys.int_info.str_digits_check_threshold ارائه شده است.

تأیید:

>>> import sys
>>> assert sys.int_info.default_max_str_digits == 4300, sys.int_info
>>> assert sys.int_info.str_digits_check_threshold == 640, sys.int_info
>>> msg = int('578966293710682886880994035146873798396722250538762761564'
...           '9252925514383915483333812743580549779436104706260696366600'
...           '571186405732').to_bytes(53, 'big')
...

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

APIهای تحت‌تأثیر

این محدودیت فقط به تبدیل‌های بالقوه کند بین int و str یا bytes اعمال می‌شود:

• int(string) با مبنای پیش‌فرض ۱۰.

• int(string, base) برای همه مبناهایی که توانی از ۲ نیستند.

• str(integer).

• repr(integer).

• هر تبدیل دیگری به رشته در مبنای ۱۰، برای مثال f"{integer}"، "{}".format(integer) یا b"%d" % integer.

این محدودیت‌ها شامل توابعی با الگوریتم خطی نمی‌شوند:

• int(string, base) با مبنای ۲، ۴، ۸، ۱۶ یا ۳۲.

• int.from_bytes() و int.to_bytes().

• hex(), oct(), bin().

• زبان کوچک مشخصات قالب‌بندی برای اعداد مبنای شانزده، مبنای هشت و مبنای دو.

• str به float.

• str به decimal.Decimal.

پیکربندی محدودیت

پیش از راه‌اندازی پایتون می‌توانید از یک متغیر محیطی یا پرچم خط فرمان مفسر برای پیکربندی محدودیت استفاده کنید:

• PYTHONINTMAXSTRDIGITS، برای مثال PYTHONINTMAXSTRDIGITS=640 python3 برای تنظیم حد روی ۶۴۰ یا PYTHONINTMAXSTRDIGITS=0 python3 برای غیرفعال کردن محدودیت.

• -X int_max_str_digits، برای مثال python3 -X int_max_str_digits=640

• sys.flags.int_max_str_digits شامل مقدار PYTHONINTMAXSTRDIGITS یا -X int_max_str_digits است. اگر هر دو متغیر محیطی و گزینه -X تنظیم شده باشند، گزینه -X اولویت دارد. مقدار -1 نشان می‌دهد که هر دو تنظیم‌نشده بودند، بنابراین مقدار sys.int_info.default_max_str_digits در هنگام مقداردهی اولیه استفاده شده است.

از طریق کد، می‌توانید محدودیت فعلی را بررسی کنید و با استفاده از این APIهای sys محدودیت جدیدی تنظیم کنید:

• sys.get_int_max_str_digits() و sys.set_int_max_str_digits() getter و setter برای محدودیت سراسری مفسر هستند. زیرمفسرها محدودیت خودشان را دارند.

اطلاعات درباره مقدار پیش‌فرض و کمینه را می‌توان در sys.int_info یافت:

• sys.int_info.default_max_str_digits محدودیت پیش‌فرض درون‌ساخته (compiled-in) است.

• sys.int_info.str_digits_check_threshold کمترین مقدار پذیرفته‌شده برای محدودیت است (به‌جز ۰ که آن را غیرفعال می‌کند).

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

ملاحظه

تنظیم یک حد پایین می‌تواند منجر به مشکلاتی شود. اگرچه نادر است، اما کدهایی وجود دارند که در کد منبع خود ثابت‌های عدد صحیح به مبنای ده دارند که از حداقل آستانه بیشترند. پیامد تنظیم این حد آن است که کد منبع پایتون حاوی مقادیر لفظی عدد صحیح مبنای ده طولانی‌تر از حد، هنگام تجزیه با خطایی مواجه می‌شود؛ معمولاً در زمان راه‌اندازی، زمان ایمپورت یا حتی زمان نصب — هر زمان که یک .pyc به‌روز برای آن کد از قبل وجود نداشته باشد. راه‌حلی برای کد منبعی که شامل چنین ثابت‌های بزرگی است، تبدیل آن‌ها به قالب 0x مبنای شانزده است، زیرا این قالب حدی ندارد.

اگر از یک محدودیت پایین استفاده می‌کنید، برنامه‌تان را به‌طور کامل آزمایش کنید. اطمینان حاصل کنید که آزمون‌های شما با محدودیتی اجرا می‌شوند که از طریق محیط یا پرچم از پیش تنظیم شده است، تا این محدودیت در هنگام راه‌اندازی و حتی در هر مرحله‌ی نصبی که ممکن است پایتون را برای پیش‌کامپایل کردن پرونده‌های منبع .py به پرونده‌های .pyc فراخوانی کند، اعمال شود.

پیکربندی توصیه‌شده

انتظار می‌رود مقدار پیش‌فرض sys.int_info.default_max_str_digits برای بیشتر برنامه‌ها معقول باشد. اگر برنامه شما به محدودیت متفاوتی نیاز دارد، آن را از نقطه ورود اصلی خود با استفاده از کد مستقل از نسخه پایتون تنظیم کنید، زیرا این APIها در انتشارهای وصله امنیتی در نسخه‌های پیش از 3.12 اضافه شده‌اند.

مثال:

>>> import sys
>>> if hasattr(sys, "set_int_max_str_digits"):
...     upper_bound = 68000
...     lower_bound = 4004
...     current_limit = sys.get_int_max_str_digits()
...     if current_limit == 0 or current_limit > upper_bound:
...         sys.set_int_max_str_digits(upper_bound)
...     elif current_limit < lower_bound:
...         sys.set_int_max_str_digits(lower_bound)

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

پانویس‌ها

[1]

اطلاعات بیشتر درباره این متدهای ویژه را می‌توانید در راهنمای مرجع پایتون (پیکربندی) بیابید.

[2]

در نتیجه، فهرست [1, 2] برابر با [1.0, 2.0] در نظر گرفته می‌شود، و به‌طور مشابه برای تاپل‌ها .

[3]

آن‌ها باید داشته باشند، زیرا پارسر نمی‌تواند نوع عملوندها را تشخیص دهد.

[4] (1,2,3,4)

نویسه‌های دارای حالت حروف، آن‌هایی هستند که ویژگی دسته‌بندی عمومی آن‌ها یکی از "Lu" (حرف، بزرگ)، "Ll" (حرف، کوچک) یا "Lt" (حرف، نگارش عنوان‌نویسی) است.

[5] (1,2)

بنابراین، برای این‌که فقط یک تاپل را قالب‌بندی کنید، باید یک تاپل تک‌عضوی ارائه دهید که تنها عنصر آن، تاپلی است که باید قالب‌بندی شود.