# `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. In this case, a positive or zero value for isdst causes `localtime` to presume initially that summer time (for example, Daylight Saving Time) is or is not (respectively) in effect for the specified time. A negative value for isdst causes the `localtime` to attempt to divine whether summer time is in effect for the specified time.

  Нове в версії 3.3.

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.11.10: 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.11.10: 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`.

  Нове в версії 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, що відповідають стандартам.

  Нове в версії 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-кортежів, що містять елементи форми `(тип вмісту, значення-рядка)`.

Виноски

[1]

Зауважте, що знак зміщення часового поясу протилежний знаку змінної `time.timezone` для того самого часового поясу; остання змінна відповідає стандарту POSIX, тоді як цей модуль відповідає RFC 2822.