string --- عملیات رایج رشته‌ها

کد منبع: Lib/string/__init__.py

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

Text Sequence Type --- str

String Methods

ثابت‌های رشته‌ای

ثابت‌های تعریف‌شده در این ماژول عبارتند از:

string.ascii_letters

الحاق ثابت‌های ascii_lowercase و ascii_uppercase که در ادامه شرح داده شده‌اند. این مقدار به locale وابسته نیست.

string.ascii_lowercase

حروف کوچک 'abcdefghijklmnopqrstuvwxyz'. این مقدار وابسته به locale نیست و تغییر نخواهد کرد.

string.ascii_uppercase

حروف بزرگ 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. این مقدار به locale وابسته نیست و تغییر نخواهد کرد.

string.digits

رشته '0123456789'.

string.hexdigits

رشته '0123456789abcdefABCDEF'.

string.octdigits

رشته '01234567'.

string.punctuation

رشته‌ای از نویسه‌های ASCII که در منطقه‌ی C نویسه‌های علائم نگارشی محسوب می‌شوند: !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~.

string.printable

رشته‌ای از نویسه‌های ASCII که از نظر پایتون قابل‌چاپ محسوب می‌شوند. این، ترکیبی از digits، ascii_letters، punctuation و whitespace است.

توجه

بر اساس طراحی، string.printable.isprintable() False را برمی‌گرداند. به‌ویژه، string.printable در معنای POSIX قابل چاپ نیست (به LC_CTYPE مراجعه کنید).

string.whitespace

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

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

کلاس رشته‌ی توکار امکان انجام جایگزینی‌های پیچیده‌ی متغیرها و قالب‌بندی مقدار را از طریق متد format() که در PEP 3101 توضیح داده شده است، فراهم می‌کند. کلاس Formatter در ماژول string به شما امکان می‌دهد رفتارهای قالب‌بندی رشته‌ی خودتان را با استفاده از همان پیاده‌سازی متد توکار format() ایجاد و سفارشی‌سازی کنید.

class string.Formatter

کلاس Formatter دارای متدهای عمومی زیر است:

format(format_string, /, *args, **kwargs)

متد اصلی API. این متد یک رشته‌ی قالب و مجموعه‌ای دلخواه از آرگومان‌های جایگاهی و کلیدواژه‌ای را دریافت می‌کند. این متد صرفاً یک دربرگیرنده است که vformat() را فراخوانی می‌کند.

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

vformat(format_string, args, kwargs)

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

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

parse(format_string)

format_string را با حلقه پیمایش می‌کند و یک پیمایش‌پذیر از تاپل‌های (literal_text، field_name، format_spec، conversion) برمی‌گرداند. این مورد توسط vformat() برای تفکیک رشته به متن ثابت یا فیلدهای جایگزینی استفاده می‌شود.

مقادیر موجود در تاپل از نظر مفهومی یک قطعه متن لفظی و به دنبال آن یک فیلد جایگزینی را نشان می‌دهند. اگر متن لفظی وجود نداشته باشد (که ممکن است در صورتی رخ دهد که دو فیلد جایگزینی به‌صورت متوالی ظاهر شوند)، literal_text رشته‌ای با طول صفر خواهد بود. اگر فیلد جایگزینی وجود نداشته باشد، مقادیر field_name، format_spec و conversion برابر None خواهند بود. مقدار field_name بدون تغییر باقی می‌ماند و شماره‌گذاری خودکار فیلدهای جایگاهی بدون شماره توسط vformat() انجام می‌شود.

get_field(field_name, args, kwargs)

با داشتن field_name، آن را به شیءای برای قالب‌بندی تبدیل می‌کند. شماره‌گذاری خودکار field_name بازگشتی از parse() توسط vformat() پیش از فراخوانی این متد انجام می‌شود. یک تاپل (obj, used_key) برمی‌گرداند. نسخه پیش‌فرض رشته‌هایی با قالب تعریف‌شده در PEP 3101 را می‌پذیرد، مانند "0[name]" یا "label.title". args و kwargs همان مقادیری هستند که به vformat() داده شده‌اند. مقدار بازگشتی used_key همان معنای پارامتر key در get_value() را دارد.

get_value(key, args, kwargs)

مقدار یک فیلد مشخص را بازیابی می‌کند. آرگومان key یا یک عدد صحیح است یا یک رشته. اگر عدد صحیح باشد، بیانگر اندیس آرگومان جایگاهی در args است؛ اگر رشته باشد، بیانگر یک آرگومان نام‌دار در kwargs است.

پارامتر args به فهرست آرگومان‌های جایگاهی vformat() تنظیم می‌شود، و پارامتر kwargs به دیکشنری آرگومان‌های کلیدواژه‌ای تنظیم می‌شود.

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

بنابراین برای مثال، عبارت فیلد '0.name' باعث می‌شود get_value() با آرگومان key برابر ۰ فراخوانی شود. ویژگی name پس از بازگشت get_value() با فراخوانی تابع توکار getattr() جستجو می‌شود.

اگر اندیس یا کلیدواژه به آیتمی که وجود ندارد اشاره کند، باید یک IndexError یا KeyError پرتاب شود.

check_unused_args(used_args, args, kwargs)

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

format_field(value, format_spec)

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

convert_field(value, conversion)

مقدار (بازگشت‌داده‌شده توسط get_field()) را با توجه به نوع تبدیل (مانند تاپل بازگشت‌داده‌شده توسط متد parse()) تبدیل می‌کند. نسخه پیش‌فرض انواع تبدیل 's' (str)، 'r' (repr) و 'a' (ascii) را می‌شناسد.

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

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

رشته‌های قالب حاوی «فیلدهای جایگزینی» هستند که با آکولادها {} احاطه شده‌اند. هر چیزی که داخل آکولادها نباشد، متن لفظی در نظر گرفته می‌شود و بدون تغییر به خروجی رونوشت می‌شود. اگر نیاز دارید یک نویسه آکولاد را در متن لفظی بگنجانید، می‌توانید آن را با دو بار نوشتن خنثی کنید: {{ و }}.

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

replacement_field: "{" [field_name] ["!" conversion] [":" format_spec] "}"
field_name:        arg_name ("." attribute_name | "[" element_index "]")*
arg_name:          [identifier | digit+]
attribute_name:    identifier
element_index:     digit+ | index_string
index_string:      <any source character except "]"> +
conversion:        "r" | "s" | "a"
format_spec:       format-spec:format_spec

به بیان غیررسمی‌تر، فیلد جایگزینی می‌تواند با یک field_name آغاز شود که شیءای را مشخص می‌کند که مقدار آن باید قالب‌بندی شود و به جای فیلد جایگزینی، در خروجی درج شود. پس از field_name، به‌اختیار یک فیلد conversion می‌آید که پیش از آن علامت تعجب '!' قرار دارد، و یک format_spec که پیش از آن دونقطه ':' قرار دارد. این موارد قالبی غیرپیش‌فرض برای مقدار جایگزینی مشخص می‌کنند.

همچنین بخش زبان کوچک مشخصات قالب‌بندی را ببینید.

خود field_name با یک arg_name آغاز می‌شود که یا یک عدد است یا یک کلیدواژه. اگر عدد باشد، به یک آرگومان جایگاهی اشاره می‌کند، و اگر کلیدواژه باشد، به یک آرگومان کلیدواژه‌ای نام‌دار اشاره می‌کند. اگر فراخوانی str.isdecimal() روی رشته مقدار true را برگرداند، arg_name یک عدد در نظر گرفته می‌شود. اگر arg_nameهای عددی در یک رشته‌ی قالب به‌ترتیب ۰، ۱، ۲، ... باشند، می‌توان همه‌ی آن‌ها را حذف کرد (نه فقط برخی) و اعداد ۰، ۱، ۲، ... به‌همین ترتیب به‌صورت خودکار درج می‌شوند. از آن‌جا که arg_name با علامت نقل‌قول محدود نمی‌شود، نمی‌توان کلیدهای دلخواه دیکشنری (برای مثال، رشته‌های '10' یا ':-]') را در یک رشته‌ی قالب مشخص کرد. پس از arg_name می‌تواند هر تعداد عبارت اندیس یا ویژگی بیاید. عبارتی به‌شکل '.name' ویژگی نام‌برده را با استفاده از getattr() انتخاب می‌کند، در حالی که عبارتی به‌شکل '[index]' جست‌وجوی اندیس را با استفاده از __getitem__() انجام می‌دهد.

تغییر یافته در نسخه‌ی 3.1: مشخص‌کننده‌های آرگومان جایگاهی را می‌توان برای str.format() حذف کرد، بنابراین '{} {}'.format(a, b) معادل '{0} {1}'.format(a, b) است.

تغییر یافته در نسخه‌ی 3.4: می‌توان مشخص‌کننده‌های آرگومان جایگاهی را برای Formatter حذف کرد.

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

"First, thou shalt count to {0}"  # References first positional argument
"Bring me a {}"                   # Implicitly references the first positional argument
"From {} to {}"                   # Same as "From {0} to {1}"
"My quest is {name}"              # References keyword argument 'name'
"Weight in tons {0.weight}"       # 'weight' attribute of first positional arg
"Units destroyed: {players[0]}"   # First element of keyword argument 'players'.

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

در حال حاضر از ۳ پرچم تبدیل پشتیبانی می‌شود: '!s' که str() را بر روی مقدار فراخوانی می‌کند، '!r' که repr() را فراخوانی می‌کند و '!a' که ascii() را فراخوانی می‌کند.

برخی مثال‌ها:

"Harold's a clever {0!s}"        # Calls str() on the argument first
"Bring out the holy {name!r}"    # Calls repr() on the argument first
"More {!a}"                      # Calls ascii() on the argument first

فیلد format_spec شامل مشخصاتی است که چگونگی نمایش مقدار را تعیین می‌کند، از جمله جزئیاتی مانند عرض فیلد، تراز، پرکننده، دقت اعشاری و غیره. هر نوع مقدار می‌تواند «زبان کوچک قالب‌بندی» یا تفسیر خاص خود از format_spec را تعریف کند.

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

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

برای چند مثال، بخش نمونه‌های قالب‌بندی را ببینید.

زبان کوچک مشخصات قالب‌بندی

«مشخصات قالب‌بندی» درون فیلدهای جایگزینی که در یک رشته قالب قرار دارند، استفاده می‌شوند تا چگونگی ارائه مقادیر منفرد را تعریف کنند (به سینتکس رشته قالب، اف‌استرینگ‌ها و تی‌استرینگ‌ها (t-strings) مراجعه کنید). همچنین می‌توان آن‌ها را مستقیماً به تابع توکار format() ارسال کرد. هر نوع قابل قالب‌بندی ممکن است تعریف کند که مشخصات قالب‌بندی چگونه تفسیر می‌شود.

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

قرارداد عمومی این است که مشخصات قالب‌بندی خالی، همان نتیجه‌ای را تولید می‌کند که گویی str() را روی مقدار فراخوانی کرده‌اید. مشخصات قالب‌بندی غیرخالی معمولاً نتیجه را تغییر می‌دهد.

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

format_spec:             [options][width_and_precision][type]
options:                 [[fill]align][sign]["z"]["#"]["0"]
fill:                    <any character>
align:                   "<" | ">" | "=" | "^"
sign:                    "+" | "-" | " "
width_and_precision:     [width_with_grouping][precision_with_grouping]
width_with_grouping:     [width][grouping]
precision_with_grouping: "." [precision][grouping] | "." grouping
width:                   digit+
precision:               digit+
grouping:                "," | "_"
type:                    "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g"
                         | "G" | "n" | "o" | "s" | "x" | "X" | "%"

اگر یک مقدار معتبر برای align مشخص شود، می‌توان پیش از آن یک نویسه fill قرار داد که می‌تواند هر نویسه‌ای باشد و در صورت حذف، پیش‌فرض آن نویسه فاصله است. استفاده از یک آکولاد به‌صورت لفظی ("{" یا "}") به‌عنوان نویسه fill در یک اف‌استرینگ یا هنگام استفاده از متد str.format() ممکن نیست. با این حال، می‌توان یک آکولاد را با یک فیلد جایگزینی تودرتو درج کرد. این محدودیت بر تابع format() تأثیری ندارد.

معنای گزینه‌های مختلف ترازبندی به شرح زیر است:

گزینه

معنی

'<'

فیلد را وادار می‌کند که در فضای موجود چپ‌تراز باشد (این حالت برای بیشتر اشیاء پیش‌فرض است).

'>'

فیلد را مجبور می‌کند که در فضای موجود راست‌چین باشد (این حالت برای اعداد پیش‌فرض است).

'='

قرار گرفتن پرکننده (padding) پس از علامت (در صورت وجود) و پیش از ارقام را اجباری می‌کند. این گزینه برای چاپ فیلدها در قالب '+000000120' به کار می‌رود. این گزینه‌ی تراز فقط برای انواع عددی معتبر است، به‌جز complex. برای اعداد، هرگاه '0' بلافاصله پیش از عرض فیلد بیاید، این گزینه به‌صورت پیش‌فرض اعمال می‌شود.

'^'

فیلد را وادار می‌کند که در فضای موجود وسط‌چین شود.

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

گزینه‌ی sign فقط برای انواع عددی معتبر است و می‌تواند یکی از موارد زیر باشد:

گزینه

معنی

'+'

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

'-'

نشان می‌دهد که علامت باید فقط برای اعداد منفی استفاده شود (این رفتار پیش‌فرض است).

فاصله

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

گزینه 'z' مقادیر صفر منفی ممیز شناور را پس از گرد شدن به دقت قالب، به صفر مثبت تبدیل می‌کند. این گزینه فقط برای انواع نمایش ممیز شناور معتبر است.

تغییر یافته در نسخه‌ی 3.11: گزینه 'z' افزوده شد (همچنین PEP 682 را ببینید).

گزینه‌ی '#' باعث می‌شود که «شکل جایگزین» برای تبدیل استفاده شود. شکل جایگزین برای انواع مختلف به‌طور متفاوتی تعریف می‌شود. این گزینه تنها برای انواع عدد صحیح، شناور و مختلط معتبر است. برای اعداد صحیح، هنگامی که خروجی به‌صورت مبنای دو، مبنای هشت یا مبنای شانزده باشد، این گزینه پیشوند مربوطه یعنی '0b'، '0o'، '0x' یا '0X' را به مقدار خروجی اضافه می‌کند. برای شناور و مختلط، شکل جایگزین باعث می‌شود که نتیجه‌ی تبدیل همیشه شامل یک نویسه‌ی نقطه‌ی اعشار باشد، حتی اگر هیچ رقمی پس از آن نیاید. به‌طور معمول، یک نویسه‌ی نقطه‌ی اعشار در نتیجه‌ی این تبدیل‌ها فقط در صورتی ظاهر می‌شود که رقمی پس از آن بیاید. علاوه بر این، برای تبدیل‌های 'g' و 'G'، صفرهای پایانی از نتیجه حذف نمی‌شوند.

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

هنگامی که تراز صریحی داده نشده باشد، قرار دادن نویسه‌ی صفر ('0') پیش از فیلد width، پدینگ صفر با در نظر گرفتن علامت را برای انواع عددی، به‌جز complex، فعال می‌کند. این معادل نویسه‌ی fill برابر '0' و نوع alignment برابر '=' است.

تغییر یافته در نسخه‌ی 3.10: قرار دادن '0' پیش از فیلد width دیگر بر هم‌ترازی پیش‌فرض رشته‌ها تأثیری نمی‌گذارد.

precision یک عدد صحیح مبنای ده است که نشان می‌دهد برای انواع نمایش 'f' و 'F' چند رقم باید بعد از نقطه اعشار نمایش داده شوند، یا برای انواع نمایش 'g' یا 'G' چند رقم باید پیش و پس از نقطه اعشار نمایش داده شوند. برای انواع نمایش رشته، این فیلد حداکثر اندازه فیلد را نشان می‌دهد — به عبارت دیگر، نشان می‌دهد که چند نویسه از محتوای فیلد استفاده خواهد شد. استفاده از precision برای انواع نمایش عدد صحیح مجاز نیست.

گزینه‌ی grouping پس از فیلدهای width و precision، جداکننده‌ی گروه ارقام را برای بخش‌های صحیح و کسری یک عدد به‌ترتیب مشخص می‌کند. این گزینه می‌تواند یکی از موارد زیر باشد:

گزینه

معنی

','

برای نوع نمایش عدد صحیح 'd' و انواع نمایش ممیز شناور، به‌جز 'n'، هر ۳ رقم یک ویرگول درج می‌کند. برای سایر انواع نمایش، این گزینه پشتیبانی نمی‌شود.

'_'

برای نوع نمایش عدد صحیح 'd' و انواع نمایش ممیز شناور، به‌جز 'n'، به‌ازای هر ۳ رقم یک زیرخط درج می‌کند. برای انواع نمایش عدد صحیح 'b'، 'o'، 'x' و 'X'، به‌ازای هر ۴ رقم یک زیرخط درج می‌شود. برای سایر انواع نمایش، این گزینه پشتیبانی نمی‌شود.

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

تغییر یافته در نسخه‌ی 3.1: گزینه ',' افزوده شد (همچنین PEP 378 را ببینید).

تغییر یافته در نسخه‌ی 3.6: گزینه‌ی '_' اضافه شد (همچنین PEP 515 را ببینید).

تغییر یافته در نسخه‌ی 3.14: پشتیبانی از گزینه‌ی grouping برای بخش کسری.

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

انواع ارائه‌ی در دسترس برای رشته عبارتند از:

نوع

معنی

's'

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

None

همان 's'.

انواع ارائه‌ی عدد صحیح موجود عبارتند از:

نوع

معنی

'b'

قالب دودویی. عدد را در مبنای ۲ خروجی می‌دهد.

'c'

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

'd'

عدد صحیح دهدهی. عدد را در مبنای ۱۰ خروجی می‌دهد.

'o'

قالب مبنای هشت. عدد را در مبنای ۸ خروجی می‌دهد.

'x'

قالب مبنای شانزده. عدد را در مبنای ۱۶ خروجی می‌دهد و برای ارقام بزرگ‌تر از ۹ از حروف کوچک استفاده می‌کند.

'X'

قالب مبنای شانزده. عدد را در مبنای ۱۶ خروجی می‌دهد و برای ارقام بزرگ‌تر از ۹ از حروف بزرگ استفاده می‌کند. در صورتی که '#' مشخص شده باشد، پیشوند '0x' نیز به '0X' تبدیل به حروف بزرگ می‌شود.

'n'

عدد. این همان 'd' است، با این تفاوت که از تنظیمات locale برای درج جداکننده‌های مناسب گروه ارقام استفاده می‌کند. توجه داشته باشید که locale پیش‌فرض، locale سیستم نیست. بسته به مورد استفاده خود، ممکن است بخواهید پیش از استفاده از 'n'، LC_NUMERIC را با locale.setlocale() تنظیم کنید.

None

همانند 'd'.

علاوه بر انواع نمایش بالا، می‌توان اعداد صحیح را با انواع نمایش ممیز شناور که در زیر فهرست شده‌اند نیز قالب‌بندی کرد (به‌جز 'n' و None). هنگام این کار، برای تبدیل عدد صحیح به عدد ممیز شناور پیش از قالب‌بندی از float() استفاده می‌شود.

انواع نمایش موجود برای مقادیر float و Decimal عبارتند از:

نوع

معنی

'e'

نماد علمی. برای دقت داده‌شده p، عدد را در نماد علمی با حرف 'e' که ضریب را از توان جدا می‌کند، قالب‌بندی می‌کند. ضریب یک رقم پیش از نقطه اعشار و p رقم پس از آن دارد، که در مجموع p + 1 رقم معنادار می‌شود. وقتی دقتی داده نشده باشد، از دقت 6 رقم پس از نقطه اعشار برای float استفاده می‌کند و تمام ارقام ضریب را برای Decimal نمایش می‌دهد. اگر p=0 باشد، نقطه اعشار حذف می‌شود مگر اینکه گزینه # استفاده شده باشد.

برای float، توان همیشه حداقل شامل دو رقم است و اگر مقدار صفر باشد، صفر خواهد بود.

'E'

نماد علمی. مانند 'e' است، با این تفاوت که از 'E' بزرگ به‌عنوان نویسه‌ی جداکننده استفاده می‌کند.

'f'

نماد نقطه‌ثابت. برای دقت داده‌شده p، عدد را به‌صورت یک عدد اعشاری با دقیقاً p رقم پس از نقطه اعشار قالب‌بندی می‌کند. اگر دقتی داده نشده باشد، برای float از دقت 6 رقم پس از نقطه اعشار استفاده می‌کند، و برای Decimal از دقتی به‌اندازه کافی زیاد برای نمایش تمام ارقام ضریب استفاده می‌کند. اگر p=0 باشد، نقطه اعشار حذف می‌شود، مگر اینکه از گزینه # استفاده شده باشد.

'F'

نماد نقطه‌ثابت. مانند 'f'، اما nan را به NAN و inf را به INF تبدیل می‌کند.

'g'

قالب عمومی. برای دقت داده‌شده p >= 1، عدد به p رقم بامعنا گرد می‌شود و سپس نتیجه بسته به بزرگی آن، در قالب ممیز ثابت یا نماد علمی قالب‌بندی می‌شود. دقت 0 معادل دقت 1 در نظر گرفته می‌شود.

قواعد دقیق به شرح زیر است: فرض کنید نتیجه‌ای که با نوع نمایش 'e' و دقت p-1 قالب‌بندی شده باشد، توان exp داشته باشد. سپس، اگر m <= exp < p باشد، که در آن m برای floatها برابر با -۴ و برای Decimals برابر با -۶ است، عدد با نوع نمایش 'f' و دقت p-1-exp قالب‌بندی می‌شود. در غیر این صورت، عدد با نوع نمایش 'e' و دقت p-1 قالب‌بندی می‌شود. در هر دو حالت، صفرهای انتهایی بی‌اهمیت از بخش معنادار (significand) حذف می‌شوند، و اگر هیچ رقمی پس از آن باقی نمانده باشد، نقطه‌ی اعشار نیز حذف می‌شود، مگر آنکه از گزینه‌ی '#' استفاده شده باشد.

در صورتی که دقتی مشخص نشده باشد، برای float از دقت 6 رقم معنادار استفاده می‌شود. برای Decimal، ضریب نتیجه از ارقام ضریب مقدار تشکیل می‌شود؛ برای مقادیری که از نظر قدر مطلق کوچک‌تر از 1e-6 هستند و برای مقادیری که ارزش مکانی کم‌اهمیت‌ترین رقم آن‌ها بزرگ‌تر از ۱ است، از نماد علمی استفاده می‌شود و در غیر این صورت از نماد نقطه‌ثابت استفاده می‌شود.

بی‌نهایت مثبت و منفی، صفر مثبت و منفی و مقادیر NaN، صرف‌نظر از دقت، به‌ترتیب به‌صورت inf، -inf، 0، -0 و nan قالب‌بندی می‌شوند.

'G'

قالب عمومی. همانند 'g' است، با این تفاوت که اگر عدد بیش از حد بزرگ شود، به 'E' تغییر می‌کند. نمایش بی‌نهایت و NaN نیز با حروف بزرگ است.

'n'

عدد. این همان 'g' است، با این تفاوت که از تنظیمات locale فعلی برای درج جداکننده‌های مناسب گروه‌بندی ارقام در بخش صحیح یک عدد استفاده می‌کند. توجه داشته باشید که تنظیمات locale پیش‌فرض، تنظیمات locale سیستم نیست. بسته به مورد استفاده شما، ممکن است بخواهید پیش از استفاده از 'n'، LC_NUMERIC را با locale.setlocale() تنظیم کنید.

'%'

درصد. عدد را در ۱۰۰ ضرب می‌کند و آن را در قالب ثابت ('f') نمایش می‌دهد و به دنبال آن علامت درصد قرار می‌گیرد.

None

برای float، این مانند نوع 'g' است، با این تفاوت که هنگامی که برای قالب‌بندی نتیجه از نماد نقطه‌ثابت استفاده می‌شود، همیشه حداقل یک رقم پس از نقطه اعشار را شامل می‌شود و هرگاه exp >= p - 1 باشد، به نماد علمی تغییر می‌کند. وقتی دقت مشخص نشده باشد، دقت به‌اندازه‌ای خواهد بود که برای نمایش وفادارانه‌ی مقدار داده‌شده لازم است.

برای Decimal، این معادل 'g' یا 'G' است، بسته به مقدار context.capitals در زمینه‌ی اعشاری جاری.

اثر کلی، مطابقت با خروجی str() است، همان‌گونه که توسط سایر اصلاح‌کننده‌های قالب تغییر یافته است.

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

انواع نمایش موجود برای complex همان انواع موجود برای float هستند ('%' مجاز نیست). هر دو بخش حقیقی و موهومی یک عدد مختلط، مطابق نوع نمایش مشخص‌شده، به‌صورت اعداد ممیز شناور قالب‌بندی می‌شوند. این دو با علامت اجباری بخش موهومی از هم جدا می‌شوند و این بخش با یک پسوند j پایان می‌یابد. اگر نوع نمایش وجود نداشته باشد، نتیجه با خروجی str() مطابقت خواهد داشت (اعداد مختلط با بخش حقیقی غیرصفر نیز در پرانتز قرار می‌گیرند)، که ممکن است توسط سایر اصلاح‌کننده‌های قالب تغییر کند.

نمونه‌های قالب‌بندی

این بخش شامل مثال‌هایی از سینتکس str.format() و مقایسه‌ای با قالب‌بندی قدیمی % است.

در بیشتر موارد، سینتکس شبیه به قالب‌بندی قدیمی % است، با اضافه شدن {} و استفاده از : به‌جای %. برای مثال، '%03.2f' را می‌توان به '{:03.2f}' تبدیل کرد.

سینتکس جدید قالب‌بندی همچنین از گزینه‌های جدید و متفاوتی پشتیبانی می‌کند که در مثال‌های زیر نشان داده شده‌اند.

دسترسی به آرگومان‌ها بر اساس جایگاه:

>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
'abracadabra'

دسترسی به آرگومان‌ها با نام:

>>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
'Coordinates: 37.24N, -115.81W'
>>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
>>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
'Coordinates: 37.24N, -115.81W'

دسترسی به ویژگی‌های آرگومان‌ها:

>>> c = 3-5j
>>> ('The complex number {0} is formed from the real part {0.real} '
...  'and the imaginary part {0.imag}.').format(c)
'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
>>> class Point:
...     def __init__(self, x, y):
...         self.x, self.y = x, y
...     def __str__(self):
...         return 'Point({self.x}, {self.y})'.format(self=self)
...
>>> str(Point(4, 2))
'Point(4, 2)'

دسترسی به آیتم‌های آرگومان‌ها:

>>> coord = (3, 5)
>>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
'X: 3;  Y: 5'

جایگزینی %s و %r:

>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"

تراز کردن متن و تعیین عرض:

>>> '{:<30}'.format('left aligned')
'left aligned                  '
>>> '{:>30}'.format('right aligned')
'                 right aligned'
>>> '{:^30}'.format('centered')
'           centered           '
>>> '{:*^30}'.format('centered')  # use '*' as a fill char
'***********centered***********'

جایگزینی %+f، %-f و % f و تعیین علامت:

>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
'3.140000; -3.140000'

جایگزینی %x و %o و تبدیل مقدار به مبناهای مختلف:

>>> # format also supports binary numbers
>>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
>>> # with 0x, 0o, or 0b as prefix:
>>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

استفاده از ویرگول یا زیرخط به‌عنوان جداکننده گروه ارقام:

>>> '{:,}'.format(1234567890)
'1,234,567,890'
>>> '{:_}'.format(1234567890)
'1_234_567_890'
>>> '{:_b}'.format(1234567890)
'100_1001_1001_0110_0000_0010_1101_0010'
>>> '{:_x}'.format(1234567890)
'4996_02d2'
>>> '{:_}'.format(123456789.123456789)
'123_456_789.12345679'
>>> '{:.,}'.format(123456789.123456789)
'123456789.123,456,79'
>>> '{:,._}'.format(123456789.123456789)
'123,456,789.123_456_79'

بیان یک درصد:

>>> points = 19
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 86.36%'

استفاده از قالب‌بندی مختص نوع:

>>> import datetime as dt
>>> d = dt.datetime(2010, 7, 4, 12, 15, 58)
>>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
'2010-07-04 12:15:58'

آرگومان‌های تودرتو و نمونه‌های پیچیده‌تر:

>>> for align, text in zip('<^>', ['left', 'center', 'right']):
...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
...
'left<<<<<<<<<<<<'
'^^^^^center^^^^^'
'>>>>>>>>>>>right'
>>>
>>> octets = [192, 168, 0, 1]
>>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
'C0A80001'
>>> int(_, 16)
3232235521
>>>
>>> width = 5
>>> for num in range(5,12):
...     for base in 'dXob':
...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
...     print()
...
    5     5     5   101
    6     6     6   110
    7     7     7   111
    8     8    10  1000
    9     9    11  1001
   10     A    12  1010
   11     B    13  1011

رشته‌های قالب ($-strings)

توجه

این قابلیت که در اینجا توضیح داده شده است، در پایتون 2.4 معرفی شد؛ یک روش قالب‌بندی ساده مبتنی بر عبارت‌های باقاعده. این قابلیت پیش از str.format()، formatted string literals و template string literals وجود داشته است.

این مورد به مقادیر لفظی رشته قالبی (t-strings)، که در پایتون 3.14 معرفی شده‌اند، مربوط نمی‌شود. حاصل ارزیابی این موارد، اشیای string.templatelib.Template است که در ماژول string.templatelib قرار دارند.

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

رشته‌های قالب از جایگزینی‌های مبتنی بر $ با استفاده از قوانین زیر پشتیبانی می‌کنند:

  • $$ یک خنثی‌سازی است؛ با یک $ جایگزین می‌شود.

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

  • ${identifier} معادل $identifier است. هنگامی که نویسه‌های معتبر شناسه پس از جای‌نگهدار بیایند اما بخشی از آن نباشند، استفاده از این قالب الزامی است، مانند "${noun}ification".

هر ظهور دیگر $ در رشته، منجر به پرتاب ValueError خواهد شد.

ماژول string یک کلاس Template ارائه می‌دهد که این قوانین را پیاده‌سازی می‌کند. متدهای Template عبارتند از:

class string.Template(template)

سازنده یک آرگومان دریافت می‌کند که رشته‌ی الگو است.

substitute(mapping={}, /, **kwds)

جایگذاری قالب را انجام می‌دهد و یک رشته جدید برمی‌گرداند. mapping هر شیء دیکشنری‌مانندی است که کلیدهای آن با جای‌نگهدارهای قالب مطابقت دارند. به‌عنوان جایگزین، می‌توانید آرگومان‌های کلیدواژه‌ای ارائه دهید، که در آن‌ها کلیدواژه‌ها همان جای‌نگهدارها هستند. وقتی هر دو mapping و kwds داده شده باشند و جای‌نگهدارهای تکراری وجود داشته باشد، جای‌نگهدارهای kwds اولویت دارند.

safe_substitute(mapping={}, /, **kwds)

مانند substitute()، با این تفاوت که اگر جای‌نگهدارها در mapping و kwds موجود نباشند، به‌جای پرتاب یک استثنای KeyError، جای‌نگهدار اصلی به‌صورت دست‌نخورده در رشته‌ی حاصل ظاهر خواهد شد. همچنین، برخلاف substitute()، هر ظهور دیگرِ $ صرفاً $ را برمی‌گرداند، به‌جای پرتاب ValueError.

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

is_valid()

اگر قالب دارای جای‌نگهدارنده‌های نامعتبری باشد که باعث شود substitute() یک ValueError پرتاب کند، False را برمی‌گرداند.

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

get_identifiers()

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

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

نمونه‌های Template همچنین یک ویژگی داده‌ای عمومی ارائه می‌دهند:

template

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

در اینجا مثالی از چگونگی استفاده از یک Template آورده شده است:

>>> from string import Template
>>> s = Template('$who likes $what')
>>> s.substitute(who='tim', what='kung pao')
'tim likes kung pao'
>>> d = dict(who='tim')
>>> Template('Give $who $100').substitute(d)
Traceback (most recent call last):
...
ValueError: Invalid placeholder in string: line 1, col 11
>>> Template('$who likes $what').substitute(d)
Traceback (most recent call last):
...
KeyError: 'what'
>>> Template('$who likes $what').safe_substitute(d)
'tim likes $what'

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

  • delimiter -- این رشته‌ی لفظی، جداکننده‌ی معرف جای‌نگهدار را توصیف می‌کند. مقدار پیش‌فرض $ است. توجه داشته باشید که این نباید یک عبارت باقاعده باشد، زیرا پیاده‌سازی در صورت نیاز re.escape() را روی این رشته فراخوانی می‌کند. همچنین توجه داشته باشید که نمی‌توانید جداکننده را پس از ایجاد کلاس تغییر دهید (یعنی یک جداکننده‌ی متفاوت باید در فضای نام کلاسِ زیرکلاس تنظیم شود).

  • idpattern -- این عبارت باقاعدهی است که الگوی جای‌نگهدارهای بدون آکولاد را توصیف می‌کند. مقدار پیش‌فرض، عبارت باقاعده (?a:[_a-z][_a-z0-9]*) است. اگر این مقدار داده شده باشد و braceidpattern برابر None باشد، این الگو برای جای‌نگهدارهای دارای آکولاد نیز اعمال خواهد شد.

    توجه

    از آن‌جا که flags پیش‌فرض re.IGNORECASE است، الگوی [a-z] می‌تواند با برخی نویسه‌های غیر ASCII تطابق داشته باشد. به همین دلیل، ما در اینجا از پرچم محلی a استفاده می‌کنیم.

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

  • braceidpattern — این مانند idpattern است، اما الگوی جای‌نگهدارهای دارای آکولاد را توصیف می‌کند. پیش‌فرض آن None است که به معنای بازگشت به idpattern است (یعنی هم داخل آکولادها و هم خارج از آن‌ها از یک الگو استفاده می‌شود). اگر داده شود، این به شما امکان می‌دهد الگوهای متفاوتی برای جای‌نگهدارهای دارای آکولاد و بدون آکولاد تعریف کنید.

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

  • flags -- پرچم‌های عبارت باقاعده که هنگام کامپایل عبارت باقاعده‌ی مورد استفاده برای تشخیص جایگزینی‌ها اعمال خواهند شد. مقدار پیش‌فرض re.IGNORECASE است. توجه داشته باشید که re.VERBOSE همواره به پرچم‌ها اضافه خواهد شد، بنابراین idpatterns سفارشی باید از قراردادهای عبارت‌های باقاعده پرجزئیات (verbose) پیروی کنند.

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

به‌عنوان جایگزین، می‌توانید کل الگوی عبارت باقاعده را با بازنویسی ویژگی کلاس pattern فراهم کنید. اگر این کار را انجام دهید، مقدار باید یک رشته‌ی الگوی عبارت باقاعده یا یک شیء عبارت باقاعده‌ی کامپایل‌شده، با چهار گروه ثبت‌کننده نام‌دار باشد. گروه‌های ثبت‌کننده با قوانین بیان‌شده در بالا، به‌همراه قانون جای‌نگهدار نامعتبر، مطابقت دارند:

  • escaped -- این گروه با دنباله خنثی‌سازی، برای مثال $$، در الگوی پیش‌فرض مطابقت دارد.

  • named -- این گروه با نام جای‌نگهدار بدون آکولاد مطابقت دارد؛ نباید جداکننده را در گروه ثبت‌کننده بگنجاند.

  • braced -- این گروه با نام جای‌نگهدار محصور در آکولاد مطابقت دارد؛ نباید در گروه ثبت‌کننده (capturing group) شامل جداکننده یا آکولادها باشد.

  • invalid -- این گروه با هر الگوی جداکننده دیگری (معمولاً یک جداکننده) مطابقت دارد و باید در انتهای عبارت باقاعده قرار گیرد.

متدهای این کلاس در صورتی استثنای ValueError را پرتاب می‌کنند که الگو با قالب تطبیق داشته باشد، بدون این‌که یکی از این گروه‌های نام‌دار تطبیق یافته باشد.

توابع کمکی

string.capwords(s, sep=None)

آرگومان را با استفاده از str.split() به کلمات تقسیم کنید، هر کلمه را با استفاده از str.capitalize() حرف اول بزرگ کنید، و کلمات با حرف اول بزرگ را با استفاده از str.join() به‌هم بپیوندید. اگر آرگومان دوم اختیاری sep وجود نداشته باشد یا None باشد، دنباله‌هایی از نویسه‌های فضای خالی با یک فاصله جایگزین می‌شوند و فضاهای خالی ابتدا و انتها حذف می‌شوند، در غیر این صورت از sep برای تقسیم و به‌هم پیوستن کلمات استفاده می‌شود.