معرفی کتابخانه colorama در پایتون

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

نصب

برای نصب از pip استفاده کنید:

pip install colorama

پس از نصب می‌توانید در اسکریپت خود کتابخانه را import کرده و از آن استفاده کنید.

مبانی و API

رایج‌ترین اجزای colorama عبارت‌اند از:

• init(): مقداردهی اولیه که روی ویندوز ترجمهٔ ANSI به فراخوانی‌های API ویندوز را فعال می‌کند.
• Fore: رنگ متن (مثل Fore.RED).
• Back: رنگ پس‌زمینه (مثل Back.GREEN).
• Style: سبک‌های پایه مثل BRIGHT و RESET_ALL.
• deinit(): بازگرداندن حالت قبل و حذف ترجمهٔ ANSI.
• AnsiToWin32: برای پوشش دستی stream ها کاربرد دارد (مثلاً هنگام کار با logging یا subprocess).

جدول کلیدواژه‌های رنگی

مثال‌های عملی

مثال ساده: چاپ متن رنگی

from colorama import init, Fore, Back, Style

init()  # روی ویندوز لازم است

print(Fore.RED + "این متن قرمز است" + Style.RESET_ALL)
print(Back.YELLOW + Fore.BLUE + "متن آبی روی پس‌زمینه زرد" + Style.RESET_ALL)

در این کد ابتدا init() فراخوانی می‌شود تا در ویندوز ترجمهٔ کدهای ANSI انجام شود. سپس از Fore و Back برای تعیین رنگ متن و پس‌زمینه استفاده شده و در انتها با Style.RESET_ALL وضعیت رنگی به حالت پیش‌فرض بازگردانده می‌شود. اگر RESET_ALL فراموش شود، رنگ بر روی خروجی‌های بعدی هم اعمال خواهد شد و ممکن است ظاهر نامطلوبی ایجاد شود.

استفاده از autoreset

from colorama import init, Fore

init(autoreset=True)

print(Fore.GREEN + "پیام موفقیت‌آمیز")  # پس از چاپ، رنگ به صورت خودکار بازنشانی می‌شود
print("این متن بدون رنگ است")

پارامتر autoreset=True باعث می‌شود پس از هر پرینت، رنگ‌ها به صورت خودکار ریست شوند. این روش برای جلوگیری از فراموشی RESET_ALL مفید است، اما در صورت چاپ رشته‌های چندبخشی یا استفادهٔ مکرر ممکن است کارایی کمی متفاوت باشد.

یکپارچه‌سازی با logging

import logging
import sys
from colorama import init, Fore, Style, AnsiToWin32

init()

class ColoredFormatter(logging.Formatter):
    LEVEL_COLOR = {
        logging.DEBUG: Fore.CYAN,
        logging.INFO: Fore.GREEN,
        logging.WARNING: Fore.YELLOW,
        logging.ERROR: Fore.RED,
        logging.CRITICAL: Fore.RED + Style.BRIGHT
    }
    def format(self, record):
        color = self.LEVEL_COLOR.get(record.levelno, '')
        msg = super().format(record)
        return color + msg + Style.RESET_ALL

handler = logging.StreamHandler(AnsiToWin32(sys.stderr).stream)
handler.setFormatter(ColoredFormatter('%(levelname)s: %(message)s'))
logger = logging.getLogger('myapp')
logger.setLevel(logging.DEBUG)
logger.addHandler(handler)

logger.info('اطلاعات')
logger.error('خطا رخ داد')

در این مثال یک Formatter سفارشی ساخته شده که بسته به سطح لاگ، رنگ مناسب را قرار می‌دهد. توجه کنید که برای سازگاری با ویندوز از AnsiToWin32 استفاده شده و StreamHandler به شیء stream حاصل وصل شده است. این روش تضمین می‌کند لاگ‌های رنگی حتی در ویندوز نیز نمایش صحیحی داشته باشند.

نکات پیشرفته و بهترین شیوه‌ها

• روی یونیکس/مک نیازی به init نیست، اما فراخوانی آن بی‌خطر است و کارپذیری را تضمین می‌کند.
• colorama بیشتر برای رنگ‌های پایه (8 رنگ و نسخهٔ روشن) طراحی شده و از truecolor (24-bit) پشتیبانی کامل ندارد؛ برای رنگ‌های پیچیده‌تر از کتابخانه‌هایی مثل rich یا blessed استفاده کنید.
• برای لاگینگ و برنامه‌هایی که روی فایل یا pipe هدایت می‌شوند، قبل از اعمال رنگ بررسی کنید که stream واقعاً ترمینال است (با sys.stdout.isatty()) تا از ارسال کدهای ANSI به فایل‌های لاگ جلوگیری شود.
• در اسکریپت‌های طولانی، از autoreset یا بازنشانی صریح (Style.RESET_ALL) برای جلوگیری از نشت رنگ استفاده کنید.
• در هنگام استفاده با ابزارهایی مثل tqdm یا subprocess ممکن است نیاز به wrap کردن stream با AnsiToWin32 داشته باشید.

موارد کاربرد

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

محدودیت‌ها و نکات تکمیلی

colorama بیشتر تمرکز روی سادگی و سازگاری میان پلتفرم‌ها دارد؛ بنابراین اگر نیاز به جلوه‌های پیچیده، انیمیشن ترمینال یا پشتیبانی کامل از رنگ‌های 24 بیتی دارید، بهتر است از کتابخانه‌های پیشرفته‌تر استفاده کنید. همچنین در محیط‌های IDE که ترمینال آن‌ها کدهای ANSI را پشتیبانی نمی‌کند، رنگ‌ها ممکن است به صورت رشتهٔ خام نمایش داده شوند.

در نهایت، colorama برای بسیاری از پروژه‌های CLI کوچک و متوسط یک راه‌حل سریع، سبک و مؤثر است. با درک محدودیت‌ها و استفادهٔ مناسب از init، autoreset و AnsiToWin32 می‌توانید خروجی‌های واضح و حرفه‌ای تولید کنید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال