آموزش پایتون - هشدارها

در پایتون، یک هشدار (warning) پیامی است که نشان می‌دهد در طول اجرای کد شما اتفاقی غیرمنتظره رخ داده است. برخلاف خطا (error)، هشدار مانع از اجرای برنامه نمی‌شود. هشدارها برای آگاه‌سازی کاربر درباره مشکلات احتمالی یا قابلیت‌های منسوخ‌شده (deprecated) در کد استفاده می‌شوند.

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

نمایش پیام هشدار

برای نمایش پیام هشدار در پایتون، می‌توانید از تابع ()warn از ماژول warnings استفاده کنید. در ادامه یک مثال آورده شده است −

import warnings

# Normal message
print("TutorialsPoint")

# Warning message
warnings.warn("You got a warning!")

خروجی کد بالا به صورت زیر خواهد بود:

TutorialsPoint

Warnings/Errors:
/home/cg/root/d732ac89/main.py:7: UserWarning: You got a warning!
  warnings.warn("You got a warning!")

انواع کلاس‌های هشدار

هشدارها در پایتون توسط مجموعه‌ای از کلاس‌ها بر اساس مکانیسم مدیریت استثناها (exception handling) مدیریت می‌شوند. رایج‌ترین انواع هشدارها عبارتند از −

۱. کلاس UserWarning

کلاس UserWarning کلاس هشدار پیش‌فرض در پایتون است. اگر هشداری داشته باشید که در هیچ‌یک از دسته‌بندی‌های دیگر قرار نگیرد، به عنوان UserWarning دسته‌بندی می‌شود. برای مشخص کردن UserWarning، از UserWarning به عنوان آرگومان دوم تابع ()warn استفاده کنید. در ادامه یک مثال آورده شده است −

import warnings

# Warning message
warnings.warn("You got a warning!", UserWarning)

۲. کلاس DeprecationWarning

کلاس DeprecationWarning برای نشان دادن این استفاده می‌شود که یک قابلیت یا ماژول منسوخ شده است و در نسخه‌های آینده پایتون حذف خواهد شد. برای مشخص کردن DeprecationWarning، از DeprecationWarning به عنوان آرگومان دوم تابع ()warn استفاده کنید. در ادامه یک مثال آورده شده است −

import warnings

# Warning message
warnings.warn("This feature is deprecated!", DeprecationWarning)

۳. کلاس SyntaxWarning

کلاس SyntaxWarning برای نشان دادن وجود یک مشکل مربوط به سنتکس (نحو) در کد استفاده می‌شود، اما شدت آن به اندازه‌ای نیست که باعث بروز SyntaxError شود. برای مشخص کردن SyntaxWarning، از SyntaxWarning به عنوان آرگومان دوم تابع ()warn استفاده کنید. در ادامه یک مثال آورده شده است −

import warnings

# Warning message
warnings.warn("This is a syntax warning!", SyntaxWarning)

# Function with potential syntax issue
def func(x):
    return x is 10  # using "is" instead of "=="

۴. کلاس RuntimeWarning

کلاس RuntimeWarning یک کلاس پایه است که برای نشان دادن وجود یک مسئله مشکوک مرتبط با زمان اجرا (runtime) استفاده می‌شود. برای مشخص کردن RuntimeWarning، از RuntimeWarning به عنوان آرگومان دوم تابع ()warn استفاده کنید. در ادامه یک مثال آورده شده است −

import warnings

# Warning message
warnings.warn("This is a runtime warning!", RuntimeWarning)

۵. کلاس ImportWarning

کلاس ImportWarning برای نشان دادن وجود مشکلی مرتبط با وارد کردن (import) یک ماژول استفاده می‌شود. برای مشخص کردن ImportWarning، از ImportWarning به عنوان آرگومان دوم تابع ()warn استفاده کنید. در ادامه یک مثال آورده شده است −

import warnings

# Warning message
warnings.warn("This is an import warning!", ImportWarning)

فیلترهای هشدار

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

تابع ()filterwarnings از ماژول warnings می‌تواند برای مشخص کردن فیلترهای هشدار استفاده شود. این تابع می‌تواند پارامترهای زیر را بپذیرد:

• default − این رفتار پیش‌فرض است. اولین رخ‌داد هر هشدار را برای هر مکانی که هشدار صادر می‌شود نمایش می‌دهد.
• always − این گزینه همیشه پیام هشدار را نمایش می‌دهد، حتی اگر قبلاً نمایش داده شده باشد.
• ignore − این گزینه برای جلوگیری از نمایش پیام‌های هشدار استفاده می‌شود.
• error − این گزینه هشدار را به یک استثنا (exception) تبدیل می‌کند که اجرای برنامه را متوقف خواهد کرد.
• module − این گزینه اولین رخ‌داد هشدارهای منطبق را برای هر ماژولی که هشدار در آن صادر می‌شود چاپ می‌کند.
• once − این گزینه اولین رخ‌داد هشدارهای منطبق را صرف‌نظر از مکان آن چاپ می‌کند.

مثال: تبدیل هشدار به خطا

در ادامه یک کد ساده پایتون آورده شده است که نحوه تبدیل هشدارها به خطا را نشان می‌دهد −

import warnings

# Turn warning into an error
warnings.filterwarnings("error", category=UserWarning)
try:
    warnings.warn("This is a warning!", UserWarning)
except UserWarning as e:
    print("Caught as error:", e)

خروجی کد بالا به صورت زیر خواهد بود −

Caught as error: This is a warning!

مثال: نادیده گرفتن هشدارها

در ادامه یک کد ساده پایتون آورده شده است که نحوه نادیده گرفتن هشدارها را نشان می‌دهد −

import warnings

# Ignore all warnings
warnings.filterwarnings("ignore")

print("Warning message: ")
warnings.warn("This warning will be ignored!")

خروجی کد بالا به صورت زیر خواهد بود:

Warning message: 

توابع موجود در ماژول Warning

ماژول warnings دارای چند تابع است که می‌توانید از آن‌ها برای مدیریت هشدارها در کد پایتون خود استفاده کنید. در ادامه برخی از پرکاربردترین توابع آورده شده است −

۱. ()warnings.warn

این تابع برای صادر کردن یک پیام هشدار استفاده می‌شود. می‌توانید پیام هشدار و دسته‌بندی هشدار را مشخص کنید. سنتکس این تابع به صورت زیر است −

warnings.warn(message, category=None, stacklevel=1, 
              source=None, *, skip_file_prefixes=())

در اینجا، message پیام هشداری است که می‌خواهید نمایش دهید، و category نوع هشدار است (مانند UserWarning، DeprecationWarning و غیره).

آرگومان stacklevel می‌تواند توسط توابع رابط (wrapper) نوشته‌شده در پایتون استفاده شود تا سطح پشته (stack level) هشدار را تنظیم کند. آرگومان کلیدواژه‌ای skip_file_prefixes می‌تواند برای مشخص کردن اینکه هنگام شمارش سطوح پشته از کدام فریم‌های پشته صرف‌نظر شود استفاده شود.

۲. ()warnings.showwarning

تابع ()showwarning برای نوشتن پیام‌های هشدار در یک فایل استفاده می‌شود. در ادامه سنتکس این تابع آمده است:

warnings.showwarning(message, category, filename, lineno, file=None, line=None)

در اینجا، message پیام هشدار، category نوع هشدار، filename نام فایلی که هشدار باید در آن ذخیره شود، و lineno شماره خطی است که هشدار در آن رخ داده است.

۳. ()warnings.warn_explicit

تابع ()warn_explicit برای ارسال پیام هشدار با کنترل بیشتر روی زمینه (context) هشدار استفاده می‌شود. می‌توان از آن برای ارسال صریح پیام، دسته‌بندی، نام فایل و شماره خط، و در صورت تمایل نام ماژول و ثبت‌کننده (registry) استفاده کرد. در ادامه سنتکس این تابع آمده است −

warnings.warn_explicit(message, category, filename, lineno, module=None, 
                        registry=None, module_globals=None, source=None)

پارامترها همان معانی توابع قبلی را دارند.

۴. ()warnings.filterwarnings

تابع ()filterwarnings برای تنظیم فیلترهای هشدار استفاده می‌شود. ما قبلاً نحوه استفاده از این تابع را برای نادیده گرفتن، همیشه نمایش دادن، یا تبدیل هشدارها به خطا بررسی کرده‌ایم. در ادامه سنتکس کامل این تابع آمده است −

warnings.filterwarnings(action, message='', category=Warning, module='', lineno=0, append=False)

پارامتر "action" می‌تواند هر یک از مقادیر زیر را بپذیرد: "default"، "always"، "ignore"، "error"، "module" یا "once". سایر پارامترها اختیاری هستند.

۵. ()warnings.simplefilter

تابع ()simplefilter یک رابط ساده‌تر برای تابع ()filterwarnings است. این تابع برای تنظیم فیلتر برای دسته‌بندی خاصی از هشدارها استفاده می‌شود. در ادامه سنتکس این تابع آمده است −

warnings.simplefilter(action, category=Warning, lineno=0, append=False)

پارامترها همان معانی توابع قبلی را دارند.

۶. ()warnings.resetwarnings

تابع ()resetwarnings برای بازگرداندن فیلترهای هشدار به حالت پیش‌فرض آن‌ها استفاده می‌شود. این تابع زمانی مفید است که بخواهید فیلترهای سفارشی تنظیم‌شده را پاک کنید. در ادامه سنتکس این تابع آمده است −

warnings.resetwarnings()

این تابع هیچ پارامتری نمی‌گیرد.

نتیجه‌گیری

در این فصل، درباره هشدارها در پایتون آموختیم. هشدارها با خطاها متفاوت هستند زیرا مانع اجرای برنامه نمی‌شوند. هشدار صرفاً برای آگاه‌سازی برنامه‌نویس درباره مشکلات احتمالی در کد استفاده می‌شود. ماژول warnings روشی برای صادر کردن پیام‌های هشدار و کنترل رفتار آن‌ها ارائه می‌دهد.