email.utils: ابزارهای متفرقه

کد منبع: Lib/email/utils.py

در ماژول email.utils چند ابزار مفید ارائه شده است:

email.utils.localtime(dt=None)

زمان محلی را به‌صورت یک شیء datetime آگاه برمی‌گرداند. اگر بدون آرگومان فراخوانی شود، زمان جاری را برمی‌گرداند. در غیر این صورت، آرگومان dt باید یک نمونه از datetime باشد، و این نمونه به منطقه زمانی محلی بر اساس پایگاه داده منطقه زمانی سیستم تبدیل می‌شود. اگر dt ساده (naive) باشد (یعنی dt.tzinfo برابر None است)، فرض می‌شود که در زمان محلی قرار دارد.

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

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.14 حذف شده است: پارامتر isdst.

email.utils.make_msgid(idstring=None, domain=None)

رشته‌ای مناسب برای سرآیند Message-ID منطبق با RFC 2822 برمی‌گرداند. اگر idstring اختیاری داده شود، رشته‌ای است که برای تقویت یکتایی شناسه‌ی پیام استفاده می‌شود. اگر domain اختیاری داده شود، بخش پس از '@' در msgid را فراهم می‌کند. مقدار پیش‌فرض، نام میزبان محلی است. معمولاً نیازی به تغییر این پیش‌فرض نیست، اما ممکن است در موارد خاصی مفید باشد، مانند ساخت یک سیستم توزیع‌شده که از یک نام دامنه‌ی ثابت در چندین میزبان استفاده می‌کند.

تغییر یافته در نسخه‌ی 3.2: کلیدواژه‌ی domain افزوده شد.

توابع باقی‌مانده بخشی از API ایمیل قدیمی (Compat32) هستند. نیازی به استفاده‌ی مستقیم از این‌ها با API جدید نیست، زیرا تجزیه و قالب‌بندی ارائه‌شده توسط آن‌ها به‌طور خودکار توسط سازوکار تجزیه‌ی سرآیند در API جدید انجام می‌شود.

email.utils.quote(str)

یک رشته جدید برمی‌گرداند که در آن بک‌اسلش‌های موجود در str با دو بک‌اسلش، و علامت‌های نقل‌قول دوتایی با بک‌اسلش-علامت نقل‌قول دوتایی جایگزین شده‌اند.

email.utils.unquote(str)

یک رشته جدید برمی‌گرداند که نسخه‌ی بدون علامت نقل‌قول از str است. اگر str با علامت نقل‌قول دوتایی شروع و تمام شود، آن‌ها حذف می‌شوند. به همین ترتیب، اگر str با علامت‌های زاویه‌ای شروع و تمام شود، آن‌ها حذف می‌شوند.

email.utils.parseaddr(address, *, strict=True)

نشانی را تجزیه می‌کند -- که باید مقدار یک فیلد حاوی نشانی مانند To یا Cc باشد -- به اجزای تشکیل‌دهنده‌ی آن، یعنی نام واقعی و نشانی ایمیل. یک تاپل از آن اطلاعات برمی‌گرداند، مگر اینکه تجزیه ناموفق باشد، که در این صورت یک تاپل دوتایی از ('', '') برگردانده می‌شود.

اگر strict درست باشد، از یک پارسر سخت‌گیر استفاده می‌شود که ورودی‌های بدشکل را رد می‌کند.

تغییر یافته در نسخه‌ی 3.13: افزودن پارامتر اختیاری strict و رد کردن ورودی‌های بدشکل به‌صورت پیش‌فرض.

email.utils.formataddr(pair, charset='utf-8')

این تابع معکوس parseaddr() است و یک تاپل دوتایی به شکل (realname, email_address) دریافت می‌کند و مقدار رشته‌ای مناسب برای سرآیند To یا Cc را بازمی‌گرداند. اگر عنصر اول pair نادرست باشد، عنصر دوم بدون تغییر بازگردانده می‌شود.

charset اختیاری، مجموعه نویسه‌ای است که در کدگذاری RFC 2047 برای realname استفاده خواهد شد، اگر realname حاوی نویسه‌های غیر ASCII باشد. می‌تواند نمونه‌ای از str یا Charset باشد. مقدار پیش‌فرض آن utf-8 است.

تغییر یافته در نسخه‌ی 3.3: گزینه‌ی charset افزوده شد.

email.utils.getaddresses(fieldvalues, *, strict=True)

این متد فهرستی از تاپل‌های دوتایی با قالبی که توسط parseaddr() برگردانده می‌شود را برمی‌گرداند. fieldvalues دنباله‌ای از مقادیر فیلد سرآیند است که ممکن است توسط Message.get_all برگردانده شود.

اگر strict درست باشد، از یک پارسر سخت‌گیر استفاده می‌شود که ورودی‌های بدشکل را رد می‌کند.

در اینجا یک مثال ساده آمده است که تمام گیرندگان یک پیام را به دست می‌آورد:

from email.utils import getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

تغییر یافته در نسخه‌ی 3.13: افزودن پارامتر اختیاری strict و رد کردن ورودی‌های بدشکل به‌صورت پیش‌فرض.

email.utils.parsedate(date)

تلاش می‌کند یک تاریخ را طبق قواعد RFC 2822 تجزیه کند. با این حال، برخی برنامه‌های ایمیل آن قالب را همان‌طور که مشخص شده است دنبال نمی‌کنند، بنابراین parsedate() سعی می‌کند در این موارد به‌درستی حدس بزند. date رشته‌ای حاوی یک تاریخ RFC 2822 است، مانند "Mon, 20 Nov 1995 19:12:08 -0500". اگر در تجزیه تاریخ موفق شود، parsedate() یک تاپل ۹تایی برمی‌گرداند که می‌توان آن را مستقیماً به time.mktime() ارسال کرد؛ در غیر این صورت None برگردانده می‌شود. توجه داشته باشید که اندیس‌های ۶، ۷ و ۸ تاپل نتیجه قابل استفاده نیستند.

email.utils.parsedate_tz(date)

همان عملکرد parsedate() را انجام می‌دهد، اما یا None یا یک تاپل ۱۰تایی بازمی‌گرداند؛ ۹ عنصر اول، تاپلی را تشکیل می‌دهند که می‌توان آن را مستقیماً به time.mktime() ارسال کرد، و عنصر دهم، اختلاف منطقه زمانی تاریخ نسبت به UTC (که اصطلاح رسمی برای زمان میانگین گرینویچ است) [1] است. اگر رشته ورودی منطقه زمانی نداشته باشد، آخرین عنصر تاپل برگردانده‌شده 0 است که نشان‌دهنده UTC است. توجه داشته باشید که اندیس‌های ۶، ۷ و ۸ تاپل نتیجه قابل استفاده نیستند.

email.utils.parsedate_to_datetime(date)

معکوس format_datetime(). همان کارکرد parsedate() را دارد، اما در صورت موفقیت یک datetime برمی‌گرداند؛ در غیر این صورت، اگر date حاوی مقدار نامعتبری باشد، مانند ساعتی بزرگ‌تر از ۲۳ یا آفست منطقه زمانی خارج از بازه‌ی -۲۴ تا ۲۴ ساعت، ValueError پرتاب می‌شود. اگر تاریخ ورودی دارای منطقه زمانی -0000 باشد، datetime یک datetime ساده خواهد بود، و اگر تاریخ مطابق RFCها باشد، نشان‌دهنده‌ی زمانی در UTC خواهد بود، اما بدون هیچ نشانه‌ای از منطقه زمانی واقعی مبدأ پیامی که تاریخ از آن آمده است. اگر تاریخ ورودی دارای هر آفست منطقه زمانی معتبر دیگری باشد، datetime یک datetime آگاه همراه با یک timezone tzinfo متناظر خواهد بود.

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

email.utils.mktime_tz(tuple)

یک تاپل ۱۰تایی را که توسط parsedate_tz() برگردانده می‌شود، به یک برچسب زمانی UTC (ثانیه‌های سپری‌شده از Epoch) تبدیل می‌کند. اگر آیتم منطقه‌ی زمانی در تاپل None باشد، زمان محلی فرض می‌شود.

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

یک رشته‌ی تاریخ را مطابق با RFC 2822 برمی‌گرداند، برای نمونه:

Fri, 09 Nov 2001 01:08:47 -0000

timeval اختیاری، در صورت ارائه، یک مقدار زمان ممیز شناور است که time.gmtime() و time.localtime() آن را می‌پذیرند؛ در غیر این صورت از زمان جاری استفاده می‌شود.

localtime پرچمی اختیاری است که وقتی True باشد، timeval را تفسیر می‌کند و تاریخی بر اساس منطقه‌ی زمانی محلی به‌جای UTC برمی‌گرداند و ساعت تابستانی را به‌درستی در نظر می‌گیرد. مقدار پیش‌فرض False است، به این معنا که از UTC استفاده می‌شود.

usegmt اختیاری، پرچمی است که وقتی True باشد، یک رشته‌ی تاریخ را با منطقه‌ی زمانی به‌صورت رشته‌ی ASCII GMT خروجی می‌دهد، نه به‌صورت عددی -0000. این برای برخی پروتکل‌ها (مانند HTTP) لازم است. این فقط زمانی اعمال می‌شود که localtime برابر False باشد. مقدار پیش‌فرض False است.

email.utils.format_datetime(dt, usegmt=False)

مانند formatdate، اما ورودی یک نمونه datetime است. اگر یک datetime ساده باشد، فرض می‌شود «UTC بدون اطلاعات درباره منطقه‌ی زمانی مبدأ» است و برای منطقه‌ی زمانی از -0000 قراردادی استفاده می‌شود. اگر یک datetime آگاه باشد، از آفست عددی منطقه‌ی زمانی استفاده می‌شود. اگر یک منطقه‌ی زمانی آگاه با آفست صفر باشد، می‌توان usegmt را روی True تنظیم کرد، که در این صورت رشته‌ی GMT به‌جای آفست عددی منطقه‌ی زمانی استفاده می‌شود. این راهی برای تولید سرآیندهای تاریخ HTTP مطابق با استانداردها فراهم می‌کند.

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

email.utils.decode_rfc2231(s)

رشته‌ی s را مطابق RFC 2231 کدگشایی کنید.

email.utils.encode_rfc2231(s, charset=None, language=None)

رشته‌ی s را مطابق RFC 2231 کدگذاری می‌کند. آرگومان‌های اختیاری charset و language، در صورت داده شدن، به ترتیب نام مجموعه‌نویسه و نام زبان مورد استفاده هستند. اگر هیچ‌کدام داده نشود، s همان‌طور که هست برگردانده می‌شود. اگر charset داده شود اما language داده نشود، رشته با استفاده از رشته‌ی خالی برای language کدگذاری می‌شود.

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

When a header parameter is encoded in RFC 2231 format, Message.get_param may return a 3-tuple containing the character set, language, and value. collapse_rfc2231_value() turns this into a string. Optional errors is passed to the errors argument of str's encode() method; it defaults to 'replace'. Optional fallback_charset specifies the character set to use if the one in the RFC 2231 header is not known by Python; it defaults to 'us-ascii'.

برای سهولت، اگر value ارسال‌شده به collapse_rfc2231_value() یک تاپل نباشد، باید یک رشته باشد و بدون علامت نقل‌قول برگردانده می‌شود.

email.utils.decode_params(params)

کدگشایی فهرست پارامترها مطابق RFC 2231. params دنباله‌ای از ۲-تایی‌ها شامل عناصری به‌شکل (content-type, string-value) است.

پانویس‌ها