"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" 클래스를 사용하는 것이 좋습니다.

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

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

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

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

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

   *keyfile*과 *certfile*은 *context*의 레거시 대안입니다 - SSL 연결을
   위해 각각 PEM 형식의 개인 키와 인증서 체인 파일을 가리킬 수 있습니
   다.

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

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

   버전 3.6부터 폐지: *keyfile*과 *certfile*은 폐지되었고, *context*로
   대체합니다. 대신 "ssl.SSLContext.load_cert_chain()"을 사용하거나,
   "ssl.create_default_context()"가 시스템의 신뢰할 수 있는 CA 인증서
   를 선택하도록 하십시오.

한가지 예외가 "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'...]}" 형식의 딕셔너리를 반환합니다.

   버전 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**에서 정의되었
   습니다.

   버전 3.5에 추가.

POP3.stls(context=None)

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

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

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

   버전 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)

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