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

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

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

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

یادداشت‌ها:

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]

در اینجا sign اختیاری می‌تواند + یا - باشد. integer و fraction رشته‌هایی از ارقام مبنای شانزده هستند و exponent یک عدد صحیح دهدهی با یک علامت پیش‌روِ اختیاری است. بزرگی و کوچکی حروف اهمیتی ندارد و باید حداقل یک رقم مبنای شانزده در عدد صحیح یا کسر وجود داشته باشد. این سینتکس شبیه به سینتکسِ مشخص‌شده در بخش ۶.۴.۴.۲ از استاندارد C99 است و همچنین به سینتکسِ استفاده‌شده در جاوا ۱.۵ به بعد. به‌ویژه، خروجیِ float.hex() به‌عنوان یک لفظیِ اعشاریِ مبنای شانزده در کد C یا جاوا قابل‌استفاده است و رشته‌های مبنای شانزده تولیدشده توسط نویسهِ قالب %a زبان C یا Double.toHexString جاوا توسط 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 در اختیار پایتون قرار می‌گیرد.

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

• اگر 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

پیمایش‌پذیرها¶

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

container.__iter__()¶

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

پیمایش‌گرها¶

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

iterator.__iter__()¶

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

iterator.__next__()¶

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

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

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

انواع تولیدگر¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

یادداشت‌ها:

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

آیتمِ در index را بازیابی کنید و همچنین آن را از sequence حذف کنید. به‌صورت پیش‌فرض، آخرین آیتم در sequence حذف و برگردانده می‌شود.

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 را پرتاب می‌کند.

تاپل‌ها¶

تاپل‌هادنباله‌های تغییرناپذیری هستند که معمولاً برای ذخیره مجموعه‌هایی از داده‌های ناهمگون (مانند تاپل‌های ۲تایی تولیدشده توسط تابع توکار 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).)

متدهای رشته¶

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

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

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

str.capitalize()¶

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

>>> 'PYTHON IS AMAZING'.capitalize()
'Python is amazing'
>>> 'Njemačka starts With a non-ASCII digraph'.capitalize()
'Njemačka starts with a non-ascii digraph'

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

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

str.casefold()¶

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

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

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

الگوریتم یکسان‌سازی حروف بزرگ و کوچک در بخش ۳.۱۳.۳ با عنوان «Default Case Folding» از استاندارد یونیکس شرح داده شده است.

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

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

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

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

str.isascii()¶

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

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

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

الگوریتم کوچک‌سازی حروف استفاده‌شده در بخش 3.13.2 'Default Case Conversion' از استاندارد یونیکد شرح داده شده است.

str.lstrip(chars=None, /)¶

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

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

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

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

static str.maketrans(dict, /)¶

static str.maketrans(from, to, remove='', /)

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

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

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

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

str.partition(sep, /)¶

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

برای مثال:

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

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

str.removeprefix(prefix, /)¶

اگر رشته با رشته‌ی prefix شروع شود، string[len(prefix):] را برمی‌گرداند. در غیر این صورت، نسخه‌ای از رشته اصلی را برمی‌گرداند:

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

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

یک فهرست از کلمات موجود در رشته را با استفاده از sep به‌عنوان رشته جداکننده برگردانید. اگر maxsplit داده شده باشد، حداکثر maxsplit تجزیه انجام می‌شود، آن‌هایی که در rightmost هستند. اگر sep مشخص نشده باشد یا None باشد، هر رشته whitespace یک جداکننده است. به‌جز تجزیه از راست، rsplit() شبیه به split() رفتار می‌کند که به‌صورت مفصل در ادامه توصیف شده است.

str.rstrip(chars=None, /)¶

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

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

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

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

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

str.split(sep=None, maxsplit=-1)¶

فهرستی از واژه‌های موجود در رشته را با استفاده از sep به‌عنوان رشته‌ی جداکننده بازمی‌گرداند. اگر maxsplit داده شود، حداکثر maxsplit جداسازی انجام می‌شود (بدین ترتیب، فهرست حداکثر maxsplit+1 المان خواهد داشت). اگر maxsplit مشخص نشده باشد یا -1 باشد، هیچ محدودیتی بر تعداد جداسازی‌ها وجود ندارد (تمام جداسازی‌های ممکن انجام می‌شوند).

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

برای مثال:

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

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

برای مثال:

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

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

برای مثال:

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

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

str.splitlines(keepends=False)¶

فهرستی از سطرهای رشته را با شکستن در مرزهای سطر برمی‌گرداند. شکستگی‌های خط در فهرست حاصل گنجانده نمی‌شوند، مگر اینکه keepends داده شده و 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', '']