ماژول textwrap یکی از کتابخانههای استاندارد و بسیار کاربردی پایتون است که برای قالببندی متون، شکستن خطوط طولانی به پاراگرافهای منظم، و مدیریت تورفتگیها (Indentation) استفاده میشود. این ابزار به ویژه در ساخت ابزارهای خط فرمان (CLI)، تولید گزارشهای متنی و تمیز کردن ورودیهای کاربر کاربرد دارد.
سطح مقدماتی (Beginner Level)
در این سطح با توابع اصلی ماژول textwrap آشنا میشویم که برای کارهای روزمره و ساده طراحی شدهاند. هدف اصلی در اینجا یادگیری نحوه نمایش مرتب متنها در عرض (Width) مشخص است.
۱. شکستن متن با wrap و fill
دو تابع اصلی این ماژول wrap() و fill() هستند.
wrap(text, width): متن را به قطعاتی با طول مشخص میشکند و یک لیست از رشتهها برمیگرداند.fill(text, width): دقیقاً همان کار را میکند، اما خروجی را به صورت یک رشته واحد که با\nجدا شده است برمیگرداند.
مثال ۱: استفاده از wrap (خروجی لیست)
در این مثال میبینیم که چگونه یک متن طولانی به لیستی از خطوط کوتاهتر تبدیل میشود.
مثال ۲: استفاده از fill (خروجی متنی)
معمولاً برای چاپ در ترمینال از fill استفاده میکنیم چون مستقیماً قابل چاپ است.
مثال ۳: ساختار کلی (بدون اجرا)
اگر بخواهیم فقط منطق را نشان دهیم، ساختار به این صورت است:
import textwrap
def format_for_ui(text):
# این تابع فقط یک تکه کد است و فراخوانی نمیشود
return textwrap.fill(text, width=50)۲. حذف تورفتگیهای زائد با dedent
وقتی در پایتون یک متن چندخطی (Triple-quoted string) را داخل یک تابع یا کلاس مینویسید، فاصلههای سمت راست کد (Indentation) نیز جزوی از رشته میشوند. تابع dedent() این فاصلههای مشترک اولیه را حذف میکند تا متن به سمت راست بچسبد.
مثال ۱: مشکل تورفتگی (بدون اجرا)
در کد زیر، متن دارای فاصلههایی است که شاید نخواهیم در خروجی نهایی باشند:
def get_sql_query():
# این فاصله سمت راست در رشته نهایی وجود خواهد داشت
query = """
SELECT *
FROM users
WHERE active = 1
"""
return queryمثال ۲: حل مشکل با dedent (اجرایی)
این کد نشان میدهد چگونه dedent فضاهای خالی سمت چپ را پاکسازی میکند.
سطح پیشرفته (Professional Level)
در سطح حرفهای، ما نیاز به کنترل دقیقتری روی نحوه شکستن خطوط، مدیریت کلمات خیلی طولانی، و اضافه کردن پیشوندها (Prefix) به پاراگرافها داریم. همچنین با کلاس TextWrapper برای بهینهسازی پرفورمنس کار خواهیم کرد.
۱. مدیریت پیشوندها با indent
تابع indent() به ابتدای تمام خطوط یک متن، یک رشته خاص (مثل > یا \t) اضافه میکند. این قابلیت برای نقلقول کردن (Quoting) در ایمیلها یا لاگها بسیار مفید است.
مثال ۱: نقلقول کردن یک پیام
مثال ۲: استفاده از predicate برای فیلتر خطوط
شما میتوانید با آرگومان predicate تعیین کنید کدام خطوط تورفتگی بگیرند.
۲. خلاصهسازی متن با shorten
تابع shorten() برای کوتاه کردن متن به یک اندازه مشخص و اضافه کردن [...] (placeholder) در انتهای آن استفاده میشود. این تابع هوشمند است و کلمات را نصفه نمیبرد، مگر اینکه مجبور شود.
مثال ۱: ساخت پیشنمایش خبر
۳. کلاس TextWrapper (برای کارایی بالا)
اگر قرار است یک تنظیم خاص را روی صدها رشته مختلف اعمال کنید، استفاده مداوم از توابع wrap یا fill بهینه نیست، زیرا هر بار یک شیء جدید میسازند. در عوض، یک نمونه از کلاس TextWrapper بسازید و بارها از آن استفاده کنید.
ویژگیهای مهم TextWrapper:
initial_indent: تورفتگی فقط برای خط اول.subsequent_indent: تورفتگی برای تمام خطوط به جز خط اول.fix_sentence_endings: تلاش برای اصلاح فاصلهگذاری پایان جملات (بیشتر برای انگلیسی).
مثال ۱: تنظیمات پیشرفته پاراگراف
مثال ۲: مدیریت کلمات طولانی
به صورت پیشفرض، اگر کلمهای از width بزرگتر باشد، textwrap آن را میشکند. با break_long_words=False میتوان از این کار جلوگیری کرد (گرچه ممکن است از کادر بیرون بزند).
۴. نکات فنی و Edge Caseها
هنگام کار با متون فارسی و ترکیب آن با انگلیسی، ممکن است جهت متن (RTL/LTR) در ترمینال بهم بریزد. textwrap ذاتا بر اساس تعداد کاراکتر کار میکند و نه پیکسل نمایشی.
# نکته فنی (Static Code)
# textwrap با کاراکترهای یونیکد عریض (Wide characters) مثل ایموجیها
# گاهی اوقات در محاسبه عرض دچار خطا میشود.
import textwrap
def handle_unicode_text(text):
# برای زبانهای آسیایی یا دارای ایموجی،
# ممکن است نیاز به کتابخانههای جانبی مثل wcwidth باشد
pass