syslog --- روال‌های کتابخانه‌ای syslog یونیکس¶

این ماژول رابطی به روتین‌های کتابخانه syslog در Unix فراهم می‌کند. برای شرحی دقیق از امکانات syslog به صفحات راهنمای Unix مراجعه کنید.

این ماژول، خانواده‌ای از روال‌های سیستمی syslog را پوشش می‌دهد. یک کتابخانه‌ی پایتون خالص که می‌تواند با یک سرور syslog ارتباط برقرار کند، در ماژول logging.handlers به‌عنوان SysLogHandler در دسترس است.

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

syslog.syslog(message)¶

syslog.syslog(priority, message)

رشته‌ی message را به گزارش‌گیر سیستم ارسال کنید. در صورت لزوم، یک خط جدید به انتها اضافه می‌شود. هر پیام با اولویتی متشکل از امکانات (facility) و سطح (level) برچسب‌گذاری می‌شود. آرگومان اختیاری priority، که پیش‌فرض آن LOG_INFO است، اولویت پیام را تعیین می‌کند. اگر امکانات با استفاده از یا منطقی (LOG_INFO | LOG_USER) در priority کدگذاری نشده باشد، از مقدار داده‌شده در فراخوانی openlog() استفاده می‌شود.

اگر openlog() پیش از فراخوانی syslog() فراخوانی نشده باشد، openlog() بدون آرگومان فراخوانی خواهد شد.

یک رویداد حسابرسی syslog.syslog را با آرگومان‌های priority و message پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.2: در نسخه‌های پیشین، اگر openlog() پیش از فراخوانی syslog() فراخوانی نشده بود، به‌صورت خودکار فراخوانی نمی‌شد و فراخوانی openlog() به پیاده‌سازی syslog واگذار می‌شد.

تغییر یافته در نسخه‌ی 3.12: این تابع در زیرمفسرها محدود است. (تنها کدی که در چندین مفسر اجرا می‌شود تحت تأثیر قرار می‌گیرد و این محدودیت برای بیشتر کاربران مرتبط نیست.) openlog() باید در مفسر اصلی فراخوانی شود، پیش از آنکه بتوان از syslog() در یک زیرمفسر استفاده کرد. در غیر این صورت، RuntimeError پرتاب خواهد شد.

syslog.openlog([ident[, logoption[, facility]]])¶

گزینه‌های گزارش‌گیری برای فراخوانی‌های بعدی syslog() را می‌توان با فراخوانی openlog() تنظیم کرد. اگر گزارش در حال حاضر باز نباشد، syslog()، openlog() را بدون آرگومان فراخوانی می‌کند.

آرگومان کلیدواژه‌ای اختیاری ident رشته‌ای است که به ابتدای هر پیام اضافه می‌شود و مقدار پیش‌فرض آن sys.argv[0] است، با حذف اجزای ابتدایی مسیر. آرگومان کلیدواژه‌ای اختیاری logoption (مقدار پیش‌فرض آن ۰ است) یک فیلد بیتی است — برای مشاهده‌ی مقادیر قابل ترکیب، به بخش زیر مراجعه کنید. آرگومان کلیدواژه‌ای اختیاری facility (مقدار پیش‌فرض آن LOG_USER است) مقدار پیش‌فرض facility را برای پیام‌هایی که facility آن‌ها به‌طور صریح کدگذاری نشده است، تعیین می‌کند.

یک رویداد حسابرسی syslog.openlog را با آرگومان‌های ident، logoption و facility پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.2: در نسخه‌های پیشین، آرگومان‌های کلیدواژه‌ای مجاز نبودند و ident الزامی بود.

تغییر یافته در نسخه‌ی 3.12: این تابع در زیرمفسرها محدود شده است. (فقط کدی که در چندین مفسر اجرا می‌شود، تحت تأثیر قرار می‌گیرد و این محدودیت برای بیشتر کاربران مرتبط نیست.) این تابع فقط می‌تواند در مفسر اصلی فراخوانی شود. اگر در یک زیرمفسر فراخوانی شود، RuntimeError را پرتاب می‌کند.

syslog.closelog()¶

مقادیر ماژول syslog را بازنشانی می‌کند و closelog() کتابخانه‌ی سیستم را فراخوانی می‌کند.

این باعث می‌شود ماژول همان رفتاری را داشته باشد که هنگام ایمپورت اولیه دارد. برای مثال، openlog() در اولین فراخوانی syslog() فراخوانی خواهد شد (اگر openlog() از قبل فراخوانی نشده باشد)، و ident و سایر پارامترهای openlog() به مقادیر پیش‌فرض بازنشانی می‌شوند.

یک رویداد حسابرسی syslog.closelog را بدون آرگومان پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.12: این تابع در زیرمفسرها محدود شده است. (فقط کدی که در چندین مفسر اجرا می‌شود، تحت تأثیر قرار می‌گیرد و این محدودیت برای بیشتر کاربران مرتبط نیست.) این تابع فقط می‌تواند در مفسر اصلی فراخوانی شود. اگر در یک زیرمفسر فراخوانی شود، RuntimeError را پرتاب می‌کند.

syslog.setlogmask(maskpri)¶

نقاب اولویت را روی maskpri تنظیم می‌کند و مقدار نقاب پیشین را برمی‌گرداند. فراخوانی‌های syslog() با سطح اولویتی که در maskpri تنظیم نشده باشد نادیده گرفته می‌شوند. پیش‌فرض این است که همه اولویت‌ها ثبت شوند. تابع LOG_MASK(pri) نقاب اولویت منفرد pri را محاسبه می‌کند. تابع LOG_UPTO(pri) نقاب همه اولویت‌ها تا pri و شامل خود آن را محاسبه می‌کند.

یک رویداد حسابرسی syslog.setlogmask را با آرگومان maskpri پرتاب می‌کند.

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

syslog.LOG_EMERG¶

syslog.LOG_ALERT¶

syslog.LOG_CRIT¶

syslog.LOG_ERR¶

syslog.LOG_WARNING¶

syslog.LOG_NOTICE¶

syslog.LOG_INFO¶

syslog.LOG_DEBUG¶

سطوح اولویت (از بالا به پایین).

syslog.LOG_AUTH¶

syslog.LOG_AUTHPRIV¶

syslog.LOG_CRON¶

syslog.LOG_DAEMON¶

syslog.LOG_FTP¶

syslog.LOG_INSTALL¶

syslog.LOG_KERN¶

syslog.LOG_LAUNCHD¶

syslog.LOG_LPR¶

syslog.LOG_MAIL¶

syslog.LOG_NETINFO¶

syslog.LOG_NEWS¶

syslog.LOG_RAS¶

syslog.LOG_REMOTEAUTH¶

syslog.LOG_SYSLOG¶

syslog.LOG_USER¶

syslog.LOG_UUCP¶

syslog.LOG_LOCAL0¶

syslog.LOG_LOCAL1¶

syslog.LOG_LOCAL2¶

syslog.LOG_LOCAL3¶

syslog.LOG_LOCAL4¶

syslog.LOG_LOCAL5¶

syslog.LOG_LOCAL6¶

syslog.LOG_LOCAL7¶

امکانات، بسته به دسترسی‌پذیری در <syslog.h> برای LOG_AUTHPRIV، LOG_FTP، LOG_NETINFO، LOG_REMOTEAUTH، LOG_INSTALL و LOG_RAS.

تغییر یافته در نسخه‌ی 3.13: LOG_FTP، LOG_NETINFO، LOG_REMOTEAUTH، LOG_INSTALL، LOG_RAS و LOG_LAUNCHD افزوده شدند.

syslog.LOG_PID¶

syslog.LOG_CONS¶

syslog.LOG_NDELAY¶

syslog.LOG_ODELAY¶

syslog.LOG_NOWAIT¶

syslog.LOG_PERROR¶

گزینه‌های گزارش، بسته به دسترسی‌پذیری در <syslog.h> برای LOG_ODELAY، LOG_NOWAIT و LOG_PERROR.

import syslog

syslog.syslog('Processing started')
if error:
    syslog.syslog(syslog.LOG_ERR, 'Processing started')

syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')