`imaplib` --- کلاینت پروتکل IMAP4¶

کد منبع: Lib/imaplib.py

این ماژول سه کلاس IMAP4، IMAP4_SSL و IMAP4_stream را تعریف می‌کند، که اتصال به یک سرور IMAP4 را کپسوله می‌کنند و زیرمجموعه‌ی بزرگی از پروتکل کلاینت IMAP4rev1 را، همان‌طور که در RFC 3501 تعریف شده است، پیاده‌سازی می‌کنند. این ماژول با سرورهای IMAP4 (RFC 1730) سازگاری رو به عقب دارد، اما توجه داشته باشید که دستور STATUS در IMAP4 پشتیبانی نمی‌شود.

دسترس‌پذیری: not WASI.

این ماژول روی WebAssembly کار نمی‌کند یا در دسترس نیست. برای اطلاعات بیشتر، سکوهای WebAssembly را ببینید.

ماژول imaplib سه کلاس را ارائه می‌دهد، IMAP4 کلاس پایه است:

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

این کلاس پروتکل واقعی IMAP4 را پیاده‌سازی می‌کند. هنگام مقداردهی اولیه‌ی نمونه، اتصال ایجاد می‌شود و نسخه‌ی پروتکل (IMAP4 یا IMAP4rev1) تعیین می‌شود. اگر host مشخص نشده باشد، '' (میزبان محلی) استفاده می‌شود. اگر port ذکر نشود، پورت استاندارد IMAP4 (۱۴۳) استفاده می‌شود. پارامتر اختیاری timeout، مهلت زمانی را به ثانیه برای تلاش اتصال مشخص می‌کند. اگر مهلت داده نشود یا None باشد، مهلت پیش‌فرض سراسری سوکت استفاده می‌شود.

کلاس IMAP4 از دستور with پشتیبانی می‌کند. هنگامی که به این شکل استفاده شود، با خروج از دستور with، فرمان LOGOUT IMAP4 به‌طور خودکار صادر می‌شود. مثلاً:

>>> 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¶: این استثنا زمانی پرتاب می‌شود که وضعیت یک صندوق پستی قابل‌نوشتن توسط سرور تغییر کند. این استثنا زیرکلاسی از IMAP4.error است. اکنون کلاینت دیگری اجازه‌ی نوشتن دارد و برای به دست آوردن دوباره‌ی اجازه‌ی نوشتن، باید صندوق پستی دوباره باز شود.

همچنین یک زیرکلاس برای اتصالات امن وجود دارد:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)¶

این یک زیرکلاس مشتق‌شده از IMAP4 است که از طریق یک سوکت رمزنگاری‌شده با SSL متصل می‌شود (برای استفاده از این کلاس، به یک ماژول socket نیاز دارید که با پشتیبانی از SSL کامپایل شده باشد). اگر host مشخص نشده باشد، از '' (میزبان محلی) استفاده می‌شود. اگر port حذف شده باشد، از پورت استاندارد IMAP4-over-SSL (۹۹۳) استفاده می‌شود. ssl_context یک شیء ssl.SSLContext است که امکان تجمیع گزینه‌های پیکربندی SSL، گواهی‌ها و کلیدهای خصوصی را در یک ساختار واحد (که ممکن است طولانی‌مدت باشد) فراهم می‌کند. لطفاً برای بهترین شیوه‌ها، ملاحظات امنیتی را مطالعه کنید.

توجه

با ssl_context پیش‌فرض، اتصال رمزگذاری شده است، اما گواهی سرور و نام میزبان تأیید نمی‌شوند. برای تأیید آن‌ها، یک زمینه ایجادشده توسط ssl.create_default_context() را ارسال کنید.

پارامتر اختیاری timeout، مهلت زمانی‌ای را بر حسب ثانیه برای تلاش اتصال مشخص می‌کند. اگر timeout داده نشود یا None باشد، از مهلت زمانی پیش‌فرض سراسری سوکت استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.3: پارامتر ssl_context اضافه شد.

تغییر یافته در نسخه‌ی 3.4: این کلاس اکنون از بررسی نام میزبان با ssl.SSLContext.check_hostname و Server Name Indication (ببینید ssl.HAS_SNI) پشتیبانی می‌کند.

تغییر یافته در نسخه‌ی 3.9: پارامتر اختیاری timeout افزوده شد.

تغییر یافته در نسخه‌ی 3.12: پارامترهای keyfile و certfile که منسوخ‌شده بودند، حذف شده‌اند.

دومین زیرکلاس امکان اتصال‌هایی را که توسط یک فرآیند فرزند ایجاد شده‌اند، فراهم می‌کند:

class imaplib.IMAP4_stream(command)¶: این زیرکلاسی مشتق‌شده از IMAP4 است که به توصیف‌گرهای پرونده stdin/stdout ایجادشده از طریق ارسال command به subprocess.Popen() متصل می‌شود.

توابع ابزار زیر تعریف شده‌اند:

imaplib.Internaldate2tuple(resp)¶: یک bytes-like object حاوی پاسخ IMAP4 INTERNALDATE را تجزیه می‌کند و زمان محلی متناظر را برمی‌گرداند. مقدار بازگشتی یک تاپل time.struct_time یا None است اگر ورودی قالب نادرستی داشته باشد.

imaplib.Int2AP(num)¶: یک عدد صحیح را با استفاده از نویسه‌های مجموعه‌ی [A .. P] به یک نمایش بایتی تبدیل می‌کند.

imaplib.ParseFlags(resp)¶: یک bytes-like object حاوی پاسخ FLAGS IMAP4 را به یک تاپل از پرچم‌های جداگانه به‌صورت bytes تبدیل می‌کند. اگر ورودی قالب نادرستی داشته باشد، مقدار بازگشتی یک تاپل خالی است.

imaplib.Time2Internaldate(date_time)¶: date_time را به نمایش INTERNALDATE در IMAP4 تبدیل می‌کند. مقدار بازگشتی یک رشته به شکل: "DD-Mmm-YYYY HH:MM:SS +HHMM" (شامل علامت‌های نقل‌قول دوتایی) است. آرگومان date_time می‌تواند یک عدد (int یا float) باشد که ثانیه‌های سپری‌شده از مبدأ زمان را نشان می‌دهد (مانند آنچه time.time() بازمی‌گرداند)، یک تاپل ۹تایی که زمان محلی را نشان می‌دهد، یک نمونه از time.struct_time (مانند آنچه time.localtime() بازمی‌گرداند)، یک نمونه آگاه از datetime.datetime، یا یک رشته‌ی دارای علامت‌های نقل‌قول دوتایی باشد. در آخرین حالت، فرض می‌شود که از قبل در قالب صحیح باشد.

توجه داشته باشید که شماره‌های پیام IMAP4 با تغییر صندوق پستی تغییر می‌کنند؛ به‌ویژه، پس از اینکه دستور EXPUNGE حذف‌ها را انجام داد، پیام‌های باقی‌مانده دوباره شماره‌گذاری می‌شوند. بنابراین بسیار توصیه می‌شود که به‌جای آن‌ها از UIDها، همراه با دستور UID استفاده کنید.

در انتهای ماژول، یک بخش آزمایش وجود دارد که شامل نمونه‌ای مفصل‌تر از کاربرد است.

همچنین ملاحظه نمائید

اسناد توصیف‌کننده پروتکل، کدهای منبع سرورهایی که آن را پیاده‌سازی می‌کنند، تهیه‌شده توسط مرکز اطلاعات IMAP دانشگاه واشینگتن، همگی در (کد منبع) https://github.com/uw-imap/imap (نگه‌داری نمی‌شود) یافت می‌شوند.

اشیای IMAP4¶

تمام دستورات IMAP4rev1 با متدهایی به همان نام، چه با حروف بزرگ و چه با حروف کوچک، بازنمایی می‌شوند.

All arguments to commands are converted to strings, except for AUTHENTICATE, and the last argument to APPEND which is passed as an IMAP4 literal. If necessary (the string contains IMAP4 protocol-sensitive characters and isn't enclosed with either parentheses or double quotes) each string is quoted. However, the password argument to the LOGIN command is always quoted. If you want to avoid having an argument string quoted (eg: the flags argument to STORE) then enclose the string in parentheses (eg: r'(\Deleted)'). Or you can quote the string yourself; an argument that is already enclosed in double quotes is left unchanged. In general, however, it is better to pass arguments unquoted and let the module quote them as needed.

Mailbox names are encoded as modified UTF-7 (RFC 3501, section 5.1.3), so a mailbox name containing non-ASCII characters can be passed as an ordinary str. A str that is already valid modified UTF-7 is left unchanged, so that a name obtained from list() (raw bytes decoded to text) round-trips; pass bytes to send the exact bytes with no encoding. When UTF8=ACCEPT is enabled (see enable()), mailbox names are sent as UTF-8 instead.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Non-ASCII mailbox names are automatically encoded as modified UTF-7.

بیشتر دستورها یک تاپلبرمی‌گردانند: (type, [data, ...]) که در آن type معمولاً 'OK' یا 'NO' است، و data یا متن پاسخ دستور است، یا نتایج الزامی دستور. هر data یا یک bytes است، یا یک تاپل. اگر یک تاپل باشد، بخش اول سرآیند پاسخ است، و بخش دوم شامل داده است (یعنی مقدار 'literal').

The message_set options to the commands below can be a string specifying one or more messages to be acted upon. It may be a simple message number ('1'), a range of message numbers ('2:4'), or a group of non-contiguous ranges separated by commas ('1:3,6:9'). A range can contain an asterisk to indicate an infinite upper bound ('3:*').

Alternatively it can be specified using integers and range objects. It may be a single message number or a sequence. The sequence items may be integers, (start, stop) tuples (where None or '*' stands for the last message), or range objects. For example, [1, (3, 5), 8] and [range(1, 6), 8] are both equivalent to '1,3:5,8'.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added support for the structured message_set.

Command arguments that are parenthesized lists of atoms --- such as the flag_list argument of store() and the flags argument of append(), the names argument of status(), the sort_criteria argument of sort(), or the message_parts argument of fetch() --- can be passed as a sequence of strings instead of a single preformatted string. For example, [r'\Seen', r'\Answered'] is equivalent to (\Seen \Answered).

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added support for passing these arguments as a sequence.

The value-bearing arguments of the search and fetch commands can be quoted by hand, but this is error prone. Instead, they may contain ? placeholders that are substituted, and quoted as required, from a params keyword argument, in the manner of sqlite3 parameter substitution:

# SEARCH FROM me@example.com SUBJECT "trip report"
M.search(None, 'FROM ? SUBJECT ?', params=['me@example.com', 'trip report'])

# FETCH 1:5 (FLAGS BODY[HEADER.FIELDS (DATE FROM)])
M.fetch('1:5', 'FLAGS BODY[HEADER.FIELDS ?]', params=[['DATE', 'FROM']])

The placeholders are:

? --- an astring: a string (which will be quoted if necessary), an integer, or a list of integers and/or strings (which will be sent as a parenthesized list);
?f --- a flag or a list of flags, sent verbatim without quoting;
?s --- a message_set in the structured form described above.

?? stands for a literal ?.

Substitution is only performed when params is given; if no params are given, an argument containing a literal ? is unchanged. The params keyword is accepted by search(), fetch(), sort(), thread() and uid().

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased): The params keyword argument.

یک نمونه از IMAP4 دارای متدهای زیر است:

IMAP4.append(mailbox, flags, date_time, message, *, translate_line_endings=True)¶

message را به صندوق پستی نام‌گذاری‌شده می‌افزاید.

flags می‌تواند None یا رشته‌ای از توکن‌های پرچم IMAP باشد. پرچم‌های متعدد با فاصله از یکدیگر جدا می‌شوند، برای مثال r'\Seen \Answered'. اگر flags از قبل در پرانتز قرار نداشته باشد، پرانتزها به‌طور خودکار اضافه می‌شوند.

If translate_line_endings is true (the default), line endings in message are translated to CRLF. Pass False to send the message literal exactly as given, which is required to preserve messages that contain bare CR or LF. In that case message must already use CRLF line endings as required by RFC 3501; for example, serialize email messages using email.policy.SMTP.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the translate_line_endings parameter.

IMAP4.authenticate(mechanism, authobject)¶

فرمان احراز هویت --- به پردازش پاسخ نیاز دارد.

mechanism مشخص می‌کند که کدام سازوکار احراز هویت باید استفاده شود؛ این سازوکار باید در متغیر نمونه capabilities به شکل AUTH=mechanism ظاهر شود.

authobject باید یک شیء فراخوانی‌پذیر باشد:

data = authobject(response)

برای پردازش پاسخ‌های ادامه‌ی سرور فراخوانی خواهد شد؛ آرگومان response که به آن داده می‌شود، bytes خواهد بود. باید data از نوع bytes را برگرداند که به‌صورت base64 کدگذاری و به سرور ارسال خواهد شد. اگر به‌جای آن باید پاسخ لغو کلاینت * ارسال شود، باید None برگرداند.

تغییر یافته در نسخه‌ی 3.5: نام‌های کاربری و گذرواژه‌های رشته‌ای اکنون به‌جای محدود بودن به ASCII، به utf-8 کدگذاری می‌شوند.

IMAP4.check()¶: نقطه بازرسی صندوق پستی را روی سرور ایجاد کنید.

IMAP4.close()¶: صندوق پستی انتخاب‌شده‌ی فعلی را می‌بندد. پیام‌های حذف‌شده از صندوق پستی قابل‌نوشتن حذف می‌شوند. این فرمان توصیه‌شده پیش از LOGOUT است.

IMAP4.copy(message_set, new_mailbox, *, uid=False)¶

پیام‌های message_set را به انتهای new_mailbox کپی کنید.

If uid is true, message_set is a set of UIDs and the UID COPY command is used instead of COPY.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the uid parameter.

IMAP4.create(mailbox)¶: صندوق پستی جدیدی با نام mailbox ایجاد کنید.

IMAP4.delete(mailbox)¶: صندوق پستی قدیمی به نام mailbox را حذف کنید.

IMAP4.deleteacl(mailbox, who)¶: فهرست‌های کنترل دسترسی (ACLs) تنظیم‌شده برای who بر روی mailbox را حذف کنید (هرگونه حقی را بردارید).

IMAP4.enable(capability)¶: فعال‌سازی capability (ببینید RFC 5161). بیشتر قابلیت‌ها نیازی به فعال‌سازی ندارند. در حال حاضر فقط قابلیت UTF8=ACCEPT پشتیبانی می‌شود (ببینید RFC 6855).

اضافه شده در نسخه‌ی 3.5: خود متد enable()، و پشتیبانی از RFC 6855.

IMAP4.expunge(message_set=None, *, uid=False)¶

آیتم‌های حذف‌شده را به‌طور دائم از صندوق پستی انتخاب‌شده حذف می‌کند. برای هر پیام حذف‌شده یک پاسخ EXPUNGE تولید می‌کند. داده بازگشتی شامل فهرستی از شماره پیام‌های EXPUNGE به ترتیب دریافت است.

If uid is true, the UID EXPUNGE command (RFC 4315) is used to remove only the messages that both are marked as deleted and have a UID in message_set. message_set is required in this case, and must be omitted otherwise.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the message_set and uid parameters.

IMAP4.fetch(message_set, message_parts, *, uid=False, params=None)¶

(بخش‌هایی از) پیام‌ها را واکشی کنید. message_parts باید رشته‌ای از نام‌های بخش پیام باشد که داخل پرانتز قرار گرفته است، مثلاً: "(UID BODY[TEXT])". داده‌های بازگشتی، تاپل‌هایی از پاکت (envelope) و داده‌ی بخش پیام هستند.

If uid is true, message_set is a set of UIDs and the message numbers in the response are UIDs (UID FETCH).

If params is given, ? placeholders in message_parts are substituted with the quoted parameters (see the placeholders).

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the params and uid parameters.

IMAP4.getacl(mailbox)¶: ACLs برای mailbox را دریافت کنید. این متد غیراستاندارد است، اما توسط سرور Cyrus پشتیبانی می‌شود.

IMAP4.getannotation(mailbox, entry, attribute)¶: ANNOTATIONs مشخص‌شده برای mailbox را بازیابی می‌کند. این متد غیراستاندارد است، اما توسط سرور Cyrus پشتیبانی می‌شود.

IMAP4.getquota(root)¶: میزان استفاده از منابع و محدودیت‌های quota root را دریافت کنید. این متد بخشی از افزونه‌ی QUOTA در IMAP4 است که در rfc2087 تعریف‌شده است.

IMAP4.getquotaroot(mailbox)¶: فهرست quota roots برای mailbox مشخص‌شده را دریافت کنید. این متد بخشی از افزونه IMAP4 QUOTA تعریف‌شده در rfc2087 است.

IMAP4.id(fields=None)¶: Send client identification information to the server and return the identification information sent back by the server (the ID command, defined in RFC 2971). fields is a mapping of field names to values (for example, {'name': 'myclient', 'version': '1.0'}); a value can be None. The server must support the ID capability.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

IMAP4.idle(duration=None)¶

یک Idler برمی‌گرداند: یک مدیر زمینه پیمایش‌پذیر که دستور IDLE در IMAP4 را همان‌طور که در RFC 2177 تعریف شده است، پیاده‌سازی می‌کند.

شیء برگردانده‌شده هنگامی که با دستور with فعال می‌شود، فرمان IDLE را ارسال می‌کند، پاسخ‌های بدون برچسب IMAP را از طریق پروتکل iterator تولید می‌کند و هنگام خروج از زمینه، DONE را ارسال می‌کند.

تمام پاسخ‌های بدون برچسبی که پس از ارسال دستور IDLE می‌رسند (از جمله هر پاسخی که پیش از تأیید دستور توسط سرور می‌رسد) از طریق تکرار در دسترس خواهند بود. همه پاسخ‌های باقی‌مانده (آن‌هایی که در زمینه with تکرار نشده‌اند) را می‌توان پس از پایان IDLE به روش معمول با استفاده از IMAP4.response() بازیابی کرد.

پاسخ‌ها به‌صورت تاپل‌های (type, [data, ...]) نمایش داده می‌شوند، همان‌طور که در اشیاء IMAP4 توضیح داده شده است.

آرگومان duration حداکثر مدت‌زمان (به ثانیه) را برای بی‌کار ماندن تنظیم می‌کند؛ پس از آن، هر تکرار جاری متوقف خواهد شد. این آرگومان می‌تواند یک int یا float باشد، یا برای نداشتن محدودیت زمانی، None باشد. فراخوان‌کنندگانی که می‌خواهند از مهلت‌های زمانی بی‌کاری در سرورهایی که آن‌ها را اعمال می‌کنند اجتناب کنند، باید آن را حداکثر ۲۹ دقیقه (۱۷۴۰ ثانیه) نگه دارند. به یک اتصال سوکت نیاز دارد؛ در اتصال‌های IMAP4_stream، duration باید None باشد.

>>> with M.idle(duration=29 * 60) as idler:
...     for typ, data in idler:
...         print(typ, data)
...
EXISTS [b'1']
RECENT [b'1']

Idler.burst(interval=0.1)¶

یک رگبار از پاسخ‌ها را با فاصله‌ای حداکثر interval ثانیه از یکدیگر تولید کنید (که به‌صورت یک int یا float بیان می‌شود).

این تولیدگر جایگزینی برای پیمایش هر بار یک پاسخ است و برای کمک به پردازش دسته‌ای کارآمد در نظر گرفته شده است. این تولیدگر، پاسخ بعدی را به همراه هر یک از پاسخ‌های بعدی که بلافاصله در دسترس باشند بازیابی می‌کند. (برای مثال، یک دنباله سریع از پاسخ‌های EXPUNGE پس از یک حذف انبوه.)

به یک اتصال سوکت نیاز دارد؛ با اتصال‌های IMAP4_stream کار نمی‌کند.

>>> with M.idle() as idler:
...     # get a response and any others following by < 0.1 seconds
...     batch = list(idler.burst())
...     print(f'processing {len(batch)} responses...')
...     print(batch)
...
processing 3 responses...
[('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]

نکته

حداکثر مدت‌زمان زمینه‌ی IDLE، همان‌طور که به IMAP4.idle() ارسال می‌شود، هنگام انتظار برای نخستین پاسخ در یک رگبار رعایت می‌شود. بنابراین، یک Idler منقضی‌شده باعث می‌شود این تولیدگر بلافاصله بدون تولید هیچ چیزی بازگشت کند. فراخوانی‌کنندگان باید در صورت استفاده از آن در یک حلقه، این را در نظر بگیرند.

توجه

پیمایش‌گر بازگردانده‌شده توسط IMAP4.idle() فقط درون یک دستور with قابل استفاده است. پیش یا پس از آن زمینه، پاسخ‌های درخواست‌نشده هر زمان که یک فرمان به پایان برسد، به‌صورت داخلی جمع‌آوری می‌شوند و می‌توانند با IMAP4.response() بازیابی شوند.

توجه

نام و ساختار کلاس Idler رابط‌های داخلی هستند و ممکن است تغییر کنند. کد فراخوان می‌تواند بر پایدار ماندن مدیریت زمینه، تکرار و متد عمومی آن اتکا کند، اما نباید از این کلاس زیرکلاس بسازد، آن را نمونه‌سازی کند، آن را مقایسه کند یا به هر شکل دیگری مستقیماً به آن ارجاع دهد.

اضافه شده در نسخه‌ی 3.14.

IMAP4.list(directory='', pattern='*')¶: نام صندوق‌های پستی در directory را که با pattern مطابقت دارند، فهرست می‌کند. مقدار پیش‌فرض directory، پوشه پستی سطح بالا است و pattern به‌طور پیش‌فرض با هر چیزی مطابقت دارد. داده بازگشتی شامل فهرستی از پاسخ‌های LIST است.

IMAP4.login(user, password)¶: کلاینت را با استفاده از یک گذرواژه‌ی متن‌آشکار شناسایی کنید. password داخل علامت نقل‌قول قرار خواهد گرفت.

IMAP4.login_cram_md5(user, password)¶: Force use of CRAM-MD5 authentication when identifying the client to protect the password. It will only work if the server CAPABILITY response includes the phrase AUTH=CRAM-MD5.

تغییر یافته در نسخه‌ی 3.15: اگر پشتیبانی از MD5 در دسترس نباشد، یک IMAP4.error پرتاب می‌شود.

IMAP4.login_plain(user, password)¶

Authenticate using the PLAIN SASL mechanism (RFC 4616).

This is a plaintext authentication mechanism that can be used instead of login() when UTF-8 support is required (see RFC 6855). Since the credentials are only base64-encoded, not encrypted, this method should only be used over a TLS-protected connection, such as IMAP4_SSL or after starttls().

It will only work if the server supports the PLAIN mechanism, which it need not advertise as AUTH=PLAIN in its CAPABILITY response.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

IMAP4.logout()¶: اتصال به سرور را خاموش می‌کند. پاسخ BYE سرور را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.8: این متد دیگر استثناهای دلخواه را به‌صورت خاموش نادیده نمی‌گیرد.

IMAP4.lsub(directory='', pattern='*')¶: نام‌های صندوق پستی مشترک‌شده در پوشه را که با الگو مطابقت دارند، فهرست می‌کند. directory به‌طور پیش‌فرض پوشه سطح بالا است و pattern به‌طور پیش‌فرض با هر صندوق پستی مطابقت دارد. داده‌های بازگشتی، تاپل‌هایی از پاکت و داده‌ی بخش پیام هستند.

IMAP4.move(message_set, new_mailbox, *, uid=False)¶

Move message_set messages onto end of new_mailbox.

The server must support the MOVE capability (RFC 6851).

If uid is true, message_set is a set of UIDs and the UID MOVE command is used instead of MOVE.

اضافه شده در نسخه‌ی 3.16.0a0 (unreleased).

IMAP4.myrights(mailbox)¶: نمایش فهرست‌های کنترل دسترسی (ACL) من برای یک صندوق پستی (یعنی حقوقی که من روی صندوق پستی دارم).

IMAP4.namespace()¶: فضای نام های IMAP را، همان‌طور که در RFC 2342 تعریف شده است، بازمی‌گرداند.

IMAP4.noop()¶: NOOP را به سرور ارسال کنید.

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

سوکتی را به port در host باز می‌کند. پارامتر اختیاری timeout مهلت زمانی‌ای را بر حسب ثانیه برای تلاش برای اتصال مشخص می‌کند. اگر timeout داده نشود یا None باشد، از مهلت زمانی پیش‌فرض سراسری سوکت استفاده می‌شود. همچنین توجه داشته باشید که اگر پارامتر timeout برابر صفر تنظیم شده باشد، برای رد کردن ایجاد یک سوکت غیرمسدود، یک ValueError پرتاب می‌شود. این متد به‌طور ضمنی توسط سازنده‌ی IMAP4 فراخوانی می‌شود. اشیای اتصال برقرارشده توسط این متد در متدهای IMAP4.read()، IMAP4.readline()، IMAP4.send() و IMAP4.shutdown() استفاده خواهند شد. شما می‌توانید این متد را بازنویسی کنید.

یک رویداد حسابرسی imaplib.open را با آرگومان‌های self، host و port پرتاب می‌کند.

تغییر یافته در نسخه‌ی 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, [..., ]*, uid=False, params=None)¶

صندوق پستی را برای پیام‌های منطبق جستجو می‌کند. charset می‌تواند None باشد، که در این صورت هیچ CHARSET در درخواست به سرور مشخص نخواهد شد. پروتکل IMAP ایجاب می‌کند که حداقل یک معیار مشخص شود؛ هنگامی که سرور خطایی بازگرداند، یک استثنا پرتاب خواهد شد. اگر قابلیت UTF8=ACCEPT با استفاده از دستور enable() فعال شده باشد، charset باید None باشد.

If uid is true, the message numbers in the response are UIDs (UID SEARCH).

A criterion passed as str is encoded to charset (which must name a codec known to Python); pass bytes to send a criterion that is already encoded, for example when charset is one that Python does not support. When charset is None (as it must be under UTF8=ACCEPT), the criterion is sent using the connection's encoding instead.

If params is given, ? placeholders in the criteria are substituted with the quoted parameters (see the placeholders).

مثال:

# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"John Smith"')

# or:
typ, msgnums = M.search(None, '(FROM "John Smith")')

# or, letting the module quote the value (this is recommended):
typ, msgnums = M.search(None, 'FROM ?', params=['John Smith'])

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the params and uid parameters. str search criteria are encoded to charset.

IMAP4.select(mailbox='INBOX', readonly=False)¶: یک صندوق پستی را انتخاب کنید. داده‌ی بازگشتی، تعداد پیام‌های موجود در mailbox است (پاسخ EXISTS). مقدار پیش‌فرض mailbox برابر 'INBOX' است. اگر پرچم readonly تنظیم شده باشد، تغییرات در صندوق پستی مجاز نیست.

IMAP4.send(data)¶

data را به سرور راه دور ارسال می‌کند. شما می‌توانید این متد را بازنویسی کنید.

یک رویداد حسابرسی imaplib.send را با آرگومان‌های self و data پرتاب می‌کند.

IMAP4.setacl(mailbox, who, what)¶: یک ACL برای mailbox تنظیم کنید. این متد استاندارد نیست، اما توسط سرور Cyrus پشتیبانی می‌شود.

IMAP4.setannotation(mailbox, entry, attribute[, ...])¶: ANNOTATIONs را برای mailbox تنظیم می‌کند. این متد غیراستاندارد است، اما توسط سرور Cyrus پشتیبانی می‌شود.

IMAP4.setquota(root, limits)¶: محدودیت‌های منبع limits برای quota root را تنظیم می‌کند. این متد بخشی از افزونه‌ی IMAP4 QUOTA تعریف‌شده در rfc2087 است.

IMAP4.shutdown()¶: اتصال برقرارشده در open را می‌بندد. این متد به‌طور ضمنی توسط IMAP4.logout() فراخوانی می‌شود. شما می‌توانید این متد را بازنویسی کنید.

IMAP4.socket()¶: نمونه سوکت استفاده‌شده برای اتصال به سرور را برمی‌گرداند.

IMAP4.sort(sort_criteria, charset, search_criterion, [..., ]*, uid=False, params=None)¶

دستور sort گونه‌ای از search با معناشناسی مرتب‌سازی برای نتایج است. داده‌ی بازگشتی شامل فهرستی جداشده با فاصله از شماره‌های پیام منطبق است.

Sort دو آرگومان پیش از آرگومان(های) search_criterion دارد؛ فهرستی داخل پرانتز از sort_criteria و charset جستجو. توجه داشته باشید که برخلاف search، آرگومان charset جستجو الزامی است. همچنین دستور uid sort نیز وجود دارد که معادل sort است، همان‌طور که uid search معادل search است. دستور sort ابتدا صندوق پستی را برای پیام‌هایی که با معیارهای جستجوی داده‌شده مطابقت دارند، جستجو می‌کند و از آرگومان charset برای تفسیر رشته‌های موجود در معیارهای جستجو استفاده می‌کند. سپس شماره‌های پیام‌های منطبق را برمی‌گرداند.

If uid is true, the message numbers in the response are UIDs (UID SORT).

As with search(), a search_criterion passed as str is encoded to charset; pass bytes to send one already encoded.

If params is given, ? placeholders in the search criteria are substituted with the quoted parameters (see the placeholders).

این یک دستور توسعه‌ای IMAP4rev1 است.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the params and uid parameters. str search criteria are encoded to charset.

IMAP4.starttls(ssl_context=None)¶: فرمان STARTTLS را ارسال کنید. آرگومان ssl_context اختیاری است و باید یک شیء ssl.SSLContext باشد. این کار رمزنگاری را در اتصال IMAP فعال می‌کند. لطفاً برای بهترین شیوه‌ها، ملاحظات امنیتی را مطالعه کنید.

توجه

با ssl_context پیش‌فرض، اتصال رمزگذاری شده است، اما گواهی سرور و نام میزبان تأیید نمی‌شوند. برای تأیید آن‌ها، یک زمینه ایجادشده توسط ssl.create_default_context() را ارسال کنید.

اضافه شده در نسخه‌ی 3.2.

تغییر یافته در نسخه‌ی 3.4: این متد اکنون از بررسی نام میزبان با ssl.SSLContext.check_hostname و نشانگر نام سرور (Server Name Indication) پشتیبانی می‌کند (به ssl.HAS_SNI مراجعه کنید).

IMAP4.status(mailbox, names)¶: شرایط وضعیت نام‌گذاری‌شده برای mailbox را درخواست کنید.

IMAP4.store(message_set, command, flag_list, *, uid=False)¶

وضعیت پرچم‌ها را برای پیام‌های صندوق پستی تغییر می‌دهد. command در بخش 6.4.6 از RFC 3501 به‌عنوان یکی از مقادیر "FLAGS"، "+FLAGS" یا "-FLAGS" مشخص شده است، که به‌صورت اختیاری می‌تواند پسوند ".SILENT" داشته باشد.

If uid is true, message_set is a set of UIDs and the UID STORE command is used instead of STORE.

برای مثال، برای تنظیم پرچم حذف روی همه‌ی پیام‌ها:

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

توجه

ایجاد پرچم‌های حاوی ']' (برای مثال: "[test]") RFC 3501 (پروتکل IMAP) را نقض می‌کند. با این حال، imaplib از نظر تاریخی اجازه‌ی ایجاد چنین پرچم‌هایی را می‌داده است و سرورهای IMAP محبوب، مانند Gmail، چنین پرچم‌هایی را می‌پذیرند و تولید می‌کنند. برنامه‌هایی غیر از پایتون نیز وجود دارند که چنین پرچم‌هایی را ایجاد می‌کنند. اگرچه این یک نقض RFC است و انتظار می‌رود کلاینت‌ها و سرورهای IMAP سخت‌گیر باشند، imaplib همچنان به دلایل سازگاری با نسخه‌های پیشین اجازه می‌دهد چنین پرچم‌هایی ایجاد شوند، و از پایتون 3.6، اگر از سرور ارسال شوند، آن‌ها را مدیریت می‌کند، زیرا این کار سازگاری در دنیای واقعی را بهبود می‌بخشد.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the uid parameter.

IMAP4.subscribe(mailbox)¶: اشتراک در صندوق پستی جدید.

IMAP4.thread(threading_algorithm, charset, search_criterion, [..., ]*, uid=False, params=None)¶

دستور thread گونه‌ای از search با معنای نخ‌بندی برای نتایج است. داده‌های بازگشتی شامل فهرستی جداشده با فاصله از اعضای نخ هستند.

اعضای نخ شامل صفر یا چند شماره پیام هستند که با فاصله از هم جدا شده‌اند و والد و فرزند متوالی را نشان می‌دهند.

Thread دو آرگومان پیش از آرگومان یا آرگومان‌های search_criterion دارد؛ یک threading_algorithm و charset جستجو. توجه داشته باشید که برخلاف search، آرگومان charset جستجو الزامی است. هم‌چنین یک دستور uid thread وجود دارد که متناظر با thread است، همان‌طور که uid search متناظر با search است. دستور thread ابتدا صندوق پستی را برای یافتن پیام‌هایی که با معیارهای جستجوی داده‌شده مطابقت دارند، جستجو می‌کند و از آرگومان charset برای تفسیر رشته‌های موجود در معیارهای جستجو استفاده می‌کند. سپس پیام‌های منطبق را به‌صورت نخ‌بندی‌شده بر اساس الگوریتم نخ‌بندی مشخص‌شده بازمی‌گرداند.

If uid is true, the message numbers in the response are UIDs (UID THREAD).

As with search(), a search_criterion passed as str is encoded to charset; pass bytes to send one already encoded.

If params is given, ? placeholders in the search criteria are substituted with the quoted parameters (see the placeholders).

این یک دستور توسعه‌ای IMAP4rev1 است.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the params and uid parameters. str search criteria are encoded to charset.

IMAP4.uid(command, arg, [..., ]*, params=None)¶

دستور را با آرگومان‌هایی برای پیام‌های شناسایی‌شده با UID، به‌جای شماره پیام، اجرا می‌کند. پاسخ متناسب با دستور را برمی‌گرداند. دست‌کم یک آرگومان باید ارائه شود؛ اگر هیچ آرگومانی ارائه نشود، سرور خطایی برمی‌گرداند و استثنایی پرتاب خواهد شد.

If params is given, ? placeholders in the SEARCH, SORT and THREAD criteria or in the FETCH parts are substituted with the quoted parameters (see the placeholders).

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Added the params parameter.

IMAP4.unsubscribe(mailbox)¶: اشتراک خود را از صندوق پستی قدیمی لغو کنید.

IMAP4.unselect()¶: imaplib.IMAP4.unselect() منابع سرور مرتبط با صندوق پستی انتخاب‌شده را آزاد می‌کند و سرور را به وضعیت احراز هویت‌شده بازمی‌گرداند. این دستور همان اقداماتی را انجام می‌دهد که imaplib.IMAP4.close() انجام می‌دهد، با این تفاوت که هیچ پیامی به‌طور دائم از صندوق پستی انتخاب‌شده‌ی فعلی حذف نمی‌شود.

اضافه شده در نسخه‌ی 3.9.

IMAP4.xatom(name[, ...])¶: اجازه دادن به دستورات توسعه‌ای ساده که توسط سرور در پاسخ CAPABILITY اعلام می‌شوند.

ویژگی‌های زیر برای نمونه‌های IMAP4 تعریف شده‌اند:

IMAP4.capabilities¶

یک تاپل از قابلیت‌های تبلیغ‌شده توسط سرور، با حروف بزرگ.

این مقدار در هنگام برقراری اتصال تنظیم می‌شود، و پس از یک login()، authenticate() یا starttls() موفق، به‌روزرسانی می‌شود، زیرا سرور می‌تواند قابلیت‌های متفاوتی را در وضعیت‌های مختلف اتصال تبلیغ کند.

تغییر یافته در نسخه‌ی 3.14.7: پس از login() و authenticate() به‌روزرسانی می‌شود.

IMAP4.PROTOCOL_VERSION¶: جدیدترین پروتکل پشتیبانی‌شده در پاسخ CAPABILITY از سرور.

IMAP4.debug¶: مقدار عدد صحیح برای کنترل خروجی اشکال‌زدایی. مقدار اولیه از متغیر ماژول Debug گرفته می‌شود. مقادیر بزرگ‌تر از ۳ هر دستور را ردگیری می‌کنند.

IMAP4.utf8_enabled¶: مقدار بولی که معمولاً False است، اما اگر دستور enable() برای قابلیت UTF8=ACCEPT با موفقیت صادر شود، به True تنظیم می‌شود.

اضافه شده در نسخه‌ی 3.5.

property IMAP4.file¶: Internal BufferedReader associated with the underlying socket. This property is documented for legacy purposes but not part of the public interface. The caller is responsible to ensure that the current file is closed before changing it.

منسوخ شده از نسخه‌ی 3.15, در نسخه‌ی 3.19 حذف خواهد شد.

مثال IMAP4¶

در اینجا یک مثال حداقلی (بدون بررسی خطا) آمده است که یک صندوق پستی را باز می‌کند و تمام پیام‌ها را دریافت و چاپ می‌کند:

import getpass, imaplib

M = imaplib.IMAP4(host='example.org')
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()

توجه

یک پاسخ FETCH ممکن است حاوی داده‌های اضافی یا درخواست‌نشده باشد (به RFC 3501، بخش 7.4.2 مراجعه کنید)، بنابراین کد محصول باید به‌جای اتکا به data[0][1]، کل پاسخ را بررسی کند.

`imaplib` --- کلاینت پروتکل IMAP4¶

اشیای IMAP4¶

مثال IMAP4¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

imaplib --- کلاینت پروتکل IMAP4¶

اشیای IMAP4¶

مثال IMAP4¶

`imaplib` --- کلاینت پروتکل IMAP4¶