textwrap --- پیچیدن و پر کردن متن

کد منبع: Lib/textwrap.py

---

ماژول textwrap چند تابع سهولت‌بخش و همچنین TextWrapper، کلاسی که تمام کارها را انجام می‌دهد، فراهم می‌کند. اگر فقط در حال پیچیدن (wrapping) یا پر کردن (filling) یک یا دو رشته متنی هستید، توابع سهولت‌بخش باید کافی باشند؛ در غیر این صورت، برای کارایی باید از نمونه‌ای از TextWrapper استفاده کنید.

textwrap.wrap(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

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

آرگومان‌های کلیدواژه‌ای اختیاری متناظر با ویژگی‌های نمونه‌ی TextWrapper هستند که در زیر مستند شده‌اند.

برای جزئیات بیشتر درباره چگونگی رفتار wrap()، متد TextWrapper.wrap() را ببینید.

textwrap.fill(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

بند واحد موجود در text را سطربندی می‌کند و یک رشته واحد شامل بند سطربندی‌شده را برمی‌گرداند. fill() میان‌بری برای

"\n".join(wrap(text, ...))

به‌ویژه، fill() دقیقاً همان آرگومان‌های کلیدواژه‌ای wrap() را می‌پذیرد.

textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

متن text داده‌شده را فشرده و کوتاه کنید تا در عرض width داده‌شده جای گیرد.

ابتدا فضای سفید در text فشرده می‌شود (تمام فضای سفید با فاصله‌های تکی جایگزین می‌شود). اگر نتیجه در width بگنجد، برگردانده می‌شود. در غیر این صورت، تعداد کافی از واژه‌ها از انتها حذف می‌شوند تا واژه‌های باقی‌مانده به‌همراه placeholder در width بگنجند:

>>> textwrap.shorten("Hello  world!", width=12)
'Hello world!'
>>> textwrap.shorten("Hello  world!", width=11)
'Hello [...]'
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'

آرگومان‌های کلیدواژه‌ای اختیاری متناظر با ویژگی‌های نمونه‌ی TextWrapper هستند که در ادامه مستند شده‌اند. توجه داشته باشید که فضاهای خالی پیش از آنکه متن به تابع fill() کلاس TextWrapper ارسال شود، فشرده می‌شوند؛ بنابراین تغییر مقدار tabsize، expand_tabs، drop_whitespace و replace_whitespace اثری نخواهد داشت.

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

textwrap.dedent(text)

هرگونه فضای سفید مشترک را از ابتدای هر سطر در text حذف می‌کند.

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

توجه داشته باشید که تب‌ها و فاصله‌ها هر دو به‌عنوان فضای سفید در نظر گرفته می‌شوند، اما برابر نیستند: سطرهای "  hello" و "\thello" به‌عنوان سطرهایی در نظر گرفته می‌شوند که هیچ فضای سفید پیشرو مشترکی ندارند.

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

برای مثال:

def test():
    # end first line with \ to avoid the empty line!
    s = '''\
    hello
      world
    '''
    print(repr(s))          # prints '    hello\n      world\n    '
    print(repr(dedent(s)))  # prints 'hello\n  world\n'

تغییر یافته در نسخه‌ی 3.14: تابع dedent() اکنون سطرهای خالی را که فقط حاوی نویسه‌های فضای خالی هستند، به‌درستی عادی‌سازی می‌کند. پیش‌تر، پیاده‌سازی فقط سطرهای خالی حاوی تب‌ها و فاصله‌ها را عادی‌سازی می‌کرد.

textwrap.indent(text, prefix, predicate=None)

prefix را به ابتدای سطرهای انتخاب‌شده در text اضافه کنید.

سطرها با فراخوانی text.splitlines(True) جدا می‌شوند.

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

برای مثال:

>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'

آرگومان اختیاری predicate می‌تواند برای کنترل اینکه کدام سطرهای تورفتگی داده شوند استفاده شود. برای مثال، افزودن prefix حتی به سطرهای خالی و سطرهای فقط دارای فضای سفید آسان است:

>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world

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

wrap()، fill() و shorten() با ایجاد یک نمونه TextWrapper و فراخوانی یک متد واحد بر روی آن کار می‌کنند. این نمونه دوباره استفاده نمی‌شود، بنابراین برای برنامه‌هایی که رشته‌های متنی بسیاری را با استفاده از wrap() و/یا fill() پردازش می‌کنند، ممکن است کارآمدتر باشد که شیء TextWrapper خود را ایجاد کنید.

متن ترجیحاً در فضاهای خالی و درست پس از خط‌تیره‌ها در کلمات خط‌تیره‌دار شکسته می‌شود؛ تنها در این صورت است که کلمات طولانی در صورت لزوم شکسته خواهند شد، مگر اینکه TextWrapper.break_long_words روی false تنظیم شده باشد.

class textwrap.TextWrapper(**kwargs)

سازنده‌ی TextWrapper تعدادی آرگومان کلیدواژه‌ای اختیاری می‌پذیرد. هر آرگومان کلیدواژه‌ای با یک ویژگی نمونه متناظر است، بنابراین برای مثال

wrapper = TextWrapper(initial_indent="* ")

معادل است با

wrapper = TextWrapper()
wrapper.initial_indent = "* "

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

ویژگی‌های نمونه‌ی TextWrapper (و آرگومان‌های کلیدواژه‌ای سازنده) به شرح زیر است:

width

(پیش‌فرض: 70) حداکثر طول سطرهای شکسته‌شده. تا زمانی که در متن ورودی هیچ کلمه‌ی منفردی طولانی‌تر از width وجود نداشته باشد، TextWrapper تضمین می‌کند که هیچ سطر خروجی‌ای طولانی‌تر از width نویسه نخواهد بود.

expand_tabs

(پیش‌فرض: True) اگر درست باشد، همه‌ی نویسه‌های تب در text با استفاده از متد expandtabs() از text به فاصله تبدیل می‌شوند.

tabsize

(پیش‌فرض: 8) اگر expand_tabs درست باشد، تمام نویسه‌های Tab در text بسته به ستون جاری و اندازه‌ی Tab داده‌شده، به صفر یا چند فاصله تبدیل می‌شوند.

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

replace_whitespace

(پیش‌فرض: True) اگر True باشد، پس از بسط تب اما پیش از پوشش دادن، متد wrap() هر نویسه فضای خالی را با یک فاصله جایگزین می‌کند. نویسه‌های فضای خالی که جایگزین می‌شوند عبارت‌اند از: تب، خط جدید، تب عمودی، تغذیه‌ی صفحه و بازگشت به ابتدای سطر ('\t\n\v\f\r').

توجه

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

توجه

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

drop_whitespace

(پیش‌فرض: True) اگر درست باشد، فضای سفید در ابتدا و انتهای هر سطر (پس از سطربندی اما پیش از تورفتگی) حذف می‌شود. با این حال، فضای سفید در ابتدای پاراگراف حذف نمی‌شود، اگر به دنبال آن نویسه‌ای غیر از فضای سفید بیاید. اگر فضای سفیدی که حذف می‌شود یک خط کامل را تشکیل دهد، کل خط حذف می‌شود.

initial_indent

(پیش‌فرض: '') رشته‌ای که به ابتدای اولین خط از خروجی شکسته‌شده اضافه می‌شود. در طول اولین خط لحاظ می‌شود. رشته خالی تورفتگی ایجاد نمی‌کند.

subsequent_indent

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

fix_sentence_endings

(پیش‌فرض: False) اگر درست باشد، TextWrapper تلاش می‌کند پایان جملات را تشخیص دهد و تضمین کند که جملات همیشه با دقیقاً دو فاصله از هم جدا شوند. این حالت معمولاً برای متن با قلم تک‌فاصله مطلوب است. با این حال، الگوریتم تشخیص جمله کامل نیست: فرض می‌کند که پایان یک جمله از یک حرف کوچک تشکیل شده است که پس از آن یکی از '.'، '!' یا '?' می‌آید، ممکن است پس از آن یکی از '"' یا "'" و سپس یک فاصله بیاید. یکی از مشکلات این الگوریتم ناتوانی آن در تشخیص تفاوت بین «Dr.» در

[...] Dr. Frankenstein's monster [...]

و "Spot." در

[...] See Spot. See Spot run [...]

fix_sentence_endings به‌طور پیش‌فرض نادرست است.

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

break_long_words

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

break_on_hyphens

(پیش‌فرض: True) اگر True باشد، شکستن سطرهای ترجیحاً در فضاهای خالی و بلافاصله پس از خط‌تیره‌ها در کلمات مرکب انجام می‌شود، همان‌گونه که در انگلیسی مرسوم است. اگر False باشد، فقط فضاهای خالی به‌عنوان مکان‌های مناسب بالقوه برای شکست خط در نظر گرفته می‌شوند، اما اگر کلماتی واقعاً غیرقابل شکستن می‌خواهید، باید break_long_words را روی False تنظیم کنید. رفتار پیش‌فرض در نسخه‌های پیشین این بود که همیشه اجازه شکستن کلمات خط‌تیره‌دار داده شود.

max_lines

(پیش‌فرض: None) اگر None نباشد، خروجی شامل حداکثر max_lines خط خواهد بود و placeholder در انتهای خروجی ظاهر می‌شود.

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

placeholder

(پیش‌فرض: ' [...]') رشته‌ای که اگر متن خروجی بریده شده باشد، در انتهای آن ظاهر می‌شود.

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

TextWrapper همچنین برخی متدهای عمومی را نیز ارائه می‌دهد، مشابه توابع کمکی سطح ماژول:

wrap(text)

بند واحد موجود در text (یک رشته) را می‌پیچد تا طول هر خط حداکثر width نویسه باشد. تمام گزینه‌های پیچیدن از ویژگی‌های نمونه‌ی TextWrapper گرفته می‌شوند. فهرستی از سطرهای خروجی را برمی‌گرداند، بدون نویسه‌های خط جدید پایانی. اگر خروجی حاصل از پیچیدن محتوایی نداشته باشد، فهرست برگردانده‌شده خالی است.

fill(text)

پاراگراف واحد موجود در text را می‌پیچد و یک رشته واحد شامل پاراگراف پیچیده‌شده را برمی‌گرداند.