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

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

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

email.utils.localtime(dt=None)

Return local time as an aware datetime object. If called without arguments, return the current time. Otherwise the dt argument should be a datetime instance, and it is converted to the local time zone according to the system time zone database. If dt is naive (that is, dt.tzinfo is None), it is assumed to be in local time.

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

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

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

Returns a string suitable for an RFC 2822-compliant Message-ID header. Optional idstring, if given, is a string used to strengthen the uniqueness of the message id. Optional domain, if given, provides the portion of the msgid after the '@'. The default is the local hostname. It is normally not necessary to override this default, but may be useful in certain cases, such as constructing a distributed system that uses a consistent domain name across multiple hosts.

تغییر یافته در نسخه‌ی 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', *, strict=True)

The inverse of parseaddr(), this takes a 2-tuple of the form (realname, email_address) and returns the string value suitable for a To or Cc header. If the first element of pair is false, then the second element is returned unmodified.

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

If strict is true (the default), raise ValueError for inputs that contain CR or LF, which are not allowed in an email address. Set strict to False to allow non-strict inputs.

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

تغییر یافته در نسخه‌ی 3.16: Added the strict parameter.

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

This function returns a list of 2-tuples of the form returned by parseaddr(). fieldvalues is a sequence of header field values as might be returned by 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)

Attempts to parse a date according to the rules in RFC 2822 Section 3.3. However, some mailers don't follow that format as specified, so parsedate() tries to guess correctly in such cases. date is a string containing an RFC 2822 date, such as "Mon, 20 Nov 1995 19:12:08 -0500". If it succeeds in parsing the date, parsedate() returns a 9-tuple that can be passed directly to time.mktime(); otherwise None will be returned. Note that indexes 6, 7, and 8 of the result tuple are not usable.

email.utils.parsedate_tz(date)

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

email.utils.parsedate_to_datetime(date)

The inverse of format_datetime(). Performs the same function as parsedate(), but on success returns a datetime; otherwise ValueError is raised if date contains an invalid value such as an hour greater than 23 or a timezone offset not between -24 and 24 hours. If the input date has a timezone of -0000, the datetime will be a naive datetime, and if the date conforms to the RFCs it will represent a time in UTC but with no indication of the actual source timezone of the message the date comes from. If the input date has any other valid timezone offset, the datetime will be an aware datetime whose corresponding tzinfo attribute is a timezone object.

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

email.utils.mktime_tz(tuple)

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

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

Returns a date string as per RFC 2822, for example:

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

Optional timeval, if given, is a floating-point time value as accepted by time.gmtime() and time.localtime(), otherwise the current time is used.

Optional localtime is a flag that when True, interprets timeval, and returns a date relative to the local timezone instead of UTC, properly taking daylight saving time into account. The default is False meaning UTC is used.

Optional usegmt is a flag that when True, outputs a date string with the timezone as an ASCII string GMT, rather than a numeric -0000. This is needed for some protocols (such as HTTP). This only applies when localtime is False. The default is False.

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

Like formatdate(), but the input is a datetime instance. If it is a naive datetime, it is assumed to be "UTC with no information about the source timezone", and the conventional -0000 is used for the timezone. If it is an aware datetime, then the numeric timezone offset is used. If it is an aware timezone with offset zero, then usegmt may be set to True, in which case the string GMT is used instead of the numeric timezone offset. This provides a way to generate standards-conformant HTTP date headers.

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

email.utils.decode_rfc2231(s)

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

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

Encode the string s according to RFC 2231. Optional charset and language, if given, are the character set name and language name to use. If neither is given, s is returned as-is. If charset is given but language is not, the string is encoded using the empty string for 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) است.

پانویس‌ها