mailbox --- دستکاری صندوق‌های پستی در قالب‌های گوناگون

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

---

این ماژول دو کلاس Mailbox و Message را برای دسترسی و دستکاری صندوق‌های پستی روی دیسک و پیام‌های موجود در آن‌ها تعریف می‌کند. Mailbox نگاشتی شبیه دیکشنری از کلیدها به پیام‌ها ارائه می‌دهد. Message کلاس Message در ماژول email.message را با وضعیت و رفتار خاص قالب گسترش می‌دهد. قالب‌های پشتیبانی‌شده صندوق پستی شامل Maildir، mbox، MH، Babyl و MMDF هستند.

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

ماژول email

بازنمایی و دستکاری پیام‌ها.

اشیاء Mailbox

class mailbox.Mailbox

یک صندوق پستی (mailbox)، که می‌توان آن را بازرسی و تغییر داد.

کلاس Mailbox یک رابط را تعریف می‌کند و برای نمونه‌سازی در نظر گرفته نشده است. در عوض، زیرکلاس‌های مختص قالب باید از Mailbox ارث‌بری کنند و کد شما باید یک زیرکلاس مشخص را نمونه‌سازی کند.

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

می‌توان پیام‌ها را با استفاده از متد مشابه مجموعه (set-like) add() به یک نمونه Mailbox افزود و با استفاده از دستور del یا متدهای مشابه مجموعه (set-like) remove() و discard() آن‌ها را حذف کرد.

معناشناسی رابط Mailbox در برخی موارد قابل‌توجه با معناشناسی دیکشنری تفاوت دارد. هر بار که پیامی درخواست می‌شود، بازنمایی جدیدی (معمولاً یک نمونه Message) بر اساس وضعیت فعلی صندوق پستی تولید می‌شود. به‌طور مشابه، هنگامی که پیامی به یک نمونه Mailbox اضافه می‌شود، محتوای بازنمایی پیام ارائه‌شده کپی می‌شود. در هیچ‌یک از این دو حالت، مرجعی به بازنمایی پیام توسط نمونه Mailbox نگهداری نمی‌شود.

پیمایش‌گر پیش‌فرض Mailbox به‌جای کلیدها، روی بازنمایی‌های پیام تکرار می‌کند؛ برخلاف پیمایش‌گر پیش‌فرض دیکشنری که روی کلیدها تکرار می‌کند. علاوه بر این، تغییر صندوق پستی در حین تکرار ایمن و خوش‌تعریف است. پیام‌هایی که پس از ایجاد یک پیمایش‌گر به صندوق پستی افزوده شوند، توسط پیمایش‌گر دیده نخواهند شد. پیام‌هایی که پیش از آنکه پیمایش‌گر آن‌ها را بازگشت دهد، از صندوق پستی حذف شوند، بی‌سر و صدا رد می‌شوند؛ هرچند استفاده از کلیدی از پیمایش‌گر ممکن است در صورتی که پیام متناظر پس از آن حذف شود، به استثنای KeyError منجر شود.

هشدار

هنگام تغییر صندوق‌های پستی که ممکن است همزمان توسط فرایند دیگری تغییر کنند، بسیار محتاط باشید. امن‌ترین قالب صندوق پستی برای استفاده در چنین وظایفی Maildir است؛ سعی کنید برای نوشتن همزمان از قالب‌های تک‌پرونده‌ای مانند mbox اجتناب کنید. اگر در حال تغییر یک صندوق پستی هستید، باید پیش از خواندن هر پیامی در پرونده یا ایجاد هرگونه تغییر از طریق افزودن یا حذف یک پیام، آن را با فراخوانی متدهای lock() و unlock() قفل کنید. عدم قفل کردن صندوق پستی خطر از دست رفتن پیام‌ها یا خراب شدن کل صندوق پستی را به همراه دارد.

نمونه‌های Mailbox متدهای زیر را دارند:

add(message)

message را به صندوق پستی اضافه می‌کند و کلیدی را که به آن اختصاص داده شده است برمی‌گرداند.

پارامتر message می‌تواند نمونه‌ای از Message، نمونه‌ای از email.message.Message، یک رشته، یک رشته‌ی بایتی، یا یک شیء شبه‌پرونده (که باید در حالت دودویی باز باشد) باشد. اگر message نمونه‌ای از زیرکلاس Message مناسب و مختص قالب باشد (مثلاً اگر نمونه‌ای از mboxMessage باشد و این نمونه‌ای از mbox باشد)، از اطلاعات مختص قالب آن استفاده می‌شود. در غیر این صورت، از پیش‌فرض‌های معقول برای اطلاعات مختص قالب استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.2: پشتیبانی از ورودی دودویی افزوده شد.

remove(key)

__delitem__(key)

discard(key)

پیام متناظر با key را از صندوق پستی حذف می‌کند.

اگر چنین پیامی وجود نداشته باشد، در صورتی که متد به‌صورت remove() یا __delitem__() فراخوانی شده باشد، استثنای KeyError پرتاب می‌شود، اما اگر متد به‌صورت discard() فراخوانی شده باشد، هیچ استثنایی پرتاب نمی‌شود. اگر قالب صندوق پستی زیرین از تغییر همزمان توسط سایر فرآیندها پشتیبانی کند، ممکن است رفتار discard() ترجیح داده شود.

__setitem__(key, message)

پیام متناظر با key را با message جایگزین می‌کند. اگر هیچ پیامی از قبل متناظر با key وجود نداشته باشد، استثنای KeyError پرتاب می‌کند.

مانند add()، پارامتر message می‌تواند نمونه‌ای از Message، نمونه‌ای از email.message.Message، یک رشته، یک رشته بایت، یا یک شیء شبه‌پرونده (که باید در حالت دودویی باز شده باشد) باشد. اگر message نمونه‌ای از زیرکلاس مناسب و مخصوص قالبِ Message باشد (برای مثال، اگر یک نمونه از mboxMessage باشد و این یک نمونه از mbox باشد)، اطلاعات مخصوص قالب آن استفاده می‌شود. در غیر این صورت، اطلاعات مخصوص قالب پیامی که در حال حاضر متناظر با key است، بدون تغییر باقی می‌ماند.

iterkeys()

یک iterator روی همه کلیدها برمی‌گرداند

keys()

همانند iterkeys()، با این تفاوت که به‌جای یک iterator، یک list برگردانده می‌شود

itervalues()

__iter__()

یک iterator بر روی بازنمایی‌های همه پیام‌ها برمی‌گرداند. پیام‌ها به‌صورت نمونه‌هایی از زیرکلاس Message مناسب و مختص قالب بازنمایی می‌شوند، مگر اینکه هنگام مقداردهی اولیه‌ی نمونه‌ی Mailbox، یک کارخانه‌ی پیام سفارشی تعیین شده باشد.

توجه

رفتار __iter__() برخلاف دیکشنری‌ها است، که بر کلیدها تکرار می‌کنند.

values()

همانند itervalues()، با این تفاوت که یک list به‌جای یک iterator برگردانده می‌شود

iteritems()

یک iterator روی جفت‌های (key، message) برمی‌گرداند، که در آن key یک کلید و message یک بازنمایی پیام است. پیام‌ها به‌صورت نمونه‌هایی از زیرکلاس Message که مناسب و مختص قالب است بازنمایی می‌شوند، مگر آنکه یک کارخانه پیام سفارشی هنگام مقداردهی اولیه نمونه Mailbox تعیین شده باشد.

items()

مشابه iteritems()، با این تفاوت که به جای یک iterator از جفت‌ها، یک list از جفت‌ها بازگردانده می‌شود.

get(key, default=None)

__getitem__(key)

بازنمایی پیام متناظر با key را برمی‌گرداند. اگر چنین پیامی وجود نداشته باشد، در صورتی که متد به‌صورت get() فراخوانی شده باشد، default برگردانده می‌شود و در صورتی که متد به‌صورت __getitem__() فراخوانی شده باشد، استثنای KeyError پرتاب می‌شود. پیام به‌صورت نمونه‌ای از زیرکلاس Message مناسب و مختص قالب بازنمایی می‌شود، مگر اینکه یک کارخانه پیام سفارشی هنگام مقداردهی اولیه نمونه Mailbox تعیین شده باشد.

get_message(key)

بازنمایی پیام متناظر با key را به‌عنوان نمونه‌ای از زیرکلاس Message مناسب و خاصِ قالب برمی‌گرداند، یا اگر چنین پیامی وجود نداشته باشد، استثنای KeyError را پرتاب می‌کند.

get_bytes(key)

نمایش بایتی پیام متناظر با key را برمی‌گرداند، یا اگر چنین پیامی وجود نداشته باشد، استثنای KeyError را پرتاب می‌کند.

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

get_string(key)

نمایش رشته‌ای پیام مربوط به key را بازمی‌گرداند، یا اگر چنین پیامی وجود نداشته باشد، استثنای KeyError را پرتاب می‌کند. پیام از طریق email.message.Message پردازش می‌شود تا به یک نمایش پاک ۷ بیتی تبدیل شود.

get_file(key)

یک نمایش شبه‌پرونده از پیام متناظر با key برمی‌گرداند، یا در صورتی که چنین پیامی وجود نداشته باشد، یک استثنای KeyError را پرتاب می‌کند. شیء فایلشبه‌پروندهی رفتار می‌کند که گویی در حالت دودویی باز شده است. این پرونده باید هنگامی که دیگر نیازی به آن نیست، بسته شود.

تغییر یافته در نسخه‌ی 3.2: شیء پرونده در واقع یک binary file است؛ پیش‌تر به‌اشتباه در حالت متنی بازگردانده می‌شد. همچنین file-like object اکنون از پروتکل context manager پشتیبانی می‌کند: می‌توانید از یک دستور with برای بستن خودکار آن استفاده کنید.

توجه

برخلاف سایر بازنمایی‌های پیام‌ها، بازنمایی‌های شبه‌پرونده لزوماً مستقل از نمونه‌ی Mailbox که آن‌ها را ایجاد کرده است یا از صندوق پستی زیربنایی نیستند. مستندات دقیق‌تری توسط هر زیرکلاس ارائه شده است.

__contains__(key)

اگر key متناظر با یک پیام باشد، True و در غیر این صورت False را برمی‌گرداند.

__len__()

تعداد پیام‌های موجود در صندوق پستی را برمی‌گرداند.

clear()

تمام پیام‌ها را از صندوق پستی حذف کنید.

pop(key, default=None)

بازنمایی پیام متناظر با key را برمی‌گرداند و پیام را حذف می‌کند. اگر چنین پیامی وجود نداشته باشد، default را برمی‌گرداند. پیام به‌صورت نمونه‌ای از زیرکلاس Message مناسب و مختص قالب بازنمایی می‌شود، مگر اینکه یک کارخانه‌ی پیام سفارشی (message factory) هنگام مقداردهی اولیه نمونه Mailbox تعیین شده باشد.

popitem()

یک جفت (key, message) دلخواه را برمی‌گرداند، که در آن key یک کلید و message یک بازنمایی از پیام است، و پیام متناظر را حذف می‌کند. اگر صندوق پستی خالی باشد، استثنای KeyError را پرتاب می‌کند. پیام به‌صورت نمونه‌ای از زیرکلاس Message متناسب با قالب مربوط نمایش داده می‌شود، مگر اینکه یک کارخانه پیام سفارشی هنگام مقداردهی اولیه‌ی نمونه‌ی Mailbox تعیین شده باشد.

update(arg)

پارامتر arg باید یک نگاشت از کلید به پیام یا پیمایش‌پذیری از جفت‌های (کلید، پیام) باشد. صندوق پستی را به‌روزرسانی می‌کند، به‌گونه‌ای که برای هر کلید و پیام داده‌شده، پیام متناظر با کلید به پیام تنظیم می‌شود، گویی با استفاده از __setitem__(). مانند __setitem__()، هر کلید باید از قبل با پیامی در صندوق پستی متناظر باشد، در غیر این صورت یک استثنای KeyError پرتاب خواهد شد؛ بنابراین به‌طور کلی نادرست است که arg نمونه‌ای از Mailbox باشد.

توجه

برخلاف دیکشنری‌ها، آرگومان‌های کلیدواژه‌ای پشتیبانی نمی‌شوند.

flush()

هرگونه تغییر در انتظار را در سامانه فایل‌بندی می‌نویسد. برای برخی از زیرکلاس‌های Mailbox، تغییرات همیشه بلافاصله نوشته می‌شوند و flush() هیچ کاری انجام نمی‌دهد، اما شما همچنان باید عادت به فراخوانی این متد داشته باشید.

lock()

یک قفل توصیه‌ای انحصاری (advisory lock) روی صندوق پستی کسب می‌شود تا سایر فرآیندها بدانند که نباید آن را تغییر دهند. اگر قفل در دسترس نباشد، استثنای ExternalClashError پرتاب می‌شود. سازوکارهای قفل‌سازی خاصی که استفاده می‌شوند، به قالب صندوق پستی بستگی دارند. شما باید همیشه پیش از ایجاد هرگونه تغییر در محتوای صندوق پستی، آن را قفل کنید.

unlock()

قفل صندوق پستی را، در صورت وجود، آزاد کنید.

close()

صندوق پستی را تخلیه کنید، در صورت نیاز قفل آن را باز کنید و هر پرونده بازی را ببندید. برای برخی از زیرکلاس‌های Mailbox، این متد هیچ کاری انجام نمی‌دهد.

اشیای Maildir

class mailbox.Maildir(dirname, factory=None, create=True)

یک زیرکلاس از Mailbox برای صندوق‌های پستی با قالب Maildir. پارامتر factory یک شیء فراخوانی‌پذیر است که یک بازنمایی پیام شبه‌پرونده (که گویی در حالت دودویی باز شده است) می‌پذیرد و یک بازنمایی سفارشی برمی‌گرداند. اگر factory None باشد، MaildirMessage به عنوان بازنمایی پیش‌فرض پیام استفاده می‌شود. اگر create True باشد، صندوق پستی در صورتی که وجود نداشته باشد ایجاد می‌شود.

اگر create برابر True باشد و مسیر dirname وجود داشته باشد، با آن به‌عنوان یک maildir موجود رفتار می‌شود، بدون اینکه تلاش شود چیدمان پوشه‌ی آن تأیید شود.

به دلایل تاریخی است که dirname به این صورت نام‌گذاری شده است، نه path.

Maildir یک قالب صندوق پستی مبتنی بر پوشه است که برای عامل انتقال ایمیل qmail ابداع شده است و اکنون به‌طور گسترده توسط برنامه‌های دیگر پشتیبانی می‌شود. پیام‌های یک صندوق پستی Maildir در پرونده‌های جداگانه در یک ساختار پوشه‌ای مشترک ذخیره می‌شوند. این طراحی به چندین برنامه غیرمرتبط اجازه می‌دهد بدون خرابی داده‌ها به صندوق‌های پستی Maildir دسترسی پیدا کنند و آن‌ها را تغییر دهند، بنابراین نیازی به قفل کردن پرونده نیست.

صندوق‌های پستی Maildir شامل سه زیرپوشه به نام‌های tmp، new و cur هستند. پیام‌ها به‌صورت موقت در زیرپوشه‌ی tmp ایجاد می‌شوند و سپس برای نهایی‌کردن تحویل به زیرپوشه‌ی new منتقل می‌شوند. ممکن است یک عامل کاربر پستی (mail user agent) بعداً پیام را به زیرپوشه‌ی cur منتقل کند و اطلاعات مربوط به وضعیت پیام را در بخش ویژه‌ی "info" ذخیره کند که به نام پرونده آن افزوده شده است.

پوشه‌هایی به سبک معرفی‌شده توسط عامل انتقال ایمیل Courier نیز پشتیبانی می‌شوند. هر زیرپوشه‌ای از صندوق پستی اصلی، اگر '.' نخستین نویسه‌ی نام آن باشد، یک پوشه محسوب می‌شود. نام پوشه‌ها توسط Maildir بدون '.' آغازین نمایش داده می‌شوند. هر پوشه، خود یک صندوق پستی Maildir است، اما نباید شامل پوشه‌های دیگر باشد. در عوض، تودرتویی منطقی با استفاده از '.' برای جدا کردن سطح‌ها نشان داده می‌شود، برای مثال "Archived.2005.07".

colon

مشخصات Maildir استفاده از دونقطه (':') را در برخی نام پرونده‌های پیام الزامی می‌داند. با این حال، برخی سیستم‌عامل‌ها استفاده از این نویسه در نام پرونده‌ها را مجاز نمی‌دانند. اگر مایلید از قالبی مشابه Maildir در چنین سیستم‌عاملی استفاده کنید، باید نویسه دیگری را برای استفاده به‌جای آن مشخص کنید. علامت تعجب ('!') انتخاب رایجی است. برای مثال:

import mailbox
mailbox.Maildir.colon = '!'

ویژگی colon همچنین می‌تواند به‌ازای هر نمونه تنظیم شود.

تغییر یافته در نسخه‌ی 3.13: Maildir اکنون پرونده‌هایی را که با یک نقطه شروع می‌شوند، نادیده می‌گیرد.

نمونه‌های Maildir علاوه بر متدهای زیر، تمامی متدهای Mailbox را دارند:

list_folders()

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

get_folder(folder)

یک نمونه Maildir برمی‌گرداند که نشان‌دهنده پوشه‌ای است که نام آن folder است. اگر پوشه وجود نداشته باشد، استثنای NoSuchMailboxError پرتاب می‌شود.

add_folder(folder)

پوشه‌ای با نام folder ایجاد کنید و یک نمونه Maildir را که نشان‌دهنده آن است، برگردانید.

remove_folder(folder)

پوشه‌ای را که نام آن folder است حذف کنید. اگر پوشه حاوی پیامی باشد، استثنای NotEmptyError پرتاب می‌شود و پوشه حذف نخواهد شد.

clean()

پرونده‌های موقتی را که در ۳۶ ساعت گذشته به آن‌ها دسترسی پیدا نشده است، از صندوق پستی حذف کنید. مشخصات Maildir می‌گوید که برنامه‌های خواندن پست باید این کار را هر از گاهی انجام دهند.

get_flags(key)

پرچم‌های تنظیم‌شده روی پیام متناظر با key را به‌صورت یک رشته برمی‌گرداند. این معادل get_message(key).get_flags() است، اما بسیار سریع‌تر است، زیرا پرونده پیام را باز نمی‌کند. هنگام پیمایش روی کلیدها از این متد استفاده کنید تا تعیین کنید کدام پیام‌ها برای دریافت جالب هستند.

اگر یک شیء MaildirMessage دارید، در عوض از متد get_flags() آن استفاده کنید، زیرا تغییرات اعمال‌شده توسط متدهای set_flags()، add_flag() و remove_flag() پیام، تا زمانی که متد __setitem__() صندوق پستی فراخوانی نشود، در اینجا منعکس نمی‌شوند.

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

set_flags(key, flags)

برای پیام متناظر با key، پرچم‌های مشخص‌شده با flags را تنظیم می‌کند و تمام بقیه را برمی‌دارد. فراخوانی some_mailbox.set_flags(key, flags) مشابه زیر است

one_message = some_mailbox.get_message(key)
one_message.set_flags(flags)
some_mailbox[key] = one_message

اما سریع‌تر است، زیرا پرونده‌ی پیام را باز نمی‌کند.

اگر یک شیء MaildirMessage دارید، به‌جای آن از متد set_flags() آن استفاده کنید، زیرا تغییرات اعمال‌شده با این متد صندوق پستی، برای متد شیء پیام، get_flags()، قابل مشاهده نخواهد بود.

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

add_flag(key, flag)

برای پیام متناظر با key، پرچم‌های مشخص‌شده توسط flag را بدون تغییر دادن پرچم‌های دیگر تنظیم کنید. برای افزودن بیش از یک پرچم به‌صورت همزمان، flag می‌تواند رشته‌ای با بیش از یک نویسه باشد.

ملاحظات استفاده از این متد در مقایسه با متد add_flag() شیء پیام، مشابه ملاحظات مربوط به set_flags() است؛ به بحث موجود در آنجا مراجعه کنید.

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

remove_flag(key, flag)

در پیام متناظر با key، پرچم‌های مشخص‌شده با flag را بدون تغییر سایر پرچم‌ها بردارید. برای حذف همزمان بیش از یک پرچم، flag می‌تواند رشته‌ای با بیش از یک نویسه باشد.

ملاحظات استفاده از این متد در مقایسه با متد remove_flag() شیء پیام، مشابه ملاحظات set_flags() است؛ به بحث آنجا مراجعه کنید.

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

get_info(key)

رشته‌ای حاوی اطلاعات پیام متناظر با key برمی‌گرداند. این معادل get_message(key).get_info() است، اما بسیار سریع‌تر است، زیرا پرونده پیام را باز نمی‌کند. هنگام پیمایش کلیدها از این متد استفاده کنید تا مشخص کنید کدام پیام‌ها برای دریافت مورد نظر هستند.

اگر یک شیء MaildirMessage دارید، به‌جای آن از متد get_info() آن استفاده کنید، زیرا تغییرات ایجادشده توسط متد set_info() پیام تا زمانی که متد __setitem__() صندوق پستی فراخوانی نشود، در اینجا بازتاب داده نمی‌شوند.

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

set_info(key, info)

اطلاعات پیام متناظر با key را روی info تنظیم می‌کند. فراخوانی some_mailbox.set_info(key, flags) مشابه این است

one_message = some_mailbox.get_message(key)
one_message.set_info(info)
some_mailbox[key] = one_message

اما سریع‌تر است، زیرا پرونده‌ی پیام را باز نمی‌کند.

اگر یک شیء MaildirMessage دارید، به‌جای آن از متد set_info() آن استفاده کنید، زیرا تغییرات اعمال‌شده با این متد صندوق پستی برای متد شیء پیام، get_info()، قابل مشاهده نخواهد بود.

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

برخی از متدهای Mailbox که توسط Maildir پیاده‌سازی شده‌اند، شایسته‌ی نکات ویژه‌ای هستند:

add(message)

__setitem__(key, message)

update(arg)

هشدار

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

flush()

تمام تغییرات در صندوق‌های پستی Maildir بلافاصله اعمال می‌شوند، بنابراین این متد هیچ کاری انجام نمی‌دهد.

lock()

unlock()

صندوق‌های پستی Maildir از قفل‌کردن پشتیبانی نمی‌کنند (یا به آن نیاز ندارند)، بنابراین این متدها هیچ کاری انجام نمی‌دهند.

close()

نمونه‌های Maildir هیچ پرونده بازی را باز نگه نمی‌دارند و صندوق‌های پستی زیربنایی از قفل‌کردن پشتیبانی نمی‌کنند، بنابراین این متد هیچ کاری انجام نمی‌دهد.

get_file(key)

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

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

صفحه راهنمای maildir از Courier

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

استفاده از قالب maildir

یادداشت‌هایی درباره Maildir از مخترع آن. شامل یک طرح‌واره به‌روزشده برای ایجاد نام و جزئیاتی درباره معنای «info» است.

اشیاء mbox

class mailbox.mbox(path, factory=None, create=True)

یک زیرکلاس از Mailbox برای صندوق‌های پستی با قالب mbox. پارامتر factory یک شیء فراخوانی‌پذیر است که یک بازنمایی پیام شبه‌پرونده (که طوری رفتار می‌کند که گویی در حالت دودویی باز شده است) را می‌پذیرد و یک بازنمایی سفارشی را برمی‌گرداند. اگر factory برابر None باشد، از mboxMessage به عنوان بازنمایی پیش‌فرض پیام استفاده می‌شود. اگر create برابر True باشد، صندوق پستی در صورتی که وجود نداشته باشد، ایجاد می‌شود.

قالب mbox، قالب کلاسیک برای ذخیره‌ی ایمیل در سیستم‌های یونیکسی است. همه‌ی پیام‌های یک صندوق پستی mbox در یک پرونده واحد ذخیره می‌شوند و آغاز هر پیام با خطی مشخص می‌شود که پنج نویسه‌ی نخست آن "From " است.

چندین گونه از قالب mbox برای برطرف کردن کاستی‌های به‌نظر رسیده در قالب اصلی وجود دارد. به منظور سازگاری، mbox قالب اصلی را پیاده‌سازی می‌کند، که گاهی با عنوان mboxo شناخته می‌شود. این بدان معناست که سرآیند Content-Length، در صورت وجود، نادیده گرفته می‌شود و هر مورد از "From " در ابتدای یک خط در بدنه‌ی پیام هنگام ذخیره‌ی پیام به ">From " تبدیل می‌شود، اگرچه موارد ">From " هنگام خواندن پیام به "From " تبدیل نمی‌شوند.

برخی از متدهای Mailbox که توسط mbox پیاده‌سازی شده‌اند، شایسته نکات ویژه‌ای هستند:

get_bytes(key, from_=False)

توجه: این متد در مقایسه با سایر کلاس‌ها یک پارامتر اضافی (from_) دارد. نخستین خط از یک ورودی پرونده mbox، خط "From " یونیکس است. اگر from_ برابر False باشد، خط اول پرونده حذف می‌شود.

get_file(key, from_=False)

استفاده از پرونده پس از فراخوانی flush() یا close() بر روی نمونه‌ی mbox ممکن است نتایج غیرقابل‌پیش‌بینی به همراه داشته باشد یا استثنایی پرتاب کند.

توجه: این متد در مقایسه با سایر کلاس‌ها یک پارامتر اضافی (from_) دارد. نخستین خط از یک ورودی پرونده mbox، خط "From " یونیکس است. اگر from_ برابر False باشد، خط اول پرونده حذف می‌شود.

get_string(key, from_=False)

توجه: این متد در مقایسه با سایر کلاس‌ها یک پارامتر اضافی (from_) دارد. نخستین خط از یک ورودی پرونده mbox، خط "From " یونیکس است. اگر from_ برابر False باشد، خط اول پرونده حذف می‌شود.

lock()

unlock()

از سه سازوکار قفل‌گذاری استفاده می‌شود---قفل‌گذاری نقطه‌ای و، در صورت موجود بودن، فراخوانی‌های سیستمی flock() و lockf().

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

صفحه‌ی man مربوط به mbox از tin

مشخصات قالب، همراه با جزئیاتی درباره قفل‌گذاری.

پیکربندی Netscape Mail در یونیکس: چرا قالب Content-Length بد است

آرگومانی برای استفاده از قالب اصلی mbox به‌جای یک گونه‌ی متفاوت.

"mbox" خانواده‌ای از چندین قالب صندوق پستی است که با یکدیگر ناسازگار هستند

تاریخچه‌ای از انواع mbox.

اشیای MH

class mailbox.MH(path, factory=None, create=True)

زیرکلاسی از Mailbox برای صندوق‌های پستی در قالب MH. پارامتر factory یک شیء فراخوانی‌پذیر است که یک بازنمایی پیام شبه‌پرونده (که طوری رفتار می‌کند که گویی در حالت دودویی باز شده است) را می‌پذیرد و یک بازنمایی سفارشی را برمی‌گرداند. اگر factory برابر None باشد، از MHMessage به‌عنوان بازنمایی پیش‌فرض پیام استفاده می‌شود. اگر create برابر True باشد، صندوق پستی در صورتی که وجود نداشته باشد ایجاد می‌شود.

MH یک قالب صندوق پستی مبتنی بر پوشه است که برای MH Message Handling System، یک عامل کاربر پست، ابداع شده است. هر پیام در یک صندوق پستی MH در پرونده مستقل خود قرار دارد. یک صندوق پستی MH ممکن است علاوه بر پیام‌ها، شامل صندوق‌های پستی MH دیگر (به نام پوشه‌ها <folders>) باشد. پوشه‌ها می‌توانند به‌طور نامحدود تودرتو شوند. صندوق‌های پستی MH همچنین از دنباله‌ها <sequences> پشتیبانی می‌کنند، که فهرست‌های نام‌گذاری‌شده‌ای هستند که برای گروه‌بندی منطقی پیام‌ها بدون جابه‌جایی آن‌ها به پوشه‌های فرعی استفاده می‌شوند. دنباله‌ها در پرونده‌ای به نام .mh_sequences در هر پوشه تعریف می‌شوند.

کلاس MH صندوق‌های پستی MH را دستکاری می‌کند، اما تلاش نمی‌کند تمام رفتارهای mh را شبیه‌سازی کند. به‌طور خاص، پرونده‌های context یا .mh_profile را که mh برای ذخیره وضعیت و پیکربندی خود از آن‌ها استفاده می‌کند، تغییر نمی‌دهد و تحت تأثیر آن‌ها قرار نمی‌گیرد.

نمونه‌های MH علاوه بر موارد زیر، تمامی متدهای Mailbox را دارند:

تغییر یافته در نسخه‌ی 3.13: پوشه‌های پشتیبانی‌شده که حاوی پرونده .mh_sequences نیستند.

list_folders()

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

get_folder(folder)

یک نمونه MH را برمی‌گرداند که نشان‌دهنده پوشه‌ای با نام folder است. اگر پوشه وجود نداشته باشد، استثنای NoSuchMailboxError پرتاب می‌شود.

add_folder(folder)

پوشه‌ای با نام folder ایجاد می‌کند و نمونه‌ای از MH را برمی‌گرداند که نشان‌دهنده آن است.

remove_folder(folder)

پوشه‌ای را که نام آن folder است حذف کنید. اگر پوشه حاوی پیامی باشد، استثنای NotEmptyError پرتاب می‌شود و پوشه حذف نخواهد شد.

get_sequences()

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

set_sequences(sequences)

دنباله‌های موجود در صندوق پستی را بر اساس sequences بازتعریف کنید؛ sequences دیکشنری‌ای از نام‌ها است که به فهرست‌های کلید نگاشت شده‌اند، مانند آنچه get_sequences() برمی‌گرداند.

pack()

پیام‌های موجود در صندوق پستی در صورت لزوم تغییر نام داده می‌شوند تا فاصله‌های موجود در شماره‌گذاری برطرف شوند. ورودی‌های فهرست دنباله‌ها (sequences) به‌طور متناظر به‌روزرسانی می‌شوند.

توجه

کلیدهای از پیش اکسپورت شده با این عملیات باطل می‌شوند و نباید پس از آن استفاده شوند.

برخی متدهای Mailbox که توسط MH پیاده‌سازی شده‌اند، شایسته‌ی نکات ویژه‌ای هستند:

remove(key)

__delitem__(key)

discard(key)

این متدها پیام را بلافاصله حذف می‌کنند. از قرارداد MH برای علامت‌گذاری یک پیام جهت حذف با افزودن کاما به ابتدای نام آن استفاده نمی‌شود.

lock()

unlock()

از سه سازوکار قفل استفاده می‌شود---قفل نقطه‌ای و، در صورت موجود بودن، فراخوانی‌های سیستمی flock() و lockf(). برای صندوق‌های پستی MH، قفل کردن صندوق پستی به معنای قفل کردن پرونده‌ی .mh_sequences و، فقط در طول هر عملیاتی که بر آن‌ها اثر می‌گذارد، قفل کردن پرونده‌های پیام جداگانه است.

get_file(key)

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

flush()

تمام تغییرات در صندوق‌های پستی MH بلافاصله اعمال می‌شوند، بنابراین این متد کاری انجام نمی‌دهد.

close()

نمونه‌های MH هیچ پرونده‌ای را باز نگه نمی‌دارند، بنابراین این متد معادل unlock() است.

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

nmh - Message Handling System

صفحه‌ی خانگی nmh، نسخه‌ای به‌روزشده از mh اصلی.

MH و nmh: ایمیل برای کاربران و برنامه‌نویسان

کتابی دارای پروانه GPL درباره‌ی mh و nmh، همراه با مقداری اطلاعات درباره‌ی قالب صندوق پستی .

اشیای Babyl

class mailbox.Babyl(path, factory=None, create=True)

زیرکلاسی از Mailbox برای صندوق‌های پستی در قالب Babyl. پارامتر factory یک شیء فراخوانی‌پذیر است که یک بازنمایی شبه‌پرونده از پیام (که مانند پرونده‌ای که در حالت دودویی باز شده باشد رفتار می‌کند) می‌پذیرد و یک بازنمایی سفارشی را برمی‌گرداند. اگر factory برابر None باشد، از BabylMessage به عنوان بازنمایی پیش‌فرض پیام استفاده می‌شود. اگر create برابر True باشد، صندوق پستی در صورتی که وجود نداشته باشد ایجاد می‌شود.

Babyl یک قالب صندوق پستی تک‌پرونده‌ای است که توسط عامل کاربر پست الکترونیکی Rmail، که همراه با Emacs ارائه شده است، استفاده می‌شود. آغاز یک پیام با خطی مشخص می‌شود که شامل دو نویسه‌ی Control-Underscore ('\037') و Control-L ('\014') است. پایان یک پیام با آغاز پیام بعدی یا، در مورد آخرین پیام، با سطری شامل یک نویسه‌ی Control-Underscore ('\037') مشخص می‌شود.

پیام‌های موجود در یک صندوق پستی Babyl دارای دو مجموعه سرآیند هستند: سرآیندهای اصلی و سرآیندهای به‌اصطلاح قابل‌مشاهده. سرآیندهای قابل‌مشاهده معمولاً زیرمجموعه‌ای از سرآیندهای اصلی هستند که دوباره قالب‌بندی یا خلاصه شده‌اند تا جذاب‌تر شوند. هر پیام در یک صندوق پستی Babyl همچنین یک فهرست همراه از برچسب‌ها <labels> دارد، یا رشته‌های کوتاهی که اطلاعات اضافی درباره پیام را ثبت می‌کنند، و فهرستی از همه برچسب‌های تعریف‌شده توسط کاربر که در صندوق پستی وجود دارند، در بخش گزینه‌های Babyl نگهداری می‌شود.

نمونه‌های Babyl علاوه بر تمامی متدهای Mailbox، موارد زیر را نیز دارند:

get_labels()

فهرستی از نام‌های تمام برچسب‌های تعریف‌شده توسط کاربر استفاده‌شده در صندوق پستی را برمی‌گرداند.

توجه

به جای مراجعه به فهرست برچسب‌ها در بخش گزینه‌های Babyl، پیام‌های واقعی بررسی می‌شوند تا تعیین شود کدام برچسب‌ها در صندوق پستی وجود دارند، اما هر زمان که صندوق پستی تغییر کند، بخش Babyl به‌روزرسانی می‌شود.

برخی متدهای Mailbox که در Babyl پیاده‌سازی شده‌اند، شایسته‌ی نکات خاصی هستند:

get_file(key)

در صندوق‌های پستی Babyl، سرآیندهای یک پیام به‌صورت پیوسته با بدنه پیام ذخیره نمی‌شوند. برای تولید یک بازنمایی شبه‌پرونده، سرآیندها و بدنه با هم در نمونه‌ای از io.BytesIO رونوشت می‌شوند که API آن با API یک پرونده یکسان است. در نتیجه، شیء شبه‌پرونده واقعاً از صندوق پستی زیربنایی مستقل است، اما در مقایسه با یک بازنمایی رشته‌ای، باعث صرفه‌جویی در حافظه نمی‌شود.

lock()

unlock()

از سه سازوکار قفل‌گذاری استفاده می‌شود---قفل‌گذاری نقطه‌ای و، در صورت موجود بودن، فراخوانی‌های سیستمی flock() و lockf().

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

قالب پرونده‌های Babyl نسخه‌ی 5

مشخصات قالب Babyl.

خواندن ایمیل با Rmail

راهنمای Rmail، همراه با اطلاعاتی درباره معناشناسی Babyl.

اشیای MMDF

class mailbox.MMDF(path, factory=None, create=True)

زیرکلاسی از Mailbox برای صندوق‌های پستی با قالب MMDF. پارامتر factory یک شیء فراخوانی‌پذیر است که یک بازنمایی پیام شبه‌پرونده (که طوری رفتار می‌کند که گویی در حالت دودویی باز شده است) می‌پذیرد و یک بازنمایی سفارشی را برمی‌گرداند. اگر factory برابر None باشد، از MMDFMessage به‌عنوان بازنمایی پیش‌فرض پیام استفاده می‌شود. اگر create برابر True باشد، در صورتی که صندوق پستی وجود نداشته باشد، ایجاد می‌شود.

MMDF یک قالب صندوق پستی تک‌پرونده‌ای است که برای Multichannel Memorandum Distribution Facility، یک عامل انتقال ایمیل، ابداع شده است. هر پیام همان شکل یک پیام mbox را دارد، اما پیش و پس از آن با سطرهایی شامل چهار نویسه Control-A ('\001') محصور شده است. مانند قالب mbox، آغاز هر پیام با خطی مشخص می‌شود که پنج نویسه نخست آن "From " است، اما موارد اضافی "From " هنگام ذخیره‌سازی پیام‌ها به ">From " تبدیل نمی‌شوند، زیرا سطرهای جداکننده اضافی پیام مانع از اشتباه گرفتن این موارد با آغاز پیام‌های بعدی می‌شوند.

برخی از متدهای Mailbox که توسط MMDF پیاده‌سازی شده‌اند، شایسته‌ی نکات ویژه‌ای هستند:

get_bytes(key, from_=False)

توجه: این متد در مقایسه با سایر کلاس‌ها یک پارامتر اضافی (from_) دارد. نخستین خط از یک ورودی پرونده mbox، خط "From " یونیکس است. اگر from_ برابر False باشد، خط اول پرونده حذف می‌شود.

get_file(key, from_=False)

استفاده از پرونده پس از فراخوانی flush() یا close() بر روی نمونه‌ی MMDF ممکن است نتایج غیرقابل‌پیش‌بینی به همراه داشته باشد یا استثنایی پرتاب کند.

توجه: این متد در مقایسه با سایر کلاس‌ها یک پارامتر اضافی (from_) دارد. نخستین خط از یک ورودی پرونده mbox، خط "From " یونیکس است. اگر from_ برابر False باشد، خط اول پرونده حذف می‌شود.

lock()

unlock()

از سه سازوکار قفل‌گذاری استفاده می‌شود---قفل‌گذاری نقطه‌ای و، در صورت موجود بودن، فراخوانی‌های سیستمی flock() و lockf().

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

صفحه man مربوط به mmdf از tin

مشخصات قالب MMDF از مستندات tin، یک خبرخوان.

MMDF

مقاله‌ای در ویکی‌پدیا که Multichannel Memorandum Distribution Facility را توصیف می‌کند.

اشیای Message

class mailbox.Message(message=None)

زیرکلاسی از Message در ماژول email.message. زیرکلاس‌های mailbox.Message وضعیت و رفتار خاص قالب صندوق پستی را می‌افزایند.

اگر message حذف شود، نمونه جدید در یک وضعیت پیش‌فرض و خالی ایجاد می‌شود. اگر message یک نمونه از email.message.Message باشد، محتوای آن کپی می‌شود؛ علاوه بر این، اگر message یک نمونه از Message باشد، هرگونه اطلاعات خاص قالب تا حد امکان تبدیل می‌شود. اگر message یک رشته، یک رشته بایت یا یک پرونده باشد، باید حاوی پیامی مطابق با RFC 5322باشد، که خوانده و تجزیه می‌شود. پرونده‌ها باید در حالت دودویی باز باشند، اما پرونده‌های حالت متنی برای سازگاری با نسخه‌های قبلی پذیرفته می‌شوند.

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

الزامی وجود ندارد که از نمونه‌های Message برای نمایش پیام‌های بازیابی‌شده با استفاده از نمونه‌های Mailbox استفاده شود. در برخی موقعیت‌ها، ممکن است زمان و حافظه‌ی مورد نیاز برای تولید بازنمایی‌های Message قابل قبول نباشد. برای چنین موقعیت‌هایی، نمونه‌های Mailbox همچنین بازنمایی‌های رشته‌ای و شبه‌پرونده‌ای را ارائه می‌دهند، و می‌توان یک کارخانه‌ی پیام سفارشی را هنگام راه‌اندازی نمونه‌ای از Mailbox تعیین کرد.

اشیای MaildirMessage

class mailbox.MaildirMessage(message=None)

پیامی با رفتارهای خاص Maildir. پارامتر message همان معنایی را دارد که در سازنده‌ی Message دارد.

معمولاً یک برنامه عامل کاربر پست، همه‌ی پیام‌های درون زیرپوشه‌ی new را پس از نخستین باری که کاربر صندوق پست را باز و بسته می‌کند، به زیرپوشه‌ی cur منتقل می‌کند و قدیمی بودن پیام‌ها را، خواه واقعاً خوانده شده باشند خواه نه، ثبت می‌کند. به نام پرونده هر پیام در cur یک بخش "info" افزوده می‌شود تا اطلاعات مربوط به وضعیت آن ذخیره شود. (برخی پست‌خوان‌ها ممکن است یک بخش "info" نیز به پیام‌های درون new اضافه کنند.) بخش "info" ممکن است یکی از دو حالت را داشته باشد: ممکن است شامل "2," باشد و پس از آن فهرستی از پرچم‌های استانداردشده بیاید (مثلاً "2,FR") یا ممکن است شامل "1," باشد و پس از آن اطلاعات به‌اصطلاح آزمایشی بیاید. پرچم‌های استاندارد پیام‌های Maildir به شرح زیر هستند:

پرچم	معنی	توضیح
D	پیش‌نویس	درحال نوشته شدن
F	پرچم‌دار	به‌عنوان مهم علامت‌گذاری شده
P	باز فرستاده‌شده	بازارسال‌شده، دوباره ارسال‌شده، یا برگشت‌خورده
R	پاسخ‌داده‌شده	پاسخ داده‌شده به
S	دیده‌شده	خوانده‌شده
T	حذف‌شده	علامت‌گذاری‌شده برای حذف بعدی

نمونه‌های MaildirMessage متدهای زیر را ارائه می‌دهند:

get_subdir()

«new» (اگر پیام باید در زیرپوشه‌ی new ذخیره شود) یا «cur» (اگر پیام باید در زیرپوشه‌ی cur ذخیره شود) را برگردانید.

توجه

یک پیام معمولاً پس از دسترسی به صندوق پستی آن، از new به cur منتقل می‌شود، چه پیام خوانده‌شده باشد و چه نشده باشد. اگر "S" in msg.get_flags() برابر True باشد، پیام msg خوانده‌شده است.

set_subdir(subdir)

زیرپوشه‌ای را که پیام باید در آن ذخیره شود، تنظیم کنید. پارامتر subdir باید "new" یا "cur" باشد.

get_flags()

رشته‌ای را برمی‌گرداند که پرچم‌هایی را که در حال حاضر تنظیم شده‌اند، مشخص می‌کند. اگر پیام با قالب استاندارد Maildir مطابقت داشته باشد، نتیجه، الحاق صفر یا یک رخداد از هر یک از 'D'، 'F'، 'P'، 'R'، 'S' و 'T' به ترتیب الفبایی است. اگر هیچ پرچمی تنظیم‌نشده باشد یا "info" دارای معناشناسی آزمایشی باشد، رشته‌ی خالی برگردانده می‌شود.

set_flags(flags)

پرچم‌های مشخص‌شده با flags را فعال کرده و بقیه را غیرفعال می‌کند.

add_flag(flag)

پرچم(های) مشخص‌شده با flag را بدون تغییر سایر پرچم‌ها تنظیم کنید. برای افزودن بیش از یک پرچم در یک زمان، flag می‌تواند رشته‌ای با بیش از یک نویسه باشد. "info" فعلی بازنویسی می‌شود، خواه حاوی اطلاعات آزمایشی به‌جای پرچم‌ها باشد، خواه نباشد.

remove_flag(flag)

پرچم(های) مشخص‌شده با flag را بدون تغییر سایر پرچم‌ها غیرفعال می‌کند. برای حذف بیش از یک پرچم به‌صورت همزمان، flag می‌تواند رشته‌ای با بیش از یک نویسه باشد. اگر "info" به‌جای پرچم‌ها حاوی اطلاعات آزمایشی باشد، "info" فعلی تغییر نمی‌کند.

get_date()

تاریخ تحویل پیام را به‌صورت یک عدد ممیز شناور برمی‌گرداند که نشان‌دهنده‌ی ثانیه‌های سپری‌شده از مبدأ است.

set_date(date)

تاریخ تحویل پیام را روی date تنظیم کنید، عددی اعشاری که ثانیه‌های سپری‌شده از مبدا زمان را نشان می‌دهد.

get_info()

رشته‌ای حاوی "info" برای یک پیام برمی‌گرداند. این برای دسترسی و اصلاح "info" آزمایشی (یعنی نه فهرستی از پرچم‌ها) مفید است.

set_info(info)

"info" را روی info تنظیم کنید، که باید یک رشته باشد.

هنگامی که یک نمونه MaildirMessage بر اساس یک نمونه mboxMessage یا MMDFMessage ایجاد می‌شود، سرآیندهای Status و X-Status حذف می‌شوند و تبدیل‌های زیر انجام می‌شوند:

وضعیت حاصل	وضعیت mboxMessage یا MMDFMessage
زیرپوشه‌ی "cur"	پرچم O
پرچم F	پرچم F
پرچم R	پرچم A
پرچم S	پرچم R
پرچم T	پرچم D

هنگامی که یک نمونه MaildirMessage بر اساس یک نمونه MHMessage ایجاد می‌شود، تبدیل‌های زیر انجام می‌شوند:

وضعیت حاصل	وضعیت MHMessage
زیرپوشه‌ی "cur"	دنباله‌ی «unseen»
زیرپوشه‌ی "cur" و پرچم S	بدون دنباله‌ی «unseen»
پرچم F	دنباله‌ی «flagged»
پرچم R	دنباله‌ی "replied"

هنگامی که یک نمونه از MaildirMessage بر اساس یک نمونه از BabylMessage ایجاد می‌شود، تبدیل‌های زیر انجام می‌شود:

وضعیت حاصل	وضعیت BabylMessage
زیرپوشه‌ی "cur"	برچسب "unseen"
زیرپوشه‌ی "cur" و پرچم S	بدون برچسب «unseen»
پرچم P	برچسب «forwarded» یا «resent»
پرچم R	برچسب «answered»
پرچم T	برچسب «deleted»

اشیاءِ mboxMessage

class mailbox.mboxMessage(message=None)

پیامی با رفتارهای ویژه‌ی mbox. پارامتر message همان معنایی را دارد که در سازنده‌ی Message دارد.

پیام‌ها در یک صندوق پستی mbox با هم در یک پرونده واحد ذخیره می‌شوند. نشانی پاکت فرستنده و زمان تحویل معمولاً در خطی ذخیره می‌شوند که با "From " آغاز می‌شود و برای نشان دادن آغاز یک پیام استفاده می‌شود، هرچند در قالب دقیق این داده‌ها میان پیاده‌سازی‌های mbox تفاوت قابل‌توجهی وجود دارد. پرچم‌هایی که وضعیت پیام را نشان می‌دهند، مانند اینکه پیام خوانده شده باشد یا به‌عنوان مهم علامت‌گذاری شده باشد، معمولاً در سرآیندهای Status و X-Status ذخیره می‌شوند.

پرچم‌های مرسوم برای پیام‌های mbox به شرح زیر است:

پرچم	معنی	توضیح
R	خوانده‌شده	خوانده‌شده
O	قدیمی	پیش‌تر توسط MUA شناسایی شده است
D	حذف‌شده	علامت‌گذاری‌شده برای حذف بعدی
F	پرچم‌دار	به‌عنوان مهم علامت‌گذاری شده
A	پاسخ داده‌شده	پاسخ داده‌شده به

پرچم‌های «R» و «O» در سرآیند Status ذخیره می‌شوند، و پرچم‌های «D»، «F» و «A» در سرآیند X-Status ذخیره می‌شوند. پرچم‌ها و سرآیندها معمولاً به ترتیب ذکرشده ظاهر می‌شوند.

نمونه‌های mboxMessage متدهای زیر را ارائه می‌دهند:

get_from()

رشته‌ای را برمی‌گرداند که نشان‌دهنده‌ی خط "From " است؛ خطی که آغاز پیام در یک صندوق پستی mbox را علامت‌گذاری می‌کند. "From " ابتدایی و نویسه‌ی خط جدید پایانی لحاظ نمی‌شوند.

set_from(from_, time_=None)

خط "From " را روی from_ تنظیم کنید، که باید بدون "From " در ابتدا یا خط جدید در انتها مشخص شود. برای راحتی، می‌توان time_ را مشخص کرد؛ در این صورت به‌طور مناسب قالب‌بندی می‌شود و به from_ اضافه خواهد شد. اگر time_ مشخص شده باشد، باید یک نمونه از time.struct_time، یک تاپل مناسب برای ارسال به time.strftime()، یا True باشد (برای استفاده از time.gmtime()).

get_flags()

رشته‌ای را برمی‌گرداند که پرچم‌هایی را که در حال حاضر تنظیم شده‌اند مشخص می‌کند. اگر پیام با قالب مرسوم مطابقت داشته باشد، نتیجه الحاق ۰ یا ۱ مورد از هر یک از 'R'، 'O'، 'D'، 'F' و 'A'، به ترتیب زیر است.

set_flags(flags)

پرچم‌های مشخص‌شده با flags را تنظیم و تمام پرچم‌های دیگر را غیرفعال می‌کند. پارامتر flags باید حاصل الحاق صفر یا چند مورد از هر یک از 'R'، 'O'، 'D'، 'F' و 'A' به هر ترتیبی باشد.

add_flag(flag)

پرچم(های) مشخص‌شده با flag را بدون تغییر سایر پرچم‌ها تنظیم کنید. برای افزودن بیش از یک پرچم به‌طور همزمان، flag می‌تواند رشته‌ای با بیش از یک نویسه باشد.

remove_flag(flag)

پرچم(های) مشخص‌شده با flag را بدون تغییر دادن سایر پرچم‌ها غیرفعال کنید. برای حذف همزمان بیش از یک پرچم، flag می‌تواند رشته‌ای با بیش از یک نویسه باشد.

هنگامی که یک نمونه از mboxMessage بر اساس یک نمونه از MaildirMessage ایجاد می‌شود، یک خط "From " بر اساس تاریخ تحویل نمونه‌ی MaildirMessage تولید می‌شود و تبدیل‌های زیر انجام می‌شوند:

وضعیت حاصل	وضعیت MaildirMessage
پرچم R	پرچم S
پرچم O	زیرپوشه‌ی "cur"
پرچم D	پرچم T
پرچم F	پرچم F
پرچم A	پرچم R

هنگامی که یک نمونه mboxMessage بر اساس یک نمونه MHMessage ایجاد می‌شود، تبدیل‌های زیر رخ می‌دهند:

وضعیت حاصل	وضعیت MHMessage
پرچم R و پرچم O	بدون دنباله‌ی «unseen»
پرچم O	دنباله‌ی «unseen»
پرچم F	دنباله‌ی «flagged»
پرچم A	دنباله‌ی "replied"

هنگامی که یک نمونه mboxMessage بر اساس یک نمونه BabylMessage ایجاد می‌شود، تبدیل‌های زیر انجام می‌شوند:

وضعیت حاصل	وضعیت BabylMessage
پرچم R و پرچم O	بدون برچسب «unseen»
پرچم O	برچسب "unseen"
پرچم D	برچسب «deleted»
پرچم A	برچسب «answered»

هنگامی که یک نمونه mboxMessage بر اساس یک نمونه MMDFMessage ایجاد می‌شود، خط "From " رونوشت می‌شود و تمام پرچم‌ها به‌طور مستقیم متناظر هستند:

وضعیت حاصل	وضعیت MMDFMessage
پرچم R	پرچم R
پرچم O	پرچم O
پرچم D	پرچم D
پرچم F	پرچم F
پرچم A	پرچم A

اشیای MHMessage

class mailbox.MHMessage(message=None)

پیامی با رفتارهای خاص MH. پارامتر message همان معنایی را دارد که در سازنده‌ی Message دارد.

پیام‌های MH از علامت‌ها یا پرچم‌ها به معنای سنتی پشتیبانی نمی‌کنند، اما از دنباله‌ها پشتیبانی می‌کنند که گروه‌بندی‌های منطقی از پیام‌های دلخواه هستند. برخی برنامه‌های خواندن ایمیل (البته به‌جز mh و nmh استاندارد) از دنباله‌ها تقریباً به همان شیوه‌ای استفاده می‌کنند که پرچم‌ها در قالب‌های دیگر استفاده می‌شوند، به شرح زیر:

دنباله	توضیح
دیده‌نشده	خوانده‌نشده، اما پیش‌تر توسط MUA شناسایی‌شده
پاسخ داد	پاسخ داده‌شده به
علامت‌گذاری‌شده	به‌عنوان مهم علامت‌گذاری شده

نمونه‌های MHMessage متدهای زیر را ارائه می‌دهند:

get_sequences()

فهرستی از نام‌های دنباله‌هایی که شامل این پیام هستند را برمی‌گرداند.

set_sequences(sequences)

فهرست دنباله‌هایی را که شامل این پیام می‌شوند، تنظیم کنید.

add_sequence(sequence)

sequence را به فهرست دنباله‌هایی که این پیام را شامل می‌شوند، اضافه کنید.

remove_sequence(sequence)

sequence را از فهرست دنباله‌هایی که این پیام را شامل می‌شوند، حذف کنید.

هنگامی که یک نمونه از MHMessage بر اساس یک نمونه از MaildirMessage ایجاد می‌شود، تبدیل‌های زیر رخ می‌دهند:

وضعیت حاصل	وضعیت MaildirMessage
دنباله‌ی «unseen»	بدون پرچم S
دنباله‌ی "replied"	پرچم R
دنباله‌ی «flagged»	پرچم F

هنگامی که یک نمونه MHMessage بر اساس نمونه‌ای از mboxMessage یا MMDFMessage ایجاد شود، سرآیند‌های Status و X-Status حذف می‌شوند و تبدیل‌های زیر انجام می‌شوند:

وضعیت حاصل	وضعیت mboxMessage یا MMDFMessage
دنباله‌ی «unseen»	بدون پرچم R
دنباله‌ی "replied"	پرچم A
دنباله‌ی «flagged»	پرچم F

هنگامی که یک نمونه MHMessage بر اساس یک نمونه BabylMessage ایجاد می‌شود، تبدیل‌های زیر رخ می‌دهند:

وضعیت حاصل	وضعیت BabylMessage
دنباله‌ی «unseen»	برچسب "unseen"
دنباله‌ی "replied"	برچسب «answered»

اشیاء BabylMessage

class mailbox.BabylMessage(message=None)

پیامی با رفتارهای مختص Babyl. پارامتر message همان معنایی را دارد که در سازنده‌ی Message دارد.

برخی برچسب‌های پیام، که attributes نامیده می‌شوند، طبق قرارداد برای داشتن معانی خاصی تعریف شده‌اند. ویژگی‌ها به شرح زیر هستند:

برچسب	توضیح
دیده‌نشده	خوانده‌نشده، اما پیش‌تر توسط MUA شناسایی‌شده
حذف‌شده	علامت‌گذاری‌شده برای حذف بعدی
ثبت‌شده	به پرونده یا صندوق پستی دیگری کپی شد
پاسخ داده‌شده	پاسخ داده‌شده به
بازارسال‌شده	هدایت‌شده
ویرایش‌شده	تغییریافته توسط کاربر
بازارسال‌شده	ارسال مجدد

به‌طور پیش‌فرض، Rmail فقط سرآیندهای قابل مشاهده را نمایش می‌دهد. با این حال، کلاس BabylMessage از سرآیندهای اصلی استفاده می‌کند، زیرا کامل‌تر هستند. در صورت تمایل، می‌توان به‌صورت صریح به سرآیندهای قابل مشاهده دسترسی داشت.

نمونه‌های BabylMessage متدهای زیر را ارائه می‌دهند:

get_labels()

فهرستی از برچسب‌های پیام را برمی‌گرداند.

set_labels(labels)

فهرست برچسب‌های پیام را روی labels تنظیم کنید.

add_label(label)

label را به فهرست برچسب‌های پیام اضافه کنید.

remove_label(label)

label را از فهرست برچسب‌های پیام حذف کنید.

get_visible()

یک نمونه Message برمی‌گرداند که سرآیندهای آن، سرآیندهای قابل مشاهده پیام هستند و بدنه آن خالی است.

set_visible(visible)

سرآیندهای قابل مشاهده‌ی پیام را برابر با سرآیندهای message تنظیم کنید. پارامتر visible باید نمونه‌ای از Message، نمونه‌ای از email.message.Message، یک رشته، یا یک شیء شبه‌پرونده باشد (که باید در حالت متنی باز باشد).

update_visible()

هنگامی که سرآیندهای اصلی یک نمونه از BabylMessage تغییر کنند، سرآیندهای قابل مشاهده به‌طور خودکار برای تطابق با آن‌ها تغییر نمی‌کنند. این متد سرآیندهای قابل مشاهده را به شرح زیر به‌روزرسانی می‌کند: هر سرآیند قابل مشاهده که یک سرآیند اصلی متناظر دارد، به مقدار سرآیند اصلی تنظیم می‌شود، هر سرآیند قابل مشاهده که فاقد یک سرآیند اصلی متناظر است، حذف می‌شود، و هر یک از Date، From، Reply-To، To، CC و Subject که در سرآیندهای اصلی وجود دارند اما در سرآیندهای قابل مشاهده وجود ندارند، به سرآیندهای قابل مشاهده افزوده می‌شوند.

هنگامی که یک نمونه BabylMessage بر اساس یک نمونه MaildirMessage ایجاد می‌شود، تبدیل‌های زیر انجام می‌شوند:

وضعیت حاصل	وضعیت MaildirMessage
برچسب "unseen"	بدون پرچم S
برچسب «deleted»	پرچم T
برچسب «answered»	پرچم R
برچسب «forwarded»	پرچم P

هنگامی که یک نمونه BabylMessage بر پایه یک نمونه mboxMessage یا MMDFMessage ایجاد می‌شود، سرآیندهای Status و X-Status حذف می‌شوند و تبدیل‌های زیر انجام می‌شوند:

وضعیت حاصل	وضعیت mboxMessage یا MMDFMessage
برچسب "unseen"	بدون پرچم R
برچسب «deleted»	پرچم D
برچسب «answered»	پرچم A

هنگامی که یک نمونه BabylMessage بر اساس یک نمونه MHMessage ایجاد می‌شود، تبدیل‌های زیر انجام می‌شود:

وضعیت حاصل	وضعیت MHMessage
برچسب "unseen"	دنباله‌ی «unseen»
برچسب «answered»	دنباله‌ی "replied"

اشیاء MMDFMessage

class mailbox.MMDFMessage(message=None)

پیامی با رفتارهای خاص MMDF. پارامتر message همان معنایی را دارد که در سازنده‌ی Message دارد.

همانند پیام‌ها در یک صندوق پستی mbox، پیام‌های MMDF به همراه نشانی فرستنده و تاریخ تحویل در یک خط آغازین که با "From " شروع می‌شود، ذخیره می‌شوند. به همین ترتیب، پرچم‌هایی که وضعیت پیام را نشان می‌دهند معمولاً در سرآیندهای Status و X-Status ذخیره می‌شوند.

پرچم‌های مرسوم برای پیام‌های MMDF با پرچم‌های پیام mbox یکسان هستند و به شرح زیرند:

پرچم	معنی	توضیح
R	خوانده‌شده	خوانده‌شده
O	قدیمی	پیش‌تر توسط MUA شناسایی شده است
D	حذف‌شده	علامت‌گذاری‌شده برای حذف بعدی
F	پرچم‌دار	به‌عنوان مهم علامت‌گذاری شده
A	پاسخ داده‌شده	پاسخ داده‌شده به

پرچم‌های «R» و «O» در سرآیند Status ذخیره می‌شوند، و پرچم‌های «D»، «F» و «A» در سرآیند X-Status ذخیره می‌شوند. پرچم‌ها و سرآیندها معمولاً به ترتیب ذکرشده ظاهر می‌شوند.

نمونه‌های MMDFMessage متدهای زیر را ارائه می‌دهند، که با متدهای ارائه‌شده توسط mboxMessage یکسان هستند:

get_from()

رشته‌ای را برمی‌گرداند که نشان‌دهنده‌ی خط "From " است؛ خطی که آغاز پیام در یک صندوق پستی mbox را علامت‌گذاری می‌کند. "From " ابتدایی و نویسه‌ی خط جدید پایانی لحاظ نمی‌شوند.

set_from(from_, time_=None)

خط "From " را روی from_ تنظیم کنید، که باید بدون "From " در ابتدا یا خط جدید در انتها مشخص شود. برای راحتی، می‌توان time_ را مشخص کرد؛ در این صورت به‌طور مناسب قالب‌بندی می‌شود و به from_ اضافه خواهد شد. اگر time_ مشخص شده باشد، باید یک نمونه از time.struct_time، یک تاپل مناسب برای ارسال به time.strftime()، یا True باشد (برای استفاده از time.gmtime()).

get_flags()

رشته‌ای را برمی‌گرداند که پرچم‌هایی را که در حال حاضر تنظیم شده‌اند مشخص می‌کند. اگر پیام با قالب مرسوم مطابقت داشته باشد، نتیجه الحاق ۰ یا ۱ مورد از هر یک از 'R'، 'O'، 'D'، 'F' و 'A'، به ترتیب زیر است.

set_flags(flags)

پرچم‌های مشخص‌شده با flags را تنظیم و تمام پرچم‌های دیگر را غیرفعال می‌کند. پارامتر flags باید حاصل الحاق صفر یا چند مورد از هر یک از 'R'، 'O'، 'D'، 'F' و 'A' به هر ترتیبی باشد.

add_flag(flag)

پرچم(های) مشخص‌شده با flag را بدون تغییر سایر پرچم‌ها تنظیم کنید. برای افزودن بیش از یک پرچم به‌طور همزمان، flag می‌تواند رشته‌ای با بیش از یک نویسه باشد.

remove_flag(flag)

پرچم(های) مشخص‌شده با flag را بدون تغییر دادن سایر پرچم‌ها غیرفعال کنید. برای حذف همزمان بیش از یک پرچم، flag می‌تواند رشته‌ای با بیش از یک نویسه باشد.

هنگامی که یک نمونه از MMDFMessage بر اساس یک نمونه از MaildirMessage ایجاد می‌شود، یک خط "From " بر اساس تاریخ تحویل نمونه‌ی MaildirMessage تولید می‌شود و تبدیل‌های زیر انجام می‌شوند:

وضعیت حاصل	وضعیت MaildirMessage
پرچم R	پرچم S
پرچم O	زیرپوشه‌ی "cur"
پرچم D	پرچم T
پرچم F	پرچم F
پرچم A	پرچم R

هنگامی که یک نمونه MMDFMessage بر اساس یک نمونه MHMessage ایجاد می‌شود، تبدیل‌های زیر انجام می‌شوند:

وضعیت حاصل	وضعیت MHMessage
پرچم R و پرچم O	بدون دنباله‌ی «unseen»
پرچم O	دنباله‌ی «unseen»
پرچم F	دنباله‌ی «flagged»
پرچم A	دنباله‌ی "replied"

هنگامی که یک نمونه MMDFMessage بر اساس یک نمونه BabylMessage ایجاد می‌شود، تبدیل‌های زیر انجام می‌شود:

وضعیت حاصل	وضعیت BabylMessage
پرچم R و پرچم O	بدون برچسب «unseen»
پرچم O	برچسب "unseen"
پرچم D	برچسب «deleted»
پرچم A	برچسب «answered»

هنگامی که یک نمونه MMDFMessage بر اساس یک نمونه mboxMessage ایجاد می‌شود، خط "From " کپی می‌شود و تمام پرچم‌ها به‌طور مستقیم با یکدیگر متناظر هستند:

وضعیت حاصل	وضعیت mboxMessage
پرچم R	پرچم R
پرچم O	پرچم O
پرچم D	پرچم D
پرچم F	پرچم F
پرچم A	پرچم A

استثناها

کلاس‌های استثنای زیر در ماژول mailbox تعریف شده‌اند:

exception mailbox.Error

کلاس پایه برای تمام سایر استثناهای مختص ماژول.

exception mailbox.NoSuchMailboxError

زمانی پرتاب می‌شود که انتظار می‌رود یک صندوق پستی موجود باشد اما یافت نمی‌شود، مانند زمانی که از یک زیرکلاس Mailbox با مسیری که وجود ندارد (و با پارامتر create که روی False تنظیم شده است) نمونه‌سازی می‌کنید، یا هنگام باز کردن پوشه‌ای که وجود ندارد.

exception mailbox.NotEmptyError

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

exception mailbox.ExternalClashError

زمانی پرتاب می‌شود که وضعیتی مربوط به صندوق پستی خارج از کنترل برنامه باعث شود برنامه نتواند ادامه یابد؛ مانند زمانی که کسب قفلی که برنامه‌ای دیگر از قبل آن را در اختیار دارد با شکست مواجه شود، یا زمانی که نام پرونده‌ای که به‌طور یکتا تولید شده است از قبل وجود داشته باشد.

exception mailbox.FormatError

هنگامی پرتاب می‌شود که داده‌های درون یک پرونده قابل تجزیه نباشند، مانند زمانی که یک نمونه از MH تلاش می‌کند یک پرونده .mh_sequences آسیب‌دیده را بخواند.

مثال‌ها

یک مثال ساده از چاپ موضوعات همه پیام‌های یک صندوق پستی که جالب به نظر می‌رسند:

import mailbox
for message in mailbox.mbox('~/mbox'):
    subject = message['subject']       # Could possibly be None.
    if subject and 'python' in subject.lower():
        print(subject)

برای کپی کردن تمام نامه‌ها از یک صندوق پستی Babyl به یک صندوق پستی MH، با تبدیل تمام اطلاعات مختص قالبی که قابل تبدیل است:

import mailbox
destination = mailbox.MH('~/Mail')
destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
    destination.add(mailbox.MHMessage(message))
destination.flush()
destination.unlock()

این مثال نامه‌ها را از چندین فهرست پستی به صندوق‌های پستی مختلف دسته‌بندی می‌کند و مراقب است از خرابی نامه به دلیل تغییر همزمان توسط برنامه‌های دیگر، از دست رفتن نامه به دلیل وقفه در برنامه، یا خاتمه زودرس به دلیل پیام‌های بدشکل در صندوق پستی جلوگیری کند:

import mailbox
import email.errors

list_names = ('python-list', 'python-dev', 'python-bugs')

boxes = {name: mailbox.mbox('~/email/%s' % name) for name in list_names}
inbox = mailbox.Maildir('~/Maildir', factory=None)

for key in inbox.iterkeys():
    try:
        message = inbox[key]
    except email.errors.MessageParseError:
        continue                # The message is malformed. Just leave it.

    for name in list_names:
        list_id = message['list-id']
        if list_id and name in list_id:
            # Get mailbox to use
            box = boxes[name]

            # Write copy to disk before removing original.
            # If there's a crash, you might duplicate a message, but
            # that's better than losing a message completely.
            box.lock()
            box.add(message)
            box.flush()
            box.unlock()

            # Remove original message
            inbox.lock()
            inbox.discard(key)
            inbox.flush()
            inbox.unlock()
            break               # Found destination, so stop looking.

for box in boxes.itervalues():
    box.close()