"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)

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

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)

   이 메서드는 "parseaddr()"에 의해 반환된 형식의 2-튜플 리스트를 반환
   합니다. *fieldvalues*는 "Message.get_all"에 의해 반환될 수 있는 헤
   더 필드 값의 시퀀스입니다. 다음은 메시지의 모든 수신자를 얻는 간단
   한 예입니다:

      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)

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 표준을 따릅니다.
