email.utils: Miscellaneous utilities

Kode sumber: Lib/email/utils.py

Ada beberapa kakas yang berguna yang disediakan di modul email.utils

email.utils.localtime(dt=None)

Return local time as an aware datetime object. If called without arguments, return current time. Otherwise 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. The isdst parameter is ignored.

Added in version 3.3.

Deprecated since version 3.12, will be removed in version 3.14: The isdst parameter.

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

Повертає рядок, який підходить для RFC 2822-сумісного заголовка Message-ID. Необов’язковий idstring, якщо вказано, це рядок, який використовується для посилення унікальності ідентифікатора повідомлення. Необов’язковий домен, якщо вказано, надає частину msgid після "@". Типовим є локальне ім’я хоста. Зазвичай немає необхідності змінювати це значення за замовчуванням, але це може бути корисним у певних випадках, наприклад, при побудові розподіленої системи, яка використовує узгоджене доменне ім’я на кількох хостах.

Berubah pada versi 3.2: Menambahkan kata kunci domain

Решта функцій є частиною застарілого (Compat32) API електронної пошти. Немає потреби безпосередньо використовувати їх із новим API, оскільки синтаксичний аналіз і форматування, які вони надають, виконуються автоматично механізмом аналізу заголовків нового API.

email.utils.quote(str)

Повертає новий рядок із зворотними похилими рисками в str, заміненими двома зворотними похилими рисками, і подвійними лапками, заміненими зворотними похилими рисками-подвійними лапками.

email.utils.unquote(str)

Повертає новий рядок, який є версією str без лапок. Якщо str закінчується і починається подвійними лапками, вони видаляються. Так само, якщо str закінчується і починається кутовими дужками, вони видаляються.

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

Проаналізуйте адресу, яка має бути значенням деякого поля, що містить адресу, наприклад To або Cc, на його складові частини realname і email address. Повертає кортеж із цією інформацією, якщо синтаксичний аналіз не вдається, у цьому випадку повертається 2-кортеж ('', '').

Если strict имеет значение true, используйте строгий анализатор, который отклоняет неверные входные данные.

Berubah pada versi 3.13: Добавьте необязательный параметр strict и по умолчанию отклоняйте неверные входные данные.

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

Інверсія parseaddr(), приймає 2-кортеж у формі (справжнє ім’я, електронна_адреса) і повертає значення рядка, придатне для заголовка To або Cc . Якщо перший елемент pair є false, то другий елемент повертається без змін.

Необов’язковий charset — це набір символів, який використовуватиметься в RFC 2047 кодуванні realname, якщо realname містить символи, відмінні від ASCII. Може бути екземпляром str або Charset. За замовчуванням utf-8.

Berubah pada versi 3.3: Menambahkan pilihan charset

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

Этот метод возвращает список кортежей из двух форм, возвращаемых функцией parseaddr(). fieldvalues — это последовательность значений полей заголовка, которая может быть возвращена Message.get_all.

Если strict имеет значение true, используйте строгий анализатор, который отклоняет неверные входные данные.

Вот простой пример, который получает всех получателей сообщения:

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)

Berubah pada versi 3.13: Добавьте необязательный параметр strict и по умолчанию отклоняйте неверные входные данные.

email.utils.parsedate(date)

Намагається проаналізувати дату відповідно до правил у RFC 2822. однак деякі розсилки не дотримуються зазначеного формату, тому parsedate() намагається правильно вгадати в таких випадках. date — це рядок, що містить дату RFC 2822, наприклад "Mon, 20 Nov 1995 19:12:08 -0500". Якщо вдасться проаналізувати дату, parsedate() повертає 9-кортеж, який можна передати безпосередньо до time.mktime(); інакше буде повернено None. Зверніть увагу, що індекси 6, 7 і 8 кортежу результатів не можна використовувати.

email.utils.parsedate_tz(date)

Виконує ту саму функцію, що й parsedate(), але повертає або None, або 10-кортеж; перші 9 елементів утворюють кортеж, який можна передати безпосередньо до time.mktime(), а десятий — це зсув часового поясу дати відносно UTC (офіційний термін для часу за Гринвічем) [1] . Якщо вхідний рядок не має часового поясу, останнім елементом кортежу, що повертається, є 0, який представляє UTC. Зверніть увагу, що індекси 6, 7 і 8 кортежу результатів не можна використовувати.

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 is conforming 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 with the corresponding a timezone tzinfo.

Added in version 3.3.

email.utils.mktime_tz(tuple)

Перетворіть 10-кортеж, який повертає parsedate_tz(), на мітку часу UTC (секунди з епохи). Якщо елемент часового поясу в кортежі None, припустіть місцевий час.

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

Повертає рядок дати згідно з RFC 2822, наприклад:

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.

Необов’язковий місцевий час — це прапорець, який, якщо значення True інтерпретує timeval і повертає дату відносно місцевого часового поясу замість UTC, правильно враховуючи літній час. Типовим значенням є False, тобто використовується UTC.

Необов’язковий usegmt — це прапорець, який, якщо значення "Істина" виводить рядок дати з часовим поясом як рядок ASCII "GMT", а не числове "-0000". Це потрібно для деяких протоколів (наприклад, HTTP). Це стосується лише випадків, коли localtime має значення False. Типовим значенням є False.

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

Подібно до formatdate, але введенням є екземпляр datetime. Якщо це наивна дата-час, передбачається, що це "UTC без інформації про вихідний часовий пояс", а для часового поясу використовується звичайний "-0000". Якщо це відомий datetime, тоді використовується числове зміщення часового поясу. Якщо це відомий часовий пояс із нульовим зміщенням, тоді usegmt може бути встановлено на True, у цьому випадку рядок GMT використовується замість числового зсуву часового поясу. Це надає спосіб генерувати заголовки дати HTTP, що відповідають стандартам.

Added in version 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')

Якщо параметр заголовка закодовано у форматі RFC 2231, Message.get_param може повертати 3-кортеж, що містить набір символів, мову та значення. collapse_rfc2231_value() перетворює це на рядок Юнікод. Необов’язковий errors передається в аргумент errors методу str encode(); за замовчуванням 'replace'. Необов’язковий fallback_charset визначає набір символів для використання, якщо той, що міститься в заголовку RFC 2231, не відомий Python; за замовчуванням 'us-ascii'.

Для зручності, якщо значення, передане collapse_rfc2231_value(), не є кортежем, воно має бути рядком і повертається без лапок.

email.utils.decode_params(params)

Розшифруйте список параметрів відповідно до RFC 2231. параметри — це послідовність 2-кортежів, що містять елементи форми (тип вмісту, значення-рядка).

Catatan kaki