email.utils: Miscellaneous utilities

Вихідний код: Lib/email/utils.py

У модулі 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 після «@». Типовим є локальне ім’я хоста. Зазвичай немає необхідності змінювати це значення за замовчуванням, але це може бути корисним у певних випадках, наприклад, при побудові розподіленої системи, яка використовує узгоджене доменне ім’я на кількох хостах.

Змінено в версії 3.2: Додано ключове слово 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-кортеж ('', '').

If strict is true, use a strict parser which rejects malformed inputs.

Змінено в версії 3.13: Add strict optional parameter and reject malformed inputs by default.

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

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

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

Змінено в версії 3.3: Додано опцію charset.

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

This method 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.

If strict is true, use a strict parser which rejects malformed inputs.

Here’s a simple example that gets all the recipients of a message:

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: Add strict optional parameter and reject malformed inputs by default.

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)

Інверсія format_datetime(). Виконує ту саму функцію, що й parsedate(), але в разі успіху повертає datetime; інакше ValueError викликається, якщо date містить недійсне значення, таке як година більше 23 або зсув часового поясу не між -24 та 24 годинами. Якщо введена дата має часовий пояс -0000, datetime буде простим datetime, і якщо дата відповідає RFC, вона представлятиме час у UTC, але без вказівка фактичного часового поясу джерела повідомлення, з якого походить дата. Якщо введена дата має будь-яке інше дійсне зміщення часового поясу, datetime буде відомим datetime з відповідним 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-кортежів, що містять елементи форми (тип вмісту, значення-рядка).

Виноски