imaplib --- IMAP4 프로토콜 클라이언트

소스 코드: Lib/imaplib.py

이 모듈은 IMAP4, IMAP4_SSL 및 IMAP4_stream의 세 가지 클래스를 정의합니다. 이 클래스는 IMAP4 서버에 대한 연결을 캡슐화하고 RFC 2060에 정의된 대로 IMAP4rev1 클라이언트 프로토콜의 큰 부분 집합을 구현합니다. IMAP4 (RFC 1730) 서버와 하위 호환되지만, IMAP4에서는 STATUS 명령이 지원되지 않음에 유의하십시오.

imaplib 모듈은 세 가지 클래스를 제공하며, IMAP4는 베이스 클래스입니다:

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)

이 클래스는 실제 IMAP4 프로토콜을 구현합니다. 연결이 만들어지고 인스턴스가 초기화될 때 프로토콜 버전(IMAP4 또는 IMAP4rev1)이 결정됩니다. host를 지정하지 않으면, ''(로컬 호스트)가 사용됩니다. port를 생략하면, 표준 IMAP4 포트(143)가 사용됩니다. 선택적 timeout 매개 변수는 연결 시도에 대한 시간제한을 초로 지정합니다. timeout이 제공되지 않거나 None이면, 전역 기본 소켓 시간제한이 사용됩니다.

IMAP4 클래스는 with 문을 지원합니다. 이처럼 사용될 때, with 문을 빠져나갈 때 IMAP4 LOGOUT 명령이 자동으로 발행됩니다. 예를 들어:

>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

버전 3.5에서 변경: with 문에 대한 지원이 추가되었습니다.

버전 3.9에서 변경: 선택적 timeout 매개 변수가 추가되었습니다.

세 가지 예외가 IMAP4 클래스의 어트리뷰트로 정의됩니다:

exception IMAP4.error

모든 에러에 대해 발생하는 예외. 예외의 이유는 문자열로 생성자에 전달됩니다.

exception IMAP4.abort

IMAP4 서버 에러는 이 예외를 발생시킵니다. 이것은 IMAP4.error의 서브 클래스입니다. 인스턴스를 닫고 새 인스턴스를 만들면 일반적으로 이 예외에서 복구할 수 있습니다.

exception IMAP4.readonly

쓰기 가능한 사서함(mailbox)의 상태가 서버에 의해 변경되면 이 예외가 발생합니다. 이것은 IMAP4.error의 서브 클래스입니다. 이제 일부 다른 클라이언트에는 쓰기 권한이 있으며, 쓰기 권한을 다시 얻으려면 사서함을 다시 열어야 합니다.

보안 연결을 위한 서브 클래스도 있습니다:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None, timeout=None)

SSL 암호화 소켓을 통해 연결되는 IMAP4에서 파생된 서브 클래스입니다 (이 클래스를 사용하려면 SSL 지원과 함께 컴파일된 소켓 모듈이 필요합니다). host를 지정하지 않으면, ''(로컬 호스트)가 사용됩니다. port를 생략하면, 표준 IMAP4-over-SSL 포트(993)가 사용됩니다. ssl_context는 SSL 구성 옵션, 인증서 및 개인 키를 단일 (잠재적으로 오래가는) 구조로 번들링 할 수 있는 ssl.SSLContext 객체입니다. 모범 사례는 보안 고려 사항을 읽으십시오.

keyfile과 certfile은 ssl_context의 레거시 대안입니다 - SSL 연결을 위한 PEM 형식 개인 키와 인증서 체인 파일을 가리킬 수 있습니다. keyfile/certfile 매개 변수는 ssl_context와 상호 배타적이며, keyfile/certfile이 ssl_context와 함께 제공되면 ValueError가 발생함에 유의하십시오.

선택적 timeout 매개 변수는 연결 시도에 대한 시간제한을 초로 지정합니다. timeout이 제공되지 않거나 None이면, 전역 기본 소켓 시간제한이 사용됩니다.

버전 3.3에서 변경: ssl_context 매개 변수가 추가되었습니다.

버전 3.4에서 변경: 이 클래스는 이제 ssl.SSLContext.check_hostname과 서버 이름 표시(Server Name Indication)로 호스트명 확인을 지원합니다 (ssl.HAS_SNI를 참조하십시오).

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

버전 3.9에서 변경: 선택적 timeout 매개 변수가 추가되었습니다.

두 번째 서브 클래스는 자식 프로세스가 만든 연결을 허용합니다:

class imaplib.IMAP4_stream(command)

이것은 command를 subprocess.Popen()에 전달하여 만들어진 stdin/stdout 파일 기술자에 연결하는 IMAP4에서 파생된 서브 클래스입니다.

다음과 같은 유틸리티 함수가 정의됩니다:

imaplib.Internaldate2tuple(datestr)

IMAP4 INTERNALDATE 문자열을 구문 분석하고 해당 지역 시간을 반환합니다. 반환 값은 time.struct_time 튜플이거나 문자열의 형식이 잘못되면 None입니다.

imaplib.Int2AP(num)

집합 [A .. P]의 문자를 사용하여 정수를 바이트열 표현으로 변환합니다.

imaplib.ParseFlags(flagstr)

IMAP4 FLAGS 응답을 개별 플래그의 튜플로 변환합니다.

imaplib.Time2Internaldate(date_time)

date_time을 IMAP4 INTERNALDATE 표현으로 변환합니다. 반환 값은 다음과 같은 형식의 문자열입니다: "DD-Mmm-YYYY HH:MM:SS +HHMM" (큰따옴표를 포함합니다). date_time 인자는 에포크 이후의 초(time.time()이 반환하는 것과 같습니다)를 나타내는 숫자 (int 또는 float), 지역 시간을 나타내는 9-튜플인 time.struct_time의 인스턴스 (time.localtime()이 반환하는 것과 같습니다), datetime.datetime의 어웨어(aware) 인스턴스 또는 큰따옴표로 인용된(double-quoted) 문자열일 수 있습니다. 마지막 경우에는, 이미 올바른 형식으로 되어 있다고 가정합니다.

사서함이 변경됨에 따라 IMAP4 메시지 번호가 변경됨에 유의하십시오. 특히, EXPUNGE 명령이 삭제를 수행한 후 나머지 메시지의 번호가 다시 매겨집니다. 따라서 UID 명령으로 UID를 대신 사용하는 것이 좋습니다.

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

더 보기

워싱턴 대학의 IMAP Information Center의 프로토콜을 설명하는 문서와 이를 구현하는 서버의 소스는 모두 (소스 코드) https://github.com/uw-imap/imap 에서 찾을 수 있습니다 (유지 보수되지 않습니다).

IMAP4 객체

모든 IMAP4rev1 명령은 대문자나 소문자의 같은 이름의 메서드로 표현됩니다.

AUTHENTICATE와 IMAP4 리터럴로 전달되는 APPEND에 대한 마지막 인자를 제외하고, 명령에 대한 모든 인자는 문자열로 변환됩니다. 필요하면 (문자열에 IMAP4 프로토콜에 참여하는 문자가 포함되고 괄호나 큰따옴표로 묶이지 않았으면) 각 문자열이 인용됩니다. 그러나, LOGIN 명령에 대한 password 인자는 항상 인용됩니다. 인자 문자열이 인용되지 않도록 하려면 (예를 들어: STORE에 대한 flags 인자) 문자열을 괄호로 묶으십시오 (예를 들어: r'(\Deleted)').

각 명령은 튜플을 반환합니다: (type, [data, ...]) 여기서 type은 일반적으로 'OK'나 'NO'이며, data는 명령 응답의 텍스트이거나 명령의 위임된(mandated) 결과입니다. 각 data는 bytes이거나 튜플입니다. 튜플이면, 첫 번째 부분은 응답의 헤더이고, 두 번째 부분은 데이터를 포함합니다 (즉: 'literal' 값).

아래 명령에 대한 message_set 옵션은 수행할 하나 이상의 대상 메시지를 지정하는 문자열입니다. 단순 메시지 번호 ('1'), 메시지 번호 범위 ('2:4') 또는 쉼표로 구분된 불연속 범위 그룹('1:3,6:9')일 수 있습니다. 범위에는 별표가 포함되어 무한 상한을 나타낼 수 있습니다 ('3:*').

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

IMAP4.append(mailbox, flags, date_time, message)

명명된 사서함(mailbox)에 message를 추가합니다.

IMAP4.authenticate(mechanism, authobject)

인증 명령 --- 응답 처리가 필요합니다.

mechanism은 사용할 인증 메커니즘을 지정합니다 - 인스턴스 변수 capabilities에 AUTH=mechanism 형식으로 나타나야 합니다.

authobject는 콜러블 객체여야 합니다:

data = authobject(response)

서버 계속(continuation) 응답을 처리하기 위해 호출됩니다; 전달된 response 인자는 bytes입니다. base64로 인코딩되어 서버로 전송되는 bytes data를 반환해야 합니다. 클라이언트 중단 응답 *를 대신 보내야 하면 None을 반환해야 합니다.

버전 3.5에서 변경: 문자열 사용자 이름과 비밀번호는 이제 ASCII로 제한되지 않고 utf-8로 인코딩됩니다.

IMAP4.check()

서버의 사서함을 검사합니다.

IMAP4.close()

현재 선택된 사서함을 닫습니다. 삭제된 메시지는 쓰기 가능한 사서함에서 제거됩니다. LOGOUT 이전의 권장 명령입니다.

IMAP4.copy(message_set, new_mailbox)

message_set 메시지를 new_mailbox 끝에 복사합니다.

IMAP4.create(mailbox)

mailbox라는 이름의 새 사서함을 만듭니다.

IMAP4.delete(mailbox)

mailbox라는 이름의 기존 사서함을 삭제합니다.

IMAP4.deleteacl(mailbox, who)

사서함(mailbox)의 사용자(who)에 대해 설정된 ACL을 삭제합니다 (모든 권한을 제거합니다).

IMAP4.enable(capability)

capability를 활성화합니다 (RFC 5161을 참조하십시오). 대부분의 기능은 활성화할 필요 없습니다. 현재 UTF8=ACCEPT 기능만 지원됩니다 (RFC 6855를 참조하십시오).

버전 3.5에 추가: enable() 메서드 자체와 RFC 6855 지원.

IMAP4.expunge()

선택한 사서함에서 삭제된 항목을 영구적으로 제거합니다. 삭제된 각 메시지에 대해 EXPUNGE 응답을 생성합니다. 반환된 데이터에는 수신된 순서의 EXPUNGE 메시지 번호 리스트가 포함됩니다.

IMAP4.fetch(message_set, message_parts)

메시지(일부)를 가져옵니다. message_parts는 괄호로 묶인 메시지 부분 이름의 문자열이어야 합니다, 예를 들어: "(UID BODY[TEXT])"). 반환된 데이터는 메시지 부분 봉투와 데이터의 튜플입니다.

IMAP4.getacl(mailbox)

mailbox에 대한 ACL을 가져옵니다. 이 메서드는 비표준이지만, Cyrus 서버에서 지원됩니다.

IMAP4.getannotation(mailbox, entry, attribute)

mailbox에 대해 지정된 ANNOTATION을 가져옵니다. 이 메서드는 비표준이지만, Cyrus 서버에서 지원됩니다.

IMAP4.getquota(root)

quota root의 자원 사용량과 제한을 가져옵니다. 이 메서드는 rfc2087에 정의된 IMAP4 QUOTA 확장의 일부입니다.

IMAP4.getquotaroot(mailbox)

명명된 mailbox에 대한 quota roots 리스트를 가져옵니다. 이 메서드는 rfc2087에 정의된 IMAP4 QUOTA 확장의 일부입니다.

IMAP4.list([directory[, pattern]])

directory에 있는 pattern과 일치하는 사서함 이름을 나열합니다. directory는 기본적으로 최상위 메일 폴더이며, pattern은 기본적으로 모든 것과 일치합니다. 반환된 데이터는 LIST의 리스트를 포함합니다.

IMAP4.login(user, password)

평문 비밀번호를 사용하여 클라이언트를 식별합니다. password는 인용됩니다.

IMAP4.login_cram_md5(user, password)

암호를 보호하기 위해 클라이언트를 식별할 때 CRAM-MD5 인증의 사용을 강제합니다. 서버 CAPABILITY 응답에 문구 AUTH=CRAM-MD5가 포함된 경우에만 작동합니다.

IMAP4.logout()

서버에 대한 연결을 종료합니다. 서버 BYE 응답을 반환합니다.

버전 3.8에서 변경: 이 메서드는 더는 임의의 예외를 조용히 무시하지 않습니다.

IMAP4.lsub(directory='""', pattern='*')

directory에 있는 pattern과 일치하는 구독한(subscribed) 사서함 이름을 나열합니다. directory는 기본적으로 최상위 디렉터리이고 pattern은 기본적으로 모든 사서함과 일치합니다. 반환된 데이터는 메시지 부분 봉투와 데이터의 튜플입니다.

IMAP4.myrights(mailbox)

mailbox에 대한 현재 사용자의 ACL(즉, 사서함에 대해 가진 권한)을 표시합니다.

IMAP4.namespace()

RFC 2342에 정의된 대로 IMAP 이름 공간을 반환합니다.

IMAP4.noop()

서버에 NOOP을 보냅니다.

IMAP4.open(host, port, timeout=None)

host의 port로 소켓을 엽니다. 선택적 timeout 매개 변수는 연결 시도에 대한 시간제한을 초로 지정합니다. timeout이 제공되지 않거나 None이면, 전역 기본 소켓 시간제한이 사용됩니다. 또한 timeout 매개 변수가 0으로 설정되면, 비 블로킹 소켓을 만들지 못하도록 ValueError를 발생시킴에 유의하십시오. 이 메서드는 IMAP4 생성자에 의해 묵시적으로 호출됩니다. 이 메서드로 맺어진 연결 객체는 IMAP4.read(), IMAP4.readline(), IMAP4.send() 및 IMAP4.shutdown() 메서드에서 사용됩니다. 이 메서드를 재정의할 수 있습니다.

인자 self, host, port로 감사 이벤트 imaplib.open을 발생시킵니다.

버전 3.9에서 변경: timeout 매개 변수가 추가되었습니다.

IMAP4.partial(message_num, message_part, start, length)

메시지의 잘린 부분을 가져옵니다. 반환된 데이터는 메시지 부분 봉투와 데이터의 튜플입니다.

IMAP4.proxyauth(user)

인증을 user로 가정합니다. 권한 있는 관리자가 모든 사용자의 사서함으로 프락시 하도록 합니다.

IMAP4.read(size)

원격 서버에서 size 바이트를 읽습니다. 이 메서드를 재정의할 수 있습니다.

IMAP4.readline()

원격 서버에서 한 줄을 읽습니다. 이 메서드를 재정의할 수 있습니다.

IMAP4.recent()

업데이트를 서버에 요청합니다. 새 메시지가 없으면 반환된 데이터는 None이고, 그렇지 않으면 RECENT 응답의 값입니다.

IMAP4.rename(oldmailbox, newmailbox)

이름이 oldmailbox인 사서함의 이름을 newmailbox로 바꿉니다.

IMAP4.response(code)

수신되었다면 응답 code에 대한 데이터를 반환합니다, 또는 None을 반환합니다. 일반적인 유형 대신, 지정된 코드를 반환합니다.

IMAP4.search(charset, criterion[, ...])

일치하는 메시지가 있는지 사서함을 검색합니다. charset은 None일 수 있으며, 이 경우 서버에 대한 요청에 CHARSET이 지정되지 않습니다. IMAP 프로토콜은 적어도 하나의 기준을 지정하도록 요구합니다; 서버가 에러를 반환하면 예외가 발생합니다. enable() 명령을 사용하여 UTF8=ACCEPT 기능이 활성화되면 charset은 None이어야 합니다.

예:

# M은 연결된 IMAP4 인스턴스입니다...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# 또는:
typ, msgnums = M.search(None, '(FROM "LDJ")')
IMAP4.select(mailbox='INBOX', readonly=False)

사서함을 선택합니다. 반환된 데이터는 mailbox에 있는 메시지 수입니다 (EXISTS 응답). 기본 mailbox는 'INBOX'입니다. readonly 플래그가 설정되면, 사서함을 수정할 수 없습니다.

IMAP4.send(data)

data를 원격 서버로 보냅니다. 이 메서드를 재정의할 수 있습니다.

인자 self, data로 감사 이벤트 imaplib.send를 발생시킵니다.

IMAP4.setacl(mailbox, who, what)

mailbox에 대한 ACL을 설정합니다. 이 메서드는 비표준이지만, Cyrus 서버에서 지원됩니다.

IMAP4.setannotation(mailbox, entry, attribute[, ...])

mailbox에 대한 ANNOTATION을 설정합니다. 이 메서드는 비표준이지만, Cyrus 서버에서 지원됩니다.

IMAP4.setquota(root, limits)

quota root의 자원 한도(limits)를 설정합니다. 이 메서드는 rfc2087에 정의된 IMAP4 QUOTA 확장의 일부입니다.

IMAP4.shutdown()

open에서 맺은 연결을 닫습니다. 이 메서드는 IMAP4.logout()에 의해 묵시적으로 호출됩니다. 이 메서드를 재정의할 수 있습니다.

IMAP4.socket()

서버에 연결하는 데 사용된 소켓 인스턴스를 반환합니다.

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])

sort 명령은 결과에 대한 정렬이 추가된 search의 변형입니다. 반환된 데이터는 일치하는 메시지 번호의 공백으로 구분된 목록을 포함합니다.

sort에는 search_criterion 인자 앞에 두 개의 인자가 있습니다; sort_criteria의 괄호로 묶은 목록과 검색 charset. search와 달리, 검색 charset 인자는 필수임에 유의하십시오. uid search가 search에 해당하는 방식으로 sort에 해당하는 uid sort 명령도 있습니다. sort 명령은 먼저 검색 기준의 문자열 해석을 위해 charset 인자를 사용하여 주어진 검색 기준과 일치하는 메시지를 사서함에서 검색합니다. 그런 다음 일치하는 메시지 수를 반환합니다.

이것은 IMAP4rev1 확장 명령입니다.

IMAP4.starttls(ssl_context=None)

STARTTLS 명령을 보냅니다. ssl_context 인자는 선택적이며 ssl.SSLContext 객체여야 합니다. IMAP 연결의 암호화를 활성화합니다. 모범 사례는 보안 고려 사항을 읽으십시오.

버전 3.2에 추가.

버전 3.4에서 변경: 이 메서드는 이제 ssl.SSLContext.check_hostname과 서버 이름 표시(Server Name Indication)로 호스트명 확인을 지원합니다 (ssl.HAS_SNI를 참조하십시오).

IMAP4.status(mailbox, names)

mailbox에 대한 명명된 상태 조건(status conditions)을 요청합니다.

IMAP4.store(message_set, command, flag_list)

사서함의 메시지에 대한 플래그 속성을 변경합니다. command는 RFC 2060의 섹션 6.4.6에서 "FLAGS", "+ FLAGS" 또는 "-FLAGS" 중 하나로 지정되고, 선택적으로 ".SILENT" 접미사를 갖습니다.

예를 들어, 모든 메시지에 삭제 플래그를 설정하려면 다음을 수행합니다:

typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()

참고

']'을 포함하는 플래그를 만드는 것은 (예를 들어: "[test]") RFC 3501(IMAP 프로토콜)을 위반합니다. 그러나, imaplib는 역사적으로 이러한 태그를 만들 수 있도록 허락했고, Gmail과 같은 널리 사용되는 IMAP 서버는 이러한 플래그를 받아들이고 생성합니다. 역시 이러한 태그를 생성하는 비 파이썬 프로그램이 있습니다. RFC 위반이고 IMAP 클라이언트와 서버가 엄격해야 하기는 하지만, 그런데도 imaplib는 이전 버전과의 호환성을 위해 이러한 태그를 만들도록 계속 허락하며, 파이썬 3.6부터는 실제 호환성을 향상하기 때문에 서버에서 보낸다면 처리합니다.

IMAP4.subscribe(mailbox)

새 사서함을 구독합니다.

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

thread 명령은 결과에 대한 스레딩이 추가된 search의 변형입니다. 반환된 데이터는 스레드 구성원의 스페이스로 구분된 목록을 포함합니다.

스레드 구성원은 연속된 부모와 자식을 나타내는 스페이스로 구분된 0개 이상의 메시지 번호로 구성됩니다.

thread에는 search_criterion 인자 앞에 두 개의 인자가 있습니다; threading_algorithm과 검색 charset. search와 달리, 검색 charset 인자는 필수임에 유의하십시오. uid search가 search에 해당하는 방식으로 thread에 해당하는 uid thread 명령도 있습니다. thread 명령은 먼저 검색 기준의 문자열 해석을 위해 charset 인자를 사용하여 주어진 검색 기준과 일치하는 메시지를 사서함에서 검색합니다. 그런 다음 지정된 스레딩 알고리즘에 따라 스레드 된 일치 메시지들을 반환합니다.

이것은 IMAP4rev1 확장 명령입니다.

IMAP4.uid(command, arg[, ...])

메시지 번호가 아닌 UID로 식별된 메시지들로 명령 인자를 실행합니다. 명령에 적합한 응답을 반환합니다. 최소한 하나의 인자가 제공되어야 합니다; 아무것도 제공하지 않으면, 서버는 에러를 반환하고 예외가 발생합니다.

IMAP4.unsubscribe(mailbox)

기존 사서함에서 구독 취소합니다.

IMAP4.unselect()

imaplib.IMAP4.unselect()는 선택한 사서함과 관련된 서버 자원을 해제하고 서버를 인증된 상태로 되돌립니다. 이 명령은 현재 선택된 사서함에서 메시지가 영구적으로 제거되지 않는다는 점을 제외하고, imaplib.IMAP4.close()와 같은 작업을 수행합니다.

버전 3.9에 추가.

IMAP4.xatom(name[, ...])

CAPABILITY 응답에서 서버가 통지한 간단한 확장 명령을 허용합니다.

IMAP4 인스턴스에는 다음과 같은 어트리뷰트가 정의되어 있습니다:

IMAP4.PROTOCOL_VERSION

서버의 CAPABILITY 응답에서 가장 최근에 지원되는 프로토콜.

IMAP4.debug

디버깅 출력을 제어하기 위한 정숫값. 초기화 값은 모듈 변수 Debug에서 취합니다. 3보다 큰 값은 각 명령을 추적합니다.

IMAP4.utf8_enabled

일반적으로 False이지만, UTF8=ACCEPT 기능에 대해 enable() 명령이 성공적으로 발행되면 True로 설정되는 불리언 값.

버전 3.5에 추가.

IMAP4 예

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

import getpass, imaplib

M = imaplib.IMAP4()
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()