"poplib" --- POP3 프로토콜 클라이언트
*************************************

**소스 코드:** Lib/poplib.py

======================================================================

이 모듈은 POP3 서버에 대한 연결을 캡슐화하고 **RFC 1939**에 정의된 대
로 프로토콜을 구현하는 클래스 "POP3"를 정의합니다. "POP3" 클래스는
**RFC 1939**의 최소(minimal)와 선택적인(optional) 명령 집합을 모두 지
원합니다. "POP3" 클래스는 이미 맺어진 연결에서 암호화된 통신을 활성화
하기 위해 **RFC 2595**에서 도입된 "STLS" 명령도 지원합니다.

또한, 이 모듈은 SSL을 하부 프로토콜 계층으로 사용하는 POP3 서버에 연결
하기 위한 지원을 제공하는 클래스 "POP3_SSL"을 제공합니다.

POP3는 광범위하게 지원되지만 노후화되었음에 유의하십시오. POP3 서버의
구현 품질은 매우 다양하며, 그중 너무 많은 것들이 형편없습니다. 여러분
의 메일 서버가 IMAP을 지원한다면, IMAP 서버가 더 잘 구현되는 경향이 있
으므로 "imaplib.IMAP4" 클래스를 사용하는 것이 좋습니다.

가용성: not WASI.

이 모듈은 웹어셈블리에서 작동하지 않거나 제공되지 않습니다. 자세한 내
용은 웹어셈블리 플랫폼을 참조하세요.

"poplib" 모듈은 두 가지 클래스를 제공합니다:

class poplib.POP3(host, port=POP3_PORT[, timeout])

   이 클래스는 실제 POP3 프로토콜을 구현합니다. 인스턴스가 초기화될 때
   연결이 만들어집니다. *port*를 생략하면, 표준 POP3 포트(110)가 사용
   됩니다. 선택적 *timeout* 매개 변수는 연결 시도의 제한 시간을 초로
   지정합니다 (지정하지 않으면, 전역 기본 제한 시간 설정이 사용됩니다
   ).

   "self", "host", "port"를 인자로 감사 이벤트(auditing event)
   "poplib.connect"를 발생시킵니다.

   모든 명령은 "self"와 "line"을 인자로 감사 이벤트(auditing event)
   "poplib.putline"을 발생시킵니다. 여기서 "line"은 원격 호스트로 보낼
   바이트열입니다.

   버전 3.9에서 변경: *timeout* 매개 변수가 0으로 설정되면, 비 블로킹
   소켓이 만들어지지 않도록 "ValueError"를 발생시킵니다.

class poplib.POP3_SSL(host, port=POP3_SSL_PORT, *, timeout=None, context=None)

   SSL 암호화된 소켓을 통해 서버에 연결하는 "POP3"의 서브 클래스입니다
   . *port*가 지정되지 않으면, 표준 POP3-over-SSL 포트(995)가 사용됩니
   다. *timeout*은 "POP3" 생성자에서처럼 동작합니다. *context*는 선택
   적인 "ssl.SSLContext" 객체인데, SSL 구성 옵션, 인증서 및 개인 키를
   단일 (잠재적으로 수명이 긴) 구조로 묶을 수 있도록 합니다. 모범 사례
   는 보안 고려 사항을 읽으십시오.

   "self", "host", "port"를 인자로 감사 이벤트(auditing event)
   "poplib.connect"를 발생시킵니다.

   모든 명령은 "self"와 "line"을 인자로 감사 이벤트(auditing event)
   "poplib.putline"을 발생시킵니다. 여기서 "line"은 원격 호스트로 보낼
   바이트열입니다.

   버전 3.2에서 변경: *context* 매개 변수가 추가되었습니다.

   버전 3.4에서 변경: 클래스는 이제 "ssl.SSLContext.check_hostname"을
   통한 호스트 이름 검사와 *서버 이름 표시(Server Name Indication)*를
   지원합니다 ("ssl.HAS_SNI"를 참조하십시오).

   버전 3.9에서 변경: *timeout* 매개 변수가 0으로 설정되면, 비 블로킹
   소켓이 만들어지지 않도록 "ValueError"를 발생시킵니다.

   버전 3.12에서 변경: 폐지된 *keyfile* 과 *certfile* 매개 변수는 제거
   되었습니다.

한가지 예외가 "poplib" 모듈의 어트리뷰트로 정의됩니다:

exception poplib.error_proto

   이 모듈로부터 비롯된 모든 에러에서 발생하는 예외 ("socket" 모듈에서
   비롯된 에러는 잡지 않습니다). 예외의 이유는 문자열로 생성자에 전달
   됩니다.

더 보기:

  모듈 "imaplib"
     표준 파이썬 IMAP 모듈.

  Frequently Asked Questions About Fetchmail
     **fetchmail** POP/IMAP 클라이언트에 대한 FAQ는 POP 프로토콜에 기
     반하는 응용 프로그램을 작성해야 할 때 유용할 수 있는 POP3 서버 다
     양성과 RFC 위반에 대한 정보를 수집합니다.


POP3 객체
=========

모든 POP3 명령은 소문자로 바뀐 같은 이름의 메서드로 표현됩니다; 대부분
서버에서 보낸 응답 텍스트를 반환합니다.

"POP3" 인스턴스에는 다음과 같은 메서드가 있습니다:

POP3.set_debuglevel(level)

   인스턴스의 디버깅 수준을 설정합니다. 이것은 인쇄되는 디버깅 출력의
   양을 제어합니다. 기본값인 "0"은 디버깅 출력을 생성하지 않습니다.
   "1" 값은 적절한 양의 디버깅 출력을 생성하는데, 일반적으로 요청당 한
   줄입니다. "2" 이상의 값은 제어 연결에서 보내고 받은 각 줄을 로깅 하
   여 최대량의 디버깅 출력을 생성합니다.

POP3.getwelcome()

   POP3 서버가 보낸 인사말 문자열을 반환합니다.

POP3.capa()

   **RFC 2449**에 지정된 대로 서버의 기능을 조회합니다. "{'name':
   ['param'...]}" 형식의 딕셔너리를 반환합니다.

   Added in version 3.4.

POP3.user(username)

   user 명령을 보냅니다, 응답은 암호가 필요함을 가리켜야 합니다.

POP3.pass_(password)

   암호를 보냅니다, 응답에는 메시지 수와 우편함 크기가 포함됩니다. 참
   고: "quit()"가 호출될 때까지 서버의 우편함은 잠깁니다.

POP3.apop(user, secret)

   POP3 서버에 로그인하기 위해 더 안전한 APOP 인증을 사용합니다.

POP3.rpop(user)

   POP3 서버에 로그인하기 위해 RPOP 인증(유닉스 r-명령과 유사합니다)을
   사용합니다.

POP3.stat()

   우편함 상태를 가져옵니다. 결과는 2개의 정수의 튜플입니다: "(message
   count, mailbox size)".

POP3.list([which])

   메시지 목록을 요청합니다, 결과는 "(response, ['mesg_num octets',
   ...], octets)" 형식입니다. *which*가 설정되면, 목록에 표시할 메시지
   입니다.

POP3.retr(which)

   전체 메시지 번호 *which*를 가져오고 읽었음을 알리는 플래그를 설정합
   니다. 결과는 "(response, ['line', ...], octets)" 형식입니다.

POP3.dele(which)

   메시지 번호 *which*를 삭제로 표시합니다. 대부분 서버에서 삭제는 실
   제로 QUIT 때까지 수행되지 않습니다 (주된 예외는 Eudora QPOP인데, 모
   든 연결 단절 시 계류 중인 삭제를 수행하여 의도적으로 RFC를 위반합니
   다).

POP3.rset()

   우편함에 대한 모든 삭제 표시를 제거합니다.

POP3.noop()

   아무것도 하지 않습니다. 연결 유지로 사용될 수 있습니다.

POP3.quit()

   로그아웃: 변경 내용 커밋, 우편함 잠금 해제, 연결 끊기.

POP3.top(which, howmuch)

   메시지 번호 *which*의 메시지 헤더와 메시지의 *howmuch* 개 줄을 가져
   옵니다. 결과는 "(response, ['line', ...], octets)" 형식입니다.

   이 메서드가 사용하는 POP3 TOP 명령은, RETR 명령과 달리, 메시지의 읽
   었음을 알리는 플래그를 설정하지 않습니다; 불행히도, TOP은 RFC에서
   부실하게 기술되어 있고 종종 유명하지 않은 서버에서 망가져 있습니다.
   사용할 POP3 서버를 신뢰하기 전에 이 메서드를 수동으로 테스트하십시
   오.

POP3.uidl(which=None)

   메시지 다이제스트 (고유 ID) 목록을 반환합니다. *which*가 지정되면,
   결과에는 해당 메시지의 고유 ID가 "'response mesgnum uid" 형식으로
   포함됩니다. 그렇지 않으면, 결과는 목록 "(response, ['mesgnum uid',
   ...], octets)"입니다.

POP3.utf8()

   UTF-8 모드로의 전환을 시도합니다. 성공하면 서버 응답을 반환하고, 그
   렇지 않으면 "error_proto"를 발생시킵니다. **RFC 6856**에서 정의되었
   습니다.

   Added in version 3.5.

POP3.stls(context=None)

   **RFC 2595**에 지정된 대로 활성 연결에서 TLS 세션을 시작합니다. 사
   용자 인증 전에만 허용됩니다.

   *context* 매개 변수는 "ssl.SSLContext" 객체인데, SSL 구성 옵션, 인
   증서 및 개인 키를 단일 (잠재적으로 수명이 긴) 구조로 묶을 수 있도록
   합니다. 모범 사례는 보안 고려 사항을 읽으십시오.

   이 메서드는 "ssl.SSLContext.check_hostname"을 통한 호스트 이름 검사
   와 *서버 이름 표시(Server Name Indication)*를 지원합니다
   ("ssl.HAS_SNI"를 참조하십시오)

   Added in version 3.4.

"POP3_SSL"의 인스턴스에는 추가 메서드가 없습니다. 이 서브 클래스의 인
터페이스는 그 부모와 같습니다.


POP3 예제
=========

다음은 우편함을 열고 모든 메시지를 가져와서 인쇄하는 (에러 검사 없는)
최소한의 예입니다:

   import getpass, poplib

   M = poplib.POP3('localhost')
   M.user(getpass.getuser())
   M.pass_(getpass.getpass())
   numMessages = len(M.list()[1])
   for i in range(numMessages):
       for j in M.retr(i+1)[1]:
           print(j)

모듈의 끝에는, 더욱 광범위한 사용 예제가 포함된 테스트 섹션이 있습니다
.
