# `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이 주어지면, 메시지 id의 고유성을 강화하는 데 사용되는 문자열입니다. 선택적인 domain이 주어지면, msgid의 ‘@’ 다음 부분을 제공합니다. 기본값은 로컬 호스트 명입니다. 일반적으로 이 기본값을 재정의할 필요는 없지만, 여러 호스트에 걸쳐 일관된 도메인 이름을 사용하는 분산 시스템을 구성하는 경우와 같이 특정 경우에 유용할 수 있습니다.

  버전 3.2에서 변경: domain 키워드가 추가되었습니다.

나머지 함수는 레거시 (`Compat32`) email API의 일부입니다. 이것들이 제공하는 구문 분석과 포매팅은 새 API의 헤더 구문 분석 장치가 자동으로 수행하므로, 새 API에서 이것들을 직접 사용할 필요는 없습니다.

email.utils.quote(str)

  str에 있는 역 슬래시를 두 개의 역 슬래시로 대체하고, 큰따옴표는 역 슬래시-큰따옴표로 대체한 새 문자열을 반환합니다.

email.utils.unquote(str)

  str의 unquote 된 버전인 새 문자열을 반환합니다. str가 큰따옴표로 끝나고 시작하면, 큰따옴표가 제거됩니다. 마찬가지로 str이 화살괄호(angle brackets)로 끝나고 시작하면, 제거됩니다.

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

  address(To나 Cc와 같은 주소를 포함하는 필드의 값이어야 합니다)를 realname과 email 주소 구성 요소로 구문 분석합니다. 구문 분석에 실패하지 않는 한 해당 정보의 튜플을 반환합니다. 실패하면 `('', '')`의 2-튜플이 반환됩니다.

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

  버전 3.12.6에서 변경: Add strict optional parameter and reject malformed inputs by default.

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

  `parseaddr()`의 역, `(realname, email_address)` 형식의 2-튜플을 취해 To나 Cc 헤더에 적합한 문자열 값을 반환합니다. pair의 첫 번째 요소가 거짓이면, 두 번째 요소는 수정되지 않은 채 반환됩니다.

  선택적 charset은 `realname`에 비 ASCII 문자가 포함되어있을 때 `realname`의 RFC 2047 인코딩에 사용될 문자 집합입니다. `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.12.6에서 변경: 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()`는 `time.mktime()`에 직접 전달할 수 있는 9-튜플을 반환합니다; 그렇지 않으면, `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)

  `parsedate_tz()`에 의해 반환된 10-튜플을 UTC 타임스탬프(Epoch 이후 초)로 바꿉니다. 튜플의 시간대 항목이 `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.

  선택적 localtime 은, `True`일 때, timeval을 해석하고, UTC 대신 일광 절약 시간을 적절히 고려하는 지역 시간대에 상대적인 날짜를 반환토록 하는 플래그입니다. 기본값은 UTC가 사용된다는 뜻인 `False`입니다.

  선택적 usegmt는, `True`일 때, 날짜 문자열의 시간대를 숫자 `-0000` 대신 ASCII 문자열 `GMT`로 출력하도록 하는 플래그입니다. 일부 프로토콜(가령 HTTP)에 필요합니다. 이것은 localtime 이 `False`일 때만 적용됩니다. 기본값은 `False`입니다.

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

  `formatdate`와 같지만, 입력이 `datetime` 인스턴스입니다. 나이브 datetime이면, “소스 시간대에 대한 정보가 없는 UTC”로 간주하며, 관습적으로 `-0000`이 시간대로 사용됩니다. 어웨어 `datetime`이면, 숫자 시간대 오프셋이 사용됩니다. 오프셋이 0인 어웨어 시간대면, usegmt를 `True`로 설정해서 `GMT` 문자열을 숫자 시간대 오프셋 대신 사용할 수 있습니다. 이것은 표준을 준수하는 HTTP date 헤더를 생성하는 방법을 제공합니다.

  Added in version 3.3.

email.utils.decode_rfc2231(s)

  RFC 2231에 따라 s 문자열을 디코드합니다.

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

  RFC 2231에 따라 s 문자열을 인코드합니다. 선택적인 charset과 language가 주어지면, 사용할 문자 집합 이름과 언어 이름입니다. 둘 다 지정되지 않으면, s가 그대로 반환됩니다. charset이 주어졌지만, language가 지정되지 않으면, 문자열은 language에 대해 빈 문자열을 사용하여 인코딩됩니다.

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

  header 매개 변수가 RFC 2231로 인코딩되었을 때, `Message.get_param`은 문자 집합, 언어 및 값이 포함된 3-튜플을 반환할 수 있습니다. `collapse_rfc2231_value()`는 이것을 유니코드 문자열로 변환합니다. 선택적 errors는 `str`의 `encode()` 메서드의 errors 인자로 전달됩니다; 기본값은 `'replace'`입니다. 선택적 fallback_charset은 RFC 2231 헤더에 있는 것이 파이썬에 알려지지 않았을 때 사용할 문자 집합을 지정합니다; 기본값은 `'us-ascii'`입니다.

  편의상, `collapse_rfc2231_value()`에 전달된 value가 튜플이 아니면, 문자열이어야 하고 unquote 되어 반환됩니다.

email.utils.decode_params(params)

  RFC 2231에 따라 매개 변수 리스트를 디코드합니다. params는 `(content-type, string-value)` 형식의 요소를 포함하는 2-튜플의 시퀀스입니다.

각주

[1]

시간대 오프셋의 부호는 같은 시간대에 대한 `time.timezone` 변수의 부호와 반대임에 유의하십시오; 이 모듈이 RFC 2822를 따르지만, 후자의 변수는 POSIX 표준을 따릅니다.